tinybase 5.1.0-beta.0 → 5.1.0

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

@@ -9,7 +9,14 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../../common/with-schemas/index.d.ts';
-import type {GetIdChanges} from '../../../store/with-schemas/index.d.ts';
+import type {
+  IdAddedOrRemoved,
+  OptionalSchemas,
+} from '../../../store/with-schemas/index.d.ts';
+import type {
+  Persister,
+  Persists,
+} from '../../../persisters/with-schemas/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -18,23 +25,24 @@ import type {WebSocketServer} from 'ws';
  *
  * A WsServer listens to any path, allowing an app to have the concept of
  * distinct 'rooms' that only certain clients are participating in. As soon as a
- * single client connects to a new path, this listener will be called with a
- * GetIdChanges callback that you can use to determine its Id.
+ * single client connects to a new path, this listener will be called with the
+ * Id of the new path and an `addedOrRemoved` value of `1`.
  *
- * When the final client disconnects from a path, it will be called again with a
- * GetIdChanges callback that you can again use to determine its Id.
+ * When the final client disconnects from a path, it will be called again with
+ * the Id of the deactivated path and an `addedOrRemoved` value of `-1`.
  *
  * A PathIdsListener is provided when using the addPathIdsListener method. See
  * that method for specific examples.
  * @param wsServer A reference to the WsServer.
- * @param getIdChanges A function that returns information about the path Id
- * change.
+ * @param pathId The Id of the path being added or removed.
+ * @param addedOrRemoved Whether the path was added (`1`) or removed (`-1`).
  * @category Listener
- * @since v5.0.0
+ * @since v5.0.3
  */
-export type PathIdsListener<> = (
+export type PathIdsListener = (
   wsServer: WsServer,
-  getIdChanges: GetIdChanges<Id>,
+  pathId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /**
@@ -43,25 +51,27 @@ export type PathIdsListener<> = (
  *
  * A WsServer listens to any path, allowing an app to have the concept of
  * distinct 'rooms' that only certain clients are participating in. As soon as a
- * new client connects to a path, this listener will be called with a
- * GetIdChanges callback that you can use to determine its Id.
+ * new client connects to a path, this listener will be called with the Id of
+ * the path, the Id of the new client, and an `addedOrRemoved` value of `1`.
  *
- * When the client disconnects from a path, it will be called again with a
- * GetIdChanges callback that you can again use to determine its Id.
+ * When the client disconnects from a path, it will be called again with the Id
+ * of the path, the Id of the leaving client, and an `addedOrRemoved` value of
+ * `-1`.
  *
  * A ClientIdsListener is provided when using the addClientIdsListener method.
  * See that method for specific examples.
  * @param wsServer A reference to the WsServer.
  * @param pathId The path that the client joined or left.
- * @param getIdChanges A function that returns information about the client Id
- * change.
+ * @param clientId The Id of the client being added or removed.
+ * @param addedOrRemoved Whether the client was added (`1`) or removed (`-1`).
  * @category Listener
- * @since v5.0.0
+ * @since v5.0.3
  */
-export type ClientIdsListener<> = (
+export type ClientIdsListener = (
   wsServer: WsServer,
   pathId: Id,
-  getIdChanges: GetIdChanges<Id>,
+  clientId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /**
@@ -240,33 +250,35 @@ export interface WsServer {
    * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
    *
    * const server = createWsServer(new WebSocketServer({port: 8047}));
-   * const listenerId = server.addPathIdsListener((server, getIdChanges) => {
-   *   console.log(getIdChanges());
-   *   console.log(server.getPathIds());
-   * });
+   * const listenerId = server.addPathIdsListener(
+   *   (server, pathId, addedOrRemoved) => {
+   *     console.log(pathId + (addedOrRemoved == 1 ? ' added' : ' removed'));
+   *     console.log(server.getPathIds());
+   *   },
+   * );
    *
    * const synchronizer1 = await createWsSynchronizer(
    *   createMergeableStore(),
    *   new WebSocket('ws://localhost:8047/roomA'),
    * );
-   * // -> {'roomA': 1}
+   * // -> 'roomA added'
    * // -> ['roomA']
    *
    * const synchronizer2 = await createWsSynchronizer(
    *   createMergeableStore(),
    *   new WebSocket('ws://localhost:8047/roomB'),
    * );
-   * // -> {'roomB': 1}
+   * // -> 'roomB added'
    * // -> ['roomA', 'roomB']
    *
    * synchronizer1.destroy();
    * // ...
-   * // -> {'roomA': -1}
+   * // -> 'roomA removed'
    * // -> ['roomB']
    *
    * synchronizer2.destroy();
    * // ...
-   * // -> {'roomB': -1}
+   * // -> 'roomB removed'
    * // -> []
    *
    * server.delListener(listenerId);
@@ -490,21 +502,149 @@ export interface WsServer {
  * The createWsServer function creates a WsServer that facilitates
  * synchronization between clients that are using WsSynchronizer instances.
  *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createWsServer<
+ *   PathPersister extends Persister<
+ *     Persists.MergeableStoreOnly | Persists.StoreOrMergeableStore
+ *   >,
+ * >(
+ *   webSocketServer: WebSocketServer,
+ *   createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+ * ): WsServer;
+ * ```
+ *
  * This should be run in a server environment, and you must pass in a configured
  * WebSocketServer object in order to create it.
+ *
+ * If you want your server to persist data itself, you can use the optional
+ * second parameter of this function, which allows you to create a Persister for
+ * a new path - whenever a new path is accessed by a client. This Persister will
+ * only exist when there are active clients on that particular path.
+ *
+ * You are responsible for creating a MergeableStore to pass to this Persister,
+ * but starting and stopping its automatic saving and loading is taken care of
+ * by the WsServer. As a result, the server MergeableStore will be kept in sync
+ * with the clients on that path, and in turn with whatever persistence layer
+ * you have configured. See the example below.
  * @param webSocketServer A WebSocketServer object from your server environment.
+ * @param createPersisterForPath An optional function that will create a
+ * Persister (with a MergeableStore) to synchronize with the clients on a given
+ * path.
  * @returns A reference to the new WsServer object.
  * @example
- * This example creates a WsServer and then destroys it again.
+ * This example creates a WsServer that synchronizes two clients on a shared
+ * path.
  *
  * ```js
  * import {WebSocketServer} from 'ws';
+ * import {createMergeableStore} from 'tinybase';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+ * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  *
+ * // Server
  * const server = createWsServer(new WebSocketServer({port: 8047}));
+ *
+ * // Client 1
+ * const clientStore1 = createMergeableStore();
+ * clientStore1.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer1 = await createWsSynchronizer(
+ *   clientStore1,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer1.startSync();
+ * // ...
+ *
+ * // Client 2
+ * const clientStore2 = createMergeableStore();
+ * clientStore2.setCell('pets', 'felix', 'species', 'cat');
+ * const synchronizer2 = await createWsSynchronizer(
+ *   clientStore2,
+ *   new WebSocket('ws://localhost:8047/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();
  * ```
  * @example
+ * This longer example creates a WsServer that persists a MergeableStore to file
+ * that is synchronized with two clients on a shared path. Later, when a third
+ * client connects, it picks up the data the previous two were using.
+ *
+ * ```js
+ * import {WebSocketServer} from 'ws';
+ * import {createFilePersister} from 'tinybase/persisters/persister-file';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+ * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+ * import {rmSync} from 'fs';
+ *
+ * // Server
+ * const server = createWsServer(
+ *   new WebSocketServer({port: 8047}),
+ *   (pathId) =>
+ *     createFilePersister(createMergeableStore(), pathId + '.json'),
+ * );
+ *
+ * // Client 1
+ * const clientStore1 = createMergeableStore();
+ * clientStore1.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer1 = await createWsSynchronizer(
+ *   clientStore1,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer1.startSync();
+ * // ...
+ *
+ * // Client 2
+ * const clientStore2 = createMergeableStore();
+ * clientStore2.setCell('pets', 'felix', 'species', 'cat');
+ * const synchronizer2 = await createWsSynchronizer(
+ *   clientStore2,
+ *   new WebSocket('ws://localhost:8047/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();
+ *
+ * // ...
+ * // Client 3 connects later
+ * const clientStore3 = createMergeableStore();
+ * const synchronizer3 = await createWsSynchronizer(
+ *   clientStore3,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer3.startSync();
+ * // ...
+ *
+ * console.log(clientStore3.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer3.destroy();
+ * server.destroy();
+ *
+ * // Remove file for the purposes of this demo.
+ * rmSync('petShop.json');
+ * ```
+ * @example
  * This example creates a WsServer with a custom listener that displays
  * information about the address of the client that connects to it.
  *
@@ -534,4 +674,13 @@ export interface WsServer {
  * @category Creation
  * @since v5.0.0
  */
-export function createWsServer(webSocketServer: WebSocketServer): WsServer;
+export function createWsServer<
+  Schemas extends OptionalSchemas,
+  PathPersister extends Persister<
+    Schemas,
+    Persists.MergeableStoreOnly | Persists.StoreOrMergeableStore
+  >,
+>(
+  webSocketServer: WebSocketServer,
+  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+): WsServer;

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

@@ -83,15 +83,12 @@ export const enum Message {
 }
 
 /**
- * The Receive type describes a function that knows how to handle the arrival of
- * a message as part of the synchronization protocol.
- *
- * When a message arrives (most likely from another system), the function will
- * be called with parameters that indicate where the message came from, and its
- * meaning and content.
- * @param fromClientId The Id of the other client (in other words, the other
- * system) that sent the message.
- * @param requestId The optional Id of the message, which should be returned in
+ * The Send type describes a function that knows how to dispatch a message as
+ * part of the synchronization protocol.
+ * @param toClientId The optional Id of the other client (in other words, the
+ * other system) to which the message should be sent. If omitted, this is to be
+ * a broadcast.
+ * @param requestId The optional Id of the message, which should be awaited in
  * the response (if requested) to constitute a matched request/response
  * transaction.
  * @param message A number that indicates the type of the message, according to
@@ -100,20 +97,23 @@ export const enum Message {
  * @category Synchronization
  * @since v5.0.0
  */
-export type Receive = (
-  fromClientId: Id,
+export type Send = (
+  toClientId: IdOrNull,
   requestId: Id,
   message: Message,
   body: any,
 ) => void;
 
 /**
- * The Send type describes a function that knows how to dispatch a message as
- * part of the synchronization protocol.
- * @param toClientId The optional Id of the other client (in other words, the
- * other system) to which the message should be sent. If omitted, this is to be
- * a broadcast.
- * @param requestId The optional Id of the message, which should be awaited in
+ * The Receive type describes a function that knows how to handle the arrival of
+ * a message as part of the synchronization protocol.
+ *
+ * When a message arrives (most likely from another system), the function will
+ * be called with parameters that indicate where the message came from, and its
+ * meaning and content.
+ * @param fromClientId The Id of the other client (in other words, the other
+ * system) that sent the message.
+ * @param requestId The optional Id of the message, which should be returned in
  * the response (if requested) to constitute a matched request/response
  * transaction.
  * @param message A number that indicates the type of the message, according to
@@ -122,8 +122,8 @@ export type Receive = (
  * @category Synchronization
  * @since v5.0.0
  */
-export type Send = (
-  toClientId: IdOrNull,
+export type Receive = (
+  fromClientId: Id,
   requestId: Id,
   message: Message,
   body: any,
@@ -340,7 +340,7 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
    * Synchronizer, and is used for debugging purposes.
    *
    * The SynchronizerStats object contains a count of the number of times the
-   * Persister has sent and received messages.
+   * Synchronizer has sent and received messages.
    *
    * The method is intended to be used during development to ensure your
    * synchronization layer is acting as expected, for example.
@@ -395,6 +395,8 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
  *   registerReceive: (receive: Receive) => void,
  *   destroy: () => void,
  *   requestTimeoutSeconds: number,
+ *   onSend?: Send,
+ *   onReceive?: Receive,
  *   onIgnoredError?: (error: any) => void,
  * ): Synchronizer;
  * ```
@@ -403,15 +405,29 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
  * must provide parameters which identify how to send and receive changes to and
  * from this MergeableStore and its peers. This is entirely dependent upon the
  * medium of communication used.
+ *
+ * You must also provide a callback for when the Synchronizer is destroyed
+ * (which is a good place to clean up resources and stop communication
+ * listeners), and indicate how long the Synchronizer will wait for responses to
+ * message requests before timing out.
+ *
+ * A final set of optional handlers can be provided to help debug sends,
+ * receives, and errors respectively.
  * @param store The MergeableStore to synchronize.
  * @param send A Send function for sending a message.
  * @param registerReceive A callback (called once when the Synchronizer is
  * created) that is passed a Receive function that you need to ensure will
  * receive messages addressed or broadcast to this client.
- * @param destroy A function called when destroying the Persister which can be
- * used to clean up underlying resources.
+ * @param destroy A function called when destroying the Synchronizer which can
+ * be used to clean up underlying resources.
  * @param requestTimeoutSeconds An number of seconds before a request sent from
- * this Persister to another peer times out.
+ * this Synchronizer to another peer times out.
+ * @param onSend An optional handler for the messages that this Synchronizer
+ * sends. This is suitable for debugging synchronization issues in a development
+ * environment, since v5.1.
+ * @param onReceive An optional handler for the messages that this Synchronizer
+ * receives. This is suitable for debugging synchronization issues in a
+ * development environment, since v5.1.
  * @param onIgnoredError An optional handler for the errors that the
  * Synchronizer would otherwise ignore when trying to synchronize data. This is
  * suitable for debugging synchronization issues in a development environment.
@@ -485,5 +501,7 @@ export function createCustomSynchronizer<Schemas extends OptionalSchemas>(
   registerReceive: (receive: Receive) => void,
   destroy: () => void,
   requestTimeoutSeconds: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Synchronizer<Schemas>;

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

@@ -83,15 +83,12 @@ export const enum Message {
 }
 
 /**
- * The Receive type describes a function that knows how to handle the arrival of
- * a message as part of the synchronization protocol.
- *
- * When a message arrives (most likely from another system), the function will
- * be called with parameters that indicate where the message came from, and its
- * meaning and content.
- * @param fromClientId The Id of the other client (in other words, the other
- * system) that sent the message.
- * @param requestId The optional Id of the message, which should be returned in
+ * The Send type describes a function that knows how to dispatch a message as
+ * part of the synchronization protocol.
+ * @param toClientId The optional Id of the other client (in other words, the
+ * other system) to which the message should be sent. If omitted, this is to be
+ * a broadcast.
+ * @param requestId The optional Id of the message, which should be awaited in
  * the response (if requested) to constitute a matched request/response
  * transaction.
  * @param message A number that indicates the type of the message, according to
@@ -100,20 +97,23 @@ export const enum Message {
  * @category Synchronization
  * @since v5.0.0
  */
-export type Receive = (
-  fromClientId: Id,
+export type Send = (
+  toClientId: IdOrNull,
   requestId: Id,
   message: Message,
   body: any,
 ) => void;
 
 /**
- * The Send type describes a function that knows how to dispatch a message as
- * part of the synchronization protocol.
- * @param toClientId The optional Id of the other client (in other words, the
- * other system) to which the message should be sent. If omitted, this is to be
- * a broadcast.
- * @param requestId The optional Id of the message, which should be awaited in
+ * The Receive type describes a function that knows how to handle the arrival of
+ * a message as part of the synchronization protocol.
+ *
+ * When a message arrives (most likely from another system), the function will
+ * be called with parameters that indicate where the message came from, and its
+ * meaning and content.
+ * @param fromClientId The Id of the other client (in other words, the other
+ * system) that sent the message.
+ * @param requestId The optional Id of the message, which should be returned in
  * the response (if requested) to constitute a matched request/response
  * transaction.
  * @param message A number that indicates the type of the message, according to
@@ -122,8 +122,8 @@ export type Receive = (
  * @category Synchronization
  * @since v5.0.0
  */
-export type Send = (
-  toClientId: IdOrNull,
+export type Receive = (
+  fromClientId: Id,
   requestId: Id,
   message: Message,
   body: any,
@@ -340,7 +340,7 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
    * Synchronizer, and is used for debugging purposes.
    *
    * The SynchronizerStats object contains a count of the number of times the
-   * Persister has sent and received messages.
+   * Synchronizer has sent and received messages.
    *
    * The method is intended to be used during development to ensure your
    * synchronization layer is acting as expected, for example.
@@ -395,6 +395,8 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
  *   registerReceive: (receive: Receive) => void,
  *   destroy: () => void,
  *   requestTimeoutSeconds: number,
+ *   onSend?: Send,
+ *   onReceive?: Receive,
  *   onIgnoredError?: (error: any) => void,
  * ): Synchronizer;
  * ```
@@ -403,15 +405,29 @@ export interface Synchronizer<Schemas extends OptionalSchemas>
  * must provide parameters which identify how to send and receive changes to and
  * from this MergeableStore and its peers. This is entirely dependent upon the
  * medium of communication used.
+ *
+ * You must also provide a callback for when the Synchronizer is destroyed
+ * (which is a good place to clean up resources and stop communication
+ * listeners), and indicate how long the Synchronizer will wait for responses to
+ * message requests before timing out.
+ *
+ * A final set of optional handlers can be provided to help debug sends,
+ * receives, and errors respectively.
  * @param store The MergeableStore to synchronize.
  * @param send A Send function for sending a message.
  * @param registerReceive A callback (called once when the Synchronizer is
  * created) that is passed a Receive function that you need to ensure will
  * receive messages addressed or broadcast to this client.
- * @param destroy A function called when destroying the Persister which can be
- * used to clean up underlying resources.
+ * @param destroy A function called when destroying the Synchronizer which can
+ * be used to clean up underlying resources.
  * @param requestTimeoutSeconds An number of seconds before a request sent from
- * this Persister to another peer times out.
+ * this Synchronizer to another peer times out.
+ * @param onSend An optional handler for the messages that this Synchronizer
+ * sends. This is suitable for debugging synchronization issues in a development
+ * environment, since v5.1.
+ * @param onReceive An optional handler for the messages that this Synchronizer
+ * receives. This is suitable for debugging synchronization issues in a
+ * development environment, since v5.1.
  * @param onIgnoredError An optional handler for the errors that the
  * Synchronizer would otherwise ignore when trying to synchronize data. This is
  * suitable for debugging synchronization issues in a development environment.
@@ -485,5 +501,7 @@ export function createCustomSynchronizer<Schemas extends OptionalSchemas>(
   registerReceive: (receive: Receive) => void,
   destroy: () => void,
   requestTimeoutSeconds: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Synchronizer<Schemas>;