tinybase 5.0.0-beta.1 → 5.0.0-beta.11

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

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

@@ -0,0 +1,35 @@
+/**
+ * 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 {Synchronizer} from '../synchronizers';
+import {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/lib/types/synchronizers/synchronizer-ws-server.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {Id, IdOrNull, Ids} from '../common';
+import {GetIdChanges} from '../store';
+import {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/lib/types/synchronizers.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 {Id, IdOrNull} from './common';
+import {Content} from './store';
+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: 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 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(
+  store: MergeableStore,
+  send: Send,
+  onReceive: (receive: Receive) => void,
+  destroy: () => void,
+  requestTimeoutSeconds: number,
+  onIgnoredError?: (error: any) => void,
+): Synchronizer;

package/lib/types/tinybase.d.ts

@@ -3,11 +3,13 @@
  * @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 './synchronizers.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/tools.d.ts

@@ -9,8 +9,8 @@
  * @since v2.2.0
  */
 
-import {Store, TablesSchema, ValuesSchema} from './store.d';
-import {Id} from './common.d';
+import {Store, TablesSchema, ValuesSchema} from './store.d.ts';
+import {Id} from './common.d.ts';
 
 /**
  * The StoreStats type describes a set of statistics about the Store, and
@@ -417,7 +417,7 @@ export interface Tools {
    *   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');
@@ -437,7 +437,7 @@ export interface Tools {
    *   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');

package/lib/types/ui-react.d.ts

@@ -22,7 +22,7 @@
  * @module ui-react
  */
 
-import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common.d';
+import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common.d.ts';
 import {
   Cell,
   CellIdsListener,
@@ -56,22 +56,22 @@ import {
   ValueOrUndefined,
   Values,
   ValuesListener,
-} from './store.d';
+} from './store.d.ts';
 import {
   CheckpointIds,
   CheckpointIdsListener,
   CheckpointListener,
   Checkpoints,
-} from './checkpoints.d';
+} from './checkpoints.d.ts';
 import {ComponentType, ReactElement} from 'react';
-import {Indexes, SliceIdsListener, SliceRowIdsListener} from './indexes.d';
+import {Indexes, SliceIdsListener, SliceRowIdsListener} from './indexes.d.ts';
 import {
   LinkedRowIdsListener,
   LocalRowIdsListener,
   Relationships,
   RemoteRowIdListener,
-} from './relationships.d';
-import {MetricListener, Metrics} from './metrics.d';
+} from './relationships.d.ts';
+import {MetricListener, Metrics} from './metrics.d.ts';
 import {
   Queries,
   ResultCellIdsListener,
@@ -82,8 +82,10 @@ import {
   ResultSortedRowIdsListener,
   ResultTableCellIdsListener,
   ResultTableListener,
-} from './queries.d';
-import {Persister} from './persisters.d';
+} from './queries.d.ts';
+import {MergeableStore} from './mergeable-store';
+import {Persister} from './persisters.d.ts';
+import {Synchronizer} from './synchronizers';
 
 /**
  * The StoreOrStoreId type is used when you need to refer to a Store in a React
@@ -212,6 +214,7 @@ export type UndoOrRedoInformation = [boolean, Callback, Id | undefined, string];
  * useSetTableCallback hook or useSetRowCallback hook - so that the Id arguments
  * of the object to set can also be dependent on the event or parameter
  * provided (as well as the object itself being set).
+ * @category Identity
  */
 export type GetId<Parameter> = (parameter: Parameter, store: Store) => Id;
 
@@ -300,6 +303,14 @@ export function useCreateStore(
   createDeps?: React.DependencyList,
 ): Store;
 
+/**
+ * The useCreateMergeableStore hook
+ */
+export function useCreateMergeableStore(
+  create: () => MergeableStore,
+  createDeps?: React.DependencyList,
+): MergeableStore;
+
 /**
  * The useStoreIds hook is used to retrieve the Ids of all the named Store
  * objects present in the current Provider component context.
@@ -10196,8 +10207,8 @@ export function useCheckpointListener(
  * // -> '<span>{\"pets\":{\"fido\":{\"species\":\"dog\"}}}</span>'
  *
  * root.render(<App sessionKey="cujoStore" />); // !act
- * // -> 'Persister destroyed for session key fidoStore'
  * // -> 'Persister created for session key cujoStore'
+ * // -> 'Persister destroyed for session key fidoStore'
  *
  * // ... // !act
  * console.log(app.innerHTML);
@@ -10220,6 +10231,146 @@ export function useCreatePersister<
   destroyDeps?: React.DependencyList,
 ): PersisterOrUndefined;
 
+/**
+ * The useCreateSynchronizer hook is used to create a Synchronizer within a
+ * React application along with convenient memoization and callbacks.
+ *
+ * It is possible to create a Synchronizer outside of the React app with the
+ * regular createSynchronizer function and pass it in, but you may prefer to
+ * create it within the app, perhaps inside the top-level component. To prevent
+ * a new Synchronizer being created every time the app renders or re-renders,
+ * the useCreateMetrics hook performs the creation in an effect.
+ *
+ * If your asynchronous `create` function (the second parameter to the hook)
+ * contains dependencies, the changing of which should cause the Synchronizer to
+ * be recreated, you can provide them in an array in the third parameter, just
+ * as you would for any React hook with dependencies. The MergeableStore passed
+ * in as the first parameter of this hook is used as a dependency by default.
+ *
+ * A second callback, called `then`, can be provided as the fourth parameter.
+ * This is called after the creation, and can also be asynchronous, so that you
+ * can configure the Synchronizer with the startSync method, for example. If
+ * this callback contains dependencies, the changing of which should cause the
+ * Synchronizer to be reconfigured, you can provide them in an array in the
+ * fifth parameter. The Synchronizer itself is used as a dependency by default.
+ *
+ * The `create` function can return undefined, meaning that you can enable or
+ * disable synchronization conditionally within this hook. This is useful for
+ * applications which might turn on or off their cloud synchronization or
+ * collaboration features.
+ *
+ * This hook ensures the Synchronizer object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ * @param store A reference to the MergeableStore for which to create a new
+ * Synchronizer object.
+ * @param create An asynchronous function for performing the creation steps of
+ * the Synchronizer object for the Store.
+ * @param createDeps An optional array of dependencies for the `create`
+ * function, which, if any change, result in its rerun. This parameter defaults
+ * to an empty array.
+ * @param then An optional callback for performing asynchronous post-creation
+ * steps on the Synchronizer, such as starting automatic synchronization.
+ * @param thenDeps An optional array of dependencies for the `then` callback,
+ * which, if any change, result in its rerun. This parameter defaults to an
+ * empty array.
+ * @param destroy An optional callback whenever the Synchronizer is destroyed
+ * due to a change in the `createDeps` dependencies.
+ * @param destroyDeps An optional array of dependencies for the `destroy`
+ * callback, which, if any change, result in `destroy` and `then` being rerun.
+ * This parameter defaults to an empty array.
+ * @returns A reference to the Synchronizer.
+ * @example
+ * This example creates a Synchronizer at the top level of a React application.
+ * Even though the App component is rendered twice, the Synchronizer creation
+ * only occurs once by default.
+ *
+ * ```jsx
+ * const App = () => {
+ *   const store = useCreateMergeableStore(() => createMergeableStore('s1'));
+ *   const synchronizer = useCreateSynchronizer(store, async (store) => {
+ *     console.log('Synchronizer created');
+ *     return await createLocalSynchronizer(store, 'pets');
+ *   });
+ *   return <span>{JSON.stringify(useTables(store))}</span>;
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App />); // !act
+ * // -> 'Synchronizer created'
+ *
+ * // ... // !act
+ * root.render(<App />); // !act
+ * // No second Synchronizer creation
+ *
+ * root.unmount(); // !act
+ * ```
+ * @example
+ * This example creates a Synchronizer at the top level of a React application.
+ * The App component is rendered twice, each with a different top-level prop.
+ * The useCreateSynchronizer hook takes the `url` prop as a dependency, and so
+ * the Synchronizer object is created again on the second render. The first is
+ * destroyed and the `destroy` parameter is called for it.  A `then` parameter
+ * is provided to start both Synchronizers' synchronization.
+ *
+ * ```jsx
+ * const server1 = createWsServer(new ws.WebSocketServer({port: 8044}));
+ * const server2 = createWsServer(new ws.WebSocketServer({port: 8045}));
+ *
+ * const App = ({url}) => {
+ *   const store = useCreateMergeableStore(() => createMergeableStore('s1'));
+ *   const synchronizer = useCreateSynchronizer(
+ *     store,
+ *     async (store) => {
+ *       const webSocket = new WebSocket(url);
+ *       console.log(`Synchronizer created for ${webSocket.url}`);
+ *       return await createWsSynchronizer(store, webSocket);
+ *     },
+ *     [url],
+ *     async (synchronizer) => {
+ *       await synchronizer.startSync();
+ *     },
+ *     [],
+ *     (synchronizer) => {
+ *       const webSocket = synchronizer.getWebSocket();
+ *       console.log(`Synchronizer destroyed for ${webSocket.url}`);
+ *     },
+ *   );
+ *   return <span>{JSON.stringify(useTables(store))}</span>;
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App url="ws://localhost:8044/" />); // !act
+ * // ... // !act
+ * // -> 'Synchronizer created for ws://localhost:8044/'
+ *
+ * root.render(<App url="ws://localhost:8045/" />); // !act
+ * // ... // !act
+ * // -> 'Synchronizer created for ws://localhost:8045/'
+ * // -> 'Synchronizer destroyed for ws://localhost:8044/'
+ *
+ * root.unmount(); // !act
+ * // -> 'Synchronizer destroyed for ws://localhost:8045/'
+ *
+ * server1.destroy();
+ * server2.destroy();
+ * ```
+ * @category Synchronizer hooks
+ * @since v5.0.0
+ */
+export function useCreateSynchronizer<
+  SynchronizerOrUndefined extends Synchronizer | undefined,
+>(
+  store: MergeableStore,
+  create: (store: MergeableStore) => Promise<SynchronizerOrUndefined>,
+  createDeps?: React.DependencyList,
+  then?: (synchronizer: Synchronizer) => Promise<void>,
+  thenDeps?: React.DependencyList,
+  destroy?: (synchronizer: Synchronizer) => void,
+  destroyDeps?: React.DependencyList,
+): SynchronizerOrUndefined;
+
 /**
  * The ExtraProps type represents a set of arbitrary additional props.
  * @category Props

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

@@ -10,8 +10,8 @@
  * @module checkpoints
  */
 
-import {Id, IdOrNull, Ids} from './common.d';
-import {OptionalSchemas, Store} from './store.d';
+import {Id, IdOrNull, Ids} from './common.d.ts';
+import {OptionalSchemas, Store} from './store.d.ts';
 
 /**
  * The CheckpointIds type is a representation of the list of checkpoint Ids

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

@@ -17,8 +17,8 @@ import {
   OptionalTablesSchema,
   RowCallback,
   Store,
-} from './store.d';
-import {Id, IdOrNull, Ids, SortKey} from './common.d';
+} from './store.d.ts';
+import {Id, IdOrNull, Ids, SortKey} from './common.d.ts';
 
 /**
  * The Index type represents the concept of a map of Slice objects, keyed by Id.

package/lib/types/with-schemas/internal/store.d.ts

@@ -1,7 +1,9 @@
 import {
   Cell,
+  OptionalSchemas,
   OptionalTablesSchema,
   OptionalValuesSchema,
+  Store,
   Value,
 } from '../store';
 import {Id} from '../common';
@@ -100,3 +102,5 @@ export type Truncate<Params> = Params extends [...infer ShorterParams, any]
   : never;
 
 export type NoInfer<Type> = [Type][Type extends any ? 0 : never];
+
+export type StoreAlias<Schemas extends OptionalSchemas> = Store<Schemas>;