Module which uses Dexie to save data and can later use a server to synchronize the data in the database with other devices
npm install sync-client
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.
``bash`
npm install --save sync-client
`js
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 and stores as key. The version must be an integer and the stores an object in the form of a Dexie Store). You can optionally pass an upgrader function for each store to be used with Version.upgrade)Infinity
* 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
* addons: Array of addons for Dexie. The dexie-syncable and dexie-observable addons are always automatically included
__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__:
`js
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);
`
#### getID()
__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.
#### getID()
__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.
#### connect(url, options)
__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 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 the Access-Control-Allow-Credentials header.
__Returns__:
A Promise which resolves if we managed to connect to the server and rejects if we failed to connect.
#### disconnect(url)
__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.
#### removeUrl(url)
__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.
#### statusChange(url, cb)
__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.
#### getStatuses()
__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.
#### getStatus(url)
__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.
#### statuses
__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.
`bash``
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.