tinybase 5.4.0-beta.1 → 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

@@ -178,6 +178,7 @@ export interface WsServer {
   /**
    * The getClientIds method method returns the active clients that the WsServer
    * is handling for a given path.
+   * @param pathId The path for which to return the list of active clients.
    * @returns An array of the clients connected to the given path.
    * @example
    * This example creates a WsServer, sets some clients up to connect
@@ -525,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
@@ -727,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

@@ -178,6 +178,7 @@ export interface WsServer {
   /**
    * The getClientIds method method returns the active clients that the WsServer
    * is handling for a given path.
+   * @param pathId The path for which to return the list of active clients.
    * @returns An array of the clients connected to the given path.
    * @example
    * This example creates a WsServer, sets some clients up to connect
@@ -525,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
@@ -727,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

@@ -184,6 +184,7 @@ export interface WsServer {
   /**
    * The getClientIds method method returns the active clients that the WsServer
    * is handling for a given path.
+   * @param pathId The path for which to return the list of active clients.
    * @returns An array of the clients connected to the given path.
    * @example
    * This example creates a WsServer, sets some clients up to connect
@@ -520,6 +521,7 @@ export interface WsServer {
  *     | Promise<PathPersister>
  *     | Promise<[PathPersister, (store: MergeableStore) => void]>
  *     | undefined,
+ *   onIgnoredError?: (error: any) => void,
  * ): WsServer;
  * ```
  *
@@ -551,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
@@ -755,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

@@ -184,6 +184,7 @@ export interface WsServer {
   /**
    * The getClientIds method method returns the active clients that the WsServer
    * is handling for a given path.
+   * @param pathId The path for which to return the list of active clients.
    * @returns An array of the clients connected to the given path.
    * @example
    * This example creates a WsServer, sets some clients up to connect
@@ -520,6 +521,7 @@ export interface WsServer {
  *     | Promise<PathPersister>
  *     | Promise<[PathPersister, (store: MergeableStore) => void]>
  *     | undefined,
+ *   onIgnoredError?: (error: any) => void,
  * ): WsServer;
  * ```
  *
@@ -551,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
@@ -755,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

@@ -0,0 +1,119 @@
+/**
+ * The synchronizer-ws-server-durable-object module of the TinyBase project lets
+ * you create a server that facilitates synchronization between clients, running
+ * as a Cloudflare Durable Object.
+ * @see Synchronization guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server-durable-object
+ * @since v5.4.0
+ */
+
+import type {Id, IdAddedOrRemoved, Ids} from '../../index.d.cts';
+import type {Persister, Persists} from '../../persisters/index.d.cts';
+import {DurableObject} from 'cloudflare:workers';
+
+/**
+ * A WsServerDurableObject is the server component (running as a Cloudflare
+ * Durable Object) for synchronization between clients that are using
+ * WsSynchronizer instances.
+ * @category Creation
+ * @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.
+   *
+   * 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;
+
+  /**
+   * 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 Event
+   * @since v5.4.0
+   */
+  onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
+
+  /**
+   * The onClientId method is called when a client connects to, or disconnects
+   * from, the server.
+   * @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;
+}
+
+/**
+ * The getWsServerDurableObjectFetch function returns a convenient fetch handler
+ * for a Cloudflare worker to route requests to a WsServerDurableObject for the
+ * given namespace.
+ * @category Creation
+ * @since v5.4.0
+ */
+export function getWsServerDurableObjectFetch<Namespace extends string>(
+  namespace: Namespace,
+): (
+  request: Request,
+  env: {
+    [namespace in Namespace]: DurableObjectNamespace<WsServerDurableObject>;
+  },
+) => Response;

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

@@ -0,0 +1,119 @@
+/**
+ * The synchronizer-ws-server-durable-object module of the TinyBase project lets
+ * you create a server that facilitates synchronization between clients, running
+ * as a Cloudflare Durable Object.
+ * @see Synchronization guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server-durable-object
+ * @since v5.4.0
+ */
+
+import type {Id, IdAddedOrRemoved, Ids} from '../../index.d.ts';
+import type {Persister, Persists} from '../../persisters/index.d.ts';
+import {DurableObject} from 'cloudflare:workers';
+
+/**
+ * A WsServerDurableObject is the server component (running as a Cloudflare
+ * Durable Object) for synchronization between clients that are using
+ * WsSynchronizer instances.
+ * @category Creation
+ * @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.
+   *
+   * 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;
+
+  /**
+   * 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 Event
+   * @since v5.4.0
+   */
+  onPathId(pathId: Id, addedOrRemoved: IdAddedOrRemoved): void;
+
+  /**
+   * The onClientId method is called when a client connects to, or disconnects
+   * from, the server.
+   * @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;
+}
+
+/**
+ * The getWsServerDurableObjectFetch function returns a convenient fetch handler
+ * for a Cloudflare worker to route requests to a WsServerDurableObject for the
+ * given namespace.
+ * @category Creation
+ * @since v5.4.0
+ */
+export function getWsServerDurableObjectFetch<Namespace extends string>(
+  namespace: Namespace,
+): (
+  request: Request,
+  env: {
+    [namespace in Namespace]: DurableObjectNamespace<WsServerDurableObject>;
+  },
+) => Response;