tinybase 5.0.0-beta.26 → 5.0.0-beta.27

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

@@ -28,11 +28,12 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
 import type {SQLiteDatabase} from 'expo-sqlite';
 
 /**
- * The ExpoSqlitePersister interface is a minor extension to the Persister
- * interface.
+ * The ExpoSqlitePersister interface represents a Persister that lets you save
+ * and load Store data to and from a Expo-SQLite database.
  *
- * It simply provides an extra getDb method for accessing a reference to the
- * database instance the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database instance the
+ * Store is being persisted to.
  *
  * You should use the createExpoSqlitePersister function to create an
  * ExpoSqlitePersister object.
@@ -70,9 +71,8 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createExpoSqlitePersister function creates a Persister object that can
- * persist the Store to a local Expo-SQLite database (in an appropriate React
- * Native environment).
+ * The createExpoSqlitePersister function creates an ExpoSqlitePersister object
+ * that can persist the Store to a local Expo-SQLite database.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -86,6 +86,10 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
  * ): ExpoSqlitePersister;
  * ```
  *
+ * An ExpoSqlitePersister supports regular Store objects, and can also be used
+ * to persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
  * Note that this Persister is currently experimental as Expo themselves iterate
  * on the underlying database library API.
  *
@@ -103,7 +107,7 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

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

@@ -28,11 +28,12 @@ import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d
 import type {SQLiteDatabase} from 'expo-sqlite';
 
 /**
- * The ExpoSqlitePersister interface is a minor extension to the Persister
- * interface.
+ * The ExpoSqlitePersister interface represents a Persister that lets you save
+ * and load Store data to and from a Expo-SQLite database.
  *
- * It simply provides an extra getDb method for accessing a reference to the
- * database instance the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database instance the
+ * Store is being persisted to.
  *
  * You should use the createExpoSqlitePersister function to create an
  * ExpoSqlitePersister object.
@@ -70,9 +71,8 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createExpoSqlitePersister function creates a Persister object that can
- * persist the Store to a local Expo-SQLite database (in an appropriate React
- * Native environment).
+ * The createExpoSqlitePersister function creates an ExpoSqlitePersister object
+ * that can persist the Store to a local Expo-SQLite database.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -86,6 +86,10 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
  * ): ExpoSqlitePersister;
  * ```
  *
+ * An ExpoSqlitePersister supports regular Store objects, and can also be used
+ * to persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
  * Note that this Persister is currently experimental as Expo themselves iterate
  * on the underlying database library API.
  *
@@ -103,7 +107,7 @@ export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
  *
  * See the documentation for the DpcJson and DpcTabular types for more
  * information on how both of those modes can be configured.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param db The database instance that was returned from
  * `SQLite.openDatabase(...)`.
  * @param configOrStoreTableName A DatabasePersisterConfig to configure the

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

@@ -11,10 +11,12 @@ import type {MergeableStore} from '../../mergeable-store/index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
 /**
- * The FilePersister interface is a minor extension to the Persister interface.
+ * The FilePersister interface represents a Persister that lets you save and
+ * load Store data to and from a local file system.
  *
- * It simply provides an extra getFilePath method for accessing the location of
- * the local file the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getFilePath method for accessing the location of the local file the
+ * Store is being persisted to.
  *
  * You should use the createFilePersister function to create a FilePersister
  * object.
@@ -50,12 +52,14 @@ export interface FilePersister
 }
 
 /**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
+ * The createFilePersister function creates a FilePersister object that can
+ * persist the Store to a local file.
+ *
+ * A FilePersister supports both regular Store and MergeableStore objects.
  *
  * As well as providing a reference to the Store to persist, you must provide a
  * `filePath` parameter which identifies the file to persist it to.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param filePath The location of the local file to persist the Store to.
  * @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

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

@@ -11,10 +11,12 @@ import type {MergeableStore} from '../../mergeable-store/index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
 /**
- * The FilePersister interface is a minor extension to the Persister interface.
+ * The FilePersister interface represents a Persister that lets you save and
+ * load Store data to and from a local file system.
  *
- * It simply provides an extra getFilePath method for accessing the location of
- * the local file the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getFilePath method for accessing the location of the local file the
+ * Store is being persisted to.
  *
  * You should use the createFilePersister function to create a FilePersister
  * object.
@@ -50,12 +52,14 @@ export interface FilePersister
 }
 
 /**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
+ * The createFilePersister function creates a FilePersister object that can
+ * persist the Store to a local file.
+ *
+ * A FilePersister supports both regular Store and MergeableStore objects.
  *
  * As well as providing a reference to the Store to persist, you must provide a
  * `filePath` parameter which identifies the file to persist it to.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param filePath The location of the local file to persist the Store to.
  * @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

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

@@ -14,10 +14,12 @@ import type {Persister, Persists} from '../../with-schemas/index.d.cts';
 import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.cts';
 
 /**
- * The FilePersister interface is a minor extension to the Persister interface.
+ * The FilePersister interface represents a Persister that lets you save and
+ * load Store data to and from a local file system.
  *
- * It simply provides an extra getFilePath method for accessing the location of
- * the local file the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getFilePath method for accessing the location of the local file the
+ * Store is being persisted to.
  *
  * You should use the createFilePersister function to create a FilePersister
  * object.
@@ -53,8 +55,8 @@ export interface FilePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
+ * The createFilePersister function creates a FilePersister object that can
+ * persist the Store to a local file.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -66,9 +68,11 @@ export interface FilePersister<Schemas extends OptionalSchemas>
  * ): FilePersister;
  * ```
  *
+ * A FilePersister supports both regular Store and MergeableStore objects.
+ *
  * As well as providing a reference to the Store to persist, you must provide a
  * `filePath` parameter which identifies the file to persist it to.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param filePath The location of the local file to persist the Store to.
  * @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

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

@@ -14,10 +14,12 @@ import type {Persister, Persists} from '../../with-schemas/index.d.ts';
 import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
 
 /**
- * The FilePersister interface is a minor extension to the Persister interface.
+ * The FilePersister interface represents a Persister that lets you save and
+ * load Store data to and from a local file system.
  *
- * It simply provides an extra getFilePath method for accessing the location of
- * the local file the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getFilePath method for accessing the location of the local file the
+ * Store is being persisted to.
  *
  * You should use the createFilePersister function to create a FilePersister
  * object.
@@ -53,8 +55,8 @@ export interface FilePersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
+ * The createFilePersister function creates a FilePersister object that can
+ * persist the Store to a local file.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -66,9 +68,11 @@ export interface FilePersister<Schemas extends OptionalSchemas>
  * ): FilePersister;
  * ```
  *
+ * A FilePersister supports both regular Store and MergeableStore objects.
+ *
  * As well as providing a reference to the Store to persist, you must provide a
  * `filePath` parameter which identifies the file to persist it to.
- * @param store The Store to persist.
+ * @param store The Store or MergeableStore to persist.
  * @param filePath The location of the local file to persist the Store to.
  * @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

package/@types/persisters/persister-indexed-db/index.d.cts

@@ -10,11 +10,12 @@ import type {Persister} from '../index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
 /**
- * The IndexedDbPersister interface is a minor extension to the Persister
- * interface.
+ * The IndexedDbPersister interface represents a Persister that lets you save
+ * and load Store data to and from browser IndexedDB storage.
  *
- * It simply provides an extra getDbName method for accessing the unique key of
- * the IndexedDB the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDbName method for accessing the unique key of the IndexedDB the
+ * Store is being persisted to.
  *
  * You should use the createIndexedDbPersister function to create an
  * IndexedDbPersister object.
@@ -49,8 +50,11 @@ export interface IndexedDbPersister extends Persister {
 }
 
 /**
- * The createIndexedDbPersister function creates a Persister object that can
- * persist the Store to the browser's IndexedDB storage.
+ * The createIndexedDbPersister function creates an IndexedDbPersister object
+ * that can persist a Store to the browser's IndexedDB storage.
+ *
+ * An IndexedDbPersister 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 a
  * `dbName` parameter which is unique to your application. This is the key used

package/@types/persisters/persister-indexed-db/index.d.ts

@@ -10,11 +10,12 @@ import type {Persister} from '../index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
 /**
- * The IndexedDbPersister interface is a minor extension to the Persister
- * interface.
+ * The IndexedDbPersister interface represents a Persister that lets you save
+ * and load Store data to and from browser IndexedDB storage.
  *
- * It simply provides an extra getDbName method for accessing the unique key of
- * the IndexedDB the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDbName method for accessing the unique key of the IndexedDB the
+ * Store is being persisted to.
  *
  * You should use the createIndexedDbPersister function to create an
  * IndexedDbPersister object.
@@ -49,8 +50,11 @@ export interface IndexedDbPersister extends Persister {
 }
 
 /**
- * The createIndexedDbPersister function creates a Persister object that can
- * persist the Store to the browser's IndexedDB storage.
+ * The createIndexedDbPersister function creates an IndexedDbPersister object
+ * that can persist a Store to the browser's IndexedDB storage.
+ *
+ * An IndexedDbPersister 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 a
  * `dbName` parameter which is unique to your application. This is the key used

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

@@ -13,11 +13,12 @@ import type {
 import type {Persister} from '../../with-schemas/index.d.cts';
 
 /**
- * The IndexedDbPersister interface is a minor extension to the Persister
- * interface.
+ * The IndexedDbPersister interface represents a Persister that lets you save
+ * and load Store data to and from browser IndexedDB storage.
  *
- * It simply provides an extra getDbName method for accessing the unique key of
- * the IndexedDB the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDbName method for accessing the unique key of the IndexedDB the
+ * Store is being persisted to.
  *
  * You should use the createIndexedDbPersister function to create an
  * IndexedDbPersister object.
@@ -53,8 +54,8 @@ export interface IndexedDbPersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createIndexedDbPersister function creates a Persister object that can
- * persist the Store to the browser's IndexedDB storage.
+ * The createIndexedDbPersister function creates an IndexedDbPersister object
+ * that can persist a Store to the browser's IndexedDB storage.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -67,6 +68,9 @@ export interface IndexedDbPersister<Schemas extends OptionalSchemas>
  * ): IndexedDbPersister;
  * ```
  *
+ * An IndexedDbPersister 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 a
  * `dbName` parameter which is unique to your application. This is the key used
  * to identify which IndexedDB to use.

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

@@ -13,11 +13,12 @@ import type {
 import type {Persister} from '../../with-schemas/index.d.ts';
 
 /**
- * The IndexedDbPersister interface is a minor extension to the Persister
- * interface.
+ * The IndexedDbPersister interface represents a Persister that lets you save
+ * and load Store data to and from browser IndexedDB storage.
  *
- * It simply provides an extra getDbName method for accessing the unique key of
- * the IndexedDB the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDbName method for accessing the unique key of the IndexedDB the
+ * Store is being persisted to.
  *
  * You should use the createIndexedDbPersister function to create an
  * IndexedDbPersister object.
@@ -53,8 +54,8 @@ export interface IndexedDbPersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createIndexedDbPersister function creates a Persister object that can
- * persist the Store to the browser's IndexedDB storage.
+ * The createIndexedDbPersister function creates an IndexedDbPersister object
+ * that can persist a Store to the browser's IndexedDB storage.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -67,6 +68,9 @@ export interface IndexedDbPersister<Schemas extends OptionalSchemas>
  * ): IndexedDbPersister;
  * ```
  *
+ * An IndexedDbPersister 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 a
  * `dbName` parameter which is unique to your application. This is the key used
  * to identify which IndexedDB to use.

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

@@ -13,11 +13,12 @@ import type {Client} from '@libsql/client';
 import type {Store} from '../../store/index.d.cts';
 
 /**
- * The LibSqlPersister interface is a minor extension to the Persister
- * interface.
+ * The LibSqlPersister interface represents a Persister that lets you save and
+ * load Store data to and from a local LibSQL database.
  *
- * It simply provides an extra getClient method for accessing a reference to the
- * database client the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getClient method for accessing a reference to the database client the
+ * Store is being persisted to.
  *
  * You should use the createLibSqlPersister function to create a LibSqlPersister
  * object.
@@ -53,8 +54,11 @@ export interface LibSqlPersister extends Persister {
 }
 
 /**
- * The createLibSqlPersister function creates a Persister object that can
- * persist the Store to a local LibSQL database (in an appropriate environment).
+ * The createLibSqlPersister function creates a LibSqlPersister object that can
+ * persist a Store to a local LibSQL database.
+ *
+ * A LibSqlPersister 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 a
  * `client` parameter which identifies the database client.

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

@@ -13,11 +13,12 @@ import type {Client} from '@libsql/client';
 import type {Store} from '../../store/index.d.ts';
 
 /**
- * The LibSqlPersister interface is a minor extension to the Persister
- * interface.
+ * The LibSqlPersister interface represents a Persister that lets you save and
+ * load Store data to and from a local LibSQL database.
  *
- * It simply provides an extra getClient method for accessing a reference to the
- * database client the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getClient method for accessing a reference to the database client the
+ * Store is being persisted to.
  *
  * You should use the createLibSqlPersister function to create a LibSqlPersister
  * object.
@@ -53,8 +54,11 @@ export interface LibSqlPersister extends Persister {
 }
 
 /**
- * The createLibSqlPersister function creates a Persister object that can
- * persist the Store to a local LibSQL database (in an appropriate environment).
+ * The createLibSqlPersister function creates a LibSqlPersister object that can
+ * persist a Store to a local LibSQL database.
+ *
+ * A LibSqlPersister 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 a
  * `client` parameter which identifies the database client.

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

@@ -19,11 +19,12 @@ import type {
 import type {Client} from '@libsql/client';
 
 /**
- * The LibSqlPersister interface is a minor extension to the Persister
- * interface.
+ * The LibSqlPersister interface represents a Persister that lets you save and
+ * load Store data to and from a local LibSQL database.
  *
- * It simply provides an extra getClient method for accessing a reference to the
- * database client the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getClient method for accessing a reference to the database client the
+ * Store is being persisted to.
  *
  * You should use the createLibSqlPersister function to create a LibSqlPersister
  * object.
@@ -60,8 +61,8 @@ export interface LibSqlPersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createLibSqlPersister function creates a Persister object that can
- * persist the Store to a local LibSQL database (in an appropriate environment).
+ * The createLibSqlPersister function creates a LibSqlPersister object that can
+ * persist a Store to a local LibSQL database.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -75,6 +76,9 @@ export interface LibSqlPersister<Schemas extends OptionalSchemas>
  * ): LibSqlPersister;
  * ```
  *
+ * A LibSqlPersister 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 a
  * `client` parameter which identifies the database client.
  *

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

@@ -19,11 +19,12 @@ import type {
 import type {Client} from '@libsql/client';
 
 /**
- * The LibSqlPersister interface is a minor extension to the Persister
- * interface.
+ * The LibSqlPersister interface represents a Persister that lets you save and
+ * load Store data to and from a local LibSQL database.
  *
- * It simply provides an extra getClient method for accessing a reference to the
- * database client the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getClient method for accessing a reference to the database client the
+ * Store is being persisted to.
  *
  * You should use the createLibSqlPersister function to create a LibSqlPersister
  * object.
@@ -60,8 +61,8 @@ export interface LibSqlPersister<Schemas extends OptionalSchemas>
 }
 
 /**
- * The createLibSqlPersister function creates a Persister object that can
- * persist the Store to a local LibSQL database (in an appropriate environment).
+ * The createLibSqlPersister function creates a LibSqlPersister object that can
+ * persist a Store to a local LibSQL database.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -75,6 +76,9 @@ export interface LibSqlPersister<Schemas extends OptionalSchemas>
  * ): LibSqlPersister;
  * ```
  *
+ * A LibSqlPersister 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 a
  * `client` parameter which identifies the database client.
  *

package/@types/persisters/persister-partykit-client/index.d.cts

@@ -3,8 +3,8 @@
  * client portion of the PartyKit integration.
  *
  * It contains a Persister which, when run in a PartyKit client environment,
- * lets you save and load Store data from the client to durable PartyKit cloud
- * storage of a server (that is using the complementary
+ * lets you save and load Store data from the client to the durable PartyKit
+ * cloud storage of a server (that is using the complementary
  * persister-partykit-server module).
  *
  * This enables synchronization of the same Store across multiple clients in a
@@ -23,11 +23,13 @@ import type {Persister} from '../index.d.cts';
 import type {Store} from '../../store/index.d.cts';
 
 /**
- * The PartyKitPersister interface is a minor extension to the Persister
- * interface.
+ * The PartyKitPersister interface represents a Persister that lets you save and
+ * load Store data from the client to the durable PartyKit cloud storage of a
+ * server.
  *
- * It simply provides an extra getConnection method for accessing the
- * PartySocket the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getConnection method for accessing the PartySocket the Store is being
+ * persisted to.
  *
  * You should use the createPartyKitPersister function to create a
  * PartyKitPersister object.
@@ -115,9 +117,12 @@ export type PartyKitPersisterConfig = {
 };
 
 /**
- * The createPartyKitPersister function creates a Persister object that can
- * persist the Store to durable PartyKit storage, enabling synchronization of
- * the same Store across multiple clients.
+ * The createPartyKitPersister function creates a PartyKitPersister object that
+ * can persist the Store to durable PartyKit storage, enabling synchronization
+ * of the same Store across multiple clients.
+ *
+ * A PartyKitPersister 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 a
  * `connection` parameter which is a PartyKit PartySocket that you have already

package/@types/persisters/persister-partykit-client/index.d.ts

@@ -3,8 +3,8 @@
  * client portion of the PartyKit integration.
  *
  * It contains a Persister which, when run in a PartyKit client environment,
- * lets you save and load Store data from the client to durable PartyKit cloud
- * storage of a server (that is using the complementary
+ * lets you save and load Store data from the client to the durable PartyKit
+ * cloud storage of a server (that is using the complementary
  * persister-partykit-server module).
  *
  * This enables synchronization of the same Store across multiple clients in a
@@ -23,11 +23,13 @@ import type {Persister} from '../index.d.ts';
 import type {Store} from '../../store/index.d.ts';
 
 /**
- * The PartyKitPersister interface is a minor extension to the Persister
- * interface.
+ * The PartyKitPersister interface represents a Persister that lets you save and
+ * load Store data from the client to the durable PartyKit cloud storage of a
+ * server.
  *
- * It simply provides an extra getConnection method for accessing the
- * PartySocket the Store is being persisted to.
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getConnection method for accessing the PartySocket the Store is being
+ * persisted to.
  *
  * You should use the createPartyKitPersister function to create a
  * PartyKitPersister object.
@@ -115,9 +117,12 @@ export type PartyKitPersisterConfig = {
 };
 
 /**
- * The createPartyKitPersister function creates a Persister object that can
- * persist the Store to durable PartyKit storage, enabling synchronization of
- * the same Store across multiple clients.
+ * The createPartyKitPersister function creates a PartyKitPersister object that
+ * can persist the Store to durable PartyKit storage, enabling synchronization
+ * of the same Store across multiple clients.
+ *
+ * A PartyKitPersister 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 a
  * `connection` parameter which is a PartyKit PartySocket that you have already