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

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

@@ -9,7 +9,8 @@
  */
 
 import type {Id, IdOrNull, Ids} from '../../common/index.d.ts';
-import type {GetIdChanges} from '../../store/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';
 
 /**
@@ -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;

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 {GetIdChanges} 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';
 
 /**
@@ -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;