tinybase 5.4.0-beta.0 → 5.4.0-beta.2

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

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

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

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

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

@@ -0,0 +1,62 @@
+/**
+ * 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 {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 getClientIds method is used to access a list of all the connected
+   * clients on a given path.
+   * @category Getters
+   * @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 Events
+   * @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 Events
+   * @since v5.4.0
+   */
+  onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): 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,62 @@
+/**
+ * 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 {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 getClientIds method is used to access a list of all the connected
+   * clients on a given path.
+   * @category Getters
+   * @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 Events
+   * @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 Events
+   * @since v5.4.0
+   */
+  onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): 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/with-schemas/index.d.cts

@@ -0,0 +1,62 @@
+/**
+ * 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 '../../../with-schemas/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 getClientIds method is used to access a list of all the connected
+   * clients on a given path.
+   * @category Getters
+   * @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 Events
+   * @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 Events
+   * @since v5.4.0
+   */
+  onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): 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/with-schemas/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 '../../../with-schemas/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 getClientIds method is used to access a list of all the connected
+   * clients on a given path.
+   * @category Getters
+   * @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 Events
+   * @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 Events
+   * @since v5.4.0
+   */
+  onClientId(pathId: Id, clientId: Id, addedOrRemoved: IdAddedOrRemoved): 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-simple/index.d.cts

@@ -0,0 +1,145 @@
+/**
+ * The synchronizer-ws-server-simple module of the TinyBase project lets you
+ * create a server that facilitates synchronization between clients, without the
+ * complications of listeners, persistence, or statistics.
+ *
+ * This makes it more suitable to be used as a reference implementation for
+ * other server environments.
+ * @see Synchronization guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server-simple
+ * @since v5.4.0
+ */
+
+import type {WebSocketServer} from 'ws';
+
+/**
+ * The WsServerSimple interface represents an object that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics.
+ *
+ * You should use the createWsServerSimple function to create a WsServerSimple
+ * object.
+ * @category Server
+ * @since v5.4.0
+ */
+export interface WsServerSimple {
+  /**
+   * The getWebSocketServer method returns a reference to the WebSocketServer
+   * being used for this WsServerSimple.
+   * @returns The WebSocketServer reference.
+   * @example
+   * This example creates a WsServerSimple and then gets the WebSocketServer
+   * reference back out again.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * console.log(server.getWebSocketServer() == webSocketServer);
+   * // -> true
+   *
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  getWebSocketServer(): WebSocketServer;
+  /**
+   * The destroy method provides a way to clean up the server at the end of its
+   * use.
+   *
+   * This closes the underlying WebSocketServer that was provided when the
+   * WsServerSimple was created.
+   * @example
+   * This example creates a WsServerSimple and then destroys it again, closing
+   * the underlying WebSocketServer.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * webSocketServer.on('close', () => {
+   *   console.log('WebSocketServer closed');
+   * });
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * server.destroy();
+   * // ...
+   * // -> 'WebSocketServer closed'
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  destroy(): void;
+}
+
+/**
+ * The createWsServerSimple function creates a WsServerSimple that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * This should be run in a server environment, and you must pass in a configured
+ * WebSocketServer object in order to create it.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics. This makes it
+ * more suitable to be used as a reference implementation for other server
+ * environments.
+ * @param webSocketServer A WebSocketServer object from your server environment.
+ * @returns A reference to the new WsServerSimple object.
+ * @example
+ * This example creates a WsServerSimple that synchronizes two clients on a
+ * shared path.
+ *
+ * ```js
+ * import {WebSocketServer} from 'ws';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+ * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+ *
+ * // Server
+ * const server = createWsServerSimple(new WebSocketServer({port: 8053}));
+ *
+ * // Client 1
+ * const clientStore1 = createMergeableStore();
+ * clientStore1.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer1 = await createWsSynchronizer(
+ *   clientStore1,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer1.startSync();
+ * // ...
+ *
+ * // Client 2
+ * const clientStore2 = createMergeableStore();
+ * clientStore2.setCell('pets', 'felix', 'species', 'cat');
+ * const synchronizer2 = await createWsSynchronizer(
+ *   clientStore2,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer2.startSync();
+ * // ...
+ *
+ * console.log(clientStore1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * console.log(clientStore2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * server.destroy();
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+export function createWsServerSimple(
+  webSocketServer: WebSocketServer,
+): WsServerSimple;

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

@@ -0,0 +1,145 @@
+/**
+ * The synchronizer-ws-server-simple module of the TinyBase project lets you
+ * create a server that facilitates synchronization between clients, without the
+ * complications of listeners, persistence, or statistics.
+ *
+ * This makes it more suitable to be used as a reference implementation for
+ * other server environments.
+ * @see Synchronization guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server-simple
+ * @since v5.4.0
+ */
+
+import type {WebSocketServer} from 'ws';
+
+/**
+ * The WsServerSimple interface represents an object that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics.
+ *
+ * You should use the createWsServerSimple function to create a WsServerSimple
+ * object.
+ * @category Server
+ * @since v5.4.0
+ */
+export interface WsServerSimple {
+  /**
+   * The getWebSocketServer method returns a reference to the WebSocketServer
+   * being used for this WsServerSimple.
+   * @returns The WebSocketServer reference.
+   * @example
+   * This example creates a WsServerSimple and then gets the WebSocketServer
+   * reference back out again.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * console.log(server.getWebSocketServer() == webSocketServer);
+   * // -> true
+   *
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  getWebSocketServer(): WebSocketServer;
+  /**
+   * The destroy method provides a way to clean up the server at the end of its
+   * use.
+   *
+   * This closes the underlying WebSocketServer that was provided when the
+   * WsServerSimple was created.
+   * @example
+   * This example creates a WsServerSimple and then destroys it again, closing
+   * the underlying WebSocketServer.
+   *
+   * ```js
+   * import {WebSocketServer} from 'ws';
+   * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+   *
+   * const webSocketServer = new WebSocketServer({port: 8053});
+   * webSocketServer.on('close', () => {
+   *   console.log('WebSocketServer closed');
+   * });
+   * const server = createWsServerSimple(webSocketServer);
+   *
+   * server.destroy();
+   * // ...
+   * // -> 'WebSocketServer closed'
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  destroy(): void;
+}
+
+/**
+ * The createWsServerSimple function creates a WsServerSimple that facilitates
+ * synchronization between clients that are using WsSynchronizer instances.
+ *
+ * This should be run in a server environment, and you must pass in a configured
+ * WebSocketServer object in order to create it.
+ *
+ * The core functionality is equivalent to the WsServer interface, but without
+ * the complications of listeners, persistence, or statistics. This makes it
+ * more suitable to be used as a reference implementation for other server
+ * environments.
+ * @param webSocketServer A WebSocketServer object from your server environment.
+ * @returns A reference to the new WsServerSimple object.
+ * @example
+ * This example creates a WsServerSimple that synchronizes two clients on a
+ * shared path.
+ *
+ * ```js
+ * import {WebSocketServer} from 'ws';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
+ * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+ *
+ * // Server
+ * const server = createWsServerSimple(new WebSocketServer({port: 8053}));
+ *
+ * // Client 1
+ * const clientStore1 = createMergeableStore();
+ * clientStore1.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer1 = await createWsSynchronizer(
+ *   clientStore1,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer1.startSync();
+ * // ...
+ *
+ * // Client 2
+ * const clientStore2 = createMergeableStore();
+ * clientStore2.setCell('pets', 'felix', 'species', 'cat');
+ * const synchronizer2 = await createWsSynchronizer(
+ *   clientStore2,
+ *   new WebSocket('ws://localhost:8053/petShop'),
+ * );
+ * await synchronizer2.startSync();
+ * // ...
+ *
+ * console.log(clientStore1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * console.log(clientStore2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * server.destroy();
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+export function createWsServerSimple(
+  webSocketServer: WebSocketServer,
+): WsServerSimple;