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

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

@@ -64,7 +64,7 @@ import {
   ValueProps,
   ValuesProps,
 } from './internal/ui-react';
-import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common.d';
+import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common.d.ts';
 import {
   Cell,
   CellIdsListener,
@@ -98,21 +98,21 @@ import {
   ValueListener,
   Values,
   ValuesListener,
-} from './store.d';
+} from './store.d.ts';
 import {
   CheckpointIds,
   CheckpointIdsListener,
   CheckpointListener,
   Checkpoints,
-} from './checkpoints.d';
-import {Indexes, SliceIdsListener, SliceRowIdsListener} from './indexes.d';
+} from './checkpoints.d.ts';
+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,
   ResultCell,
@@ -126,9 +126,11 @@ import {
   ResultTable,
   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 {ReactElement} from 'react';
+import {Synchronizer} from './synchronizers.d.ts';
 
 export type WithSchemas<Schemas extends OptionalSchemas> = {
   /**
@@ -301,9 +303,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * It is possible to create a Store outside of the React app with the regular
  * createStore function and pass it in, but you may prefer to create it within
- * the app, perhaps inside the top-level component. To defend against a new
- * Store being created every time the app renders or re-renders, the
- * useCreateStore hook wraps the creation in a memoization.
+ * the app, perhaps inside the top-level component. To prevent a new Store being
+ * created every time the app renders or re-renders, the useCreateStore hook
+ * wraps the creation in a memoization.
  *
  * The useCreateStore hook is a very thin wrapper around the React `useMemo`
  * hook, defaulting to an empty array for its dependencies, so that by default,
@@ -380,6 +382,14 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     createDeps?: React.DependencyList,
   ) => Store<Schemas>;
 
+  /**
+ * The useCreateMergeableStore hook
+ */
+  useCreateMergeableStore: (
+    create: () => MergeableStore<Schemas>,
+    createDeps?: React.DependencyList,
+  ) => MergeableStore<Schemas>;
+
   /**
  * The useStoreIds hook is used to retrieve the Ids of all the named Store
  * objects present in the current Provider component context.
@@ -2830,8 +2840,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * specify `reuseRowIds` to be `false`, then the Id will be a monotonically
  * increasing string representation of an increasing integer, regardless of any
  * you may have previously deleted.
- * @param tableId The Id of the Table in the Store, or a GetId function
- * that will return it.
+ * @param tableId The Id of the Table in the Store, or a GetId function that
+ * will return it.
  * @param getRow A function which returns the Row object that will be used to
  * update the Store, based on the parameter the callback will receive (and which
  * is most likely a DOM event).
@@ -4199,8 +4209,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * dependencies) or the component unmounts, the listener on the underlying Store
  * will be deleted.
  * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
- * @param listener The function that will be called whenever the matching
- * Table is added or removed.
+ * @param listener The function that will be called whenever the matching Table
+ * is added or removed.
  * @param listenerDeps An optional array of dependencies for the `listener`
  * function, which, if any change, result in the re-registration of the
  * listener. This parameter defaults to an empty array.
@@ -4805,8 +4815,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * more easily done with the useHasRow hook).
  *
  * You can either listen to a single Row being added or removed (by specifying
- * the Table Id and Row Id, as the method's first two parameters) or changes
- * to any Row (by providing `null` wildcards).
+ * the Table Id and Row Id, as the method's first two parameters) or changes to
+ * any Row (by providing `null` wildcards).
  *
  * Both, either, or neither of the `tableId` and `rowId` parameters can be
  * wildcarded with `null`. You can listen to a specific Row in a specific Table,
@@ -4819,8 +4829,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * the component unmounts, the listener on the underlying Store will be deleted.
  * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
  * @param rowId The Id of the Row to listen to, or `null` as a wildcard.
- * @param listener The function that will be called whenever the matching Row
- * is added or removed.
+ * @param listener The function that will be called whenever the matching Row is
+ * added or removed.
  * @param listenerDeps An optional array of dependencies for the `listener`
  * function, which, if any change, result in the re-registration of the
  * listener. This parameter defaults to an empty array.
@@ -5081,14 +5091,14 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * own specific listener to do more than simply tracking the value (which is
  * more easily done with the useHasCell hook).
  *
- * You can either listen to a single Cell being added or removed (by
- * specifying the Table Id, Row Id, and Cell Id as the method's first three
- * parameters) or changes to any Cell (by providing `null` wildcards).
+ * You can either listen to a single Cell being added or removed (by specifying
+ * the Table Id, Row Id, and Cell Id as the method's first three parameters) or
+ * changes to any Cell (by providing `null` wildcards).
  *
- * All, some, or none of the `tableId`, `rowId`, and `cellId` parameters can
- * be wildcarded with `null`. You can listen to a specific Cell in a specific
- * Row in a specific Table, any Cell in any Row in any Table, for example - or
- * every other combination of wildcards.
+ * All, some, or none of the `tableId`, `rowId`, and `cellId` parameters can be
+ * wildcarded with `null`. You can listen to a specific Cell in a specific Row
+ * in a specific Table, any Cell in any Row in any Table, for example - or every
+ * other combination of wildcards.
  *
  * Unlike the addHasCellListener method, which returns a listener Id and
  * requires you to remove it manually, the useHasCellListener hook manages this
@@ -5518,8 +5528,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * dependencies) or the component unmounts, the listener on the underlying Store
  * will be deleted.
  * @param valueId The Id of the Value to listen to, or `null` as a wildcard.
- * @param listener The function that will be called whenever the matching
- * Value is added or removed.
+ * @param listener The function that will be called whenever the matching Value
+ * is added or removed.
  * @param listenerDeps An optional array of dependencies for the `listener`
  * function, which, if any change, result in the re-registration of the
  * listener. This parameter defaults to an empty array.
@@ -5869,18 +5879,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => Metrics,
  *   createDeps?: React.DependencyList,
- * ): Metrics;
+ * ): Metrics | undefined;
  * ```
  *
  * It is possible to create a Metrics object outside of the React app with the
  * regular createMetrics function and pass it in, but you may prefer to create
- * it within the app, perhaps inside the top-level component. To defend against
- * a new Metrics object being created every time the app renders or re-renders,
- * the useCreateMetrics hook wraps the creation in a memoization.
- *
- * The useCreateMetrics hook is a very thin wrapper around the React `useMemo`
- * hook, defaulting to the provided Store as its dependency, so that by default,
- * the creation only occurs once per Store.
+ * it within the app, perhaps inside the top-level component. To prevent a new
+ * Metrics object being created every time the app renders or re-renders, since
+ * v5.0 the useCreateMetrics hook performs the creation in an effect. As a
+ * result this hook will return `undefined` on the brief first render, which you
+ * should defend against.
  *
  * If your `create` function contains other dependencies, the changing of which
  * should also cause the Metrics object to be recreated, you can provide them in
@@ -5915,7 +5923,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *       'species',
  *     );
  *   });
- *   return <span>{metrics.getMetric('speciesCount')}</span>;
+ *   return <span>{metrics?.getMetric('speciesCount')}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -5953,7 +5961,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     },
  *     [tableToCount],
  *   );
- *   return <span>{metrics.getMetric('tableCount')}</span>;
+ *   return <span>{metrics?.getMetric('tableCount')}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -5976,7 +5984,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => Metrics<Schemas>,
     createDeps?: React.DependencyList,
-  ) => Metrics<Schemas>;
+  ) => Metrics<Schemas> | undefined;
 
   /**
  * The useMetricsIds hook is used to retrieve the Ids of all the named Metrics
@@ -6401,18 +6409,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => Indexes,
  *   createDeps?: React.DependencyList,
- * ): Indexes;
+ * ): Indexes | undefined;
  * ```
  *
  * It is possible to create an Indexes object outside of the React app with the
  * regular createIndexes function and pass it in, but you may prefer to create
- * it within the app, perhaps inside the top-level component. To defend against
- * a new Indexes object being created every time the app renders or re-renders,
- * the useCreateIndexes hook wraps the creation in a memoization.
- *
- * The useCreateIndexes hook is a very thin wrapper around the React `useMemo`
- * hook, defaulting to the provided Store as its dependency, so that by default,
- * the creation only occurs once per Store.
+ * it within the app, perhaps inside the top-level component. To prevent a new
+ * Indexes object being created every time the app renders or re-renders, since
+ * v5.0 the useCreateIndexes hook performs the creation in an effect. As a
+ * result this hook will return `undefined` on the brief first render, which you
+ * should defend against.
  *
  * If your `create` function contains other dependencies, the changing of which
  * should also cause the Indexes object to be recreated, you can provide them in
@@ -6452,7 +6458,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *       'species',
  *     );
  *   });
- *   return <span>{JSON.stringify(indexes.getSliceIds('bySpecies'))}</span>;
+ *   return <span>{JSON.stringify(indexes?.getSliceIds('bySpecies'))}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -6493,7 +6499,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     },
  *     [cellToIndex],
  *   );
- *   return <span>{JSON.stringify(indexes.getSliceIds('byCell'))}</span>;
+ *   return <span>{JSON.stringify(indexes?.getSliceIds('byCell'))}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -6516,7 +6522,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => Indexes<Schemas>,
     createDeps?: React.DependencyList,
-  ) => Indexes<Schemas>;
+  ) => Indexes<Schemas> | undefined;
 
   /**
  * The useIndexesIds hook is used to retrieve the Ids of all the named Indexes
@@ -7160,19 +7166,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => Relationships,
  *   createDeps?: React.DependencyList,
- * ): Relationships;
+ * ): Relationships | undefined;
  * ```
  *
  * It is possible to create a Relationships object outside of the React app with
  * the regular createRelationships function and pass it in, but you may prefer
  * to create it within the app, perhaps inside the top-level component. To
- * defend against a new Relationships object being created every time the app
- * renders or re-renders, the useCreateRelationships hook wraps the creation in
- * a memoization.
- *
- * The useCreateRelationships hook is a very thin wrapper around the React
- * `useMemo` hook, defaulting to the provided Store as its dependency, so that
- * by default, the creation only occurs once per Store.
+ * prevent a new Relationships object being created every time the app renders
+ * or re-renders, since v5.0 the useCreateRelationships hook performs the
+ * creation in an effect. As a result this hook will return `undefined` on the
+ * brief first render, which you should defend against.
  *
  * If your `create` function contains other dependencies, the changing of which
  * should also cause the Relationships object to be recreated, you can provide
@@ -7214,7 +7217,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *       'species',
  *     );
  *   });
- *   return <span>{relationships.getRemoteRowId('petSpecies', 'fido')}</span>;
+ *   return (
+ *     <span>{relationships?.getRemoteRowId('petSpecies', 'fido')}</span>
+ *   );
  * };
  *
  * const app = document.createElement('div');
@@ -7260,7 +7265,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     },
  *     [remoteTableAndCellToLink],
  *   );
- *   return <span>{relationships.getRemoteRowId('cellLinked', 'fido')}</span>;
+ *   return (
+ *     <span>{relationships?.getRemoteRowId('cellLinked', 'fido')}</span>
+ *   );
  * };
  *
  * const app = document.createElement('div');
@@ -7283,7 +7290,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => Relationships<Schemas>,
     createDeps?: React.DependencyList,
-  ) => Relationships<Schemas>;
+  ) => Relationships<Schemas> | undefined;
 
   /**
  * The useRelationshipsIds hook is used to retrieve the Ids of all the named
@@ -8222,18 +8229,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => Queries,
  *   createDeps?: React.DependencyList,
- * ): Queries;
+ * ): Queries | undefined;
  * ```
  *
  * It is possible to create a Queries object outside of the React app with the
  * regular createQueries function and pass it in, but you may prefer to create
- * it within the app, perhaps inside the top-level component. To defend against
- * a new Queries object being created every time the app renders or re-renders,
- * the useCreateQueries hook wraps the creation in a memoization.
- *
- * The useCreateQueries hook is a very thin wrapper around the React `useMemo`
- * hook, defaulting to the provided Store as its dependency, so that by default,
- * the creation only occurs once per Store.
+ * it within the app, perhaps inside the top-level component. To prevent a new
+ * Queries object being created every time the app renders or re-renders, since
+ * v5.0 the useCreateQueries hook performs the creation in an effect. As a
+ * result this hook will return `undefined` on the brief first render, which you
+ * should defend against.
  *
  * If your `create` function contains other dependencies, the changing of which
  * should also cause the Queries object to be recreated, you can provide them in
@@ -8276,7 +8281,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     );
  *   });
  *   return (
- *     <span>{queries.getResultCell('dogColors', 'fido', 'color')}</span>
+ *     <span>{queries?.getResultCell('dogColors', 'fido', 'color')}</span>
  *   );
  * };
  *
@@ -8318,7 +8323,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     );
  *   });
  *   return (
- *     <span>{queries.getResultCell('dogColors', 'fido', 'color')}</span>
+ *     <span>{queries?.getResultCell('dogColors', 'fido', 'color')}</span>
  *   );
  * };
  *
@@ -8340,7 +8345,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => Queries<Schemas>,
     createDeps?: React.DependencyList,
-  ) => Queries<Schemas>;
+  ) => Queries<Schemas> | undefined;
 
   /**
  * The useQueriesIds hook is used to retrieve the Ids of all the named Queries
@@ -10432,19 +10437,16 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => Checkpoints,
  *   createDeps?: React.DependencyList,
- * ): Checkpoints;
+ * ): Checkpoints | undefined;
  * ```
  *
  * It is possible to create a Checkpoints object outside of the React app with
  * the regular createCheckpoints function and pass it in, but you may prefer to
- * create it within the app, perhaps inside the top-level component. To defend
- * against a new Checkpoints object being created every time the app renders or
- * re-renders, the useCreateCheckpoints hook wraps the creation in a
- * memoization.
- *
- * The useCreateCheckpoints hook is a very thin wrapper around the React
- * `useMemo` hook, defaulting to the provided Store as its dependency, so that
- * by default, the creation only occurs once per Store.
+ * create it within the app, perhaps inside the top-level component. To prevent
+ * a new Checkpoints object being created every time the app renders or
+ * re-renders, since v5.0 the useCreateMetrics hook performs the creation in an
+ * effect. As a result this hook will return `undefined` on the brief first
+ * render, which you should defend against.
  *
  * If your `create` function contains other dependencies, the changing of which
  * should also cause the Checkpoints object to be recreated, you can provide
@@ -10474,7 +10476,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     console.log('Checkpoints created');
  *     return createCheckpoints(store).setSize(10);
  *   });
- *   return <span>{JSON.stringify(checkpoints.getCheckpointIds())}</span>;
+ *   return <span>{JSON.stringify(checkpoints?.getCheckpointIds())}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -10506,7 +10508,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     },
  *     [size],
  *   );
- *   return <span>{JSON.stringify(checkpoints.getCheckpointIds())}</span>;
+ *   return <span>{JSON.stringify(checkpoints?.getCheckpointIds())}</span>;
  * };
  *
  * const app = document.createElement('div');
@@ -10529,7 +10531,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => Checkpoints<Schemas>,
     createDeps?: React.DependencyList,
-  ) => Checkpoints<Schemas>;
+  ) => Checkpoints<Schemas> | undefined;
 
   /**
  * The useCheckpointsIds hook is used to retrieve the Ids of all the named
@@ -11487,20 +11489,18 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   store: Store,
  *   create: (store: Store) => PersisterOrUndefined,
  *   createDeps?: React.DependencyList,
- *   then?: (persister: PersisterOrUndefined) => Promise<void>,
+ *   then?: (persister: Persister) => Promise<void>,
  *   thenDeps?: React.DependencyList,
- *   destroy?: (persister: PersisterOrUndefined) => void,
+ *   destroy?: (persister: Persister) => void,
  *   destroyDeps?: React.DependencyList,
  * ): PersisterOrUndefined;
  * ```
  *
  * It is possible to create a Persister outside of the React app with the
  * regular createPersister function and pass it in, but you may prefer to create
- * it within the app, perhaps inside the top-level component. To defend against
- * a new Persister being created every time the app renders or re-renders, the
- * useCreatePersister hook wraps the creation in a memoization, and provides a
- * second callback so that you can configure the Persister, once, and
- * asynchronously, when it is created.
+ * it within the app, perhaps inside the top-level component. To prevent a new
+ * Persister being created every time the app renders or re-renders, since v5.0
+ * the useCreateMetrics hook performs the creation in an effect.
  *
  * If your `create` function (the second parameter to the hook) contains
  * dependencies, the changing of which should cause the Persister to be
@@ -11508,19 +11508,18 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * you would for any React hook with dependencies. The Store passed in as the
  * first parameter of this hook is used as a dependency by default.
  *
- * A second `then` callback can be provided as the fourth parameter. This is
- * called after the creation, and, importantly, can be asynchronous, so that you
- * can configure the Persister with the startAutoLoad method and startAutoSave
- * method, for example. If this callback contains dependencies, the changing of
- * which should cause the Persister to be reconfigured, you can provide them in
- * an array in the fifth parameter. The Persister itself 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, importantly, can be asynchronous, so
+ * that you can configure the Persister with the startAutoLoad method and
+ * startAutoSave method, for example. If this callback contains dependencies,
+ * the changing of which should cause the Persister to be reconfigured, you can
+ * provide them in an array in the fifth parameter. The Persister itself is used
+ * as a dependency by default.
  *
  * Since v4.3.0, the `create` function can return undefined, meaning that you
  * can enable or disable persistence conditionally within this hook. This is
  * useful for applications which might turn on or off their cloud persistence or
- * collaboration features. As a result, the `then` callback may also get passed
- * undefined, which you should handle accordingly.
+ * collaboration features.
  *
  * Since v4.3.19, a `destroy` function can be provided which will be called
  * after an old Persister is destroyed due to a change in the `createDeps`
@@ -11657,12 +11656,170 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     store: Store<Schemas>,
     create: (store: Store<Schemas>) => PersisterOrUndefined,
     createDeps?: React.DependencyList,
-    then?: (persister?: PersisterOrUndefined) => Promise<void>,
+    then?: (persister: Persister<Schemas>) => Promise<void>,
     thenDeps?: React.DependencyList,
-    destroy?: (persister: PersisterOrUndefined) => void,
+    destroy?: (persister: Persister<Schemas>) => void,
     destroyDeps?: React.DependencyList,
   ) => PersisterOrUndefined;
 
+  /**
+ * The useCreateSynchronizer hook is used to create a Synchronizer within a
+ * React application along with convenient memoization and callbacks.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * 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;
+ * ```
+ *
+ * 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
+ */
+  useCreateSynchronizer: <
+    SynchronizerOrUndefined extends Synchronizer<Schemas> | undefined,
+  >(
+    store: MergeableStore<Schemas>,
+    create: (
+      store: MergeableStore<Schemas>,
+    ) => Promise<SynchronizerOrUndefined>,
+    createDeps?: React.DependencyList,
+    then?: (synchronizer: Synchronizer<Schemas>) => Promise<void>,
+    thenDeps?: React.DependencyList,
+    destroy?: (synchronizer: Synchronizer<Schemas>) => void,
+    destroyDeps?: React.DependencyList,
+  ) => SynchronizerOrUndefined;
+
   /**
  * The ExtraProps type represents a set of arbitrary additional props.
  * @category Props