This module can be used to write data to IndexedDB using Dexie and to synchronize the data in IndexedDB with a server. Dexie.Syncable is used for the synchronization. This module contains an implementation of the ISyncProtocol. It was primarily written to work with sync-server but should work with other servers which offer the same API.
npm install --save sync-client
import SyncClient from 'sync-client';
// SyncClient is a subclass of Dexie
const databaseName = 'testDB'; // The name for the indexedDB database
const versions = [{
version: 1,
stores: { // Has the same format as https://github.com/dfahlander/Dexie.js/wiki/Version.stores()
test: 'id',
},
}];
const syncClient = new SyncClient(databaseName, versions);
Parameters:
- dbName: The name of the IndexedDB database
- versions: An array of objects with
version
andstores
as key. Theversion
must be an integer and thestores
an object in the form of a Dexie Store. You can optionally pass anupgrader
function for each store to be used with Version.upgrade - options: optional object parameter containing one of the following attributes
- partialsThreshold: This is an optional parameter and define the maximum number of changes we will send at once. If for example the threshold is set to 10 and we have 20 changes, dexie-syncable will send to requests each with 10 changes. Default value is
Infinity
- addons: Array of addons for Dexie. The dexie-syncable and dexie-observable addons are always automatically included
- partialsThreshold: This is an optional parameter and define the maximum number of changes we will send at once. If for example the threshold is set to 10 and we have 20 changes, dexie-syncable will send to requests each with 10 changes. Default value is
Return:
A SyncClient instance. Via this instance you can access all methods of a Dexie instance. More information can be found in the Dexie API Reference
Example:
import SyncClient from 'sync-client';
const dbVersions = [
{
version: 1,
stores: {
todos: 'id'
}
},
{
version: 2,
stores: {
todos: 'id, tags'
},
upgrader(transaction) { ... }
}
]
const syncClient = new SyncClient('MyTodosDB', dbVersions);
Description:
Creates and returns a unique ID using cuid. This method does not add anything to the database. Alternatively you can use the prototype getID()
method.
Parameters:
None.
Returns:
A string representing the ID.
Description:
Creates and returns a unique ID using cuid. This method does not add anything to the database. Alternatively you can use the static getID()
method.
Parameters:
None.
Returns:
A string representing the ID.
Description:
This method tries to connect to a server and start the synchronization process. Before trying to connect, it checks if window.navigator.onLine
is true and if yes it sends a ping to ${url}/check
to make sure that the server is online. If The checks pass it calls the connect
method of Dexie.Syncable. Subsequent calls to connect
just resolve unless we manually disconnected before by calling disconnect(url)
or if the client auto-disconnected us because of an error during synchronization or because we are offline (navigator.onLine
changed to false).
Parameters:
- url: The server URL to connect to
- options: Object. Currently supported options:
- pollInterval: Number in milliseconds telling the client how often it should sync with the server. Default value is
10000
- credentials: one of
'omit'
or'include'
. Default value is 'omit'. You can find more information about the credentials option on the Fetch API page. The'include'
value only works if the server supports theAccess-Control-Allow-Credentials
header.
- pollInterval: Number in milliseconds telling the client how often it should sync with the server. Default value is
Returns:
A Promise which resolves if we managed to connect to the server and rejects if we failed to connect.
Description:
This method tries to disconnect from a server and stop the synchronization process. Calls the disconnect
method of Dexie.Syncable.
Parameters:
- url: The server URL to disconnect from
Returns:
A Promise which resolves if we managed to disconnect and rejects if we failed to disconnect.
Description:
It disconnects from the server with the given URL and removes all relevant synchronization data from the database. It does not remove data in your tables. Calls the delete
method of Dexie.Syncable
Parameters:
- url: The server URL to disconnect from and remove its data
Returns:
A Promise which resolves if we managed to delete the data and rejects if we failed.
Description:
This method can be used to register a listener which is called every time the connection status of the given URL is changed.
Parameters:
- url: The URL for which we want to receive status changed
- cb: Callback to be called on status changed. The callback has one parameter which is the new status string
Returns:
Nothing.
Description:
This method can be used to get a list of all URLs the their current status.
Parameters:
None.
Returns:
A Promise which resolves with an array of {url: string, status: SyncClient.statuses}
object. The promise is rejected if we failed to get the statuses.
Description:
This method can be used to get the text status for one URL.
Parameters:
- url: The URL for which we want the status for
Returns:
A Promise which resolves with a status of type SyncClient.statuses
. The promise is rejected if we fail to get the status.
Description:
An object containing keys pointing to statuses of Dexie.Syncable. Instead of returning the number for a status it returns the string as key. For example SyncClient.statuses.ERROR
will return 'ERROR'
.
The following commands can be execute to run the tests.
npm install
npm test
The last command will run eslint and the unit tests for the module.
- Add integration tests
If you feel you can help in any way, be it with documentation, examples, extra testing, or new features please open an issue or pull request. If you have any questions feel free to open an issue with your question.
cuid.js has license MIT Copyright (c) Eric Elliott 2012. The file was modified to use ES2015 syntax.