tinybase 0.0.0 → 0.9.0

package/lib/debug/persisters.d.ts

@@ -0,0 +1,521 @@
+/**
+ * The persisters module of the TinyBase project provides a simple framework
+ * for saving and loading Store data, to and from different destinations, or
+ * underlying storage types.
+ *
+ * Several entry points are provided, each of which returns a new Persister
+ * object that can load and save a Store:
+ *
+ * - The createSessionPersister function returns a Persister that uses the
+ *   browser's session storage.
+ * - The createLocalPersister function returns a Persister that uses the
+ *   browser's local storage.
+ * - The createRemotePersister function returns a Persister that uses a remote
+ *   endpoint
+ * - The createFilePersister function returns a Persister that uses a local file
+ *   (in an appropriate environment)
+ *
+ * Since persistence requirements can be different for every app, the
+ * createCustomPersister function can also be used to easily create a fully
+ * customized way to save and load Store data.
+ *
+ * @packageDocumentation
+ * @module persisters
+ */
+
+import {Store, Tables} from './store.d';
+import {Callback} from './common';
+
+/**
+ * The PersisterStats type describes the number of times a Persister object has
+ * loaded or saved data.
+ *
+ * A PersisterStats object is returned from the getStats method, and is only
+ * populated in a debug build.
+ *
+ * @category Development
+ */
+export type PersisterStats = {
+  loads?: number;
+  saves?: number;
+};
+
+/**
+ * A Persister object lets you save and load Store data to and from different
+ * locations, or underlying storage types.
+ *
+ * This is useful for preserving Store data between browser sessions or reloads,
+ * saving or loading browser state to or from a server, or saving Store data to
+ * disk in a environment with filesystem access.
+ *
+ * Creating a Persister depends on the choice of underlying storage where the
+ * data is to be stored. Options include the createSessionPersister function,
+ * the createLocalPersister, the createRemotePersister function, and the
+ * createFilePersister function. The createCustomPersister function can also be
+ * used to easily create a fully customized way to save and load Store data.
+ *
+ * A Persister lets you explicit save or load data, with the save method and the
+ * load method respectively. These methods are both asynchronous (since the
+ * underlying data storage may also be) and return promises. As a result you
+ * should use the `await` keyword to call them in a way that guarantees
+ * subsequent execution order.
+ *
+ * When you don't want to deal with explicit persistence operations, a Persister
+ * object also provides automatic saving and loading. Automatic saving listens
+ * for changes to the Store and persists the data immediately. Automatic loading
+ * listens (or polls) for changes to the persisted data and reflects those
+ * changes in the Store.
+ *
+ * You can start automatic saving or loading with the startAutoSave method and
+ * startAutoLoad method. Both are asynchronous since they will do an immediate
+ * save and load before starting to listen for subsequent changes. You can stop
+ * the behavior with the stopAutoSave method and stopAutoLoad method (which are
+ * synchronous).
+ *
+ * You may often want to have both automatic saving and loading of a Store so
+ * that changes are constantly synchronized (allowing basic state preservation
+ * between browser tabs, for example). The framework has some basic provisions
+ * to prevent race conditions - for example it will not attempt to save data if
+ * it is currently loading it and vice-versa.
+ *
+ * Be aware, however, that the default implementations do not provide complex
+ * synchronization heuristics and you should comprehensively test your
+ * persistence strategy to understand the opportunity for data loss (in the case
+ * of trying to save data to a server under poor network conditions, for
+ * example).
+ *
+ * @example
+ * This example creates a Store, persists it to the browser's session storage as
+ * a JSON string, changes the persisted data, updates the Store from it, and
+ * finally destroys the Persister again.
+ *
+ * ```tsx
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSessionPersister(store, 'pets');
+ *
+ * await persister.save();
+ * console.log(sessionStorage.getItem('pets'));
+ * // -> '{"pets":{"fido":{"species":"dog"}}}'
+ *
+ * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {toto: {species: 'dog'}}}
+ *
+ * persister.destroy();
+ * sessionStorage.clear();
+ * ```
+ * @example
+ * This example creates a Store, and automatically saves and loads it to the
+ * browser's session storage as a JSON string. Changes to the Store data, or the
+ * persisted data (implicitly firing a StorageEvent), are reflected accordingly.
+ *
+ * ```tsx
+ * const store = createStore();
+ * const persister = createSessionPersister(store, 'pets');
+ *
+ * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
+ * await persister.startAutoSave();
+ *
+ * store.setTables({pets: {felix: {species: 'cat'}}});
+ * // ...
+ * console.log(sessionStorage.getItem('pets'));
+ * // -> '{"pets":{"felix":{"species":"cat"}}}'
+ *
+ * // In another browser tab:
+ * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+ * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
+ *
+ * // ...
+ * console.log(store.getTables());
+ * // -> {pets: {toto: {species: 'dog'}}}
+ *
+ * persister.destroy();
+ * sessionStorage.clear();
+ * ```
+ */
+export interface Persister {
+  /**
+   * The load method gets persisted data from storage, and loads it into the
+   * Store with which the Persister is associated, once.
+   *
+   * The optional parameter allows you to specify what the initial Tables object
+   * for the Store will be if there is nothing currently persisted. Using this
+   * instead of the `initialTables` parameter in the regular createStore
+   * function allows you to easily instantiate a Store whether it's loading from
+   * previously persisted storage or being run for the first time.
+   *
+   * This method is asynchronous because the persisted data may be on a remote
+   * machine or a filesystem. Even for those storage types that are synchronous
+   * (like browser storage) it is still recommended that you `await` calls to
+   * this method or handle the return type natively as a Promise.
+   *
+   * @param initialTables An optional Tables object used when the underlying
+   * storage has not previously been populated.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example
+   * This example creates an empty Store, and loads data into it from the
+   * browser's session storage, which for the purposes of this example has been
+   * previously populated.
+   *
+   * ```tsx
+   * sessionStorage.setItem('pets', '{"pets":{"fido":{"species":"dog"}}}');
+   *
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.load();
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * sessionStorage.clear();
+   * ```
+   * @example
+   * This example creates an empty Store, and loads data into it from the
+   * browser's session storage, which is at first empty, so the optional
+   * parameter is used. The second time the load method is called, data has
+   * previously been persisted and instead, that is loaded.
+   *
+   * ```tsx
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.load({pets: {fido: {species: 'dog'}}});
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+   * await persister.load({pets: {fido: {species: 'dog'}}});
+   * console.log(store.getTables());
+   * // -> {pets: {toto: {species: 'dog'}}}
+   *
+   * sessionStorage.clear();
+   * ```
+   * @category Load
+   */
+  load(initialTables?: Tables): Promise<Persister>;
+
+  /**
+   * The startAutoLoad method gets persisted data from storage, and loads it
+   * into the Store with which the Persister is associated, once, and then
+   * continuously.
+   *
+   * The optional parameter allows you to specify what the initial Tables object
+   * for the Store will be if there is nothing at first persisted. Using this
+   * instead of the `initialTables` parameter in the regular createStore
+   * function allows you to easily instantiate a Store whether it's loading from
+   * previously persisted storage or being run for the first time.
+   *
+   * This method first runs a single call to the load method to ensure the data
+   * is in sync with the persisted storage. It then continues to watch for
+   * changes to the underlying data (either through events or polling, depending
+   * on the storage type), automatically loading the data into the Store.
+   *
+   * This method is asynchronous because it starts by making a single call to
+   * the asynchronous load method. Even for those storage types that are
+   * synchronous (like browser storage) it is still recommended that you `await`
+   * calls to this method or handle the return type natively as a Promise.
+   *
+   * @param initialTables An optional Tables object used when the underlying
+   * storage has not previously been populated.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example
+   * This example creates an empty Store, and loads data into it from the
+   * browser's session storage, which at first is empty (so the `initialTables`
+   * parameter is used). Subsequent changes to the underlying storage are then
+   * reflected in the Store (in this case through detection of StorageEvents
+   * from session storage changes made in another browser tab).
+   *
+   * ```tsx
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * // In another browser tab:
+   * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
+   *
+   * // ...
+   * console.log(store.getTables());
+   * // -> {pets: {toto: {species: 'dog'}}}
+   *
+   * sessionStorage.clear();
+   * ```
+   * @category Load
+   */
+  startAutoLoad(initialTables?: Tables): Promise<Persister>;
+
+  /**
+   * The stopAutoLoad method stops the automatic loading of data from storage
+   * previously started with the startAutoLoad method.
+   *
+   * If the Persister is not currently set to automatically load, this method
+   * has no effect.
+   *
+   * @returns A reference to the Persister object.
+   * @example
+   * This example creates an empty Store, and starts automatically loading data
+   * into it from the browser's session storage. Once the automatic loading is
+   * stopped, subsequent changes are not reflected in the Store.
+   *
+   * ```tsx
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   * await persister.startAutoLoad();
+   *
+   * // In another browser tab:
+   * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
+   * // ...
+   * console.log(store.getTables());
+   * // -> {pets: {toto: {species: 'dog'}}}
+   *
+   * persister.stopAutoLoad();
+   *
+   * // In another browser tab:
+   * sessionStorage.setItem('pets', '{"pets":{"felix":{"species":"cat"}}}');
+   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
+   * // ...
+   * console.log(store.getTables());
+   * // -> {pets: {toto: {species: 'dog'}}}
+   * // Storage change has not been automatically loaded.
+   *
+   * sessionStorage.clear();
+   * ```
+   * @category Load
+   */
+  stopAutoLoad(): Persister;
+
+  /**
+   * The save method takes data from the Store with which the Persister is
+   * associated and persists it into storage, once.
+   *
+   * This method is asynchronous because the persisted data may be on a remote
+   * machine or a filesystem. Even for those storage types that are synchronous
+   * (like browser storage) it is still recommended that you `await` calls to
+   * this method or handle the return type natively as a Promise.
+   *
+   * @returns A Promise containing a reference to the Persister object.
+   * @example
+   * This example creates a Store with some data, and saves into the browser's
+   * session storage.
+   *
+   * ```tsx
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.save();
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"fido":{"species":"dog"}}}'
+   *
+   * persister.destroy();
+   * sessionStorage.clear();
+   * ```
+   */
+  save(): Promise<Persister>;
+
+  /**
+   * The save method takes data from the Store with which the Persister is
+   * associated and persists it into storage, once, and then continuously.
+   *
+   * This method first runs a single call to the save method to ensure the data
+   * is in sync with the persisted storage. It then continues to watch for
+   * changes to the Store, automatically saving the data to storage.
+   *
+   * This method is asynchronous because it starts by making a single call to
+   * the asynchronous save method. Even for those storage types that are
+   * synchronous (like browser storage) it is still recommended that you `await`
+   * calls to this method or handle the return type natively as a Promise.
+   *
+   * @returns A Promise containing a reference to the Persister object.
+   * @example
+   * This example creates a Store with some data, and saves into the browser's
+   * session storage. Subsequent changes to the Store are then automatically
+   * saved to the underlying storage.
+   *
+   * ```tsx
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.startAutoSave();
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"fido":{"species":"dog"}}}'
+   *
+   * store.setTables({pets: {toto: {species: 'dog'}}});
+   * // ...
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"toto":{"species":"dog"}}}'
+   *
+   * sessionStorage.clear();
+   * ```
+   */
+  startAutoSave(): Promise<Persister>;
+
+  /**
+   * The stopAutoSave method stops the automatic save of data to storage
+   * previously started with the startAutoSave method.
+   *
+   * If the Persister is not currently set to automatically save, this method
+   * has no effect.
+   *
+   * @returns A reference to the Persister object.
+   * @example
+   * This example creates a Store with some data, and saves into the browser's
+   * session storage. Subsequent changes to the Store are then automatically
+   * saved to the underlying storage. Once the automatic saving is
+   * stopped, subsequent changes are not reflected.
+   *
+   * ```tsx
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSessionPersister(store, 'pets');
+   * await persister.startAutoSave();
+   *
+   * store.setTables({pets: {toto: {species: 'dog'}}});
+   * // ...
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"toto":{"species":"dog"}}}'
+   *
+   * persister.stopAutoSave();
+   *
+   * store.setTables({pets: {felix: {species: 'cat'}}});
+   * // ...
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"toto":{"species":"dog"}}}'
+   * // Store change has not been automatically saved.
+   *
+   * sessionStorage.clear();
+   * ```
+   * @category Save
+   */
+  stopAutoSave(): Persister;
+
+  /**
+   * The getStore method returns a reference to the underlying Store that is
+   * backing this Persister object.
+   *
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets its reference in order to update its data.
+   *
+   * ```tsx
+   * const persister = createSessionPersister(createStore(), 'pets');
+   * await persister.startAutoSave();
+   *
+   * persister.getStore().setTables({pets: {fido: {species: 'dog'}}});
+   * // ...
+   * console.log(sessionStorage.getItem('pets'));
+   * // -> '{"pets":{"fido":{"species":"dog"}}}'
+   *
+   * sessionStorage.clear();
+   * ```
+   * @category Getter
+   */
+  getStore(): Store;
+
+  /**
+   * The destroy method should be called when this Persister object is no longer
+   * used.
+   *
+   * This guarantees that all of the listeners that the object registered with
+   * the underlying Store and storage are removed and it can be correctly
+   * garbage collected. It is equivalent to running the stopAutoLoad method and
+   * the stopAutoSave method in succession.
+   *
+   * @example
+   * This example creates a Store, associates a Persister object with it (that
+   * registers a TablesListener with the underlying Store), and then destroys it
+   * again, removing the listener.
+   *
+   * ```tsx
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   * await persister.startAutoSave();
+   *
+   * console.log(store.getListenerStats().tables);
+   * // -> 1
+   *
+   * persister.destroy();
+   *
+   * console.log(store.getListenerStats().tables);
+   * // -> 0
+   * ```
+   * @category Lifecycle
+   */
+  destroy(): Persister;
+
+  /**
+   * The getStats method provides a set of statistics about the Persister, and
+   * is used for debugging purposes.
+   *
+   * The PersisterStats object contains a count of the number of times the
+   * Persister has loaded and saved data.
+   *
+   * The statistics are only populated in a debug build: production builds
+   * return an empty object. The method is intended to be used during
+   * development to ensure your persistence layer is acting as expected, for
+   * example.
+   *
+   * @returns A PersisterStats object containing Persister load and save
+   * statistics.
+   * @example
+   * This example gets the load and save statistics of a Persister object.
+   * Remember that the startAutoLoad method invokes an explicit load when it
+   * starts, and the startAutoSave method invokes an explicit save when it
+   * starts - so those numbers are included in addition to the loads and saves
+   * invoked by changes to the Store and to the underlying storage.
+   *
+   * ```tsx
+   * const store = createStore();
+   * const persister = createSessionPersister(store, 'pets');
+   *
+   * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
+   * await persister.startAutoSave();
+   *
+   * store.setTables({pets: {felix: {species: 'cat'}}});
+   * // ...
+   *
+   * sessionStorage.setItem('pets', '{"pets":{"toto":{"species":"dog"}}}');
+   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
+   * // ...
+   *
+   * console.log(persister.getStats());
+   * // -> {loads: 2, saves: 2}
+   *
+   * persister.destroy();
+   * sessionStorage.clear();
+   * ```
+   * @category Development
+   */
+  getStats(): PersisterStats;
+}
+
+export function createSessionPersister(
+  store: Store,
+  storageName: string,
+): Persister;
+
+export function createLocalPersister(
+  store: Store,
+  storageName: string,
+): Persister;
+
+export function createRemotePersister(
+  store: Store,
+  loadUrl: string,
+  saveUrl: string,
+  autoLoadIntervalSeconds: number,
+): Persister;
+
+export function createFilePersister(store: Store, filePath: string): Persister;
+
+export function createCustomPersister(
+  store: Store,
+  getPersisted: () => Promise<string | null | undefined>,
+  setPersisted: (json: string) => Promise<void>,
+  startListeningToPersisted: (didChange: Callback) => void,
+  stopListeningToPersisted: Callback,
+): Persister;