tinybase 5.0.0-beta.25 → 5.0.0-beta.27

package/@types/store/with-schemas/index.d.ts

@@ -1224,7 +1224,7 @@ export type HasTableCellListener<
  * the Table whose Row Ids changed, and the number of Row objects in the Table.
  * @param store A reference to the Store that changed.
  * @param tableId The Id of the Table that changed.
- * @param count The number of Row objects in the Table
+ * @param count The number of Row objects in the Table.
  * @category Listener
  * @since v4.1.0
  */
@@ -2419,8 +2419,7 @@ export type TransactionLog<Schemas extends OptionalSchemas> = {
  *
  * The StoreListenerStats object contains a breakdown of the different types of
  * listener. Totals include both mutator and non-mutator listeners. A
- * StoreListenerStats object is returned from the getListenerStats method, and
- * is only populated in a debug build.
+ * StoreListenerStats object is returned from the getListenerStats method.
  * @category Development
  */
 export type StoreListenerStats = {
@@ -2458,7 +2457,7 @@ export type StoreListenerStats = {
   hasTableCell: number;
   /**
    * The number of RowCountListener functions registered with the Store, since
-   * v4.1.0
+   * v4.1.0.
    */
   rowCount: number;
   /**
@@ -2547,7 +2546,7 @@ export type StoreListenerStats = {
  *
  * The keyed value support is best thought of as a flat JavaScript object. The
  * Store contains a number of Value objects, each with a unique ID, and which is
- * a string, boolean, or number:
+ * a string, boolean, or number.
  *
  * ```json
  * {                  // Store
@@ -2631,8 +2630,8 @@ export type StoreListenerStats = {
  * There are two extra methods to manipulate Row objects. The addRow method is
  * like the setRow method but automatically assigns it a new unique Id. And the
  * setPartialRow method lets you update multiple Cell values in a Row without
- * affecting the others. (There is a similar setPartialValues method to do the
- * same for the Values in a Store.)
+ * affecting the others. There is a similar setPartialValues method to do the
+ * same for the Values in a Store.
  *
  * You can listen to attempts to write invalid data to a Value or Cell with the
  * addInvalidValueListener method or addInvalidCellListener method.
@@ -3888,6 +3887,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * can be chained in a fluent style.
    * @param content An array containing the tabular and keyed-value data of the
    * Store to be set.
+   * @returns A reference to the Store.
    * @example
    * This example sets the data of a Store.
    *
@@ -3954,6 +3954,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * The method returns a reference to the Store so that subsequent operations
    * can be chained in a fluent style.
    * @param tables The data of the Store to be set.
+   * @returns A reference to the Store.
    * @example
    * This example sets the tabular data of a Store.
    *
@@ -4014,6 +4015,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * can be chained in a fluent style.
    * @param tableId The Id of the Table in the Store.
    * @param table The data of a single Table to be set.
+   * @returns A reference to the Store.
    * @example
    * This example sets the data of a single Table.
    *
@@ -4133,7 +4135,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *
    * Assuming that at least some of the provided Row object is valid, a new Row
    * will be created. If the object is completely invalid, no change will be
-   * made to the Store and the method will return `undefined`
+   * made to the Store and the method will return `undefined`.
    *
    * You should not guarantee the form of the unique Id that is generated when a
    * Row is added to the Table. However it is likely to be a string
@@ -4543,8 +4545,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * @param changes The Changes to apply to the Store.
    * @returns A reference to the Store.
    * @example
-   * This example applies a Changes object that sets a Cell and
-   * removes a Value.
+   * This example applies a Changes object that sets a Cell and removes a Value.
    *
    * ```js
    * import {createStore} from 'tinybase';
@@ -5430,6 +5431,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This is useful for deciding whether to rollback a transaction, for example.
    * The returned object is only meaningful if the method is called when the
    * Store is in a transaction - such as in a TransactionListener.
+   * @returns A Changes object representing the changes.
    * @example
    * This example makes changes to the Store. At the end of the transaction,
    * detail about what changed is enumerated.
@@ -5472,6 +5474,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This is useful for deciding whether to rollback a transaction, for example.
    * The returned object is only meaningful if the method is called when the
    * Store is in a transaction - such as in a TransactionListener.
+   * @returns A TransactionLog object representing the changes.
    * @example
    * This example makes changes to the Store. At the end of the transaction,
    * detail about what changed is enumerated.
@@ -8212,11 +8215,11 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * Special note should be made for how the listener will be called when a
    * TablesSchema is present. The listener will be called:
    *
-   * - if a Table is being updated that is not specified in the TablesSchema
-   * - if a Cell is of the wrong type specified in the TablesSchema
-   * - if a Cell is omitted and is not defaulted in the TablesSchema
-   * - if an empty Row is provided and there are no Cell defaults in the
-   *   TablesSchema
+   * - if a Table is being updated that is not specified in the TablesSchema,
+   * - if a Cell is of the wrong type specified in the TablesSchema,
+   * - if a Cell is omitted and is not defaulted in the TablesSchema,
+   * - or if an empty Row is provided and there are no Cell defaults in the
+   *   TablesSchema.
    *
    * The listener will not be called if a Cell that is defaulted in the
    * TablesSchema is not provided, as long as all of the Cells that are _not_
@@ -8454,10 +8457,10 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * Special note should be made for how the listener will be called when a
    * ValuesSchema is present. The listener will be called:
    *
-   * - if a Value is being updated that is not specified in the ValuesSchema
-   * - if a Value is of the wrong type specified in the ValuesSchema
-   * - if a Value is omitted when using setValues that is not defaulted in the
-   *   ValuesSchema
+   * - if a Value is being updated that is not specified in the ValuesSchema,
+   * - if a Value is of the wrong type specified in the ValuesSchema,
+   * - or if a Value is omitted when using setValues that is not defaulted in
+   *   the ValuesSchema.
    *
    * The listener will not be called if a Value that is defaulted in the
    * ValuesSchema is not provided, as long as all of the Values that are _not_
@@ -9040,10 +9043,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * The StoreListenerStats object contains a breakdown of the different types
    * of listener. Totals include both mutator and non-mutator listeners.
    *
-   * The statistics are only populated in a debug build: production builds
-   * return an empty object. The method is intended to be used during
-   * development to ensure your application is not leaking listener
-   * registrations, for example.
+   * The method is intended to be used during development to ensure your
+   * application is not leaking listener registrations, for example.
    * @returns A StoreListenerStats object containing Store listener statistics.
    * @example
    * This example gets the listener statistics of a small and simple Store.

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

@@ -8,72 +8,353 @@
  */
 
 import type {Id, IdOrNull} from '../common/index.d.cts';
+import type {Persister, Persists} from '../persisters/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
+ * The Message enum is used to indicate the type of the message being passed
+ * between Synchronizer instances.
+ *
+ * These message comprise the basic synchronization protocol for merging
+ * MergeableStore instances across multiple systems.
+ *
+ * The enum is generally intended to be used internally within TinyBase itself
+ * and opaque to applications that use synchronization.
  * @category Synchronization
+ * @since v5.0.0
  */
-export type MessageType = number;
+export const enum Message {
+  /**
+   * A message that is a response to a previous request.
+   */
+  Response = 0,
+  /**
+   * A message that is a request to get ContentHashes from another
+   * MergeableStore.
+   */
+  GetContentHashes = 1,
+  /**
+   * A message that contains ContentHashes.
+   */
+  ContentHashes = 2,
+  /**
+   * A message that contains a ContentDiff.
+   */
+  ContentDiff = 3,
+  /**
+   * A message that is a request to get a TableDiff from another MergeableStore.
+   */
+  GetTableDiff = 4,
+  /**
+   * A message that is a request to get a RowDiff from another MergeableStore.
+   */
+  GetRowDiff = 5,
+  /**
+   * A message that is a request to get a CellDiff from another MergeableStore.
+   */
+  GetCellDiff = 6,
+  /**
+   * A message that is a request to get a ValueDiff from another MergeableStore.
+   */
+  GetValueDiff = 7,
+}
 
 /**
- * The Receive type
+ * The Receive type describes a function that knows how to handle the arrival of
+ * a message as part of the synchronization protocol.
+ *
+ * When a message arrives (most likely from another system), the function will
+ * be called with parameters that indicate where the message came from, and its
+ * meaning and content.
+ * @param fromClientId The Id of the other client (in other words, the other
+ * system) that sent the message.
+ * @param requestId The optional Id of the message, which should be returned in
+ * the response (if requested) to constitute a matched request/response
+ * transaction.
+ * @param message A number that indicates the type of the message, according to
+ * the Message enum.
+ * @param body A message-specific payload.
  * @category Synchronization
+ * @since v5.0.0
  */
 export type Receive = (
   fromClientId: Id,
   requestId: IdOrNull,
-  messageType: MessageType,
-  messageBody: any,
+  message: Message,
+  body: any,
 ) => void;
 
 /**
- * The Send type
+ * The Send type describes a function that knows how to dispatch a message as
+ * part of the synchronization protocol.
+ * @param toClientId The optional Id of the other client (in other words, the
+ * other system) to which the message should be sent. If omitted, this is to be
+ * a broadcast.
+ * @param requestId The optional Id of the message, which should be awaited in
+ * the response (if requested) to constitute a matched request/response
+ * transaction.
+ * @param message A number that indicates the type of the message, according to
+ * the Message enum.
+ * @param body A message-specific payload.
  * @category Synchronization
+ * @since v5.0.0
  */
 export type Send = (
   toClientId: IdOrNull,
   requestId: IdOrNull,
-  messageType: MessageType,
-  messageBody: any,
+  message: Message,
+  body: any,
 ) => void;
 
 /**
- * The SynchronizerStats type
+ * The SynchronizerStats type describes the number of times a Synchronizer
+ * object has sent or received data.
+ *
+ * A SynchronizerStats object is returned from the getSynchronizerStats method.
  * @category Development
+ * @since v5.0.0
  */
 export type SynchronizerStats = {
+  /**
+   * The number of times messages have been sent.
+   */
   sends: number;
+  /**
+   * The number of times messages has been received.
+   */
   receives: number;
 };
 
 /**
- * The Synchronizer interface is a minor extension to the Persister interface.
+ * The Synchronizer object lets you synchronize MergeableStore data with another
+ * TinyBase client or system.
+ *
+ * This is useful for sharing data between users, or between devices of a single
+ * user. This is especially valuable when there is the possibility that there
+ * has been a lack of immediate connectivity between clients and the
+ * synchronization requires some negotiation to orchestrate merging the
+ * MergeableStore objects together.
+ *
+ * Creating a Synchronizer depends on the choice of underlying medium over which
+ * the synchronization will take place. Options include the createWsSynchronizer
+ * function (for a Synchronizer that will sync over web-sockets), and the
+ * createLocalSynchronizer function (for a Synchronizer that will sync two
+ * MergeableStore objects in memory on one system). The createCustomSynchronizer
+ * function can also be used to easily create a fully customized way to send and
+ * receive the messages of the synchronization protocol.
  *
- * It provides extra convenience methods for starting and stopping the
- * synchronization.
+ * Note that, as an interface, it is an extension to the Persister interface,
+ * since they share underlying implementations. Think of a Synchronizer as
+ * 'persisting' your MergeableStore to another client (and vice-versa).
+ * @example
+ * This example creates two empty MergeableStore objects, creates a
+ * LocalSynchronizer for each, and starts synchronizing them. A change in one
+ * becomes evident in the other.
+ *
+ * ```js
+ * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore();
+ * const store2 = createMergeableStore();
+ *
+ * const synchronizer1 = createLocalSynchronizer(store1);
+ * const synchronizer2 = createLocalSynchronizer(store2);
+ *
+ * await synchronizer1.startSync();
+ * await synchronizer2.startSync();
+ *
+ * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * // ...
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}}}
  *
- * You should use the createCustomSynchronizer function to create a Synchronizer
- * object.
+ * store2.setRow('pets', 'felix', {species: 'cat'});
+ * // ...
+ * console.log(store1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
  * @category Synchronizer
  * @since v5.0.0
  */
-export interface Synchronizer extends Persister<2> {
+export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
   /**
-   * The startSync method
+   * The startSync method is used to start the process of synchronization
+   * between this instance and another matching Synchronizer.
+   *
+   * The underlying implementation of a Synchronizer is shared with the
+   * Persister framework, and so this startSync method is equivalent to starting
+   * both auto-loading (listening to sync messages from other active
+   * Synchronizer instances) and auto-saving (sending sync messages to it).
+   *
+   * This method is asynchronous so you should you `await` calls to this method
+   * or handle the return type natively as a Promise.
+   * @param initialContent An optional Content object used when no content is
+   * available from another other peer Synchronizer instances.
+   * @returns A Promise containing a reference to the Synchronizer object.
+   * @example
+   * This example creates two empty MergeableStore objects, creates a
+   * LocalSynchronizer for each, and starts synchronizing them. A change in one
+   * becomes evident in the other.
+   *
+   * ```js
+   * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore();
+   * const store2 = createMergeableStore();
+   *
+   * const synchronizer1 = createLocalSynchronizer(store1);
+   * const synchronizer2 = createLocalSynchronizer(store2);
+   *
+   * await synchronizer1.startSync();
+   * await synchronizer2.startSync();
+   *
+   * store1.setTables({pets: {fido: {species: 'dog'}}});
+   * // ...
+   * console.log(store2.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * store2.setRow('pets', 'felix', {species: 'cat'});
+   * // ...
+   * console.log(store1.getTables());
+   * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+   *
+   * synchronizer1.destroy();
+   * synchronizer2.destroy();
+   * ```
+   * @example
+   * This example creates two empty MergeableStore objects, creates a
+   * LocalSynchronizer for each, and starts synchronizing them with default
+   * content. The default content from the first Synchronizer's startSync method
+   * ends up populated in both MergeableStore instances: by the time the second
+   * started, the first was available to synchronize with and its default was
+   * not needed.
+   *
+   * ```js
+   * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore();
+   * const store2 = createMergeableStore();
+   *
+   * const synchronizer1 = createLocalSynchronizer(store1);
+   * const synchronizer2 = createLocalSynchronizer(store2);
+   *
+   * await synchronizer1.startSync([{pets: {fido: {species: 'dog'}}}, {}]);
+   * await synchronizer2.startSync([{pets: {felix: {species: 'cat'}}}, {}]);
+   *
+   * // ...
+   *
+   * console.log(store1.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   * console.log(store2.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * synchronizer1.destroy();
+   * synchronizer2.destroy();
+   * ```
    * @category Synchronization
+   * @since v5.0.0
    */
   startSync(initialContent?: Content): Promise<this>;
   /**
-   * The stopSync method
+   * The stopSync method is used to stop the process of synchronization between
+   * this instance and another matching Synchronizer.
+   *
+   * The underlying implementation of a Synchronizer is shared with the
+   * Persister framework, and so this startSync method is equivalent to stopping
+   * both auto-loading (listening to sync messages from other active
+   * Synchronizer instances) and auto-saving (sending sync messages to them).
+   * @returns A reference to the Synchronizer object.
+   * @example
+   * This example creates two empty MergeableStore objects, creates a
+   * LocalSynchronizer for each, and starts - then stops - synchronizing them.
+   * Subsequent changes are not merged.
+   *
+   * ```js
+   * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore();
+   * const synchronizer1 = createLocalSynchronizer(store1);
+   * await synchronizer1.startSync();
+   *
+   * const store2 = createMergeableStore();
+   * const synchronizer2 = createLocalSynchronizer(store2);
+   * await synchronizer2.startSync();
+   *
+   * store1.setTables({pets: {fido: {species: 'dog'}}});
+   * // ...
+   * console.log(store1.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   * console.log(store2.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * synchronizer1.stopSync();
+   * synchronizer2.stopSync();
+   *
+   * store1.setCell('pets', 'fido', 'color', 'brown');
+   * // ...
+   * console.log(store1.getTables());
+   * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
+   * console.log(store2.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   *
+   * synchronizer1.destroy();
+   * synchronizer2.destroy();
+   * ```
    * @category Synchronization
+   * @since v5.0.0
    */
   stopSync(): this;
   /**
-   * The getSynchronizerStats method
+   * The getSynchronizerStats method provides a set of statistics about the
+   * Synchronizer, and is used for debugging purposes.
+   *
+   * The SynchronizerStats object contains a count of the number of times the
+   * Persister has sent and received messages.
+   *
+   * The method is intended to be used during development to ensure your
+   * synchronization layer is acting as expected, for example.
+   * @returns A SynchronizerStats object containing Synchronizer send and
+   * receive statistics.
+   * @example
+   * This example gets the send and receive statistics of two active
+   * Synchronizer instances.
+   *
+   * ```js
+   * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore();
+   * const store2 = createMergeableStore();
+   *
+   * const synchronizer1 = createLocalSynchronizer(store1);
+   * const synchronizer2 = createLocalSynchronizer(store2);
+   *
+   * await synchronizer1.startSync();
+   * await synchronizer2.startSync();
+   *
+   * store1.setTables({pets: {fido: {species: 'dog'}}});
+   * // ...
+   * store2.setRow('pets', 'felix', {species: 'cat'});
+   * // ...
+   *
+   * console.log(synchronizer1.getSynchronizerStats());
+   * // -> {receives: 4, sends: 5}
+   * console.log(synchronizer2.getSynchronizerStats());
+   * // -> {receives: 5, sends: 4}
+   *
+   * synchronizer1.destroy();
+   * synchronizer2.destroy();
+   * ```
    * @category Synchronization
+   * @since v5.0.0
    */
   getSynchronizerStats(): SynchronizerStats;
 }
@@ -84,50 +365,81 @@ export interface Synchronizer extends Persister<2> {
  *
  * 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.
+ * from this MergeableStore and its peers. This is entirely dependent upon the
+ * medium of communication used.
  * @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 onReceive A callback (called once when the Synchronizer is created)
+ * that is passed a Receive function that you need to ensure can receive
+ * messages.
  * @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
+ * Synchronizer would otherwise ignore when trying to synchronize 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.
+ * This example creates a function for creating custom Synchronizer objects via
+ * a very naive pair of message buses (which are first-in, first-out). Each
+ * Synchronizer can write to the other's bus, and they each poll to read from
+ * their own. The example then uses these Synchronizer instances to sync two
+ * MergeableStore objects together
  *
  * ```js
- * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
- * import {createMergeableStore} from 'tinybase';
+ * import {
+ *   createCustomSynchronizer,
+ *   createMergeableStore,
+ *   getUniqueId,
+ * } from 'tinybase';
  *
- * const store1 = createMergeableStore('store1').setTables({
- *   pets: {fido: {species: 'dog'}},
- * });
- * const synchronizer1 = createLocalSynchronizer(store1);
+ * const bus1 = [];
+ * const bus2 = [];
  *
- * const store2 = createMergeableStore('store2');
- * const synchronizer2 = createLocalSynchronizer(store2);
+ * const createBusSynchronizer = (store, localBus, remoteBus) => {
+ *   let timer;
+ *   const clientId = getUniqueId();
+ *   return createCustomSynchronizer(
+ *     store,
+ *     (toClientId, requestId, message, body) => {
+ *       // send
+ *       remoteBus.push([clientId, requestId, message, body]);
+ *     },
+ *     (receive) => {
+ *       // onReceive
+ *       timer = setInterval(() => {
+ *         if (localBus.length > 0) {
+ *           receive(...localBus.shift());
+ *         }
+ *       }, 1);
+ *     },
+ *     () => clearInterval(timer), // destroy
+ *     1,
+ *   );
+ * };
+ *
+ * const store1 = createMergeableStore();
+ * const store2 = createMergeableStore();
+ *
+ * const synchronizer1 = createBusSynchronizer(store1, bus1, bus2);
+ * const synchronizer2 = createBusSynchronizer(store2, bus2, bus1);
+ *
+ * await synchronizer1.startSync();
  * await synchronizer2.startSync();
  *
- * await synchronizer1.save();
+ * store1.setTables({pets: {fido: {species: 'dog'}}});
  * // ...
- * // Store2 will be synced with Store1.
- *
+ * console.log(store1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}}}
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}}}
  *
- * await synchronizer1.load();
- * // Store1 will be synced with Store2.
- *
  * synchronizer1.destroy();
  * synchronizer2.destroy();
  * ```
  * @category Creation
+ * @since v5.0.0
  */
 export function createCustomSynchronizer(
   store: MergeableStore,