tinybase 4.0.0-beta.4 → 4.0.0-beta.5.1

package/lib/types/persisters.d.ts

@@ -4,22 +4,28 @@
  * underlying storage types.
  *
  * Several entry points are provided (in separately installed modules), each of
- * which returns a new Persister object that can load and save a Store:
+ * which returns a new Persister object that can load and save a Store. Between
+ * them, these allow you to store your TinyBase data locally, remotely, to
+ * SQLite databases, and across synchronization boundaries with CRDT frameworks.
  *
- * - 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).
+ * |Module|Function|Storage|
+ * |-|-|-|
+ * |persister-browser|createSessionPersister|Browser session storage|
+ * |persister-browser|createLocalPersister|Browser local storage|
+ * |persister-remote|createRemotePersister|Remote server|
+ * |persister-file|createFilePersister|Local file (where possible)|
+ * |persister-sqlite3|createSqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|
+ * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|
+ * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|
+ * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|
+ * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|
  *
  * Since persistence requirements can be different for every app, the
  * 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 Database Persistence guide
+ * @see Synchronizing Data guide
  * @see Countries demo
  * @see Todo App demos
  * @see Drawing demo
@@ -28,6 +34,7 @@
  */
 
 import {GetTransactionChanges, Store, Tables, Values} from './store.d';
+import {Id} from './common.d';
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
@@ -35,7 +42,6 @@ import {GetTransactionChanges, Store, Tables, Values} from './store.d';
  *
  * A PersisterStats object is returned from the getStats method, and is only
  * populated in a debug build.
- *
  * @category Development
  */
 export type PersisterStats = {
@@ -58,18 +64,468 @@ export type PersisterStats = {
  * 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.
+ * @category Creation
+ * @since v4.0.0
  */
 export type PersisterListener = (
   getContent?: () => [Tables, Values],
   getTransactionChanges?: GetTransactionChanges,
 ) => void;
 
+/**
+ * The DatabasePersisterConfig type describes the configuration of a
+ * database-oriented Persister, such as those for SQLite.
+ *
+ * There are two modes for persisting a Store with a database:
+ *
+ * - A JSON serialization of the whole Store, which is stored in a single row of
+ *   a table (normally called `tinybase`) within the database. This is
+ *   configured by providing a DpcJson object.
+ * - A tabular mapping of Table Ids to database table names (and vice-versa).
+ *   Values are stored in a separate special table (normally called
+ *   `tinybase_values`). This is configured by providing a DpcTabular object.
+ *
+ * Please see the DpcJson and DpcTabular type documentation for more detail on
+ * each. If not specified otherwise, JSON serialization will be used for
+ * persistence.
+ *
+ * Changes made to the database (outside of this Persister) are picked up
+ * immediately if they are made via the same connection or library that it is
+ * using. If the database is being changed by another client, the Persister
+ * needs to poll for changes. Hence both configuration types also contain an
+ * `autoLoadIntervalSeconds` property which indicates how often it should do
+ * that. This defaults to 1 second.
+ *
+ * Note that all the nested types within this type have a 'Dpc' prefix, short
+ * for 'DatabasePersisterConfig'.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * and save a JSON serialization from and to a table called `my_tinybase`,
+ * polling the database every 2 seconds. See DpcJson for more details on these
+ * settings.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'json',
+ *   storeTableName: 'my_tinybase',
+ *   autoLoadIntervalSeconds: 2,
+ * };
+ * ```
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * and save tabular data from and to tables specified in the `load` and `save`
+ * mappings. See DpcTabular for more details on these settings.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   tables: {
+ *     load: {petsInDb: 'pets', speciesInDb: 'species'},
+ *     save: {pets: 'petsInDb', species: 'speciesInDb'},
+ *   },
+ * };
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DatabasePersisterConfig = DpcJson | DpcTabular;
+
+/**
+ * The DpcJson type describes the configuration of a database-oriented Persister
+ * operating in serialized JSON mode.
+ *
+ * The only setting is the `storeTableName` property, which indicates the name
+ * of a table in the database which will be used to serialize the Store content
+ * into. It defaults to `tinybase`.
+ *
+ * That table in the database will be given two columns: a primary key column
+ * called `_id`, and one called `store`. The Persister will place a single row
+ * in this table with `_` in the `_id` column, and the JSON serialization in the
+ * `store` column, something like:
+ *
+ * ```
+ * > SELECT * FROM tinybase;
+ * +-----+-----------------------------------------------------+
+ * | _id | store                                               |
+ * +-----+-----------------------------------------------------+
+ * | _   | [{"pets":{"fido":{"species":"dog"}}},{"open":true}] |
+ * +-----+-----------------------------------------------------+
+ * ```
+ *
+ * The 'Dpc' prefix indicates that this type is used within the
+ * DatabasePersisterConfig type.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * and save a JSON serialization from and to a table called `tinybase_json`.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'json',
+ *   storeTableName: 'tinybase_json',
+ * };
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DpcJson = {
+  /**
+   * The mode to be used for persisting the Store to the database, in this case
+   * JSON serialization. See the DpcTabular type for the alternative tabular
+   * mapping mode.
+   */
+  mode: 'json';
+  /**
+   * An optional string which indicates the name of a table in the database
+   * which will be used to serialize the Store content into. It defaults to
+   * `tinybase`.
+   */
+  storeTableName?: string;
+  /**
+   * How often the Persister should poll the database for any changes made to it
+   * by other clients, defaulting to 1 second.
+   */
+  autoLoadIntervalSeconds?: number;
+};
+
+/**
+ * The DpcTabular type describes the configuration of a database-oriented
+ * Persister that is operating in tabular mapping mode.
+ *
+ * It is important to note that both the tabular mapping in ('save') and out
+ * ('load') of an underlying database are disabled by default. This is to ensure
+ * that if you pass in an existing populated database you don't run the
+ * immediate risk of corrupting or losing all your data.
+ *
+ * This configuration therefore takes a `tables` property object (with child
+ * `load` and `save` property objects) and a `values` property object. These
+ * indicate how you want to load and save Tables and Values respectively. At
+ * least one of these two properties are required for the Persister to do
+ * anything!
+ *
+ * Note that if you are planning to both load from and save to a database, it is
+ * important to make sure that the load and save table mappings are symmetrical.
+ * For example:
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   tables: {
+ *     load: {petsInDb: 'pets', speciesInDb: 'species'},
+ *     save: {pets: 'petsInDb', species: 'speciesInDb'},
+ *   },
+ * };
+ * ```
+ *
+ * See the documentation for the DpcTabularLoad, DpcTabularSave, and
+ * DpcTabularValues types for more details on how to configure the tabular
+ * mapping mode.
+ *
+ * The 'Dpc' prefix indicates that this type is used within the
+ * DatabasePersisterConfig type.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * and save Tables data from and to tables specified in the `load` and `save`
+ * mappings, and Values data from and to a table called `my_tinybase_values`.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   tables: {
+ *     load: {petsInDb: 'pets', speciesInDb: 'species'},
+ *     save: {pets: 'petsInDb', species: 'speciesInDb'},
+ *   },
+ *   values: {
+ *     load: true,
+ *     save: true,
+ *     tableName: 'my_tinybase_values',
+ *   },
+ * };
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DpcTabular = {
+  /**
+   * The mode to be used for persisting the Store to the database, in this case
+   * tabular mapping. See the DpcJson type for the alternative JSON
+   * serialization mode.
+   */
+  mode: 'tabular';
+  /**
+   * The settings for how the Store Tables are mapped to and from the database.
+   */
+  tables?: {
+    /**
+     * The settings for how the database tables are mapped into the Store Tables
+     * when loading.
+     */
+    load?: DpcTabularLoad;
+    /**
+     * The settings for how the Store Tables are mapped out to the database
+     * tables when saving.
+     */
+    save?: DpcTabularSave;
+  };
+  /**
+   * The settings for how the Store Values are mapped to and from the database.
+   */
+  values?: DpcTabularValues;
+  /**
+   * How often the Persister should poll the database for any changes made to it
+   * by other clients, defaulting to 1 second.
+   */
+  autoLoadIntervalSeconds?: number;
+};
+
+/**
+ * The DpcTabularLoad type describes the configuration for loading Tables in a
+ * database-oriented Persister that is operating in tabular mode.
+ *
+ * It is an object where each key is a name of a database table, and the value
+ * is a child configuration object for how that table should be loaded into the
+ * Store. The properties of the child configuration object are:
+ *
+ * ||Type|Description|
+ * |-|-|-|
+ * |`tableId`|Id|The Id of the Store Table into which data from this database table should be loaded.|
+ * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used as the Row Ids in the Store Table, defaulting to '_id'.|
+ *
+ * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, you
+ * can simply provide the Id of the Store Table instead of the whole object.
+ *
+ * The 'Dpc' prefix indicates that this type is used within the
+ * DatabasePersisterConfig type.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * the data of two database tables (called 'petsInDb' and 'speciesInDb') into
+ * two Store Tables (called 'pets' and 'species'). One has a column for the Row
+ * Id called 'id' and the other defaults it to '_id'.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   tables: {
+ *     load: {
+ *       petsInDb: {tableId: 'pets', rowIdColumnName: 'id'},
+ *       speciesInDb: 'species',
+ *     },
+ *   },
+ * };
+ * ```
+ *
+ * Imagine database tables that look like this:
+ *
+ * ```
+ * > SELECT * FROM petsInDb;
+ * +-------+---------+-------+
+ * | id    | species | color |
+ * +-------+---------+-------+
+ * | fido  | dog     | brown |
+ * | felix | cat     | black |
+ * +-------+---------+-------+
+ *
+ * > SELECT * FROM speciesInDb;
+ * +------+-------+
+ * | _id  | price |
+ * +------+-------+
+ * | dog  | 5     |
+ * | cat  | 4     |
+ * +------+-------+
+ * ```
+ *
+ * With the configuration above, this will load into a Store with Tables that
+ * look like this:
+ *
+ * ```json
+ * {
+ *   "pets": {
+ *     "fido": {"species": "dog", "color": "brown"},
+ *     "felix": {"species": "cat", "color": "black"},
+ *   },
+ *   "species": {
+ *     "dog": {"price": 5},
+ *     "cat": {"price": 4},
+ *   },
+ * }
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DpcTabularLoad = {
+  [tableName: string]:
+    | {
+        /**
+         * The Id of the Store Table into which data from this database table
+         * should be loaded.
+         */
+        tableId: Id;
+        /**
+         * The optional name of the column in the database table that will be
+         * used as the Row Ids in the Store Table, defaulting to '_id'.
+         */
+        rowIdColumnName?: string;
+      }
+    | Id;
+};
+
+/**
+ * The DpcTabularSave type describes the configuration for saving Tables in a
+ * database-oriented Persister that is operating in tabular mode.
+ *
+ * It is an object where each key is an Id of a Store Table, and the value is a
+ * child configuration object for how that Table should be saved out to the
+ * database. The properties of the child configuration object are:
+ *
+ * ||Type|Description|
+ * |-|-|-|
+ * |`tableName`|string|The name of the database table out to which the Store Table should be saved.|
+ * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used to save the Row Ids from the Store Table, defaulting to '_id'.|
+ * |`deleteEmptyColumns?`|boolean|Whether columns in the database table will be removed if they are empty in the Store Table, defaulting to false.|
+ * |`deleteEmptyTable?`|boolean|Whether tables in the database will be removed if the Store Table is empty, defaulting to false.|
+ *
+ * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, or
+ * enable the `deleteEmptyColumns` or `deleteEmptyTable` settings, you can
+ * simply provide the name of the database table instead of the whole object.
+ *
+ * The 'Dpc' prefix indicates that this type is used within the
+ * DatabasePersisterConfig type.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will save
+ * the data of two Store Tables (called 'pets' and 'species') into two database
+ * tables (called 'petsInDb' and 'speciesInDb'). One has a column for the Row
+ * Id called 'id' and will delete columns and the whole table if empty, the
+ * other defaults to '_id' and will not delete columns or the whole table if
+ * empty.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   tables: {
+ *     save: {
+ *       pets: {
+ *         tableName: 'petsInDb',
+ *         deleteEmptyColumns: true,
+ *         deleteEmptyTable: true,
+ *       },
+ *       species: 'speciesInDb',
+ *     },
+ *   },
+ * };
+ * ```
+ *
+ * Imagine a Store with Tables that look like this:
+ *
+ * ```json
+ * {
+ *   "pets": {
+ *     "fido": {"species": "dog", "color": "brown"},
+ *     "felix": {"species": "cat", "color": "black"},
+ *   },
+ *   "species": {
+ *     "dog": {"price": 5},
+ *     "cat": {"price": 4},
+ *   },
+ * }
+ * ```
+ *
+ * With the configuration above, this will save out to a database with tables
+ * that look like this:
+ *
+ * ```
+ * > SELECT * FROM petsInDb;
+ * +-------+---------+-------+
+ * | id    | species | color |
+ * +-------+---------+-------+
+ * | fido  | dog     | brown |
+ * | felix | cat     | black |
+ * +-------+---------+-------+
+ *
+ * > SELECT * FROM speciesInDb;
+ * +------+-------+
+ * | _id  | price |
+ * +------+-------+
+ * | dog  | 5     |
+ * | cat  | 4     |
+ * +------+-------+
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DpcTabularSave = {
+  [tableId: Id]:
+    | {
+        /**
+         * The name of the database table out to which the Store Table should be
+         * saved.
+         */
+        tableName: string;
+        /**
+         * The optional name of the column in the database table that will be
+         * used to save the Row Ids from the Store Table, defaulting to '_id'.
+         */
+        rowIdColumnName?: string;
+        /**
+         * Whether columns in the database table will be removed if they are
+         * empty in the Store Table, defaulting to false.
+         */
+        deleteEmptyColumns?: boolean;
+        /**
+         * Whether tables in the database will be removed if the Store Table
+         * is empty, defaulting to false.
+         */
+        deleteEmptyTable?: boolean;
+      }
+    | string;
+};
+
+/**
+ * The DpcTabularValues type describes the configuration for handling Values in
+ * a database-oriented Persister that is operating in tabular mode.
+ *
+ * Note that both loading and saving of Values from and to the database are
+ * disabled by default.
+ *
+ * The 'Dpc' prefix indicates that this type is used within the
+ * DatabasePersisterConfig type.
+ * @example
+ * When applied to a database Persister, this DatabasePersisterConfig will load
+ * and save the data of a Store's Values into a database
+ * table called 'my_tinybase_values'.
+ *
+ * ```js
+ * const databasePersisterConfig: DatabasePersisterConfig = {
+ *   mode: 'tabular',
+ *   values: {
+ *     load: true,
+ *     save: true,
+ *     tableName: 'my_tinybase_values',
+ *   },
+ * };
+ * ```
+ * @category Configuration
+ * @since v4.0.0
+ */
+export type DpcTabularValues = {
+  /**
+   * Whether Store Values will be loaded from a database table.
+   */
+  load?: boolean;
+  /**
+   * Whether Store Values will be saved to a database table.
+   */
+  save?: boolean;
+  /**
+   * The optional name of the database table from and to which the Store Table
+   * should be loaded or saved, defaulting to `tinybase_values`.
+   */
+  tableName?: string;
+};
+
 /**
  * A Persister object lets you save and load Store data to and from different
  * locations, or underlying storage types.
@@ -113,7 +569,6 @@ export type PersisterListener = (
  * 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
@@ -181,7 +636,6 @@ export interface Persister {
    * 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.
    * @param initialValues An optional Values object used when the underlying
@@ -249,7 +703,6 @@ export interface Persister {
    * 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.
    * @param initialValues An optional Values object used when the underlying
@@ -294,7 +747,6 @@ export interface Persister {
    *
    * 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
@@ -341,7 +793,6 @@ export interface Persister {
    * 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
@@ -374,7 +825,6 @@ export interface Persister {
    * 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
@@ -406,7 +856,6 @@ export interface Persister {
    *
    * 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
@@ -438,10 +887,52 @@ export interface Persister {
    */
   stopAutoSave(): Persister;
 
+  /**
+   * The schedule method allows you to queue up a series of asynchronous actions
+   * that must run in sequence during persistence.
+   *
+   * For example, a database Persister may need to ensure that multiple
+   * asynchronous tasks to check and update the database schema are completed
+   * before data is written to it. Therefore it's most likely you will be using
+   * this method inside your `setPersisted` implementation.
+   *
+   * Call this method to add a single asynchronous action, or a sequence of them
+   * in one call. This will also start to run the first task in the queue (which
+   * once complete will then run the next, and so on), and so this method itself
+   * is also asynchronous and returns a promise of the Persister.
+   * @returns A reference to the Persister object.
+   * @example
+   * This example creates a custom Persister object against a newly-created
+   * Store and then sequences two tasks in order to update its data on a
+   * hypothetical remote system.
+   *
+   * ```js yolo
+   * const store = createStore();
+   * const persister = createCustomPersister(
+   *   store,
+   *   async () => {
+   *     // getPersisted
+   *     return await getDataFromRemoteSystem();
+   *   },
+   *   async (getContent) => {
+   *     // setPersisted
+   *     await persister.schedule(
+   *       async () => await checkRemoteSystemIsReady(),
+   *       async () => await sendDataToRemoteSystem(getContent()),
+   *     );
+   *   },
+   *   (listener) => setInterval(listener, 1000),
+   *   (interval) => clearInterval(interval),
+   * );
+   * ```
+   * @category Lifecycle
+   * @since v4.0.0
+   */
+  schedule(...actions: Promise<any>[]): Promise<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
@@ -470,7 +961,6 @@ export interface Persister {
    * 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
@@ -504,7 +994,6 @@ export interface Persister {
    * 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
@@ -561,7 +1050,6 @@ export interface Persister {
  * function must return the content (or nothing) rather than JSON.
  * `startListeningToPersisted` has been renamed `addPersisterListener`, and
  * `stopListeningToPersisted` has been renamed `delPersisterListener`.
- *
  * @param store The Store to persist.
  * @param getPersisted An asynchronous function which will fetch content from
  * the persistence layer (or `undefined` if not present).
@@ -588,11 +1076,13 @@ export interface Persister {
  * const persister = createCustomPersister(
  *   store,
  *   async () => {
- *     try {
- *       return JSON.parse(storeJson);
- *     } catch {}
+ *     // getPersisted
+ *     return JSON.parse(storeJson);
+ *   },
+ *   async (getContent) => {
+ *     // setPersisted
+ *     storeJson = JSON.stringify(getContent());
  *   },
- *   async (getContent) => (storeJson = JSON.stringify(getContent())),
  *   (listener) => setInterval(listener, 1000),
  *   (interval) => clearInterval(interval),
  * );