tinybase 5.0.4 → 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,6 +9,7 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../common/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';
 
@@ -497,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
@@ -539,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;

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

@@ -9,6 +9,7 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../common/index.d.ts';
+import type {Persister, Persists} from '../../persisters/index.d.ts';
 import type {IdAddedOrRemoved} from '../../store/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
@@ -497,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
@@ -539,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;

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

@@ -9,7 +9,14 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../../common/with-schemas/index.d.cts';
-import type {IdAddedOrRemoved} from '../../../store/with-schemas/index.d.cts';
+import type {
+  IdAddedOrRemoved,
+  OptionalSchemas,
+} from '../../../store/with-schemas/index.d.cts';
+import type {
+  Persister,
+  Persists,
+} from '../../../persisters/with-schemas/index.d.cts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -495,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.
  *
@@ -539,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;