tinybase 4.0.0-beta.0 → 4.0.0-beta.2

package/lib/types/persisters.d.ts

@@ -3,21 +3,21 @@
  * 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
- *   server.
- * - The createFilePersister function returns a Persister that uses a local file
- *   (in an appropriate environment).
+ * Several entry points are provided (in separately installed modules), each of
+ * which returns a new Persister object that can load and save a Store:
+ *
+ * - The createSessionPersister function (in the persister-browser module)
+ *   returns a Persister that uses the browser's session storage.
+ * - The createLocalPersister function (in the persister-browser module) returns
+ *   a Persister that uses the browser's local storage.
+ * - The createRemotePersister function (in the persister-remote module) returns
+ *   a Persister that uses a remote server.
+ * - The createFilePersister function (in the persister-file module) 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.
+ * createCustomPersister function in this module can also be used to easily
+ * create a fully customized way to save and load Store data.
  *
  * @see Persisting Data guide
  * @see Countries demo
@@ -27,8 +27,7 @@
  * @module persisters
  */
 
-import {Store, Tables, Values} from './store.d';
-import {Callback} from './common.d';
+import {GetTransactionChanges, Store, Tables, Values} from './store.d';
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
@@ -50,6 +49,27 @@ export type PersisterStats = {
   saves?: number;
 };
 
+/**
+ * A PersisterListener is a callback that lets a Persister inform the Store that
+ * a change has happened to the underlying data.
+ *
+ * If the listener has the `getTransactionChanges` parameter, it will be used to
+ * make an incremental change to the Store. If not, but the `getContent`
+ * function _is_ available, that will be used to make a wholesale change to the
+ * Store. If neither are present, the content will be loaded from the
+ * Persister's load method.
+ *
+ * @param getContent An optional function that, if provided, returns an array of
+ * Store content and can be used to immediately wholesale update the Store.
+ * @param getTransactionChanges An optional function that, if provided, returns
+ * a TransactionChanges object and can be used to immediately incrementally
+ * update the Store.
+ */
+export type PersisterListener = (
+  getContent?: () => [Tables, Values],
+  getTransactionChanges?: GetTransactionChanges,
+) => void;
+
 /**
  * A Persister object lets you save and load Store data to and from different
  * locations, or underlying storage types.
@@ -165,7 +185,7 @@ export interface Persister {
    * @param initialTables An optional Tables object used when the underlying
    * storage has not previously been populated.
    * @param initialValues An optional Values object used when the underlying
-   * storage has not previously been populated, since v3.0.0.
+   * storage has not previously been populated, since v3.0.
    * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates an empty Store, and loads data into it from the
@@ -233,7 +253,7 @@ export interface Persister {
    * @param initialTables An optional Tables object used when the underlying
    * storage has not previously been populated.
    * @param initialValues An optional Values object used when the underlying
-   * storage has not previously been populated, since v3.0.0.
+   * storage has not previously been populated, since v3.0.
    * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates an empty Store, and loads data into it from the
@@ -461,12 +481,12 @@ export interface Persister {
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoSave();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 1
    *
    * persister.destroy();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 0
    * ```
    * @category Lifecycle
@@ -520,151 +540,6 @@ export interface Persister {
   //
 }
 
-/**
- * The createSessionPersister function creates a Persister object that can
- * persist the Store to the browser's session storage.
- *
- * As well as providing a reference to the Store to persist, you must provide a
- * `storageName` parameter which is unique to your application. This is the key
- * that the browser uses to identify the storage location.
- *
- * @param store The Store to persist.
- * @param storageName The unique key to identify the storage location.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's session storage.
- *
- * ```js
- * 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();
- * ```
- * @category Creation
- */
-export function createSessionPersister(
-  store: Store,
-  storageName: string,
-): Persister;
-
-/**
- * The createLocalPersister function creates a Persister object that can
- * persist the Store to the browser's local storage.
- *
- * As well as providing a reference to the Store to persist, you must provide a
- * `storageName` parameter which is unique to your application. This is the key
- * that the browser uses to identify the storage location.
- *
- * @param store The Store to persist.
- * @param storageName The unique key to identify the storage location.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's local storage.
- *
- * ```js
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createLocalPersister(store, 'pets');
- *
- * await persister.save();
- * console.log(localStorage.getItem('pets'));
- * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- *
- * persister.destroy();
- * localStorage.clear();
- * ```
- * @category Creation
- */
-export function createLocalPersister(
-  store: Store,
-  storageName: string,
-): Persister;
-
-/**
- * The createRemotePersister function creates a Persister object that can
- * persist the Store to a remote server.
- *
- * As well as providing a reference to the Store to persist, you must provide
- * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
- * server that support the `GET` method (to fetch the Store JSON to load) and
- * the `POST` method (to send the Store JSON to save) respectively.
- *
- * For when you choose to enable automatic loading for the Persister (with the
- * startAutoLoad method), it will poll the loadUrl for changes. The
- * `autoLoadIntervalSeconds` method is used to indicate how often to do this.
- *
- * @param store The Store to persist.
- * @param loadUrl The endpoint that supports a `GET` method to load JSON.
- * @param saveUrl The endpoint that supports a `POST` method to save JSON.
- * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
- * automatically loading changes from the server.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to a remote
- * server.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createRemotePersister(
- *   store,
- *   'https://example.com/load',
- *   'https://example.com/save',
- *   5,
- * );
- *
- * await persister.save();
- * // Store JSON will be sent to server in a POST request.
- *
- * await persister.load();
- * // Store JSON will be fetched from server with a GET request.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createRemotePersister(
-  store: Store,
-  loadUrl: string,
-  saveUrl: string,
-  autoLoadIntervalSeconds: number,
-): Persister;
-
-/**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
- *
- * As well as providing a reference to the Store to persist, you must provide
- * `filePath` parameter which identifies the file to persist it to.
- *
- * @param store The Store to persist.
- * @param filePath The location of the local file to persist the Store to.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to a local
- * file.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createFilePersister(store, '/app/persisted.json');
- *
- * await persister.save();
- * // Store JSON will be saved to the file.
- *
- * await persister.load();
- * // Store JSON will be loaded from the file.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createFilePersister(store: Store, filePath: string): Persister;
-
 /**
  * The createCustomPersister function creates a Persister object that you can
  * configure to persist the Store in any way you wish.
@@ -678,18 +553,28 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  * 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. `addPersisterListener` has been renamed `addPersisterListener`, and
+ * `addPersisterListener` has been renamed `delPersisterListener`.
+ *
  * @param store The Store to persist.
- * @param getPersisted An asynchronous function which will fetch JSON from the
- * persistence layer (or `null` or `undefined` if not present).
- * @param setPersisted An asynchronous function which will send JSON to the
- * persistence layer.
- * @param startListeningToPersisted A function that will register a `didChange`
+ * @param getPersisted An asynchronous function which will fetch content from
+ * the persistence layer (or `undefined` if not present).
+ * @param setPersisted 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.
+ * @param addPersisterListener 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 `stopListeningToPersisted`
- * is called.
- * @param stopListeningToPersisted A function that will unregister the listener
- * from the underlying changes to the persistence layer. It receives whatever
- * was returned from your `startListeningToPersisted` implementation.
+ * listening handle that will be provided again when `delPersisterListener` is
+ * called.
+ * @param delPersisterListener A function that will unregister the listener from
+ * the underlying changes to the persistence layer. It receives whatever was
+ * returned from your `addPersisterListener` implementation.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -702,9 +587,13 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  *
  * const persister = createCustomPersister(
  *   store,
- *   async () => storeJson,
- *   async (json) => (storeJson = json),
- *   (didChange) => setInterval(didChange, 1000),
+ *   async () => {
+ *     try {
+ *       return JSON.parse(storeJson);
+ *     } catch {}
+ *   },
+ *   async (getContent) => (storeJson = JSON.stringify(getContent())),
+ *   (listener) => setInterval(listener, 1000),
  *   (interval) => clearInterval(interval),
  * );
  *
@@ -724,8 +613,11 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  */
 export function createCustomPersister<ListeningHandle>(
   store: Store,
-  getPersisted: () => Promise<string | null | undefined>,
-  setPersisted: (json: string) => Promise<void>,
-  startListeningToPersisted: (didChange: Callback) => ListeningHandle,
-  stopListeningToPersisted: (listeningHandle: ListeningHandle) => void,
+  getPersisted: () => Promise<[Tables, Values] | undefined>,
+  setPersisted: (
+    getContent: () => [Tables, Values],
+    getTransactionChanges?: GetTransactionChanges,
+  ) => Promise<void>,
+  addPersisterListener: (listener: PersisterListener) => ListeningHandle,
+  delPersisterListener: (listeningHandle: ListeningHandle) => void,
 ): Persister;