TinyBase logoTinyBase

createCustomPersister

The createCustomPersister function creates a Persister object that you can configure to persist the Store in any way you wish.

createCustomPersister<ListeningHandle>(
  store: Store,
  getPersisted: () => Promise<undefined | [Tables, Values]>,
  setPersisted: (getContent: () => [Tables, Values], getTransactionChanges?: any) => Promise<void>,
  addPersisterListener: (listener: PersisterListener) => ListeningHandle,
  delPersisterListener: (listeningHandle: ListeningHandle) => void,
  onIgnoredError?: (error: any) => void,
): Persister
TypeDescription
storeStore

The Store to persist.

getPersisted() => Promise<undefined | [Tables, Values]>

An asynchronous function which will fetch content from the persistence layer (or undefined if not present).

setPersisted(getContent: () => [Tables, Values], getTransactionChanges?: any) => Promise<void>

An asynchronous function which will send content to the persistence layer. Since v4.0, it receives functions for getting the Store content and information about the changes made during a transaction.

addPersisterListener(listener: PersisterListener) => ListeningHandle

A function that will register a listener listener on underlying changes to the persistence layer. You can return a listening handle that will be provided again when delPersisterListener is called.

delPersisterListener(listeningHandle: ListeningHandle) => void

A function that will unregister the listener from the underlying changes to the persistence layer. It receives whatever was returned from your addPersisterListener implementation.

onIgnoredError?(error: any) => void

An optional handler for the errors that the Persister would otherwise ignore when trying to save or load data. This is suitable for debugging persistence issues in a development environment, since v4.0.4.

returnsPersister

A reference to the new Persister object.

As well as providing a reference to the Store to persist, you must provide functions that handle how to fetch, write, and listen to, the persistence layer.

The other creation functions (such as the createSessionPersister function and createFilePersister function, for example) all use this function under the covers. See those implementations for ideas on how to implement your own Persister types.

This API changed in v4.0. Any custom persisters created on previous versions should be upgraded. Most notably, the setPersisted function parameter is provided with a getContent function to get the content from the Store itself, rather than being passed pre-serialized JSON. It also receives information about the changes made during a transaction. The getPersisted function must return the content (or nothing) rather than JSON. startListeningToPersisted has been renamed addPersisterListener, and stopListeningToPersisted has been renamed delPersisterListener.

Example

This example creates a custom Persister object and persists the Store to a local string called storeJson and which would automatically load by polling for changes every second.

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
let storeJson;

const persister = createCustomPersister(
  store,
  async () => {
    // getPersisted
    return JSON.parse(storeJson);
  },
  async (getContent) => {
    // setPersisted
    storeJson = JSON.stringify(getContent());
  },
  (listener) => setInterval(listener, 1000),
  (interval) => clearInterval(interval),
);

await persister.save();
console.log(storeJson);
// -> '[{"pets":{"fido":{"species":"dog"}}},{}]'

storeJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
await persister.load();

console.log(store.getTables());
// -> {pets: {fido: {species: 'dog', color: 'brown'}}}

persister.destroy();