tinybase 5.1.0-beta.0 → 5.1.0-beta.1

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

@@ -9,8 +9,8 @@
  * @since v5.0.0
  */
 
+import type {Receive, Send, Synchronizer} from '../index.d.cts';
 import type {MergeableStore} from '../../mergeable-store/index.d.cts';
-import type {Synchronizer} from '../index.d.cts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
 /**
@@ -81,6 +81,10 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
  * As well as providing a reference to the MergeableStore to persist, you must
  * provide a configured WebSocket to send synchronization messages over.
  *
+ * You can 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.
+ *
  * This method is asynchronous because it will await the websocket's connection
  * to the server. You will need to `await` a call to this function or handle the
  * return type natively as a Promise.
@@ -88,6 +92,12 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
  * @param webSocket The WebSocket to send synchronization messages over.
  * @param requestTimeoutSeconds An optional time in seconds that the
  * Synchronizer will wait for responses to request messages, defaulting to 1.
+ * @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.
@@ -139,5 +149,7 @@ export function createWsSynchronizer<WebSocketType extends WebSocketTypes>(
   store: MergeableStore,
   webSocket: WebSocketType,
   requestTimeoutSeconds?: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Promise<WsSynchronizer<WebSocketType>>;

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

@@ -9,8 +9,8 @@
  * @since v5.0.0
  */
 
+import type {Receive, Send, Synchronizer} from '../index.d.ts';
 import type {MergeableStore} from '../../mergeable-store/index.d.ts';
-import type {Synchronizer} from '../index.d.ts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
 /**
@@ -81,6 +81,10 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
  * As well as providing a reference to the MergeableStore to persist, you must
  * provide a configured WebSocket to send synchronization messages over.
  *
+ * You can 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.
+ *
  * This method is asynchronous because it will await the websocket's connection
  * to the server. You will need to `await` a call to this function or handle the
  * return type natively as a Promise.
@@ -88,6 +92,12 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
  * @param webSocket The WebSocket to send synchronization messages over.
  * @param requestTimeoutSeconds An optional time in seconds that the
  * Synchronizer will wait for responses to request messages, defaulting to 1.
+ * @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.
@@ -139,5 +149,7 @@ export function createWsSynchronizer<WebSocketType extends WebSocketTypes>(
   store: MergeableStore,
   webSocket: WebSocketType,
   requestTimeoutSeconds?: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Promise<WsSynchronizer<WebSocketType>>;

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

@@ -9,9 +9,9 @@
  * @since v5.0.0
  */
 
+import type {Receive, Send, Synchronizer} from '../../with-schemas/index.d.cts';
 import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.cts';
 import type {OptionalSchemas} from '../../../store/with-schemas/index.d.cts';
-import type {Synchronizer} from '../../with-schemas/index.d.cts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
 /**
@@ -88,6 +88,8 @@ export interface WsSynchronizer<
  *   store: MergeableStore,
  *   webSocket: WebSocketType,
  *   requestTimeoutSeconds?: number,
+ *   onSend?: Send,
+ *   onReceive?: Receive,
  *   onIgnoredError?: (error: any) => void,
  * ): Promise<WsSynchronizer<WebSocketType>>;
  * ```
@@ -95,6 +97,10 @@ export interface WsSynchronizer<
  * As well as providing a reference to the MergeableStore to persist, you must
  * provide a configured WebSocket to send synchronization messages over.
  *
+ * You can 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.
+ *
  * This method is asynchronous because it will await the websocket's connection
  * to the server. You will need to `await` a call to this function or handle the
  * return type natively as a Promise.
@@ -102,6 +108,12 @@ export interface WsSynchronizer<
  * @param webSocket The WebSocket to send synchronization messages over.
  * @param requestTimeoutSeconds An optional time in seconds that the
  * Synchronizer will wait for responses to request messages, defaulting to 1.
+ * @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.
@@ -156,5 +168,7 @@ export function createWsSynchronizer<
   store: MergeableStore<Schemas>,
   webSocket: WebSocketType,
   requestTimeoutSeconds?: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Promise<WsSynchronizer<Schemas, WebSocketType>>;

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

@@ -9,9 +9,9 @@
  * @since v5.0.0
  */
 
+import type {Receive, Send, Synchronizer} 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';
-import type {Synchronizer} from '../../with-schemas/index.d.ts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
 /**
@@ -88,6 +88,8 @@ export interface WsSynchronizer<
  *   store: MergeableStore,
  *   webSocket: WebSocketType,
  *   requestTimeoutSeconds?: number,
+ *   onSend?: Send,
+ *   onReceive?: Receive,
  *   onIgnoredError?: (error: any) => void,
  * ): Promise<WsSynchronizer<WebSocketType>>;
  * ```
@@ -95,6 +97,10 @@ export interface WsSynchronizer<
  * As well as providing a reference to the MergeableStore to persist, you must
  * provide a configured WebSocket to send synchronization messages over.
  *
+ * You can 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.
+ *
  * This method is asynchronous because it will await the websocket's connection
  * to the server. You will need to `await` a call to this function or handle the
  * return type natively as a Promise.
@@ -102,6 +108,12 @@ export interface WsSynchronizer<
  * @param webSocket The WebSocket to send synchronization messages over.
  * @param requestTimeoutSeconds An optional time in seconds that the
  * Synchronizer will wait for responses to request messages, defaulting to 1.
+ * @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.
@@ -156,5 +168,7 @@ export function createWsSynchronizer<
   store: MergeableStore<Schemas>,
   webSocket: WebSocketType,
   requestTimeoutSeconds?: number,
+  onSend?: Send,
+  onReceive?: Receive,
   onIgnoredError?: (error: any) => void,
 ): Promise<WsSynchronizer<Schemas, WebSocketType>>;

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

@@ -9,7 +9,8 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../common/index.d.cts';
-import type {GetIdChanges} from '../../store/index.d.cts';
+import type {Persister, Persists} from '../../persisters/index.d.cts';
+import type {IdAddedOrRemoved} from '../../store/index.d.cts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -18,23 +19,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,
+  pathId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /**
@@ -43,25 +45,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,
+  clientId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /**
@@ -240,33 +244,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);
@@ -492,17 +498,132 @@ export interface 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
@@ -534,4 +655,11 @@ export interface WsServer {
  * @category Creation
  * @since v5.0.0
  */
-export function createWsServer(webSocketServer: WebSocketServer): WsServer;
+export function createWsServer<
+  PathPersister extends Persister<
+    Persists.MergeableStoreOnly | Persists.StoreOrMergeableStore
+  >,
+>(
+  webSocketServer: WebSocketServer,
+  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+): WsServer;