tinybase 5.0.0-beta.26 → 5.0.0-beta.27

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

@@ -13,15 +13,90 @@ import type {OptionalSchemas} from '../../../store/with-schemas/index.d.cts';
 import type {Synchronizer} from '../../with-schemas/index.d.cts';
 
 /**
- * The LocalSynchronizer interface.
+ * The LocalSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances on
+ * the same local machine.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export interface LocalSynchronizer extends Synchronizer {}
+ * ```
+ *
+ * Having no specialized methods, it is a synonym for the Synchronizer
+ * interface. This is also something of a showcase Synchronizer, rather than
+ * something you would use in a production environment. If you _do_ need to
+ * synchronize two in-memory MergeableStore instances, you may prefer to use the
+ * merge function on either one of them instead of going to the effort of
+ * setting up this Synchronizer.
+ *
+ * You should use the createLocalSynchronizer function to create a
+ * LocalSynchronizer object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface LocalSynchronizer<Schemas extends OptionalSchemas>
   extends Synchronizer<Schemas> {}
 
 /**
- * The createLocalSynchronizer function.
+ * The createLocalSynchronizer function creates a LocalSynchronizer object that
+ * can synchronize MergeableStore data to and from other MergeableStore
+ * instances on the same local machine.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLocalSynchronizer(
+ *   store: MergeableStore,
+ *   onIgnoredError?: (error: any) => void,
+ * ): LocalSynchronizer;
+ * ```
+ *
+ * This is something of a showcase Synchronizer, rather than something you would
+ * use in a production environment. If you _do_ need to synchronize two
+ * in-memory MergeableStore instances, you may prefer to use the merge function
+ * on either one of them instead of going to the effort of setting up this
+ * Synchronizer.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you can
+ * provide a handler for any otherwise ignored synchronization errors.
+ * @param store The MergeableStore to synchronize.
+ * @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 LocalSynchronizer object.
+ * @example
+ * This example creates a LocalSynchronizer 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
+ * @since v5.0.0
  */
 export function createLocalSynchronizer<Schemas extends OptionalSchemas>(
   store: MergeableStore<Schemas>,

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

@@ -13,15 +13,90 @@ import type {OptionalSchemas} from '../../../store/with-schemas/index.d.ts';
 import type {Synchronizer} from '../../with-schemas/index.d.ts';
 
 /**
- * The LocalSynchronizer interface.
+ * The LocalSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances on
+ * the same local machine.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export interface LocalSynchronizer extends Synchronizer {}
+ * ```
+ *
+ * Having no specialized methods, it is a synonym for the Synchronizer
+ * interface. This is also something of a showcase Synchronizer, rather than
+ * something you would use in a production environment. If you _do_ need to
+ * synchronize two in-memory MergeableStore instances, you may prefer to use the
+ * merge function on either one of them instead of going to the effort of
+ * setting up this Synchronizer.
+ *
+ * You should use the createLocalSynchronizer function to create a
+ * LocalSynchronizer object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface LocalSynchronizer<Schemas extends OptionalSchemas>
   extends Synchronizer<Schemas> {}
 
 /**
- * The createLocalSynchronizer function.
+ * The createLocalSynchronizer function creates a LocalSynchronizer object that
+ * can synchronize MergeableStore data to and from other MergeableStore
+ * instances on the same local machine.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLocalSynchronizer(
+ *   store: MergeableStore,
+ *   onIgnoredError?: (error: any) => void,
+ * ): LocalSynchronizer;
+ * ```
+ *
+ * This is something of a showcase Synchronizer, rather than something you would
+ * use in a production environment. If you _do_ need to synchronize two
+ * in-memory MergeableStore instances, you may prefer to use the merge function
+ * on either one of them instead of going to the effort of setting up this
+ * Synchronizer.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you can
+ * provide a handler for any otherwise ignored synchronization errors.
+ * @param store The MergeableStore to synchronize.
+ * @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 LocalSynchronizer object.
+ * @example
+ * This example creates a LocalSynchronizer 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
+ * @since v5.0.0
  */
 export function createLocalSynchronizer<Schemas extends OptionalSchemas>(
   store: MergeableStore<Schemas>,

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

@@ -13,14 +13,61 @@ import type {MergeableStore} from '../../mergeable-store/index.d.cts';
 import type {Synchronizer} from '../index.d.cts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
+/**
+ * The WebSocketTypes type represents the valid types of WebSocket that can be
+ * used with the WsSynchronizer.
+ *
+ * This includes the browser-native WebSocket type, as well as the WebSocket
+ * type from the well-known `ws` package (such that the Synchronizer can be used
+ * in a server environment).
+ */
 export type WebSocketTypes = WebSocket | WsWebSocket;
 
 /**
- * The WsSynchronizer interface.
+ * The WsSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via WebSockets facilitated by a server.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getWebSocket method for accessing a reference to the WebSocket being
+ * used.
+ *
+ * You should use the createWsSynchronizer function to create a WsSynchronizer
+ * object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
   extends Synchronizer {
+  /**
+   * The getWebSocket method returns reference to the WebSocket being used for
+   * synchronization.
+   * @returns The WebSocket reference.
+   * @example
+   * This example creates a server and WsSynchronizer object for a newly-created
+   * MergeableStore and then gets the WebSocket reference back out again.
+   *
+   * ```js
+   * import {WebSocket, WebSocketServer} from 'ws';
+   * import {createMergeableStore} from 'tinybase';
+   * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+   * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+   *
+   * const server = createWsServer(new WebSocketServer({port: 8046}));
+   *
+   * const store = createMergeableStore();
+   * const webSocket = new WebSocket('ws://localhost:8046');
+   * const synchronizer = await createWsSynchronizer(store, webSocket);
+   *
+   * console.log(synchronizer.getWebSocket() == webSocket);
+   * // -> true
+   *
+   * synchronizer.destroy();
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
   getWebSocket(): WebSocketType;
 }
 

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

@@ -13,14 +13,61 @@ import type {MergeableStore} from '../../mergeable-store/index.d.ts';
 import type {Synchronizer} from '../index.d.ts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
+/**
+ * The WebSocketTypes type represents the valid types of WebSocket that can be
+ * used with the WsSynchronizer.
+ *
+ * This includes the browser-native WebSocket type, as well as the WebSocket
+ * type from the well-known `ws` package (such that the Synchronizer can be used
+ * in a server environment).
+ */
 export type WebSocketTypes = WebSocket | WsWebSocket;
 
 /**
- * The WsSynchronizer interface.
+ * The WsSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via WebSockets facilitated by a server.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getWebSocket method for accessing a reference to the WebSocket being
+ * used.
+ *
+ * You should use the createWsSynchronizer function to create a WsSynchronizer
+ * object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
   extends Synchronizer {
+  /**
+   * The getWebSocket method returns reference to the WebSocket being used for
+   * synchronization.
+   * @returns The WebSocket reference.
+   * @example
+   * This example creates a server and WsSynchronizer object for a newly-created
+   * MergeableStore and then gets the WebSocket reference back out again.
+   *
+   * ```js
+   * import {WebSocket, WebSocketServer} from 'ws';
+   * import {createMergeableStore} from 'tinybase';
+   * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+   * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+   *
+   * const server = createWsServer(new WebSocketServer({port: 8046}));
+   *
+   * const store = createMergeableStore();
+   * const webSocket = new WebSocket('ws://localhost:8046');
+   * const synchronizer = await createWsSynchronizer(store, webSocket);
+   *
+   * console.log(synchronizer.getWebSocket() == webSocket);
+   * // -> true
+   *
+   * synchronizer.destroy();
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
   getWebSocket(): WebSocketType;
 }
 

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

@@ -14,16 +14,63 @@ 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';
 
+/**
+ * The WebSocketTypes type represents the valid types of WebSocket that can be
+ * used with the WsSynchronizer.
+ *
+ * This includes the browser-native WebSocket type, as well as the WebSocket
+ * type from the well-known `ws` package (such that the Synchronizer can be used
+ * in a server environment).
+ */
 export type WebSocketTypes = WebSocket | WsWebSocket;
 
 /**
- * The WsSynchronizer interface.
+ * The WsSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via WebSockets facilitated by a server.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getWebSocket method for accessing a reference to the WebSocket being
+ * used.
+ *
+ * You should use the createWsSynchronizer function to create a WsSynchronizer
+ * object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface WsSynchronizer<
   Schemas extends OptionalSchemas,
   WebSocketType extends WebSocketTypes,
 > extends Synchronizer<Schemas> {
+  /**
+   * The getWebSocket method returns reference to the WebSocket being used for
+   * synchronization.
+   * @returns The WebSocket reference.
+   * @example
+   * This example creates a server and WsSynchronizer object for a newly-created
+   * MergeableStore and then gets the WebSocket reference back out again.
+   *
+   * ```js
+   * import {WebSocket, WebSocketServer} from 'ws';
+   * import {createMergeableStore} from 'tinybase';
+   * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+   * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+   *
+   * const server = createWsServer(new WebSocketServer({port: 8046}));
+   *
+   * const store = createMergeableStore();
+   * const webSocket = new WebSocket('ws://localhost:8046');
+   * const synchronizer = await createWsSynchronizer(store, webSocket);
+   *
+   * console.log(synchronizer.getWebSocket() == webSocket);
+   * // -> true
+   *
+   * synchronizer.destroy();
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
   getWebSocket(): WebSocketType;
 }
 

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

@@ -14,16 +14,63 @@ import type {OptionalSchemas} from '../../../store/with-schemas/index.d.ts';
 import type {Synchronizer} from '../../with-schemas/index.d.ts';
 import type {WebSocket as WsWebSocket} from 'ws';
 
+/**
+ * The WebSocketTypes type represents the valid types of WebSocket that can be
+ * used with the WsSynchronizer.
+ *
+ * This includes the browser-native WebSocket type, as well as the WebSocket
+ * type from the well-known `ws` package (such that the Synchronizer can be used
+ * in a server environment).
+ */
 export type WebSocketTypes = WebSocket | WsWebSocket;
 
 /**
- * The WsSynchronizer interface.
+ * The WsSynchronizer interface represents a Synchronizer that lets you
+ * synchronize MergeableStore data to and from other MergeableStore instances
+ * via WebSockets facilitated by a server.
+ *
+ * It is a minor extension to the Synchronizer interface and simply provides an
+ * extra getWebSocket method for accessing a reference to the WebSocket being
+ * used.
+ *
+ * You should use the createWsSynchronizer function to create a WsSynchronizer
+ * object.
  * @category Synchronizer
+ * @since v5.0.0
  */
 export interface WsSynchronizer<
   Schemas extends OptionalSchemas,
   WebSocketType extends WebSocketTypes,
 > extends Synchronizer<Schemas> {
+  /**
+   * The getWebSocket method returns reference to the WebSocket being used for
+   * synchronization.
+   * @returns The WebSocket reference.
+   * @example
+   * This example creates a server and WsSynchronizer object for a newly-created
+   * MergeableStore and then gets the WebSocket reference back out again.
+   *
+   * ```js
+   * import {WebSocket, WebSocketServer} from 'ws';
+   * import {createMergeableStore} from 'tinybase';
+   * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
+   * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
+   *
+   * const server = createWsServer(new WebSocketServer({port: 8046}));
+   *
+   * const store = createMergeableStore();
+   * const webSocket = new WebSocket('ws://localhost:8046');
+   * const synchronizer = await createWsSynchronizer(store, webSocket);
+   *
+   * console.log(synchronizer.getWebSocket() == webSocket);
+   * // -> true
+   *
+   * synchronizer.destroy();
+   * server.destroy();
+   * ```
+   * @category Getter
+   * @since v5.0.0
+   */
   getWebSocket(): WebSocketType;
 }