tinybase 5.0.0-beta.19 → 5.0.0-beta.20

package/@types/synchronizers/index.d.cts

@@ -0,0 +1,139 @@
+/**
+ * The persister-sync module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizers
+ * @since v5.0.0
+ */
+
+import type {Id, IdOrNull} from '../common/index.d.cts';
+import type {Content} from '../store/index.d.cts';
+import type {MergeableStore} from '../mergeable-store/index.d.cts';
+import type {Persister} from '../persisters/index.d.cts';
+
+/**
+ * The MessageType type
+ * @category Synchronization
+ */
+export type MessageType = number;
+
+/**
+ * The Receive type
+ * @category Synchronization
+ */
+export type Receive = (
+  fromClientId: Id,
+  requestId: IdOrNull,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The Send type
+ * @category Synchronization
+ */
+export type Send = (
+  toClientId: IdOrNull,
+  requestId: IdOrNull,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The SynchronizerStats type
+ * @category Development
+ */
+export type SynchronizerStats = {
+  sends?: number;
+  receives?: number;
+};
+
+/**
+ * The Synchronizer interface is a minor extension to the Persister interface.
+ *
+ * It provides extra convenience methods for starting and stopping the
+ * synchronization.
+ *
+ * You should use the createCustomSynchronizer function to create a Synchronizer
+ * object.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface Synchronizer extends Persister<2> {
+  /**
+   * The startSync method
+   * @category Synchronization
+   */
+  startSync(initialContent?: Content): Promise<this>;
+  /**
+   * The stopSync method
+   * @category Synchronization
+   */
+  stopSync(): this;
+  /**
+   * The getSynchronizerStats method
+   * @category Synchronization
+   */
+  getSynchronizerStats(): SynchronizerStats;
+}
+
+/**
+ * The createCustomSynchronizer function creates a Synchronizer object that can
+ * persist one MergeableStore to another.
+ *
+ * As well as providing a reference to the MergeableStore to synchronize, you
+ * must provide parameters which identify how to send and receive changes to and
+ * from this MergeableStore and its peers.
+ * @param store The MergeableStore to synchronize.
+ * @param send A Send function for sending a message.
+ * @param onReceive A callback to register a Receive function for receiving a
+ * message.
+ * @param destroy A function called when destroying the Persister which can be
+ * used to clean up underlying resources.
+ * @param requestTimeoutSeconds An number of seconds before a request sent from
+ * this Persister to another peer times out.
+ * @param onIgnoredError An optional handler for the errors that the
+ * Synchronizer would otherwise ignore when trying to save or load data. This is
+ * suitable for debugging synchronization issues in a development environment.
+ * @returns A reference to the new Synchronizer object.
+ * @example
+ * This example creates a Synchronizer object and synchronizes one
+ * MergeableStore to another.
+ *
+ * ```js
+ * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore('store1').setTables({
+ *   pets: {fido: {species: 'dog'}},
+ * });
+ * const synchronizer1 = createLocalSynchronizer(store1);
+ *
+ * const store2 = createMergeableStore('store2');
+ * const synchronizer2 = createLocalSynchronizer(store2);
+ * await synchronizer2.startSync();
+ *
+ * await synchronizer1.save();
+ * // ...
+ * // Store2 will be synced with Store1.
+ *
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}}}
+ *
+ * await synchronizer1.load();
+ * // Store1 will be synced with Store2.
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ */
+export function createCustomSynchronizer(
+  store: MergeableStore,
+  send: Send,
+  onReceive: (receive: Receive) => void,
+  destroy: () => void,
+  requestTimeoutSeconds: number,
+  onIgnoredError?: (error: any) => void,
+): Synchronizer;

package/@types/synchronizers/synchronizer-local/index.d.cts

@@ -0,0 +1,27 @@
+/**
+ * The synchronizer-local module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances on the same
+ * local machine.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-local
+ * @since v5.0.0
+ */
+
+import type {MergeableStore} from '../../mergeable-store/index.d.cts';
+import type {Synchronizer} from '../index.d.cts';
+
+/**
+ * The LocalSynchronizer interface
+ * @category Synchronizer
+ */
+export interface LocalSynchronizer extends Synchronizer {}
+
+/**
+ * The createLocalSynchronizer function
+ * @category Creation
+ */
+export function createLocalSynchronizer(
+  store: MergeableStore,
+  onIgnoredError?: (error: any) => void,
+): LocalSynchronizer;

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

@@ -0,0 +1,29 @@
+/**
+ * The synchronizer-local module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances on the same
+ * local machine.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-local
+ * @since v5.0.0
+ */
+
+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';
+
+/**
+ * The LocalSynchronizer interface
+ * @category Synchronizer
+ */
+export interface LocalSynchronizer<Schemas extends OptionalSchemas>
+  extends Synchronizer<Schemas> {}
+
+/**
+ * The createLocalSynchronizer function
+ * @category Creation
+ */
+export function createLocalSynchronizer<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  onIgnoredError?: (error: any) => void,
+): LocalSynchronizer<Schemas>;

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

@@ -0,0 +1,36 @@
+/**
+ * The synchronizer-ws module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances via WebSockets
+ * facilitated by a server.
+ * @see Synchronizing Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-client
+ * @since v5.0.0
+ */
+
+import type {MergeableStore} from '../../mergeable-store/index.d.cts';
+import type {Synchronizer} from '../index.d.cts';
+import type {WebSocket as WsWebSocket} from 'ws';
+
+export type WebSocketTypes = WebSocket | WsWebSocket;
+
+/**
+ * The WsSynchronizer interface
+ * @category Synchronizer
+ */
+export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
+  extends Synchronizer {
+  getWebSocket(): WebSocketType;
+}
+
+/**
+ * The createWsSynchronizer function
+ * @category Creation
+ */
+export function createWsSynchronizer<WebSocketType extends WebSocketTypes>(
+  store: MergeableStore,
+  webSocket: WebSocketType,
+  requestTimeoutSeconds?: number,
+  onIgnoredError?: (error: any) => void,
+): Promise<WsSynchronizer<WebSocketType>>;

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

@@ -0,0 +1,42 @@
+/**
+ * The synchronizer-ws module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances via WebSockets
+ * facilitated by a server.
+ * @see Synchronizing Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-client
+ * @since v5.0.0
+ */
+
+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';
+
+export type WebSocketTypes = WebSocket | WsWebSocket;
+
+/**
+ * The WsSynchronizer interface
+ * @category Synchronizer
+ */
+export interface WsSynchronizer<
+  Schemas extends OptionalSchemas,
+  WebSocketType extends WebSocketTypes,
+> extends Synchronizer<Schemas> {
+  getWebSocket(): WebSocketType;
+}
+
+/**
+ * The createWsSynchronizer function
+ * @category Creation
+ */
+export function createWsSynchronizer<
+  Schemas extends OptionalSchemas,
+  WebSocketType extends WebSocketTypes,
+>(
+  store: MergeableStore<Schemas>,
+  webSocket: WebSocketType,
+  requestTimeoutSeconds?: number,
+  onIgnoredError?: (error: any) => void,
+): Promise<WsSynchronizer<Schemas, WebSocketType>>;

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

@@ -0,0 +1,58 @@
+/**
+ * The synchronizer-ws-server module of the TinyBase project lets you create
+ * a server that facilitates synchronization between clients.
+ * @see Synchronizing Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server
+ * @since v5.0.0
+ */
+
+import type {Id, IdOrNull, Ids} from '../../common/index.d.cts';
+import type {GetIdChanges} from '../../store/index.d.cts';
+import type {WebSocketServer} from 'ws';
+
+/**
+ * The PathIdsListener type
+ */
+export type PathIdsListener<> = (
+  wsServer: WsServer,
+  getIdChanges: GetIdChanges,
+) => void;
+
+/**
+ * The ClientIdsListener type
+ */
+export type ClientIdsListener<> = (
+  wsServer: WsServer,
+  pathId: Id,
+  getIdChanges: GetIdChanges,
+) => void;
+
+/**
+ * The WsServerStats type
+ */
+export type WsServerStats = {
+  paths?: number;
+  clients?: number;
+};
+
+/**
+ * The WsServer interface
+ */
+export interface WsServer {
+  getWebSocketServer: () => WebSocketServer;
+  getPathIds: () => Ids;
+  getClientIds: (pathId: Id) => Ids;
+  addPathIdsListener: (listener: PathIdsListener) => Id;
+  addClientIdsListener: (pathId: IdOrNull, listener: ClientIdsListener) => Id;
+  delListener(listenerId: Id): WsServer;
+  getStats: () => WsServerStats;
+  destroy: () => void;
+}
+
+/**
+ * The createWsServer function
+ * @category Creation
+ */
+export function createWsServer(WebSocketServer: WebSocketServer): WsServer;

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

@@ -0,0 +1,58 @@
+/**
+ * The synchronizer-ws-server module of the TinyBase project lets you create
+ * a server that facilitates synchronization between clients.
+ * @see Synchronizing Data guide
+ * @see Todo App v6 (collaboration) demo
+ * @packageDocumentation
+ * @module synchronizer-ws-server
+ * @since v5.0.0
+ */
+
+import type {Id, IdOrNull, Ids} from '../../../common/with-schemas/index.d.cts';
+import type {GetIdChanges} from '../../../store/with-schemas/index.d.cts';
+import type {WebSocketServer} from 'ws';
+
+/**
+ * The PathIdsListener type
+ */
+export type PathIdsListener<> = (
+  wsServer: WsServer,
+  getIdChanges: GetIdChanges<Id>,
+) => void;
+
+/**
+ * The ClientIdsListener type
+ */
+export type ClientIdsListener<> = (
+  wsServer: WsServer,
+  pathId: Id,
+  getIdChanges: GetIdChanges<Id>,
+) => void;
+
+/**
+ * The WsServerStats type
+ */
+export type WsServerStats = {
+  paths?: number;
+  clients?: number;
+};
+
+/**
+ * The WsServer interface
+ */
+export interface WsServer {
+  getWebSocketServer: () => WebSocketServer;
+  getPathIds: () => Ids;
+  getClientIds: (pathId: Id) => Ids;
+  addPathIdsListener: (listener: PathIdsListener) => Id;
+  addClientIdsListener: (pathId: IdOrNull, listener: ClientIdsListener) => Id;
+  delListener(listenerId: Id): WsServer;
+  getStats: () => WsServerStats;
+  destroy: () => void;
+}
+
+/**
+ * The createWsServer function
+ * @category Creation
+ */
+export function createWsServer(WebSocketServer: WebSocketServer): WsServer;

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

@@ -0,0 +1,156 @@
+/**
+ * The persister-sync module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizers
+ * @since v5.0.0
+ */
+
+import type {
+  Content,
+  OptionalSchemas,
+} from '../../store/with-schemas/index.d.cts';
+import type {Id, IdOrNull} from '../../common/with-schemas/index.d.cts';
+import type {MergeableStore} from '../../mergeable-store/with-schemas/index.d.cts';
+import type {Persister} from '../../persisters/with-schemas/index.d.cts';
+
+/**
+ * The MessageType type
+ * @category Synchronization
+ */
+export type MessageType = number;
+
+/**
+ * The Receive type
+ * @category Synchronization
+ */
+export type Receive = (
+  fromClientId: Id,
+  requestId: Id,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The Send type
+ * @category Synchronization
+ */
+export type Send = (
+  toClientId: IdOrNull,
+  requestId: Id,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The SynchronizerStats type
+ * @category Development
+ */
+export type SynchronizerStats = {
+  sends?: number;
+  receives?: number;
+};
+
+/**
+ * The Synchronizer interface is a minor extension to the Persister interface.
+ *
+ * It provides extra convenience methods for starting and stopping the
+ * synchronization.
+ *
+ * You should use the createCustomSynchronizer function to create a Synchronizer
+ * object.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface Synchronizer<Schemas extends OptionalSchemas>
+  extends Persister<Schemas, 2> {
+  /**
+   * The startSync method
+   * @category Synchronization
+   */
+  startSync(initialContent?: Content<Schemas, true>): Promise<this>;
+  /**
+   * The stopSync method
+   * @category Synchronization
+   */
+  stopSync(): this;
+  /**
+   * The getSynchronizerStats method
+   * @category Synchronization
+   */
+  getSynchronizerStats(): SynchronizerStats;
+}
+
+/**
+ * The createCustomSynchronizer function creates a Synchronizer object that can
+ * persist one MergeableStore to another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createCustomSynchronizer(
+ *   store: MergeableStore,
+ *   send: Send,
+ *   onReceive: (receive: Receive) => void,
+ *   destroy: () => void,
+ *   requestTimeoutSeconds: number,
+ *   onIgnoredError?: (error: any) => void,
+ * ): Synchronizer;
+ * ```
+ *
+ * As well as providing a reference to the MergeableStore to synchronize, you
+ * must provide parameters which identify how to send and receive changes to and
+ * from this MergeableStore and its peers.
+ * @param store The MergeableStore to synchronize.
+ * @param send A Send function for sending a message.
+ * @param onReceive A callback to register a Receive function for receiving a
+ * message.
+ * @param destroy A function called when destroying the Persister which can be
+ * used to clean up underlying resources.
+ * @param requestTimeoutSeconds An number of seconds before a request sent from
+ * this Persister to another peer times out.
+ * @param onIgnoredError An optional handler for the errors that the
+ * Synchronizer would otherwise ignore when trying to save or load data. This is
+ * suitable for debugging synchronization issues in a development environment.
+ * @returns A reference to the new Synchronizer object.
+ * @example
+ * This example creates a Synchronizer object and synchronizes one
+ * MergeableStore to another.
+ *
+ * ```js
+ * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore('store1').setTables({
+ *   pets: {fido: {species: 'dog'}},
+ * });
+ * const synchronizer1 = createLocalSynchronizer(store1);
+ *
+ * const store2 = createMergeableStore('store2');
+ * const synchronizer2 = createLocalSynchronizer(store2);
+ * await synchronizer2.startSync();
+ *
+ * await synchronizer1.save();
+ * // ...
+ * // Store2 will be synced with Store1.
+ *
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}}}
+ *
+ * await synchronizer1.load();
+ * // Store1 will be synced with Store2.
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ */
+export function createCustomSynchronizer<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  send: Send,
+  onReceive: (receive: Receive) => void,
+  destroy: () => void,
+  requestTimeoutSeconds: number,
+  onIgnoredError?: (error: any) => void,
+): Synchronizer<Schemas>;