tinybase 5.0.0-beta.0 → 5.0.0-beta.10

package/lib/types/with-schemas/synchronizers/synchronizer-local.d.ts

@@ -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 {MergeableStore} from '../mergeable-store';
+import {OptionalSchemas} from '../store';
+import {Synchronizer} from '../synchronizers';
+
+/**
+ * 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/lib/types/with-schemas/synchronizers/synchronizer-ws-client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ * @packageDocumentation
+ * @module synchronizer-ws-client
+ * @since v5.0.0
+ */
+
+import {MergeableStore} from '../mergeable-store';
+import {OptionalSchemas} from '../store';
+import {Synchronizer} from '../synchronizers';
+import {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/lib/types/with-schemas/synchronizers/synchronizer-ws-server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The synchronizer-ws-server module of the TinyBase project lets you create
+ * a server that facilitates synchronization between clients.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-ws-server
+ * @since v5.0.0
+ */
+
+import {Ids} from '../common';
+import {WebSocketServer} from 'ws';
+
+/**
+ * The WsServerStats type
+ */
+export type WsServerStats = {
+  paths?: number;
+  clients?: number;
+};
+
+/**
+ * The WsServer interface
+ */
+export interface WsServer {
+  getWebSocketServer: () => WebSocketServer;
+  getPaths: () => string[];
+  getClientIds: (path: string) => Ids;
+  getStats: () => WsServerStats;
+  destroy: () => void;
+}
+
+/**
+ * The createWsServer function
+ * @category Creation
+ */
+export function createWsServer(WebSocketServer: WebSocketServer): WsServer;

package/lib/types/with-schemas/synchronizers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 {Content, OptionalSchemas} from './store';
+import {Id, IdOrNull} from './common';
+import {MergeableStore} from './mergeable-store';
+import {Persister} from './persisters';
+
+/**
+ * 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, true> {
+  /**
+   * 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 a `client` parameter which identifies the Client that is used to
+ * transmit changes to and from this MergeableStore and its peers.
+ * @param store The MergeableStore to synchronize.
+ * @param client The reference of the Client.
+ * @param requestTimeoutSeconds An optional number of seconds before a request
+ * to the Client times out, defaulting to 5.
+ * @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
+ * 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>;

package/lib/types/with-schemas/tinybase.d.ts

@@ -3,11 +3,12 @@
  * @packageDocumentation
  */
 
-export * from './checkpoints.d';
-export * from './common.d';
-export * from './indexes.d';
-export * from './metrics.d';
-export * from './persisters.d';
-export * from './queries.d';
-export * from './relationships.d';
-export * from './store.d';
+export * from './checkpoints.d.ts';
+export * from './common.d.ts';
+export * from './indexes.d.ts';
+export * from './metrics.d.ts';
+export * from './persisters.d.ts';
+export * from './queries.d.ts';
+export * from './relationships.d.ts';
+export * from './mergeable-store.d.ts';
+export * from './store.d.ts';

package/lib/types/with-schemas/tools.d.ts

@@ -9,8 +9,8 @@
  * @since v2.2.0
  */
 
-import {OptionalSchemas, Store} from './store.d';
-import {Id} from './common.d';
+import {OptionalSchemas, Store} from './store.d.ts';
+import {Id} from './common.d.ts';
 
 /**
  * The StoreStats type describes a set of statistics about the Store, and
@@ -416,7 +416,7 @@ export interface Tools<in out Schemas extends OptionalSchemas> {
    *   await createTools(store).getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
-   * console.log(dTsLines[17]);
+   * console.log(dTsLines[15]);
    * // -> `export type Tables = {pets?: {[rowId: Id]: {price?: number}}};`
    *
    * const tsLines = ts.split('\n');
@@ -436,7 +436,7 @@ export interface Tools<in out Schemas extends OptionalSchemas> {
    *   await createTools(store).getPrettyStoreApi('shop');
    *
    * const dTsLines = dTs.split('\n');
-   * console.log(dTsLines[17]);
+   * console.log(dTsLines[15]);
    * // -> 'export type Tables = {pets?: {[rowId: Id]: {price: number}}};'
    *
    * const tsLines = ts.split('\n');