tinybase 5.0.0-beta.26 → 5.0.0-beta.28

package/@types/persisters/index.d.cts

@@ -1,42 +1,46 @@
 /**
  * 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 (in separately installed modules), each of
- * 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.
- *
- * |Module|Function|Storage|
- * |-|-|-|
- * |persister-browser|createSessionPersister|Browser session storage|
- * |persister-browser|createLocalPersister|Browser local storage|
- * |persister-indexed-db|createIndexedDbPersister|Browser IndexedDB|
- * |persister-remote|createRemotePersister|Remote server|
- * |persister-file|createFilePersister|Local file (where possible)|
- * |persister-partykit-client|createPartyKitPersister|PartyKit with the persister-partykit-server module|
- * |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-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
- * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|
- * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|
- * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|
- * |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)|
+ * saving and loading Store and MergeableStore data, to and from different
+ * destinations, or underlying storage types.
+ *
+ * Many entry points are provided (in separately installed modules), each of
+ * which returns different types of Persister 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.
+ *
+ * |Persister|Storage|Store|MergeableStore
+ * |-|-|-|-|
+ * |SessionPersister|Browser session storage|Yes|Yes
+ * |LocalPersister|Browser local storage|Yes|Yes
+ * |FilePersister|Local file (where possible)|Yes|Yes
+ * |IndexedDbPersister|Browser IndexedDB|Yes|No
+ * |RemotePersister|Remote server|Yes|No
+ * |Sqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|Yes|Yes*
+ * |SqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|Yes|Yes*
+ * |ExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|Yes|Yes*
+ * |CrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|Yes|No
+ * |ElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|Yes|No
+ * |LibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|Yes|No
+ * |PowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|Yes|No
+ * |YjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|Yes|No
+ * |SqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|Yes|No
+ * |PartyKitPersister|[PartyKit](https://www.partykit.io/), via the persister-partykit-server module|Yes|No|
+ *
+ * (*) Note that SQLite-based Persisters can currently only persist
+ * MergeableStore data when using the JSON-based DpcJson mode, and not in a
+ * tabular fashion.
  *
  * 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 Persistence guides
  * @see Countries demo
  * @see Todo App demos
  * @see Drawing demo
  * @packageDocumentation
  * @module persisters
+ * @since v1.0.0
  */
 
 import type {Changes, Content, Store} from '../store/index.d.cts';
@@ -48,29 +52,50 @@ import type {
 import type {Id} from '../common/index.d.cts';
 
 /**
- * The Persists enum.
+ * The Persists enum is used to indicate whether a Persister can support a
+ * regular Store, a MergeableStore, or both.
  *
- * This is used to indicate what types of Store a Persister can support.
+ * The enum is intended to be used by the author of a Persister to indicate
+ * which types of store can be persisted. If you discover type errors when
+ * trying to instantiate a Persister, it is most likely that you are passing in
+ * an unsupported type of store.
+ *
+ * See the createCustomPersister method for an example of this enum being used.
  * @category Mergeable
  * @since v5.0.0
  */
 export const enum Persists {
   /**
-   * The StoreOnly enum value.
+   * Indicates that only a regular Store can be supported by a Persister.
+   * @category Enum
+   * @since v5.0.0
    */
   StoreOnly = 1,
   /**
-   * The MergeableStoreOnly enum value.
+   * Indicates that only a MergeableStore can be supported by a Persister.
+   * @category Enum
+   * @since v5.0.0
    */
   MergeableStoreOnly = 2,
   /**
-   * The StoreOrMergeableStore enum value.
+   * Indicates that either a regular Store or a MergeableStore can be supported
+   * by a Persister.
+   * @category Enum
+   * @since v5.0.0
    */
   StoreOrMergeableStore = 3,
 }
 
 /**
- * The PersistedStore type.
+ * The PersistedStore type is a generic representation of the type of store
+ * being handled by a Persister.
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling a regular Store, a MergeableStore, or
+ * either.
+ *
+ * If the generic parameter is unspecified, the StoreOnly enum value is used,
+ * meaning that PersistedStore is equivalent to a regular Store.
  * @category Mergeable
  * @since v5.0.0
  */
@@ -82,7 +107,16 @@ export type PersistedStore<Persist extends Persists = Persists.StoreOnly> =
       : Store;
 
 /**
- * The PersistedContent type.
+ * The PersistedContent type is a generic representation of the content in the
+ * type of store being handled by a Persister.
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling content from a regular Store (the Content
+ * type), a MergeableStore (the MergeableContent type), or either (the union of
+ * the two).
+ *
+ * If the generic parameter is unspecified, the StoreOnly enum value is used,
+ * meaning that PersistedContent is equivalent to the Content type.
  * @category Mergeable
  * @since v5.0.0
  */
@@ -94,7 +128,13 @@ export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
       : Content;
 
 /**
- * The PersistedChanges type.
+ * The PersistedChanges type is a generic representation of changes made to the
+ * type of store being handled by a Persister.
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling changes for a regular Store (the Changes
+ * type), a MergeableStore (the MergeableChanges type), or either (the union of
+ * the two).
  * @category Mergeable
  * @since v5.0.0
  */
@@ -106,14 +146,19 @@ export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
       : Changes;
 
 /**
- * A PersisterListener is a callback that lets a Persister inform the Store that
- * a change has happened to the underlying data.
+ * A PersisterListener is a generic representation of the callback that lets a
+ * Persister inform the store that a change has happened to the underlying data.
+ *
+ * Using the values of the Persists enum, the generic parameter indicates
+ * whether the Persister is handling content and changes from a regular Store, a
+ * MergeableStore, or either.
  *
  * If the listener is called with the `changes` parameter, it will be used to
  * make an incremental change to the Store. If not, but the `content` parameter
  * is available, that will be used to make a wholesale change to the Store. If
  * neither are present, the content will be loaded using the Persister's load
- * method. Prior to v5.0, these parameters were callbacks.
+ * method. Prior to v5.0, these parameters were callbacks and the overall type
+ * was non-generic.
  * @param content If provided, this is a Content object from the the Persister
  * that will be used to immediately wholesale update the Store.
  * @param changes If provided, this is a Changes object from the the Persister
@@ -133,14 +178,19 @@ export type PersisterListener<Persist extends Persists = Persists.StoreOnly> = (
  *
  * A PersisterStats object is returned from the getStats method.
  * @category Development
+ * @since v1.0.0
  */
 export type PersisterStats = {
   /**
    * The number of times data has been loaded.
+   * @category Stat
+   * @since v1.0.0
    */
   loads: number;
   /**
    * The number of times data has been saved.
+   * @category Stat
+   * @since v1.0.0
    */
   saves: number;
 };
@@ -252,27 +302,37 @@ 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.
+   * @category Configuration
+   * @since v4.0.0
    */
   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`.
+   * @category Configuration
+   * @since v4.0.0
    */
   storeTableName?: string;
   /**
    * The optional name of the column in the database table that will be used as
    * the Id for the Store, defaulting to '_id', since v5.0.
+   * @category Configuration
+   * @since v4.0.0
    */
   storeIdColumnName?: string;
   /**
    * The optional name of the column in the database table that will be used for
    * the JSON of the Store, defaulting to 'store', since v5.0.
+   * @category Configuration
+   * @since v4.0.0
    */
   storeColumnName?: string;
   /**
    * How often the Persister should poll the database for any changes made to it
    * by other clients, defaulting to 1 second.
+   * @category Configuration
+   * @since v4.0.0
    */
   autoLoadIntervalSeconds?: number;
 };
@@ -281,6 +341,11 @@ export type DpcJson = {
  * The DpcTabular type describes the configuration of a database-oriented
  * Persister that is operating in tabular mapping mode.
  *
+ * This configuration can only be used when the Persister is persisting a
+ * regular Store. For those database-oriented Persister types that support
+ * MergeableStore data, you will need to use JSON-serialization, es described
+ * in the DpcJson section.
+ *
  * 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
@@ -343,30 +408,42 @@ 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.
+   * @category Configuration
+   * @since v4.0.0
    */
   mode: 'tabular';
   /**
    * The settings for how the Store Tables are mapped to and from the database.
+   * @category Configuration
+   * @since v4.0.0
    */
   tables?: {
     /**
      * The settings for how the database tables are mapped into the Store Tables
      * when loading.
+     * @category Configuration
+     * @since v4.0.0
      */
     load?: DpcTabularLoad;
     /**
      * The settings for how the Store Tables are mapped out to the database
      * tables when saving.
+     * @category Configuration
+     * @since v4.0.0
      */
     save?: DpcTabularSave;
   };
   /**
    * The settings for how the Store Values are mapped to and from the database.
+   * @category Configuration
+   * @since v4.0.0
    */
   values?: DpcTabularValues;
   /**
    * How often the Persister should poll the database for any changes made to it
    * by other clients, defaulting to 1 second.
+   * @category Configuration
+   * @since v4.0.0
    */
   autoLoadIntervalSeconds?: number;
 };
@@ -453,11 +530,15 @@ export type DpcTabularLoad = {
         /**
          * The Id of the Store Table into which data from this database table
          * should be loaded.
+         * @category Configuration
+         * @since v4.0.0
          */
         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'.
+         * @category Configuration
+         * @since v4.0.0
          */
         rowIdColumnName?: string;
       }
@@ -562,21 +643,29 @@ export type DpcTabularSave = {
         /**
          * The name of the database table out to which the Store Table should be
          * saved.
+         * @category Configuration
+         * @since v4.0.0
          */
         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'.
+         * @category Configuration
+         * @since v4.0.0
          */
         rowIdColumnName?: string;
         /**
          * Whether columns in the database table will be removed if they are
          * empty in the Store Table, defaulting to false.
+         * @category Configuration
+         * @since v4.0.0
          */
         deleteEmptyColumns?: boolean;
         /**
-         * Whether tables in the database will be removed if the Store Table
-         * is empty, defaulting to false.
+         * Whether tables in the database will be removed if the Store Table is
+         * empty, defaulting to false.
+         * @category Configuration
+         * @since v4.0.0
          */
         deleteEmptyTable?: boolean;
       }
@@ -615,15 +704,21 @@ export type DpcTabularSave = {
 export type DpcTabularValues = {
   /**
    * Whether Store Values will be loaded from a database table.
+   * @category Configuration
+   * @since v4.0.0
    */
   load?: boolean;
   /**
    * Whether Store Values will be saved to a database table.
+   * @category Configuration
+   * @since v4.0.0
    */
   save?: boolean;
   /**
    * The optional name of the database table from and to which the Store Values
    * should be loaded or saved, defaulting to `tinybase_values`.
+   * @category Configuration
+   * @since v4.0.0
    */
   tableName?: string;
 };
@@ -632,15 +727,22 @@ export type DpcTabularValues = {
  * 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.
+ * This is useful for preserving Store or MergeableStore 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 function, 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.
+ * the createFilePersister function, as just simple examples. The
+ * createCustomPersister function can also be used to easily create a fully
+ * customized way to save and load Store data.
+ *
+ * Using the values of the Persists enum, the generic parameter to the Persister
+ * indicates whether it can handle a regular Store, a MergeableStore, or either.
+ * Consult the table in the overall persisters module documentation to see
+ * current support for each. The different levels of support are also described
+ * for each of the types of Persister themselves.
  *
  * 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
@@ -735,6 +837,7 @@ export type DpcTabularValues = {
  * sessionStorage.clear();
  * ```
  * @category Persister
+ * @since v1.0.0
  */
 export interface Persister<Persist extends Persists = Persists.StoreOnly> {
   //
@@ -800,6 +903,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Load
+   * @since v1.0.0
    */
   load(initialContent?: Content): Promise<this>;
 
@@ -856,6 +960,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Load
+   * @since v1.0.0
    */
   startAutoLoad(initialContent?: Content): Promise<this>;
 
@@ -903,6 +1008,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Load
+   * @since v1.0.0
    */
   stopAutoLoad(): this;
 
@@ -964,6 +1070,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Save
+   * @since v1.0.0
    */
   save(): Promise<this>;
 
@@ -1004,6 +1111,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Save
+   * @since v1.0.0
    */
   startAutoSave(): Promise<this>;
 
@@ -1044,6 +1152,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Save
+   * @since v1.0.0
    */
   stopAutoSave(): this;
 
@@ -1128,9 +1237,9 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
   schedule(...actions: Promise<any>[]): Promise<this>;
 
   /**
-   * The getStore method returns a reference to the underlying Store that is
-   * backing this Persister object.
-   * @returns A reference to the Store.
+   * The getStore method returns a reference to the underlying Store or
+   * MergeableStore that is backing this Persister object.
+   * @returns A reference to the Store or MergeableStore.
    * @example
    * This example creates a Persister object against a newly-created Store and
    * then gets its reference in order to update its data.
@@ -1150,6 +1259,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Getter
+   * @since v1.0.0
    */
   getStore(): PersistedStore<Persist>;
 
@@ -1183,6 +1293,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * // -> 0
    * ```
    * @category Lifecycle
+   * @since v1.0.0
    */
   destroy(): this;
 
@@ -1228,6 +1339,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * sessionStorage.clear();
    * ```
    * @category Development
+   * @since v1.0.0
    */
   getStats(): PersisterStats;
   //
@@ -1272,41 +1384,43 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  * @param onIgnoredError 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.
- * @param persistable Since v5.0, an optional integer to indicate which types of
- * Store are supported by this Persister: `1` indicates only a regular Store is
- * supported, `2` indicates only a MergeableStore is supported, and `3`
- * indicates that both Store and MergeableStore are supported.
+ * @param persist Since v5.0, an optional integer from the Persists enum to
+ * indicate which types of Store are supported by this Persister: `1` indicates
+ * only a regular Store is supported, `2` indicates only a MergeableStore is
+ * supported, and `3` indicates that both Store and MergeableStore are
+ * supported.
  * @returns A reference to the new Persister object.
  * @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.
+ * This example creates a custom Persister object and persists a Store to a
+ * local string called `persistedJson` and which would automatically load by
+ * polling for changes every second. It implicitly supports only a regular
+ * Store.
  *
  * ```js
  * import {createCustomPersister, createStore} from 'tinybase';
  *
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * let storeJson;
+ * let persistedJson;
  *
  * const persister = createCustomPersister(
  *   store,
  *   async () => {
  *     // getPersisted
- *     return JSON.parse(storeJson);
+ *     return JSON.parse(persistedJson);
  *   },
  *   async (getContent) => {
  *     // setPersisted
- *     storeJson = JSON.stringify(getContent());
+ *     persistedJson = JSON.stringify(getContent());
  *   },
  *   (listener) => setInterval(listener, 1000),
  *   (interval) => clearInterval(interval),
  * );
  *
  * await persister.save();
- * console.log(storeJson);
+ * console.log(persistedJson);
  * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
  *
- * storeJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
+ * persistedJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
  * await persister.load();
  *
  * console.log(store.getTables());
@@ -1314,7 +1428,77 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  *
  * persister.destroy();
  * ```
+ * @example
+ * This example demonstrates a Persister creation function which returns a
+ * Persister. This can persists a store to a local string called `persistedJson`
+ * and which would automatically load by polling for changes every second.
+ * It emits warnings to the console and explicitly supports either a Store or a
+ * MergeableStore.
+ *
+ * ```js
+ * import {
+ *   Persists,
+ *   createCustomPersister,
+ *   createMergeableStore,
+ *   createStore,
+ * } from 'tinybase';
+ *
+ * let persistedJson;
+ * const createJsonPersister = (storeOrMergeableStore) =>
+ *   createCustomPersister(
+ *     storeOrMergeableStore,
+ *     async () => {
+ *       // getPersisted
+ *       return JSON.parse(persistedJson);
+ *     },
+ *     async (getContent) => {
+ *       // setPersisted
+ *       persistedJson = JSON.stringify(getContent());
+ *     },
+ *     (listener) => setInterval(listener, 1000),
+ *     (interval) => clearInterval(interval),
+ *     console.warn,
+ *     Persists.StoreOrMergeableStore,
+ *   );
+ *
+ * const store = createStore();
+ * store.setTables({pets: {fido: {species: 'dog'}}});
+ * const storePersister = createJsonPersister(store);
+ * await storePersister.save();
+ * console.log(persistedJson);
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ * storePersister.destroy();
+ *
+ * const mergeableStore = createMergeableStore('mergeableStore1'); // !resetHlc
+ * mergeableStore.setTables({pets: {fido: {species: 'dog'}}});
+ * const mergeableStorePersister = createJsonPersister(mergeableStore);
+ * await mergeableStorePersister.save();
+ * console.log(JSON.parse(persistedJson));
+ * // ->
+ * [
+ *   [
+ *     {
+ *       pets: [
+ *         {
+ *           fido: [
+ *             {species: ['dog', 'Nn1JUF-----Zjl0M', 4176151067]},
+ *             '',
+ *             2722999044,
+ *           ],
+ *         },
+ *         '',
+ *         3367164653,
+ *       ],
+ *     },
+ *     '',
+ *     30627183,
+ *   ],
+ *   [{}, '', 0],
+ * ];
+ * mergeableStorePersister.destroy();
+ * ```
  * @category Creation
+ * @since v1.0.0
  */
 export function createCustomPersister<
   ListeningHandle,
@@ -1331,5 +1515,5 @@ export function createCustomPersister<
   ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-  persistable?: Persist,
+  persist?: Persist,
 ): Persister<Persist>;