tinybase 5.4.0-beta.2 → 5.4.0-beta.3

package/@types/persisters/persister-durable-object-storage/with-schemas/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The persister-durable-object-storage module of the TinyBase project lets you
+ * save and load Store data to and from Cloudflare Durable Object storage (in an
+ * appropriate environment).
+ * @see Persistence guides
+ * @packageDocumentation
+ * @module persister-durable-object-storage
+ * @since v5.4.0
+ */
+
+import type {Persister, Persists} from '../../with-schemas/index.d.ts';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
+import type {OptionalSchemas} from '../../../store/with-schemas/index.d.ts';
+
+/**
+ * The DurableObjectStoragePersister interface represents a Persister that lets
+ * you save and load Store data to and from Cloudflare Durable Object storage.
+ *
+ * You should use the createDurableObjectStoragePersister function to create a
+ * DurableObjectStoragePersister object, most likely within the createPersister
+ * method of a WsServerDurableObject.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getStorage method for accessing a reference to the storage that the
+ * Store is being persisted to.
+ * @category Persister
+ * @since v5.4.0
+ */
+export interface DurableObjectStoragePersister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas, Persists.MergeableStoreOnly> {
+  /**
+   * The getStorage method returns a reference to the storage that the Store is
+   * being persisted to.
+   * @returns The reference to the storage.
+   * @example
+   * This example creates a Persister object against a newly-created Store
+   * (within the createPersister method of a WsServerDurableObject instance) and
+   * then gets the storage reference back out again.
+   *
+   * ```js yolo
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * // Within the createPersister method of a WsServerDurableObject instance.
+   * const store = createMergeableStore().setTables();
+   * const persister = createDurableObjectStoragePersister(
+   *   store,
+   *   this.ctx.storage,
+   * );
+   *
+   * console.log(persister.getStorage() == this.ctx.storage);
+   * // -> true
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  getStorage(): DurableObjectStorage;
+}
+
+/**
+ * The createDurableObjectStoragePersister function creates a
+ * DurableObjectStoragePersister object that can persist the Store to and from
+ * Cloudflare Durable Object storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createDurableObjectStoragePersister(
+ *   store: MergeableStore,
+ *   durableObjectStorage: DurableObjectStorage,
+ *   storagePrefix?: string,
+ *   onIgnoredError?: (error: any) => void,
+ * ): DurableObjectStoragePersister;
+ * ```
+ *
+ * You will mostly use this within the createPersister method of a
+ * WsServerDurableObject.
+ *
+ * A DurableObjectStoragePersister only supports MergeableStore objects, and
+ * cannot be used to persist a regular Store.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a `storage` parameter which identifies the Durable Object storage to
+ * persist it to.
+ * @param store The MergeableStore to persist.
+ * @param storage The Durable Object storage to persist the Store to.
+ * @param storagePrefix An optional prefix to use on the keys in storage, which
+ * is useful if you want to ensure the Persister will not affect unrelated
+ * Durable Object storage. Defaults to an empty string.
+ * @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.
+ * @returns A reference to the new DurableObjectStoragePersister object.
+ * @example
+ * This example creates a Persister object against a newly-created
+ * MergeableStore (within the createPersister method of a WsServerDurableObject
+ * instance) and then gets the storage reference back out again.
+ *
+ * ```js yolo
+ * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * // Within the createPersister method of a WsServerDurableObject instance.
+ * const store = createMergeableStore().setTables();
+ * const persister = createDurableObjectStoragePersister(
+ *   store,
+ *   this.ctx.storage,
+ * );
+ *
+ * return persister;
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+export function createDurableObjectStoragePersister<
+  Schemas extends OptionalSchemas,
+>(
+  store: MergeableStore<Schemas>,
+  durableObjectStorage: DurableObjectStorage,
+  storagePrefix?: string,
+  onIgnoredError?: (error: any) => void,
+): DurableObjectStoragePersister<Schemas>;

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

@@ -206,12 +206,14 @@ export type PersistedContent<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
- *   Persist extends Persists.StoreOrMergeableStore
- *     ? Changes | MergeableChanges
- *     : Persist extends Persists.MergeableStoreOnly
- *       ? MergeableChanges
- *       : Changes;
+ * export type PersistedChanges<
+ *   Persist extends Persists = Persists.StoreOnly,
+ *   Hashed extends boolean = false,
+ * > = Persist extends Persists.StoreOrMergeableStore
+ *   ? Changes | MergeableChanges<Hashed>
+ *   : Persist extends Persists.MergeableStoreOnly
+ *     ? MergeableChanges<Hashed>
+ *     : Changes;
  * ```
  *
  * Using the values of the Persists enum, the generic parameter indicates
@@ -1923,8 +1925,9 @@ export function createCustomPersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of
@@ -2004,8 +2007,9 @@ export function createCustomSqlitePersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of

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

@@ -206,12 +206,14 @@ export type PersistedContent<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
- *   Persist extends Persists.StoreOrMergeableStore
- *     ? Changes | MergeableChanges
- *     : Persist extends Persists.MergeableStoreOnly
- *       ? MergeableChanges
- *       : Changes;
+ * export type PersistedChanges<
+ *   Persist extends Persists = Persists.StoreOnly,
+ *   Hashed extends boolean = false,
+ * > = Persist extends Persists.StoreOrMergeableStore
+ *   ? Changes | MergeableChanges<Hashed>
+ *   : Persist extends Persists.MergeableStoreOnly
+ *     ? MergeableChanges<Hashed>
+ *     : Changes;
  * ```
  *
  * Using the values of the Persists enum, the generic parameter indicates
@@ -1923,8 +1925,9 @@ export function createCustomPersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of
@@ -2004,8 +2007,9 @@ export function createCustomSqlitePersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of

package/@types/synchronizers/synchronizer-ws-server/index.d.cts

@@ -526,6 +526,9 @@ export interface WsServer {
  * Persister to synchronize with the clients on a given path (or a two-item
  * array of Persister and callback that lets you handle data after persistence
  * has started).
+ * @param onIgnoredError An optional handler for the errors that the server
+ * would otherwise ignore when trying to sync data. This is suitable for
+ * debugging issues in a development environment.
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -728,4 +731,5 @@ export function createWsServer<
     | Promise<PathPersister>
     | Promise<[PathPersister, (store: MergeableStore) => void]>
     | undefined,
+  onIgnoredError?: (error: any) => void,
 ): WsServer;

package/@types/synchronizers/synchronizer-ws-server/index.d.ts

@@ -526,6 +526,9 @@ export interface WsServer {
  * Persister to synchronize with the clients on a given path (or a two-item
  * array of Persister and callback that lets you handle data after persistence
  * has started).
+ * @param onIgnoredError An optional handler for the errors that the server
+ * would otherwise ignore when trying to sync data. This is suitable for
+ * debugging issues in a development environment.
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -728,4 +731,5 @@ export function createWsServer<
     | Promise<PathPersister>
     | Promise<[PathPersister, (store: MergeableStore) => void]>
     | undefined,
+  onIgnoredError?: (error: any) => void,
 ): WsServer;

package/@types/synchronizers/synchronizer-ws-server/with-schemas/index.d.cts

@@ -521,6 +521,7 @@ export interface WsServer {
  *     | Promise<PathPersister>
  *     | Promise<[PathPersister, (store: MergeableStore) => void]>
  *     | undefined,
+ *   onIgnoredError?: (error: any) => void,
  * ): WsServer;
  * ```
  *
@@ -552,6 +553,9 @@ export interface WsServer {
  * Persister to synchronize with the clients on a given path (or a two-item
  * array of Persister and callback that lets you handle data after persistence
  * has started).
+ * @param onIgnoredError An optional handler for the errors that the server
+ * would otherwise ignore when trying to sync data. This is suitable for
+ * debugging issues in a development environment.
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -756,4 +760,5 @@ export function createWsServer<
     | Promise<PathPersister>
     | Promise<[PathPersister, (store: MergeableStore<Schemas>) => void]>
     | undefined,
+  onIgnoredError?: (error: any) => void,
 ): WsServer;

package/@types/synchronizers/synchronizer-ws-server/with-schemas/index.d.ts

@@ -521,6 +521,7 @@ export interface WsServer {
  *     | Promise<PathPersister>
  *     | Promise<[PathPersister, (store: MergeableStore) => void]>
  *     | undefined,
+ *   onIgnoredError?: (error: any) => void,
  * ): WsServer;
  * ```
  *
@@ -552,6 +553,9 @@ export interface WsServer {
  * Persister to synchronize with the clients on a given path (or a two-item
  * array of Persister and callback that lets you handle data after persistence
  * has started).
+ * @param onIgnoredError An optional handler for the errors that the server
+ * would otherwise ignore when trying to sync data. This is suitable for
+ * debugging issues in a development environment.
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -756,4 +760,5 @@ export function createWsServer<
     | Promise<PathPersister>
     | Promise<[PathPersister, (store: MergeableStore<Schemas>) => void]>
     | undefined,
+  onIgnoredError?: (error: any) => void,
 ): WsServer;

package/@types/synchronizers/synchronizer-ws-server-durable-object/index.d.cts

@@ -10,6 +10,7 @@
  */
 
 import type {Id, IdAddedOrRemoved, Ids} from '../../index.d.cts';
+import type {Persister, Persists} from '../../persisters/index.d.cts';
 import {DurableObject} from 'cloudflare:workers';
 
 /**
@@ -20,10 +21,54 @@ import {DurableObject} from 'cloudflare:workers';
  * @since v5.4.0
  */
 export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
+  /**
+   * The createPersister method is used to return a persister for the
+   * Durable Object to preserve Store state for when clients are not connected.
+   *
+   * This should almost certainly be a DurableObjectStoragePersister, created
+   * with the createDurableObjectStoragePersister function.
+   * @example
+   * This example creates a Persister object against a newly-created
+   * MergeableStore (within the createPersister method of a
+   * WsServerDurableObject instance) and then gets the storage reference back
+   * out again.
+   *
+   * ```js yolo
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * // Within the createPersister method of a WsServerDurableObject instance.
+   * const store = createMergeableStore().setTables();
+   * const persister = createDurableObjectStoragePersister(
+   *   store,
+   *   this.ctx.storage,
+   * );
+   *
+   * return persister;
+   * ```
+   * @category Creation
+   * @since v5.4.0
+   */
+  createPersister():
+    | Persister<Persists.MergeableStoreOnly>
+    | Promise<Persister<Persists.MergeableStoreOnly>>
+    | undefined;
+
+  /**
+   * The getPathId method is used to get the Id of the path that is being
+   * served.
+   * @category Getter
+   * @since v5.4.0
+   */
+  getPathId(): Id;
+
   /**
    * The getClientIds method is used to access a list of all the connected
    * clients on a given path.
-   * @category Getters
+   *
+   * Note that if you call this method from the onClientId method as a client is
+   * getting removed, it will still be returned in the list of client Ids.
+   * @category Getter
    * @since v5.4.0
    */
   getClientIds(pathId: Id): Ids;
@@ -31,7 +76,7 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onPathId method is called when the first client connects to, or the
    * last client disconnects from, the server with a given path Id.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
@@ -39,10 +84,22 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onClientId method is called when a client connects to, or disconnects
    * from, the server.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): void;
+
+  /**
+   * The onMessage method is called when a message is handled by the server.
+   *
+   * Note that this method is potentially called very frequently, and should be
+   * performant. A pathId is not passed as an argument, since it has a small
+   * cost to provide by default. You can use the getPathId method yourself if
+   * that information is needed.
+   * @category Event
+   * @since v5.4.0
+   */
+  onMessage(_fromClientId: Id, _toClientId: Id, _remainder: string): void;
 }
 
 /**

package/@types/synchronizers/synchronizer-ws-server-durable-object/index.d.ts

@@ -10,6 +10,7 @@
  */
 
 import type {Id, IdAddedOrRemoved, Ids} from '../../index.d.ts';
+import type {Persister, Persists} from '../../persisters/index.d.ts';
 import {DurableObject} from 'cloudflare:workers';
 
 /**
@@ -20,10 +21,54 @@ import {DurableObject} from 'cloudflare:workers';
  * @since v5.4.0
  */
 export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
+  /**
+   * The createPersister method is used to return a persister for the
+   * Durable Object to preserve Store state for when clients are not connected.
+   *
+   * This should almost certainly be a DurableObjectStoragePersister, created
+   * with the createDurableObjectStoragePersister function.
+   * @example
+   * This example creates a Persister object against a newly-created
+   * MergeableStore (within the createPersister method of a
+   * WsServerDurableObject instance) and then gets the storage reference back
+   * out again.
+   *
+   * ```js yolo
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * // Within the createPersister method of a WsServerDurableObject instance.
+   * const store = createMergeableStore().setTables();
+   * const persister = createDurableObjectStoragePersister(
+   *   store,
+   *   this.ctx.storage,
+   * );
+   *
+   * return persister;
+   * ```
+   * @category Creation
+   * @since v5.4.0
+   */
+  createPersister():
+    | Persister<Persists.MergeableStoreOnly>
+    | Promise<Persister<Persists.MergeableStoreOnly>>
+    | undefined;
+
+  /**
+   * The getPathId method is used to get the Id of the path that is being
+   * served.
+   * @category Getter
+   * @since v5.4.0
+   */
+  getPathId(): Id;
+
   /**
    * The getClientIds method is used to access a list of all the connected
    * clients on a given path.
-   * @category Getters
+   *
+   * Note that if you call this method from the onClientId method as a client is
+   * getting removed, it will still be returned in the list of client Ids.
+   * @category Getter
    * @since v5.4.0
    */
   getClientIds(pathId: Id): Ids;
@@ -31,7 +76,7 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onPathId method is called when the first client connects to, or the
    * last client disconnects from, the server with a given path Id.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
@@ -39,10 +84,22 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onClientId method is called when a client connects to, or disconnects
    * from, the server.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): void;
+
+  /**
+   * The onMessage method is called when a message is handled by the server.
+   *
+   * Note that this method is potentially called very frequently, and should be
+   * performant. A pathId is not passed as an argument, since it has a small
+   * cost to provide by default. You can use the getPathId method yourself if
+   * that information is needed.
+   * @category Event
+   * @since v5.4.0
+   */
+  onMessage(_fromClientId: Id, _toClientId: Id, _remainder: string): void;
 }
 
 /**

package/@types/synchronizers/synchronizer-ws-server-durable-object/with-schemas/index.d.cts

@@ -9,7 +9,16 @@
  * @since v5.4.0
  */
 
-import type {Id, IdAddedOrRemoved, Ids} from '../../../with-schemas/index.d.cts';
+import type {
+  Id,
+  IdAddedOrRemoved,
+  Ids,
+  OptionalSchemas,
+} from '../../../with-schemas/index.d.cts';
+import type {
+  Persister,
+  Persists,
+} from '../../../persisters/with-schemas/index.d.cts';
 import {DurableObject} from 'cloudflare:workers';
 
 /**
@@ -19,11 +28,67 @@ import {DurableObject} from 'cloudflare:workers';
  * @category Creation
  * @since v5.4.0
  */
-export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
+export class WsServerDurableObject<
+  Schemas extends OptionalSchemas,
+  Env = unknown,
+> extends DurableObject<Env> {
+  /**
+   * The createPersister method is used to return a persister for the
+   * Durable Object to preserve Store state for when clients are not connected.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * createPersister():
+   *   | Persister<Persists.MergeableStoreOnly>
+   *   | Promise<Persister<Persists.MergeableStoreOnly>>
+   *   | undefined;
+   * ```
+   *
+   * This should almost certainly be a DurableObjectStoragePersister, created
+   * with the createDurableObjectStoragePersister function.
+   * @example
+   * This example creates a Persister object against a newly-created
+   * MergeableStore (within the createPersister method of a
+   * WsServerDurableObject instance) and then gets the storage reference back
+   * out again.
+   *
+   * ```js yolo
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * // Within the createPersister method of a WsServerDurableObject instance.
+   * const store = createMergeableStore().setTables();
+   * const persister = createDurableObjectStoragePersister(
+   *   store,
+   *   this.ctx.storage,
+   * );
+   *
+   * return persister;
+   * ```
+   * @category Creation
+   * @since v5.4.0
+   */
+  createPersister():
+    | Persister<Schemas, Persists.MergeableStoreOnly>
+    | Promise<Persister<Schemas, Persists.MergeableStoreOnly>>
+    | undefined;
+
+  /**
+   * The getPathId method is used to get the Id of the path that is being
+   * served.
+   * @category Getter
+   * @since v5.4.0
+   */
+  getPathId(): Id;
+
   /**
    * The getClientIds method is used to access a list of all the connected
    * clients on a given path.
-   * @category Getters
+   *
+   * Note that if you call this method from the onClientId method as a client is
+   * getting removed, it will still be returned in the list of client Ids.
+   * @category Getter
    * @since v5.4.0
    */
   getClientIds(pathId: Id): Ids;
@@ -31,7 +96,7 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onPathId method is called when the first client connects to, or the
    * last client disconnects from, the server with a given path Id.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
@@ -39,10 +104,22 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
   /**
    * The onClientId method is called when a client connects to, or disconnects
    * from, the server.
-   * @category Events
+   * @category Event
    * @since v5.4.0
    */
   onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): void;
+
+  /**
+   * The onMessage method is called when a message is handled by the server.
+   *
+   * Note that this method is potentially called very frequently, and should be
+   * performant. A pathId is not passed as an argument, since it has a small
+   * cost to provide by default. You can use the getPathId method yourself if
+   * that information is needed.
+   * @category Event
+   * @since v5.4.0
+   */
+  onMessage(_fromClientId: Id, _toClientId: Id, _remainder: string): void;
 }
 
 /**
@@ -52,11 +129,16 @@ export class WsServerDurableObject<Env = unknown> extends DurableObject<Env> {
  * @category Creation
  * @since v5.4.0
  */
-export function getWsServerDurableObjectFetch<Namespace extends string>(
+export function getWsServerDurableObjectFetch<
+  Schemas extends OptionalSchemas,
+  Namespace extends string,
+>(
   namespace: Namespace,
 ): (
   request: Request,
   env: {
-    [namespace in Namespace]: DurableObjectNamespace<WsServerDurableObject>;
+    [namespace in Namespace]: DurableObjectNamespace<
+      WsServerDurableObject<Schemas>
+    >;
   },
 ) => Response;