tinybase 5.0.0-beta.27 → 5.0.0-beta.28

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

@@ -1,7 +1,7 @@
 /**
- * The persister-sync module of the TinyBase project lets you synchronize
+ * The synchronizers module of the TinyBase project lets you synchronize
  * MergeableStore data to and from other MergeableStore instances.
- * @see Synchronizing Data guide
+ * @see Synchronization guide
  * @packageDocumentation
  * @module synchronizers
  * @since v5.0.0
@@ -27,35 +27,51 @@ import type {MergeableStore} from '../mergeable-store/index.d.cts';
 export const enum Message {
   /**
    * A message that is a response to a previous request.
+   * @category Enum
+   * @since v5.0.0
    */
   Response = 0,
   /**
    * A message that is a request to get ContentHashes from another
    * MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetContentHashes = 1,
   /**
    * A message that contains ContentHashes.
+   * @category Enum
+   * @since v5.0.0
    */
   ContentHashes = 2,
   /**
    * A message that contains a ContentDiff.
+   * @category Enum
+   * @since v5.0.0
    */
   ContentDiff = 3,
   /**
    * A message that is a request to get a TableDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetTableDiff = 4,
   /**
    * A message that is a request to get a RowDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetRowDiff = 5,
   /**
    * A message that is a request to get a CellDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetCellDiff = 6,
   /**
    * A message that is a request to get a ValueDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetValueDiff = 7,
 }
@@ -118,16 +134,20 @@ export type Send = (
 export type SynchronizerStats = {
   /**
    * The number of times messages have been sent.
+   * @category Stat
+   * @since v5.0.0
    */
   sends: number;
   /**
    * The number of times messages has been received.
+   * @category Stat
+   * @since v5.0.0
    */
   receives: number;
 };
 
 /**
- * The Synchronizer object lets you synchronize MergeableStore data with another
+ * A 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
@@ -369,9 +389,9 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  * medium of communication used.
  * @param store The MergeableStore to synchronize.
  * @param send A Send function for sending 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 registerReceive A callback (called once when the Synchronizer is
+ * created) that is passed a Receive function that you need to ensure will
+ * receive messages addressed or broadcast to this client.
  * @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
@@ -407,7 +427,7 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  *       remoteBus.push([clientId, requestId, message, body]);
  *     },
  *     (receive) => {
- *       // onReceive
+ *       // registerReceive
  *       timer = setInterval(() => {
  *         if (localBus.length > 0) {
  *           receive(...localBus.shift());
@@ -429,11 +449,13 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  * await synchronizer2.startSync();
  *
  * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * store2.setTables({pets: {felix: {species: 'cat'}}});
+ *
  * // ...
  * console.log(store1.getTables());
- * // -> {pets: {fido: {species: 'dog'}}}
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  * console.log(store2.getTables());
- * // -> {pets: {fido: {species: 'dog'}}}
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
  * synchronizer1.destroy();
  * synchronizer2.destroy();
@@ -444,7 +466,7 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
 export function createCustomSynchronizer(
   store: MergeableStore,
   send: Send,
-  onReceive: (receive: Receive) => void,
+  registerReceive: (receive: Receive) => void,
   destroy: () => void,
   requestTimeoutSeconds: number,
   onIgnoredError?: (error: any) => void,

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

@@ -1,7 +1,7 @@
 /**
- * The persister-sync module of the TinyBase project lets you synchronize
+ * The synchronizers module of the TinyBase project lets you synchronize
  * MergeableStore data to and from other MergeableStore instances.
- * @see Synchronizing Data guide
+ * @see Synchronization guide
  * @packageDocumentation
  * @module synchronizers
  * @since v5.0.0
@@ -27,35 +27,51 @@ import type {MergeableStore} from '../mergeable-store/index.d.ts';
 export const enum Message {
   /**
    * A message that is a response to a previous request.
+   * @category Enum
+   * @since v5.0.0
    */
   Response = 0,
   /**
    * A message that is a request to get ContentHashes from another
    * MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetContentHashes = 1,
   /**
    * A message that contains ContentHashes.
+   * @category Enum
+   * @since v5.0.0
    */
   ContentHashes = 2,
   /**
    * A message that contains a ContentDiff.
+   * @category Enum
+   * @since v5.0.0
    */
   ContentDiff = 3,
   /**
    * A message that is a request to get a TableDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetTableDiff = 4,
   /**
    * A message that is a request to get a RowDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetRowDiff = 5,
   /**
    * A message that is a request to get a CellDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetCellDiff = 6,
   /**
    * A message that is a request to get a ValueDiff from another MergeableStore.
+   * @category Enum
+   * @since v5.0.0
    */
   GetValueDiff = 7,
 }
@@ -118,16 +134,20 @@ export type Send = (
 export type SynchronizerStats = {
   /**
    * The number of times messages have been sent.
+   * @category Stat
+   * @since v5.0.0
    */
   sends: number;
   /**
    * The number of times messages has been received.
+   * @category Stat
+   * @since v5.0.0
    */
   receives: number;
 };
 
 /**
- * The Synchronizer object lets you synchronize MergeableStore data with another
+ * A 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
@@ -369,9 +389,9 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  * medium of communication used.
  * @param store The MergeableStore to synchronize.
  * @param send A Send function for sending 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 registerReceive A callback (called once when the Synchronizer is
+ * created) that is passed a Receive function that you need to ensure will
+ * receive messages addressed or broadcast to this client.
  * @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
@@ -407,7 +427,7 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  *       remoteBus.push([clientId, requestId, message, body]);
  *     },
  *     (receive) => {
- *       // onReceive
+ *       // registerReceive
  *       timer = setInterval(() => {
  *         if (localBus.length > 0) {
  *           receive(...localBus.shift());
@@ -429,11 +449,13 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  * await synchronizer2.startSync();
  *
  * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * store2.setTables({pets: {felix: {species: 'cat'}}});
+ *
  * // ...
  * console.log(store1.getTables());
- * // -> {pets: {fido: {species: 'dog'}}}
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  * console.log(store2.getTables());
- * // -> {pets: {fido: {species: 'dog'}}}
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
  * synchronizer1.destroy();
  * synchronizer2.destroy();
@@ -444,7 +466,7 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
 export function createCustomSynchronizer(
   store: MergeableStore,
   send: Send,
-  onReceive: (receive: Receive) => void,
+  registerReceive: (receive: Receive) => void,
   destroy: () => void,
   requestTimeoutSeconds: number,
   onIgnoredError?: (error: any) => void,

package/@types/synchronizers/synchronizer-broadcast-channel/index.d.cts

@@ -0,0 +1,114 @@
+/**
+ * The synchronizer-broadcast-channel module of the TinyBase project lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via a browser's BroadcastChannel API.
+ * @see Synchronization guide
+ * @packageDocumentation
+ * @module synchronizer-broadcast-channel
+ * @since v5.0.0
+ */
+
+import type {MergeableStore} from '../../mergeable-store/index.d.cts';
+import type {Synchronizer} from '../index.d.cts';
+
+/**
+ * The BroadcastChannelSynchronizer interface represents a Synchronizer that
+ * lets you synchronize MergeableStore data to and from other MergeableStore
+ * instances via a browser's BroadcastChannel API.
+ *
+ * You should use the createBroadcastChannelSynchronizer function to create a
+ * BroadcastChannelSynchronizer object.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getChannelName method for accessing the name of the channel being used.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface BroadcastChannelSynchronizer extends Synchronizer {
+  /**
+   * The getChannelName method returns the name of the channel being used for
+   * synchronization.
+   * @returns The channel name.
+   * @example
+   * This example creates a BroadcastChannelSynchronizer object for a
+   * newly-created MergeableStore and then gets the channel name back out again.
+   *
+   * ```js
+   * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore();
+   * const synchronizer = await createBroadcastChannelSynchronizer(
+   *   store,
+   *   'channelA',
+   * );
+   *
+   * console.log(synchronizer.getChannelName());
+   * // -> 'channelA'
+   *
+   * synchronizer.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
+  getChannelName(): string;
+}
+
+/**
+ * The createBroadcastChannelSynchronizer function creates a
+ * BroadcastChannelSynchronizer object that can synchronize MergeableStore data
+ * to and from other MergeableStore instances via a browser's BroadcastChannel
+ * API.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a channel name, used by all the browser tabs, workers, or contexts
+ * that need to synchronize together.
+ * @param store The MergeableStore to synchronize.
+ * @param channelName The name of the channel to use.
+ * @param onIgnoredError An optional handler for the errors that the
+ * 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 BroadcastChannelSynchronizer object.
+ * @example
+ * This example creates two BroadcastChannelSynchronizer objects to synchronize
+ * one MergeableStore to another.
+ *
+ * ```js
+ * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore();
+ * const store2 = createMergeableStore();
+ *
+ * const synchronizer1 = createBroadcastChannelSynchronizer(
+ *   store1,
+ *   'channelA',
+ * );
+ * const synchronizer2 = createBroadcastChannelSynchronizer(
+ *   store2,
+ *   'channelA',
+ * );
+ *
+ * await synchronizer1.startSync();
+ * await synchronizer2.startSync();
+ *
+ * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * store2.setTables({pets: {felix: {species: 'cat'}}});
+ *
+ * // ...
+ * console.log(store1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ * @since v5.0.0
+ */
+export function createBroadcastChannelSynchronizer(
+  store: MergeableStore,
+  channelName: string,
+  onIgnoredError?: (error: any) => void,
+): BroadcastChannelSynchronizer;

package/@types/synchronizers/synchronizer-broadcast-channel/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The synchronizer-broadcast-channel module of the TinyBase project lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via a browser's BroadcastChannel API.
+ * @see Synchronization guide
+ * @packageDocumentation
+ * @module synchronizer-broadcast-channel
+ * @since v5.0.0
+ */
+
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Synchronizer} from '../index.d.ts';
+
+/**
+ * The BroadcastChannelSynchronizer interface represents a Synchronizer that
+ * lets you synchronize MergeableStore data to and from other MergeableStore
+ * instances via a browser's BroadcastChannel API.
+ *
+ * You should use the createBroadcastChannelSynchronizer function to create a
+ * BroadcastChannelSynchronizer object.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getChannelName method for accessing the name of the channel being used.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface BroadcastChannelSynchronizer extends Synchronizer {
+  /**
+   * The getChannelName method returns the name of the channel being used for
+   * synchronization.
+   * @returns The channel name.
+   * @example
+   * This example creates a BroadcastChannelSynchronizer object for a
+   * newly-created MergeableStore and then gets the channel name back out again.
+   *
+   * ```js
+   * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore();
+   * const synchronizer = await createBroadcastChannelSynchronizer(
+   *   store,
+   *   'channelA',
+   * );
+   *
+   * console.log(synchronizer.getChannelName());
+   * // -> 'channelA'
+   *
+   * synchronizer.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
+  getChannelName(): string;
+}
+
+/**
+ * The createBroadcastChannelSynchronizer function creates a
+ * BroadcastChannelSynchronizer object that can synchronize MergeableStore data
+ * to and from other MergeableStore instances via a browser's BroadcastChannel
+ * API.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a channel name, used by all the browser tabs, workers, or contexts
+ * that need to synchronize together.
+ * @param store The MergeableStore to synchronize.
+ * @param channelName The name of the channel to use.
+ * @param onIgnoredError An optional handler for the errors that the
+ * 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 BroadcastChannelSynchronizer object.
+ * @example
+ * This example creates two BroadcastChannelSynchronizer objects to synchronize
+ * one MergeableStore to another.
+ *
+ * ```js
+ * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore();
+ * const store2 = createMergeableStore();
+ *
+ * const synchronizer1 = createBroadcastChannelSynchronizer(
+ *   store1,
+ *   'channelA',
+ * );
+ * const synchronizer2 = createBroadcastChannelSynchronizer(
+ *   store2,
+ *   'channelA',
+ * );
+ *
+ * await synchronizer1.startSync();
+ * await synchronizer2.startSync();
+ *
+ * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * store2.setTables({pets: {felix: {species: 'cat'}}});
+ *
+ * // ...
+ * console.log(store1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ * @since v5.0.0
+ */
+export function createBroadcastChannelSynchronizer(
+  store: MergeableStore,
+  channelName: string,
+  onIgnoredError?: (error: any) => void,
+): BroadcastChannelSynchronizer;

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

@@ -0,0 +1,128 @@
+/**
+ * The synchronizer-broadcast-channel module of the TinyBase project lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via a browser's BroadcastChannel API.
+ * @see Synchronization guide
+ * @packageDocumentation
+ * @module synchronizer-broadcast-channel
+ * @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 BroadcastChannelSynchronizer interface represents a Synchronizer that
+ * lets you synchronize MergeableStore data to and from other MergeableStore
+ * instances via a browser's BroadcastChannel API.
+ *
+ * You should use the createBroadcastChannelSynchronizer function to create a
+ * BroadcastChannelSynchronizer object.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getChannelName method for accessing the name of the channel being used.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface BroadcastChannelSynchronizer<Schemas extends OptionalSchemas>
+  extends Synchronizer<Schemas> {
+  /**
+   * The getChannelName method returns the name of the channel being used for
+   * synchronization.
+   * @returns The channel name.
+   * @example
+   * This example creates a BroadcastChannelSynchronizer object for a
+   * newly-created MergeableStore and then gets the channel name back out again.
+   *
+   * ```js
+   * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore();
+   * const synchronizer = await createBroadcastChannelSynchronizer(
+   *   store,
+   *   'channelA',
+   * );
+   *
+   * console.log(synchronizer.getChannelName());
+   * // -> 'channelA'
+   *
+   * synchronizer.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
+  getChannelName(): string;
+}
+
+/**
+ * The createBroadcastChannelSynchronizer function creates a
+ * BroadcastChannelSynchronizer object that can synchronize MergeableStore data
+ * to and from other MergeableStore instances via a browser's BroadcastChannel
+ * API.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createBroadcastChannelSynchronizer(
+ *   store: MergeableStore,
+ *   channelName: string,
+ *   onIgnoredError?: (error: any) => void,
+ * ): BroadcastChannelSynchronizer;
+ * ```
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a channel name, used by all the browser tabs, workers, or contexts
+ * that need to synchronize together.
+ * @param store The MergeableStore to synchronize.
+ * @param channelName The name of the channel to use.
+ * @param onIgnoredError An optional handler for the errors that the
+ * 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 BroadcastChannelSynchronizer object.
+ * @example
+ * This example creates two BroadcastChannelSynchronizer objects to synchronize
+ * one MergeableStore to another.
+ *
+ * ```js
+ * import {createBroadcastChannelSynchronizer} from 'tinybase/synchronizers/synchronizer-broadcast-channel';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store1 = createMergeableStore();
+ * const store2 = createMergeableStore();
+ *
+ * const synchronizer1 = createBroadcastChannelSynchronizer(
+ *   store1,
+ *   'channelA',
+ * );
+ * const synchronizer2 = createBroadcastChannelSynchronizer(
+ *   store2,
+ *   'channelA',
+ * );
+ *
+ * await synchronizer1.startSync();
+ * await synchronizer2.startSync();
+ *
+ * store1.setTables({pets: {fido: {species: 'dog'}}});
+ * store2.setTables({pets: {felix: {species: 'cat'}}});
+ *
+ * // ...
+ * console.log(store1.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ * @since v5.0.0
+ */
+export function createBroadcastChannelSynchronizer<
+  Schemas extends OptionalSchemas,
+>(
+  store: MergeableStore<Schemas>,
+  channelName: string,
+  onIgnoredError?: (error: any) => void,
+): BroadcastChannelSynchronizer<Schemas>;