tinybase 5.1.0 → 5.1.2

package/@types/persisters/persister-powersync/index.d.cts

@@ -9,7 +9,7 @@
  */
 
 import type {DatabasePersisterConfig, Persister} from '../index.d.cts';
-import type {AbstractPowerSyncDatabase} from '@journeyapps/powersync-sdk-common';
+import type {AbstractPowerSyncDatabase} from '@powersync/common';
 import type {Store} from '../../store/index.d.cts';
 
 /**
@@ -38,7 +38,7 @@ export interface PowerSyncPersister extends Persister {
    * ```js yolo
    * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
    * import {createStore} from 'tinybase';
-   * import {usePowerSync} from '@journeyapps/powersync-react';
+   * import {usePowerSync} from '@powersync/react';
    *
    * const ps = usePowerSync();
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -98,7 +98,7 @@ export interface PowerSyncPersister extends Persister {
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -134,7 +134,7 @@ export interface PowerSyncPersister extends Persister {
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

package/@types/persisters/persister-powersync/index.d.ts

@@ -9,7 +9,7 @@
  */
 
 import type {DatabasePersisterConfig, Persister} from '../index.d.ts';
-import type {AbstractPowerSyncDatabase} from '@journeyapps/powersync-sdk-common';
+import type {AbstractPowerSyncDatabase} from '@powersync/common';
 import type {Store} from '../../store/index.d.ts';
 
 /**
@@ -38,7 +38,7 @@ export interface PowerSyncPersister extends Persister {
    * ```js yolo
    * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
    * import {createStore} from 'tinybase';
-   * import {usePowerSync} from '@journeyapps/powersync-react';
+   * import {usePowerSync} from '@powersync/react';
    *
    * const ps = usePowerSync();
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -98,7 +98,7 @@ export interface PowerSyncPersister extends Persister {
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -134,7 +134,7 @@ export interface PowerSyncPersister extends Persister {
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

package/@types/persisters/persister-powersync/with-schemas/index.d.cts

@@ -16,7 +16,7 @@ import type {
   OptionalSchemas,
   Store,
 } from '../../../store/with-schemas/index.d.cts';
-import type {AbstractPowerSyncDatabase} from '@journeyapps/powersync-sdk-common';
+import type {AbstractPowerSyncDatabase} from '@powersync/common';
 
 /**
  * The PowerSyncPersister interface represents a Persister that lets you save
@@ -45,7 +45,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
    * ```js yolo
    * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
    * import {createStore} from 'tinybase';
-   * import {usePowerSync} from '@journeyapps/powersync-react';
+   * import {usePowerSync} from '@powersync/react';
    *
    * const ps = usePowerSync();
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -117,7 +117,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -153,7 +153,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

package/@types/persisters/persister-powersync/with-schemas/index.d.ts

@@ -16,7 +16,7 @@ import type {
   OptionalSchemas,
   Store,
 } from '../../../store/with-schemas/index.d.ts';
-import type {AbstractPowerSyncDatabase} from '@journeyapps/powersync-sdk-common';
+import type {AbstractPowerSyncDatabase} from '@powersync/common';
 
 /**
  * The PowerSyncPersister interface represents a Persister that lets you save
@@ -45,7 +45,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
    * ```js yolo
    * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
    * import {createStore} from 'tinybase';
-   * import {usePowerSync} from '@journeyapps/powersync-react';
+   * import {usePowerSync} from '@powersync/react';
    *
    * const ps = usePowerSync();
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -117,7 +117,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -153,7 +153,7 @@ export interface PowerSyncPersister<Schemas extends OptionalSchemas>
  * ```js yolo
  * import {createPowerSyncPersister} from 'tinybase/persisters/persister-powersync';
  * import {createStore} from 'tinybase';
- * import {usePowerSync} from '@journeyapps/powersync-react';
+ * import {usePowerSync} from '@powersync/react';
  *
  * const ps = usePowerSync();
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

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

@@ -81,6 +81,12 @@ 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.
  *
+ * Instead of the raw browser implementation of WebSocket You may prefer to use
+ * the [Reconnecting
+ * WebSocket](https://github.com/pladaria/reconnecting-websocket) wrapper so
+ * that if a client goes offline, it can easily re-establish a connection when
+ * it comes back online. Its API is compatible with this Synchronizer.
+ *
  * 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.

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

@@ -81,6 +81,12 @@ 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.
  *
+ * Instead of the raw browser implementation of WebSocket You may prefer to use
+ * the [Reconnecting
+ * WebSocket](https://github.com/pladaria/reconnecting-websocket) wrapper so
+ * that if a client goes offline, it can easily re-establish a connection when
+ * it comes back online. Its API is compatible with this Synchronizer.
+ *
  * 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.

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

@@ -97,6 +97,12 @@ 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.
  *
+ * Instead of the raw browser implementation of WebSocket You may prefer to use
+ * the [Reconnecting
+ * WebSocket](https://github.com/pladaria/reconnecting-websocket) wrapper so
+ * that if a client goes offline, it can easily re-establish a connection when
+ * it comes back online. Its API is compatible with this Synchronizer.
+ *
  * 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.

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

@@ -97,6 +97,12 @@ 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.
  *
+ * Instead of the raw browser implementation of WebSocket You may prefer to use
+ * the [Reconnecting
+ * WebSocket](https://github.com/pladaria/reconnecting-websocket) wrapper so
+ * that if a client goes offline, it can easily re-establish a connection when
+ * it comes back online. Its API is compatible with this Synchronizer.
+ *
  * 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.

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

@@ -11,6 +11,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 {MergeableStore} from '../../mergeable-store/index.d.cts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -509,10 +510,20 @@ export interface WsServer {
  * 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.
+ *
+ * It is not safe to add or manipulate data in the MergeableStore during the
+ * `createPersisterForPath` function, since changes will probably be overwritten
+ * when the Persister starts. If you wish to modify data - or upgrade a schema,
+ * for example - you can have that function instead return an array containing
+ * the Persister _and_ a callback that takes the MergeableStore. That callback
+ * will get called after the Persister has started, and is an appropriate place
+ * to manipulate data in a way that will be transmitted to clients. Again, 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.
+ * Persister to synchronize with the clients on a given path (or a two-item
+ * array of Persister and callback that lets you handle data after persistence
+ * has started).
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -574,7 +585,10 @@ export interface WsServer {
  * const server = createWsServer(
  *   new WebSocketServer({port: 8047}),
  *   (pathId) =>
- *     createFilePersister(createMergeableStore(), pathId + '.json'),
+ *     createFilePersister(
+ *       createMergeableStore(),
+ *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
  * );
  *
  * // Client 1
@@ -626,6 +640,49 @@ export interface WsServer {
  * rmSync('petShop.json');
  * ```
  * @example
+ * This example creates a WsServer that persists a MergeableStore to file that
+ * is synchronized with two clients on a shared path, but also which updates its
+ * data once synchronization has started.
+ *
+ * ```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.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
+ *     (store) => store.setValue('pathId', pathId),
+ *   ],
+ * );
+ *
+ * const clientStore = createMergeableStore();
+ * clientStore.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer = await createWsSynchronizer(
+ *   clientStore,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer.startSync();
+ * // ...
+ *
+ * console.log(clientStore.getContent());
+ * // -> [{pets: {fido: {species: 'dog'}}}, {"pathId": "petShop"}]
+ *
+ * synchronizer.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.
  *
@@ -661,5 +718,10 @@ export function createWsServer<
   >,
 >(
   webSocketServer: WebSocketServer,
-  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+  createPersisterForPath?: (
+    pathId: Id,
+  ) =>
+    | PathPersister
+    | [PathPersister, (store: MergeableStore) => void]
+    | undefined,
 ): WsServer;

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

@@ -11,6 +11,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 {MergeableStore} from '../../mergeable-store/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -509,10 +510,20 @@ export interface WsServer {
  * 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.
+ *
+ * It is not safe to add or manipulate data in the MergeableStore during the
+ * `createPersisterForPath` function, since changes will probably be overwritten
+ * when the Persister starts. If you wish to modify data - or upgrade a schema,
+ * for example - you can have that function instead return an array containing
+ * the Persister _and_ a callback that takes the MergeableStore. That callback
+ * will get called after the Persister has started, and is an appropriate place
+ * to manipulate data in a way that will be transmitted to clients. Again, 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.
+ * Persister to synchronize with the clients on a given path (or a two-item
+ * array of Persister and callback that lets you handle data after persistence
+ * has started).
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -574,7 +585,10 @@ export interface WsServer {
  * const server = createWsServer(
  *   new WebSocketServer({port: 8047}),
  *   (pathId) =>
- *     createFilePersister(createMergeableStore(), pathId + '.json'),
+ *     createFilePersister(
+ *       createMergeableStore(),
+ *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
  * );
  *
  * // Client 1
@@ -626,6 +640,49 @@ export interface WsServer {
  * rmSync('petShop.json');
  * ```
  * @example
+ * This example creates a WsServer that persists a MergeableStore to file that
+ * is synchronized with two clients on a shared path, but also which updates its
+ * data once synchronization has started.
+ *
+ * ```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.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
+ *     (store) => store.setValue('pathId', pathId),
+ *   ],
+ * );
+ *
+ * const clientStore = createMergeableStore();
+ * clientStore.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer = await createWsSynchronizer(
+ *   clientStore,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer.startSync();
+ * // ...
+ *
+ * console.log(clientStore.getContent());
+ * // -> [{pets: {fido: {species: 'dog'}}}, {"pathId": "petShop"}]
+ *
+ * synchronizer.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.
  *
@@ -661,5 +718,10 @@ export function createWsServer<
   >,
 >(
   webSocketServer: WebSocketServer,
-  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+  createPersisterForPath?: (
+    pathId: Id,
+  ) =>
+    | PathPersister
+    | [PathPersister, (store: MergeableStore) => void]
+    | undefined,
 ): WsServer;

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

@@ -17,6 +17,7 @@ import type {
   Persister,
   Persists,
 } from '../../../persisters/with-schemas/index.d.cts';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.cts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -511,7 +512,12 @@ export interface WsServer {
  *   >,
  * >(
  *   webSocketServer: WebSocketServer,
- *   createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+ *   createPersisterForPath?: (
+ *     pathId: Id,
+ *   ) =>
+ *     | PathPersister
+ *     | [PathPersister, (store: MergeableStore) => void]
+ *     | undefined,
  * ): WsServer;
  * ```
  *
@@ -528,10 +534,20 @@ export interface WsServer {
  * 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.
+ *
+ * It is not safe to add or manipulate data in the MergeableStore during the
+ * `createPersisterForPath` function, since changes will probably be overwritten
+ * when the Persister starts. If you wish to modify data - or upgrade a schema,
+ * for example - you can have that function instead return an array containing
+ * the Persister _and_ a callback that takes the MergeableStore. That callback
+ * will get called after the Persister has started, and is an appropriate place
+ * to manipulate data in a way that will be transmitted to clients. Again, 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.
+ * Persister to synchronize with the clients on a given path (or a two-item
+ * array of Persister and callback that lets you handle data after persistence
+ * has started).
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -593,7 +609,10 @@ export interface WsServer {
  * const server = createWsServer(
  *   new WebSocketServer({port: 8047}),
  *   (pathId) =>
- *     createFilePersister(createMergeableStore(), pathId + '.json'),
+ *     createFilePersister(
+ *       createMergeableStore(),
+ *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
  * );
  *
  * // Client 1
@@ -645,6 +664,49 @@ export interface WsServer {
  * rmSync('petShop.json');
  * ```
  * @example
+ * This example creates a WsServer that persists a MergeableStore to file that
+ * is synchronized with two clients on a shared path, but also which updates its
+ * data once synchronization has started.
+ *
+ * ```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.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
+ *     (store) => store.setValue('pathId', pathId),
+ *   ],
+ * );
+ *
+ * const clientStore = createMergeableStore();
+ * clientStore.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer = await createWsSynchronizer(
+ *   clientStore,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer.startSync();
+ * // ...
+ *
+ * console.log(clientStore.getContent());
+ * // -> [{pets: {fido: {species: 'dog'}}}, {"pathId": "petShop"}]
+ *
+ * synchronizer.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.
  *
@@ -682,5 +744,10 @@ export function createWsServer<
   >,
 >(
   webSocketServer: WebSocketServer,
-  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+  createPersisterForPath?: (
+    pathId: Id,
+  ) =>
+    | PathPersister
+    | [PathPersister, (store: MergeableStore<Schemas>) => void]
+    | undefined,
 ): WsServer;

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

@@ -17,6 +17,7 @@ import type {
   Persister,
   Persists,
 } from '../../../persisters/with-schemas/index.d.ts';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
 /**
@@ -511,7 +512,12 @@ export interface WsServer {
  *   >,
  * >(
  *   webSocketServer: WebSocketServer,
- *   createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+ *   createPersisterForPath?: (
+ *     pathId: Id,
+ *   ) =>
+ *     | PathPersister
+ *     | [PathPersister, (store: MergeableStore) => void]
+ *     | undefined,
  * ): WsServer;
  * ```
  *
@@ -528,10 +534,20 @@ export interface WsServer {
  * 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.
+ *
+ * It is not safe to add or manipulate data in the MergeableStore during the
+ * `createPersisterForPath` function, since changes will probably be overwritten
+ * when the Persister starts. If you wish to modify data - or upgrade a schema,
+ * for example - you can have that function instead return an array containing
+ * the Persister _and_ a callback that takes the MergeableStore. That callback
+ * will get called after the Persister has started, and is an appropriate place
+ * to manipulate data in a way that will be transmitted to clients. Again, 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.
+ * Persister to synchronize with the clients on a given path (or a two-item
+ * array of Persister and callback that lets you handle data after persistence
+ * has started).
  * @returns A reference to the new WsServer object.
  * @example
  * This example creates a WsServer that synchronizes two clients on a shared
@@ -593,7 +609,10 @@ export interface WsServer {
  * const server = createWsServer(
  *   new WebSocketServer({port: 8047}),
  *   (pathId) =>
- *     createFilePersister(createMergeableStore(), pathId + '.json'),
+ *     createFilePersister(
+ *       createMergeableStore(),
+ *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
  * );
  *
  * // Client 1
@@ -645,6 +664,49 @@ export interface WsServer {
  * rmSync('petShop.json');
  * ```
  * @example
+ * This example creates a WsServer that persists a MergeableStore to file that
+ * is synchronized with two clients on a shared path, but also which updates its
+ * data once synchronization has started.
+ *
+ * ```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.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *     ),
+ *     (store) => store.setValue('pathId', pathId),
+ *   ],
+ * );
+ *
+ * const clientStore = createMergeableStore();
+ * clientStore.setCell('pets', 'fido', 'species', 'dog');
+ * const synchronizer = await createWsSynchronizer(
+ *   clientStore,
+ *   new WebSocket('ws://localhost:8047/petShop'),
+ * );
+ * await synchronizer.startSync();
+ * // ...
+ *
+ * console.log(clientStore.getContent());
+ * // -> [{pets: {fido: {species: 'dog'}}}, {"pathId": "petShop"}]
+ *
+ * synchronizer.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.
  *
@@ -682,5 +744,10 @@ export function createWsServer<
   >,
 >(
   webSocketServer: WebSocketServer,
-  createPersisterForPath?: (pathId: Id) => PathPersister | undefined,
+  createPersisterForPath?: (
+    pathId: Id,
+  ) =>
+    | PathPersister
+    | [PathPersister, (store: MergeableStore<Schemas>) => void]
+    | undefined,
 ): WsServer;

package/cjs/es6/min/checkpoints/index.cjs

@@ -1 +1 @@
-"use strict";const e=e=>null==e,n=(n,t,l)=>e(n)?void 0:t(n),t=e=>e.length,l=(e,n)=>e.includes(n),r=(e,n)=>e.forEach(n),s=e=>0==t(e),o=(e,...n)=>e.push(...n),u=e=>e.pop(),i=e=>e.shift(),c=Object.freeze,d=e=>{var n;return null!=(n=null==e?void 0:e.size)?n:0},a=(v=d,e=>{return n=(e,n)=>e+v(n),k(e).reduce(n,0);var n});var v;const h=(e,n)=>{var t;return null!=(t=null==e?void 0:e.has(n))&&t},p=n=>e(n)||0==d(n),k=e=>{var n;return[...null!=(n=null==e?void 0:e.values())?n:[]]},g=(e,n)=>null==e?void 0:e.forEach(n),C=(e,n)=>null==e?void 0:e.delete(n),f=e=>new Map(e),L=(e,n)=>null==e?void 0:e.get(n),w=(n,t,l)=>e(l)?(C(n,t),n):null==n?void 0:n.set(t,l),S=(e,n,t,l)=>(h(e,n)?null==l||l(L(e,n)):w(e,n,t()),L(e,n)),y=(e,l,r,s,o=0)=>n((r?S:L)(e,l[o],o>t(l)-2?r:f),(n=>{if(o>t(l)-2)return(null==s?void 0:s(n))&&w(e,l[o]),n;const u=y(n,l,r,s,o+1);return p(n)&&w(e,l[o]),u})),z=n=>new Set(Array.isArray(n)||e(n)?n:[n]),E=/^\d+$/,I=((d,v)=>{const k=new WeakMap;return d=>{k.has(d)||k.set(d,(d=>{let v,k,I,V=100,A=f(),F=f(),M=1;const _=f(),b=f(),[j,x,B]=(l=>{let s;const[u,c]=(()=>{const e=[];let n=0;return[t=>{var l;return null!=(l=t?i(e):null)?l:""+n++},n=>{E.test(n)&&t(e)<1e3&&o(e,n)}]})(),d=f();return[(e,n,t,l=[],r=(()=>[]))=>{null!=s||(s=ee);const o=u(1);var i,c;return w(d,o,[e,n,t,l,r]),c=o,null==(i=y(n,null!=t?t:[""],z))||i.add(c),o},(e,n,...l)=>r(((e,n=[""])=>{const l=[],s=(e,u)=>u==t(n)?o(l,e):null===n[u]?g(e,(e=>s(e,u+1))):r([n[u],null],(n=>s(L(e,n),u+1)));return s(e,0),l})(e,n),(e=>g(e,(e=>L(d,e)[0](s,...null!=n?n:[],...l))))),e=>n(L(d,e),(([,n,t])=>(y(n,null!=t?t:[""],void 0,(n=>(C(n,e),p(n)?1:0))),w(d,e),c(e),t))),l=>n(L(d,l),(([n,,l=[],o,u])=>{const i=(...c)=>{var d,a;const v=t(c);v==t(l)?n(s,...c,...u(c)):e(l[v])?r(null!=(a=null==(d=o[v])?void 0:d.call(o,...c))?a:[],(e=>i(...c,e))):i(...c,l[v])};i()}))]})(),O=f(),T=f(),W=[],$=[],m=(n,t)=>{M=0,d.transaction((()=>{const[l,r]=L(O,t);g(l,((t,l)=>g(t,((t,r)=>g(t,((t,s)=>((n,t,l,r,s)=>e(s)?n.delCell(t,l,r,!0):n.setCell(t,l,r,s))(d,l,r,s,t[n]))))))),g(r,((t,l)=>((n,t,l)=>e(l)?n.delValue(t):n.setValue(t,l))(d,l,t[n])))})),M=1},q=e=>{w(O,e),w(T,e),x(b,[e])},D=(e,n)=>r(((e,n)=>e.splice(0,n))(e,null!=n?n:t(e)),q),G=()=>D(W,t(W)-V),H=()=>n(v,(()=>{o(W,v),G(),D($),v=void 0,I=1})),J=()=>{v=u(W),I=1};let K,N;const P=(n="")=>(e(v)&&(v=""+k++,w(O,v,[A,F]),Y(v,n),A=f(),F=f(),I=1),v),Q=()=>{s(W)||(((e,...n)=>{e.unshift(...n)})($,P()),m(0,v),v=u(W),I=1)},R=()=>{s($)||(o(W,v),v=i($),m(1,v),I=1)},U=()=>{I&&(x(_),I=0)},X=e=>{const n=P(e);return U(),n},Y=(e,n)=>(Z(e)&&L(T,e)!==n&&(w(T,e,n),x(b,[e])),ee),Z=e=>h(O,e),ee={setSize:e=>(V=e,G(),ee),addCheckpoint:X,setCheckpoint:Y,getStore:()=>d,getCheckpointIds:()=>[[...W],v,[...$]],forEachCheckpoint:e=>{return n=e,g(T,((e,t)=>n(t,e)));var n},hasCheckpoint:Z,getCheckpoint:e=>L(T,e),goBackward:()=>(Q(),U(),ee),goForward:()=>(R(),U(),ee),goTo:n=>{const t=l(W,n)?Q:l($,n)?R:null;for(;!e(t)&&n!=v;)t();return U(),ee},addCheckpointIdsListener:e=>j(e,_),addCheckpointListener:(e,n)=>j(n,b,[e]),delListener:e=>(B(e),ee),clear:()=>(D(W),D($),e(v)||q(v),v=void 0,k=0,X(),ee),clearForward:()=>(s($)||(D($),x(_)),ee),destroy:()=>{d.delListener(K),d.delListener(N)},getListenerStats:()=>({checkpointIds:a(_),checkpoint:a(b)}),_registerListeners:()=>{K=d.addCellListener(null,null,null,((e,n,t,l,r,s)=>{if(M){H();const e=S(A,n,f),o=S(e,t,f),u=S(o,l,(()=>[s,void 0]));u[1]=r,u[0]===r&&p(w(o,l))&&p(w(e,t))&&p(w(A,n))&&J(),U()}})),N=d.addValueListener(null,((e,n,t,l)=>{if(M){H();const e=S(F,n,(()=>[l,void 0]));e[1]=t,e[0]===t&&p(w(F,n))&&J(),U()}}))}};return c(ee.clear())})(d));const I=k.get(d);return null==v||v(I),I}})(0,(e=>e._registerListeners()));exports.createCheckpoints=I;
+"use strict";const e=e=>null==e,n=(n,t,l)=>e(n)?void 0:t(n),t=e=>e.length,l=(e,n)=>e.includes(n),r=(e,n)=>e.forEach(n),s=e=>0==t(e),o=(e,...n)=>e.push(...n),u=e=>e.pop(),i=e=>e.shift(),c=Object.freeze,d=e=>{var n;return null!=(n=null==e?void 0:e.size)?n:0},a=(v=d,e=>{return n=(e,n)=>e+v(n),k(e).reduce(n,0);var n});var v;const h=(e,n)=>{var t;return null!=(t=null==e?void 0:e.has(n))&&t},p=n=>e(n)||0==d(n),k=e=>{var n;return[...null!=(n=null==e?void 0:e.values())?n:[]]},g=(e,n)=>null==e?void 0:e.forEach(n),C=(e,n)=>null==e?void 0:e.delete(n),f=e=>new Map(e),L=(e,n)=>null==e?void 0:e.get(n),w=(n,t,l)=>e(l)?(C(n,t),n):null==n?void 0:n.set(t,l),S=(e,n,t,l)=>(h(e,n)?null==l||l(L(e,n)):w(e,n,t()),L(e,n)),y=(e,l,r,s,o=0)=>n((r?S:L)(e,l[o],o>t(l)-2?r:f),(n=>{if(o>t(l)-2)return(null==s?void 0:s(n))&&w(e,l[o]),n;const u=y(n,l,r,s,o+1);return p(n)&&w(e,l[o]),u})),z=n=>new Set(Array.isArray(n)||e(n)?n:[n]),E=/^\d+$/,I=((d,v)=>{const k=new WeakMap;return d=>{k.has(d)||k.set(d,(d=>{let v,k,I,V=100,A=f(),F=f(),M=1;const _=f(),b=f(),[j,x,B]=(()=>{let l;const[s,u]=(()=>{const e=[];let n=0;return[t=>{var l;return null!=(l=t?i(e):null)?l:""+n++},n=>{E.test(n)&&t(e)<1e3&&o(e,n)}]})(),c=f();return[(e,n,t,r=[],o=()=>[])=>{null!=l||(l=ee);const u=s(1);var i,d;return w(c,u,[e,n,t,r,o]),d=u,null==(i=y(n,null!=t?t:[""],z))||i.add(d),u},(e,n,...s)=>r(((e,n=[""])=>{const l=[],s=(e,u)=>u==t(n)?o(l,e):null===n[u]?g(e,(e=>s(e,u+1))):r([n[u],null],(n=>s(L(e,n),u+1)));return s(e,0),l})(e,n),(e=>g(e,(e=>L(c,e)[0](l,...null!=n?n:[],...s))))),e=>n(L(c,e),(([,n,t])=>(y(n,null!=t?t:[""],void 0,(n=>(C(n,e),p(n)?1:0))),w(c,e),u(e),t))),s=>n(L(c,s),(([n,,s=[],o,u])=>{const i=(...c)=>{var d,a;const v=t(c);v==t(s)?n(l,...c,...u(c)):e(s[v])?r(null!=(a=null==(d=o[v])?void 0:d.call(o,...c))?a:[],(e=>i(...c,e))):i(...c,s[v])};i()}))]})(),O=f(),T=f(),W=[],$=[],m=(n,t)=>{M=0,d.transaction((()=>{const[l,r]=L(O,t);g(l,((t,l)=>g(t,((t,r)=>g(t,((t,s)=>((n,t,l,r,s)=>e(s)?n.delCell(t,l,r,!0):n.setCell(t,l,r,s))(d,l,r,s,t[n]))))))),g(r,((t,l)=>((n,t,l)=>e(l)?n.delValue(t):n.setValue(t,l))(d,l,t[n])))})),M=1},q=e=>{w(O,e),w(T,e),x(b,[e])},D=(e,n)=>r(((e,n)=>e.splice(0,n))(e,null!=n?n:t(e)),q),G=()=>D(W,t(W)-V),H=()=>n(v,(()=>{o(W,v),G(),D($),v=void 0,I=1})),J=()=>{v=u(W),I=1};let K,N;const P=(n="")=>(e(v)&&(v=""+k++,w(O,v,[A,F]),Y(v,n),A=f(),F=f(),I=1),v),Q=()=>{s(W)||(((e,...n)=>{e.unshift(...n)})($,P()),m(0,v),v=u(W),I=1)},R=()=>{s($)||(o(W,v),v=i($),m(1,v),I=1)},U=()=>{I&&(x(_),I=0)},X=e=>{const n=P(e);return U(),n},Y=(e,n)=>(Z(e)&&L(T,e)!==n&&(w(T,e,n),x(b,[e])),ee),Z=e=>h(O,e),ee={setSize:e=>(V=e,G(),ee),addCheckpoint:X,setCheckpoint:Y,getStore:()=>d,getCheckpointIds:()=>[[...W],v,[...$]],forEachCheckpoint:e=>{return n=e,g(T,((e,t)=>n(t,e)));var n},hasCheckpoint:Z,getCheckpoint:e=>L(T,e),goBackward:()=>(Q(),U(),ee),goForward:()=>(R(),U(),ee),goTo:n=>{const t=l(W,n)?Q:l($,n)?R:null;for(;!e(t)&&n!=v;)t();return U(),ee},addCheckpointIdsListener:e=>j(e,_),addCheckpointListener:(e,n)=>j(n,b,[e]),delListener:e=>(B(e),ee),clear:()=>(D(W),D($),e(v)||q(v),v=void 0,k=0,X(),ee),clearForward:()=>(s($)||(D($),x(_)),ee),destroy:()=>{d.delListener(K),d.delListener(N)},getListenerStats:()=>({checkpointIds:a(_),checkpoint:a(b)}),_registerListeners:()=>{K=d.addCellListener(null,null,null,((e,n,t,l,r,s)=>{if(M){H();const e=S(A,n,f),o=S(e,t,f),u=S(o,l,(()=>[s,void 0]));u[1]=r,u[0]===r&&p(w(o,l))&&p(w(e,t))&&p(w(A,n))&&J(),U()}})),N=d.addValueListener(null,((e,n,t,l)=>{if(M){H();const e=S(F,n,(()=>[l,void 0]));e[1]=t,e[0]===t&&p(w(F,n))&&J(),U()}}))}};return c(ee.clear())})(d));const I=k.get(d);return null==v||v(I),I}})(0,(e=>e._registerListeners()));exports.createCheckpoints=I;