SyncManager

import { SyncManager } from '@signaldb/sync'

const syncManager = new SyncManager({
  pull: async () => {
    // your pull logic
  },
  push: async () => {
    // your push logic
  },
})

syncManager.addCollection(someCollection, {
  name: 'someCollection',
})

The SyncManager class in SignalDB is designed to handle the synchronization of collections between your local storage and a remote source. It manages both pushing local changes to the server and pulling updates from the server, ensuring that your data remains consistent and up-to-date.

Constructor

new SyncManager(options)

Creates a new instance of SyncManager.

Parameters

• options (Options): Configuration options for the sync manager.

  • pull: Function to fetch data from the remote source. The function gets the collection options as the first parameter. The second parameter is an object containing the following properties:

    • lastFinishedSyncStart: The start time of the last finished sync (if available).
    • lastFinishedSyncEnd: The end time of the last finished sync (if available).

    It must return a promise resolving to either { items } — all items of the collection on the server, which the sync manager compares against its last snapshot — or { changes: { added, modified, removed } } — only what changed since the last sync. See implementing the pull method.

  • push: Function to send changes to the remote source. The function gets the collection options as the first parameter. The second parameter is an object that contains the following properties:

    • changes:
      • added: An array of added items.
      • modified: An array of updated items.
      • modifiedFields: A map with the modified fields per item id.
      • removed: An array of removed items.
    • rawChanges: An array of the raw change operations.

  • registerRemoteChange: Optional function to register a callback for remote changes. The callback can also return a cleanup function to remove the listener.

  • id: Optional unique identifier for the sync manager.

  • dataAdapter: Optional data adapter for the sync manager's own collections — the ones holding its changes, snapshots and sync operations. Pass the same one your collections use so that everything lives in one place. Defaults to a DefaultDataAdapter, which keeps that bookkeeping in memory only, so it does not survive a reload.

  • reactivity: Optional reactivity adapter for handling reactivity.

  • onError: Optional function to handle errors.

  • autostart: Optional flag to start syncing automatically after adding collections (default: true).

  • debounceTime: Optional time in milliseconds to debounce pushing changes (default: 100).

Methods

All methods that start, pause or perform work — removeCollection, syncAll, sync, startSync, pauseSync, startAll, pauseAll, pushChanges and dispose — return a promise. Await it, or handle its rejection: a failed sync rejects the promise of the call that started it.

addCollection(collection, options)

Adds a collection to the sync manager.

Parameters

• collection (Collection): The collection to add.
• options (SyncOptions): Configuration options for the collection.

Adding a collection registers added, changed and removed listeners on it. Calling addCollection again with the same name replaces the previous registration instead of adding a second set of listeners.

removeCollection(name)

Removes a collection from the sync manager. This pauses the sync process for the collection and detaches all event listeners the sync manager attached to it. The collection itself isn't disposed and stays usable afterwards. Listeners registered by your application are left untouched.

Parameters

• name (string): The name of the collection.

getCollection(name) (deprecated)

Retrieves a collection and its options by name, as a tuple [collection, options]. Use getCollectionProperties instead.

getCollectionProperties(name)

Retrieves a registered collection and its options by name. Throws if no collection with that name was added.

Parameters

• name (string): The name of the collection.

Returns

• An object with the properties collection (the Collection), options (the SyncOptions passed to addCollection), readyPromise (resolves when the collection is ready) and syncPaused (boolean).

syncAll()

Starts the sync process for all collections managed by the sync manager. The returned promise rejects with one combined error if syncing any of the collections failed.

isSyncing(name?, async?)

⚡️ this function is reactive!

Checks if a specific collection or any collection is currently being synced. Called in a reactive scope of the reactivity adapter passed to the sync manager, it reruns when that changes.

Parameters

• name (string, optional): The name of the collection. If omitted, checks all collections.
• async (boolean, optional): If true, the active sync operations are read through an { async: true } query and a promise is returned. Use this when the sync manager's dataAdapter cannot answer a query on the spot — an AsyncDataAdapter or a WorkerDataAdapter — or when several instances of the application share its storage.

Returns

• boolean: true if syncing, false otherwise.
• Promise<boolean> if async is true.

isReady()

Returns a promise that resolves once the sync manager's own collections — changes, snapshots and sync operations — are ready. sync and syncAll wait for it themselves; you only need it to wait for the sync manager before calling anything else.

sync(name, options)

Starts the sync process for a specific collection.

Parameters

• name (string): The name of the collection.
• options (object, optional): Sync options.
  • force (boolean, optional): If true, forces the sync process even if no changes are detected.
  • onlyWithChanges (boolean, optional): If true, syncs only if there are changes.

startSync(name)

Setup a collection to be synced with remote changes and enable automatic pushing changes to the remote source.

Parameters

• name (string): The name of the collection.

pauseSync(name)

Pauses the sync process for a collection. This means that the collection will not be synced with remote changes and changes will not automatically be pushed to the remote source.

Parameters

• name (string): The name of the collection.

startAll()

Setup all collections to be synced with remote changes and enable automatic pushing changes to the remote source.

pauseAll()

Pauses the sync process for all collections. This means that the collections will not be synced with remote changes and changes will not automatically be pushed to the remote source.

pushChanges(name)

Initiates the push process for a collection, syncing only if there are changes.

Parameters

• name (string): The name of the collection.

dispose()

Disposes all internal collections and other data structures. It also detaches the event listeners that the sync manager attached to the registered collections, so those collections can be reused with a new SyncManager afterwards (for example on a logout/login cycle).