tinybase 5.0.0-beta.25 → 5.0.0-beta.27

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

@@ -1,30 +1,34 @@
 /**
  * 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.
+ * saving and loading Store and MergeableStore 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)|
+ * |Module|Function|Storage|Store|MergeableStore
+ * |-|-|-|-|-|
+ * |persister-browser|createSessionPersister|Browser session storage|Yes|Yes
+ * |persister-browser|createLocalPersister|Browser local storage|Yes|Yes
+ * |persister-file|createFilePersister|Local file (where possible)|Yes|Yes
+ * |persister-sqlite3|createSqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|Yes|Yes*
+ * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|Yes|Yes*
+ * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|Yes|Yes*
+ * |persister-indexed-db|createIndexedDbPersister|Browser IndexedDB|Yes|No
+ * |persister-remote|createRemotePersister|Remote server|Yes|No
+ * |persister-partykit-client|createPartyKitPersister|PartyKit with the persister-partykit-server module|Yes|No
+ * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|Yes|No
+ * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|Yes|No
+ * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|Yes|No
+ * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|Yes|No
+ * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|Yes|No
+ * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|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
@@ -48,52 +52,107 @@ import type {
 import type {Id} from '../common/index.d.ts';
 
 /**
- * The StoreTypes type
+ * The Persists enum is used to indicate whether a Persister can support a
+ * regular Store, a MergeableStore, or both.
+ *
+ * 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 type StoreTypes =
-  | 1 // Store only
-  | 2 // MergeableStore only
-  | 3; // Store and MergeableStore
+export const enum Persists {
+  /**
+   * Indicates that only a regular Store can be supported by a Persister.
+   */
+  StoreOnly = 1,
+  /**
+   * Indicates that only a MergeableStore can be supported by a Persister.
+   */
+  MergeableStoreOnly = 2,
+  /**
+   * Indicates that either a regular Store or a MergeableStore can be supported
+   * by a Persister.
+   */
+  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
  */
-export type PersistedStore<StoreType extends StoreTypes = 1> =
-  StoreType extends 3
+export type PersistedStore<Persist extends Persists = Persists.StoreOnly> =
+  Persist extends Persists.StoreOrMergeableStore
     ? Store | MergeableStore
-    : StoreType extends 2
+    : Persist extends Persists.MergeableStoreOnly
       ? MergeableStore
       : 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
  */
-export type PersistedContent<StoreType extends StoreTypes = 1> =
-  StoreType extends 3
+export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
+  Persist extends Persists.StoreOrMergeableStore
     ? Content | MergeableContent
-    : StoreType extends 2
+    : Persist extends Persists.MergeableStoreOnly
       ? MergeableContent
       : 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
  */
-export type PersistedChanges<StoreType extends StoreTypes = 1> =
-  StoreType extends 3
+export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
+  Persist extends Persists.StoreOrMergeableStore
     ? Changes | MergeableChanges
-    : StoreType extends 2
+    : Persist extends Persists.MergeableStoreOnly
       ? MergeableChanges
       : 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
@@ -102,17 +161,16 @@ export type PersistedChanges<StoreType extends StoreTypes = 1> =
  * @category Creation
  * @since v4.0.0
  */
-export type PersisterListener<StoreType extends StoreTypes = 1> = (
-  content?: PersistedContent<StoreType>,
-  changes?: PersistedChanges<StoreType>,
+export type PersisterListener<Persist extends Persists = Persists.StoreOnly> = (
+  content?: PersistedContent<Persist>,
+  changes?: PersistedChanges<Persist>,
 ) => void;
 
 /**
  * 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.
+ * A PersisterStats object is returned from the getStats method.
  * @category Development
  */
 export type PersisterStats = {
@@ -200,7 +258,7 @@ export type DatabasePersisterConfig = DpcJson | DpcTabular;
  * called `_id`, and one called `store`. (These column names can be changed
  * using the `rowIdColumnName` and `storeColumnName` settings). 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:
+ * JSON serialization in the `store` column, something like the following.
  *
  * ```
  * > SELECT * FROM tinybase;
@@ -262,6 +320,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
@@ -275,7 +338,7 @@ export type DpcJson = {
  *
  * 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:
+ * For example, consider the following.
  *
  * ```js
  * import type {DatabasePersisterConfig} from 'tinybase';
@@ -556,8 +619,8 @@ export type DpcTabularSave = {
          */
         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.
          */
         deleteEmptyTable?: boolean;
       }
@@ -613,15 +676,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
@@ -717,7 +787,7 @@ export type DpcTabularValues = {
  * ```
  * @category Persister
  */
-export interface Persister<StoreType extends StoreTypes = 1> {
+export interface Persister<Persist extends Persists = Persists.StoreOnly> {
   //
   /**
    * The load method gets persisted data from storage, and loads it into the
@@ -1109,9 +1179,9 @@ export interface Persister<StoreType extends StoreTypes = 1> {
   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.
@@ -1132,7 +1202,7 @@ export interface Persister<StoreType extends StoreTypes = 1> {
    * ```
    * @category Getter
    */
-  getStore(): PersistedStore<StoreType>;
+  getStore(): PersistedStore<Persist>;
 
   /**
    * The destroy method should be called when this Persister object is no longer
@@ -1174,10 +1244,8 @@ export interface Persister<StoreType extends StoreTypes = 1> {
    * 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.
+   * 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
@@ -1255,41 +1323,43 @@ export interface Persister<StoreType extends StoreTypes = 1> {
  * @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 supportedStoreType 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());
@@ -1297,22 +1367,91 @@ export interface Persister<StoreType extends StoreTypes = 1> {
  *
  * 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
  */
 export function createCustomPersister<
   ListeningHandle,
-  StoreType extends StoreTypes = 1,
+  Persist extends Persists = Persists.StoreOnly,
 >(
-  store: PersistedStore<StoreType>,
-  getPersisted: () => Promise<PersistedContent<StoreType> | undefined>,
+  store: PersistedStore<Persist>,
+  getPersisted: () => Promise<PersistedContent<Persist> | undefined>,
   setPersisted: (
-    getContent: () => PersistedContent<StoreType>,
-    changes?: PersistedChanges<StoreType>,
+    getContent: () => PersistedContent<Persist>,
+    changes?: PersistedChanges<Persist>,
   ) => Promise<void>,
   addPersisterListener: (
-    listener: PersisterListener<StoreType>,
+    listener: PersisterListener<Persist>,
   ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-  supportedStoreType?: StoreType,
-): Persister<StoreType>;
+  persist?: Persist,
+): Persister<Persist>;

package/@types/persisters/persister-automerge/index.d.cts

@@ -1,6 +1,6 @@
 /**
  * The persister-automerge module of the TinyBase project provides a way to save
- * and load Store data, to and from an Automerge document.
+ * and load Store data to and from an Automerge document.
  *
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
@@ -16,11 +16,12 @@ import type {Persister} from '../index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
 /**
- * The AutomergePersister interface is a minor extension to the Persister
- * interface.
+ * The AutomergePersister interface represents a Persister that lets you save
+ * and load Store data to and from an Automerge document.
  *
- * It simply provides an extra getDocHandle method for accessing the Automerge
- * document handler the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDocHandle method for accessing the Automerge document handler the
+ * Store is being persisted to.
  *
  * You should use the createAutomergePersister function to create an
  * AutomergePersister object.
@@ -57,8 +58,11 @@ export interface AutomergePersister extends Persister {
 }
 
 /**
- * The createAutomergePersister function creates a Persister object that can
- * persist the Store to an Automerge document.
+ * The createAutomergePersister function creates an AutomergePersister object
+ * that can persist the Store to an Automerge document.
+ *
+ * An AutomergePersister only supports regular Store objects, and cannot be used
+ * to persist the metadata of a MergeableStore.
  *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.

package/@types/persisters/persister-automerge/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * The persister-automerge module of the TinyBase project provides a way to save
- * and load Store data, to and from an Automerge document.
+ * and load Store data to and from an Automerge document.
  *
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
@@ -16,11 +16,12 @@ import type {Persister} from '../index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
 /**
- * The AutomergePersister interface is a minor extension to the Persister
- * interface.
+ * The AutomergePersister interface represents a Persister that lets you save
+ * and load Store data to and from an Automerge document.
  *
- * It simply provides an extra getDocHandle method for accessing the Automerge
- * document handler the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDocHandle method for accessing the Automerge document handler the
+ * Store is being persisted to.
  *
  * You should use the createAutomergePersister function to create an
  * AutomergePersister object.
@@ -57,8 +58,11 @@ export interface AutomergePersister extends Persister {
 }
 
 /**
- * The createAutomergePersister function creates a Persister object that can
- * persist the Store to an Automerge document.
+ * The createAutomergePersister function creates an AutomergePersister object
+ * that can persist the Store to an Automerge document.
+ *
+ * An AutomergePersister only supports regular Store objects, and cannot be used
+ * to persist the metadata of a MergeableStore.
  *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.

package/@types/persisters/persister-automerge/with-schemas/index.d.cts

@@ -1,6 +1,6 @@
 /**
  * The persister-automerge module of the TinyBase project provides a way to save
- * and load Store data, to and from an Automerge document.
+ * and load Store data to and from an Automerge document.
  *
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
@@ -19,11 +19,12 @@ import type {DocHandle} from '@automerge/automerge-repo';
 import type {Persister} from '../../with-schemas/index.d.cts';
 
 /**
- * The AutomergePersister interface is a minor extension to the Persister
- * interface.
+ * The AutomergePersister interface represents a Persister that lets you save
+ * and load Store data to and from an Automerge document.
  *
- * It simply provides an extra getDocHandle method for accessing the Automerge
- * document handler the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDocHandle method for accessing the Automerge document handler the
+ * Store is being persisted to.
  *
  * You should use the createAutomergePersister function to create an
  * AutomergePersister object.
@@ -61,8 +62,8 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createAutomergePersister function creates a Persister object that can
- * persist the Store to an Automerge document.
+ * The createAutomergePersister function creates an AutomergePersister object
+ * that can persist the Store to an Automerge document.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -75,6 +76,9 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * ): AutomergePersister;
  * ```
  *
+ * An AutomergePersister only supports regular Store objects, and cannot be used
+ * to persist the metadata of a MergeableStore.
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.
  * @param store The Store to persist.

package/@types/persisters/persister-automerge/with-schemas/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * The persister-automerge module of the TinyBase project provides a way to save
- * and load Store data, to and from an Automerge document.
+ * and load Store data to and from an Automerge document.
  *
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
@@ -19,11 +19,12 @@ import type {DocHandle} from '@automerge/automerge-repo';
 import type {Persister} from '../../with-schemas/index.d.ts';
 
 /**
- * The AutomergePersister interface is a minor extension to the Persister
- * interface.
+ * The AutomergePersister interface represents a Persister that lets you save
+ * and load Store data to and from an Automerge document.
  *
- * It simply provides an extra getDocHandle method for accessing the Automerge
- * document handler the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDocHandle method for accessing the Automerge document handler the
+ * Store is being persisted to.
  *
  * You should use the createAutomergePersister function to create an
  * AutomergePersister object.
@@ -61,8 +62,8 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createAutomergePersister function creates a Persister object that can
- * persist the Store to an Automerge document.
+ * The createAutomergePersister function creates an AutomergePersister object
+ * that can persist the Store to an Automerge document.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -75,6 +76,9 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * ): AutomergePersister;
  * ```
  *
+ * An AutomergePersister only supports regular Store objects, and cannot be used
+ * to persist the metadata of a MergeableStore.
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.
  * @param store The Store to persist.