SyncClient

Synopsis

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.

Installation

npm install --save sync-client

Basic Usage

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);

API

constructor(dbName, versions, options)

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
• 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

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);

Static Methods

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.

Prototype Methods

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 '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 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.

Static Properties

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'.

Running the tests

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.

TODO

• Add integration tests

Contributing

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.

License

MIT License

cuid.js has license MIT Copyright (c) Eric Elliott 2012. The file was modified to use ES2015 syntax.