tinybase 9.4.0 → 9.5.0-beta.1

package/@types/ui-react/with-schemas/index.d.ts

@@ -7520,7 +7520,80 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     metricsOrMetricsId?: MetricsOrMetricsId<Schemas>,
   ) => Metrics<Schemas> | undefined;
 
-  // useProvideMetrics
+  /**
+ * The useProvideMetrics hook is used to add a Metrics object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideMetrics(metricsId: Id, metrics: Metrics): void;
+ * ```
+ *
+ * Normally you will register a Metrics object by Id in a context by using the
+ * `metricsById` prop of the top-level Provider component. This hook, however,
+ * lets you dynamically add a new Metrics object to the context, from within a
+ * descendent component. This is useful for applications where the set of
+ * Metrics objects is not known at the time of the first render of the root
+ * Provider.
+ *
+ * A Metrics object added to the Provider context in this way will be available
+ * to other components within the context (using the useMetrics hook and so on).
+ * If you use the same Id as an existing Metrics object registration, the new
+ * one will take priority over one provided by the `metricsById` prop.
+ *
+ * Note that other components that consume a Metrics object registered like this
+ * should defend against it being undefined at first. On the first render, the
+ * other component will likely not yet have completed the registration. In the
+ * example below, we use the null-safe `useMetrics('petMetrics')?` to do this.
+ * @param metricsId The Id of the Metrics object to be registered with the
+ * Provider.
+ * @param metrics The Metrics object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Metrics object into it which is then consumable by a peer child component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createMetrics, createStore} from 'tinybase';
+ * import {
+ *   Provider,
+ *   useCreateMetrics,
+ *   useCreateStore,
+ *   useMetrics,
+ *   useProvideMetrics,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterMetrics />
+ *     <ConsumeMetrics />
+ *   </Provider>
+ * );
+ * const RegisterMetrics = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore().setCell('pets', 'fido', 'color', 'brown'),
+ *   );
+ *   const metrics = useCreateMetrics(store, (store) =>
+ *     createMetrics(store).setMetricDefinition('petCount', 'pets', 'count'),
+ *   );
+ *   useProvideMetrics('petMetrics', metrics);
+ *   return null;
+ * };
+ * const ConsumeMetrics = () => (
+ *   <span>{useMetrics('petMetrics')?.getMetric('petCount')}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>1</span>'
+ * ```
+ * @category Metrics hooks
+ * @since v5.3.0
+ */
   useProvideMetrics: (metricsId: Id, metrics: Metrics<Schemas>) => void;
 
   /**
@@ -8125,7 +8198,87 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
   ) => Indexes<Schemas> | undefined;
 
-  // useProvideIndexes
+  /**
+ * The useProvideIndexes hook is used to add an Indexes object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideIndexes(indexesId: Id, indexes: Indexes): void;
+ * ```
+ *
+ * Normally you will register an Indexes object by Id in a context by using the
+ * `indexesById` prop of the top-level Provider component. This hook, however,
+ * lets you dynamically add a new Indexes object to the context, from within a
+ * descendent component. This is useful for applications where the set of
+ * Indexes objects is not known at the time of the first render of the root
+ * Provider.
+ *
+ * A Indexes object added to the Provider context in this way will be available
+ * to other components within the context (using the useIndexes hook and so on).
+ * If you use the same Id as an existing Indexes object registration, the new
+ * one will take priority over one provided by the `indexesById` prop.
+ *
+ * Note that other components that consume an Indexes object registered like
+ * this should defend against it being undefined at first. On the first render,
+ * the other component will likely not yet have completed the registration. In
+ * the example below, we use the null-safe `useIndexes('petIndexes')?` to do
+ * this.
+ * @param indexesId The Id of the Indexes object to be registered with the
+ * Provider.
+ * @param indexes The Indexes object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers an
+ * Indexes object into it which is then consumable by a peer child component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createIndexes, createStore} from 'tinybase';
+ * import {
+ *   Provider,
+ *   useCreateIndexes,
+ *   useCreateStore,
+ *   useIndexes,
+ *   useProvideIndexes,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterIndexes />
+ *     <ConsumeIndexes />
+ *   </Provider>
+ * );
+ * const RegisterIndexes = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore().setCell('pets', 'fido', 'color', 'brown'),
+ *   );
+ *   const indexes = useCreateIndexes(store, (store) =>
+ *     createIndexes(store).setIndexDefinition(
+ *       'petsByColor',
+ *       'pets',
+ *       'color',
+ *     ),
+ *   );
+ *   useProvideIndexes('petIndexes', indexes);
+ *   return null;
+ * };
+ * const ConsumeIndexes = () => (
+ *   <span>
+ *     {JSON.stringify(useIndexes('petIndexes')?.getSliceIds('petsByColor'))}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["brown"]</span>'
+ * ```
+ * @category Indexes hooks
+ * @since v5.3.0
+ */
   useProvideIndexes: (indexesId: Id, indexes: Indexes<Schemas>) => void;
 
   /**
@@ -9065,7 +9218,98 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId<Schemas>,
   ) => Relationships<Schemas> | undefined;
 
-  // useProvideRelationships
+  /**
+ * The useProvideRelationships hook is used to add a Relationships object by Id
+ * to a Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideRelationships(
+ *   relationshipsId: Id,
+ *   relationships: Relationships,
+ * ): void;
+ * ```
+ *
+ * Normally you will register a Relationships object by Id in a context by using
+ * the `relationshipsById` prop of the top-level Provider component. This hook,
+ * however, lets you dynamically add a new Relationships object to the context,
+ * from within a component. This is useful for applications where the set of
+ * Relationships objects is not known at the time of the first render of the
+ * root Provider.
+ *
+ * A Relationships object added to the Provider context in this way will be
+ * available to other components within the context (using the useRelationships
+ * hook and so on). If you use the same Id as an existing Relationships object
+ * registration, the new one will take priority over one provided by the
+ * `relationshipsById` prop.
+ *
+ * Note that other components that consume a Relationships object registered
+ * like this should defend against it being undefined at first. On the first
+ * render, the other component will likely not yet have completed the
+ * registration. In the example below, we use the null-safe
+ * `useRelationships('petRelationships')?` to do this.
+ * @param relationshipsId The Id of the Relationships object to be registered
+ * with the Provider.
+ * @param relationships The Relationships object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Relationships object into it which is then consumable by a peer child
+ * component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createRelationships, createStore} from 'tinybase';
+ * import {
+ *   Provider,
+ *   useCreateRelationships,
+ *   useCreateStore,
+ *   useProvideRelationships,
+ *   useRelationships,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterRelationships />
+ *     <ConsumeRelationships />
+ *   </Provider>
+ * );
+ * const RegisterRelationships = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore()
+ *       .setTable('pets', {fido: {species: 'dog'}})
+ *       .setTable('species', {dog: {price: 5}}),
+ *   );
+ *   const relationships = useCreateRelationships(store, (store) =>
+ *     createRelationships(store).setRelationshipDefinition(
+ *       'petSpecies',
+ *       'pets',
+ *       'species',
+ *       'species',
+ *     ),
+ *   );
+ *   useProvideRelationships('petRelationships', relationships);
+ *   return null;
+ * };
+ * const ConsumeRelationships = () => (
+ *   <span>
+ *     {useRelationships('petRelationships')?.getRemoteRowId(
+ *       'petSpecies',
+ *       'fido',
+ *     )}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>dog</span>'
+ * ```
+ * @category Relationships hooks
+ * @since v5.3.0
+ */
   useProvideRelationships: (
     relationshipsId: Id,
     relationships: Relationships<Schemas>,
@@ -10217,7 +10461,88 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
   ) => Queries<Schemas> | undefined;
 
-  // useProvideQueries
+  /**
+ * The useProvideQueries hook is used to add a Queries object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideQueries(queriesId: Id, queries: Queries): void;
+ * ```
+ *
+ * Normally you will register a Queries object by Id in a context by using the
+ * `queriesById` prop of the top-level Provider component. This hook, however,
+ * lets you dynamically add a new Queries object to the context, from within a
+ * component. This is useful for applications where the set of Queries objects
+ * is not known at the time of the first render of the root Provider.
+ *
+ * A Queries object added to the Provider context in this way will be available
+ * to other components within the context (using the useQueries hook and so on).
+ * If you use the same Id as an existing Queries object registration, the new
+ * one will take priority over one provided by the `queriesById` prop.
+ *
+ * Note that other components that consume a Queries object registered like this
+ * should defend against it being undefined at first. On the first render, the
+ * other component will likely not yet have completed the registration. In the
+ * example below, we use the null-safe `useQueries('petQueries')?` to do this.
+ * @param queriesId The Id of the Queries object to be registered with the
+ * Provider.
+ * @param queries The Queries object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Queries object into it which is then consumable by a peer child component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {
+ *   Provider,
+ *   useCreateQueries,
+ *   useCreateStore,
+ *   useProvideQueries,
+ *   useQueries,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterQueries />
+ *     <ConsumeQueries />
+ *   </Provider>
+ * );
+ * const RegisterQueries = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore().setRow('pets', 'fido', {color: 'brown', legs: 4}),
+ *   );
+ *   const queries = useCreateQueries(store, (store) =>
+ *     createQueries(store).setQueryDefinition(
+ *       'brownLegs',
+ *       'pets',
+ *       ({select, where}) => {
+ *         select('legs');
+ *         where('color', 'brown');
+ *       },
+ *     ),
+ *   );
+ *   useProvideQueries('petQueries', queries);
+ *   return null;
+ * };
+ * const ConsumeQueries = () => (
+ *   <span>
+ *     {JSON.stringify(useQueries('petQueries')?.getResultTable('brownLegs'))}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>{\"fido\":{\"legs\":4}}</span>'
+ * ```
+ * @category Queries hooks
+ * @since v5.3.0
+ */
   useProvideQueries: (queriesId: Id, queries: Queries<Schemas>) => void;
 
   /**
@@ -13610,7 +13935,86 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId<Schemas>,
   ) => Checkpoints<Schemas> | undefined;
 
-  // useProvideCheckpoints
+  /**
+ * The useProvideCheckpoints hook is used to add a Checkpoints object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideCheckpoints(
+ *   checkpointsId: Id,
+ *   checkpoints: Checkpoints,
+ * ): void;
+ * ```
+ *
+ * Normally you will register a Checkpoints object by Id in a context by using
+ * the `checkpointsById` prop of the top-level Provider component. This hook,
+ * however, lets you dynamically add a new Checkpoints object to the context,
+ * from within a component. This is useful for applications where the set of
+ * Checkpoints objects is not known at the time of the first render of the root
+ * Provider.
+ *
+ *  A Checkpoints object added to the Provider context in this way will be
+ *  available to other components within the context (using the useCheckpoints
+ *  hook and so on). If you use the same Id as an existing Checkpoints object
+ *  registration, the new one will take priority over one provided by the
+ *  `checkpointsById` prop.
+ *
+ *  Note that other components that consume a Checkpoints object registered like
+ *  this should defend against it being undefined at first. On the first render,
+ *  the other component will likely not yet have completed the registration. In
+ *  the example below, we use the null-safe `useCheckpoints('petCheckpoints')?`
+ *  to do this.
+ * @param checkpointsId The Id of the Checkpoints object to be registered with
+ * the Provider.
+ * @param checkpoints The Checkpoints object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Checkpoints object into it which is then consumable by a peer child
+ * component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import {
+ *   Provider,
+ *   useCheckpoints,
+ *   useCreateCheckpoints,
+ *   useCreateStore,
+ *   useProvideCheckpoints,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterCheckpoints />
+ *     <ConsumeCheckpoints />
+ *   </Provider>
+ * );
+ * const RegisterCheckpoints = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore().setCell('pets', 'fido', 'color', 'brown'),
+ *   );
+ *   const checkpoints = useCreateCheckpoints(store, createCheckpoints);
+ *   useProvideCheckpoints('petCheckpoints', checkpoints);
+ *   return null;
+ * };
+ * const ConsumeCheckpoints = () => (
+ *   <span>
+ *     {JSON.stringify(useCheckpoints('petCheckpoints')?.getCheckpointIds())}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>[[],"0",[]]</span>'
+ * ```
+ * @category Checkpoints hooks
+ * @since v5.3.0
+ */
   useProvideCheckpoints: (
     checkpointsId: Id,
     checkpoints: Checkpoints<Schemas>,
@@ -14894,7 +15298,89 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     persisterOrPersisterId?: PersisterOrPersisterId<Schemas>,
   ) => Persister<Schemas, Persists.StoreOrMergeableStore> | undefined;
 
-  // useProvidePersister
+  /**
+ * The useProvidePersister hook is used to add a Persister object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvidePersister(
+ *   persisterId: Id,
+ *   persister: AnyPersister,
+ * ): void;
+ * ```
+ *
+ * Normally you will register a Persister object by Id in a context by using the
+ * `persistersById` prop of the top-level Provider component. This hook,
+ * however, lets you dynamically add a new Persister object to the context, from
+ * within a component. This is useful for applications where the set of
+ * Persister objects is not known at the time of the first render of the root
+ * Provider.
+ *
+ * A Persister object added to the Provider context in this way will be
+ * available to other components within the context (using the usePersister hook
+ * and so on). If you use the same Id as an existing Persister object
+ * registration, the new one will take priority over one provided by the
+ * `persistersById` prop.
+ *
+ * Note that other components that consume a Persister object registered like
+ * this should defend against it being undefined at first. On the first render,
+ * the other component will likely not yet have completed the registration. In
+ * the example below, we use the null-safe `usePersister('petPersister')?` to do
+ * this.
+ * @param persisterId The Id of the Persister object to be registered with the
+ * Provider.
+ * @param persister The Persister object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Persister object into it which is then consumable by a peer child
+ * component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+ * import {
+ *   Provider,
+ *   useCreatePersister,
+ *   useCreateStore,
+ *   usePersister,
+ *   useProvidePersister,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterPersister />
+ *     <ConsumePersister />
+ *   </Provider>
+ * );
+ * const RegisterPersister = () => {
+ *   const store = useCreateStore(() =>
+ *     createStore().setCell('pets', 'fido', 'color', 'brown'),
+ *   );
+ *   const persister = useCreatePersister(store, (store) =>
+ *     createSessionPersister(store, 'pets'),
+ *   );
+ *   useProvidePersister('petPersister', persister);
+ *   return null;
+ * };
+ * const ConsumePersister = () => (
+ *   <span>{usePersister('petPersister')?.getStatus()}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ *
+ * // ... // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>0</span>'
+ * ```
+ * @category Persister hooks
+ * @since v5.3.0
+ */
   useProvidePersister: (
     persisterId: Id,
     persister: AnyPersister<Schemas> | undefined,
@@ -15450,7 +15936,90 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     synchronizerOrSynchronizerId?: SynchronizerOrSynchronizerId<Schemas>,
   ) => Synchronizer<Schemas> | undefined;
 
-  // useProvideSynchronizer
+  /**
+ * The useProvideSynchronizer hook is used to add a Synchronizer object by Id to
+ * a Provider component, but imperatively from a component within it.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useProvideSynchronizer(
+ *   synchronizerId: Id,
+ *   synchronizer: Synchronizer,
+ * ): void;
+ * ```
+ *
+ * Normally you will register a Synchronizer object by Id in a context by using
+ * the `synchronizersById` prop of the top-level Provider component. This hook,
+ * however, lets you dynamically add a new Synchronizer object to the context,
+ * from within a component. This is useful for applications where the set of
+ * Synchronizer objects is not known at the time of the first render of the root
+ * Provider.
+ *
+ * A Synchronizer object added to the Provider context in this way will be
+ * available to other components within the context (using the useSynchronizer
+ * hook and so on). If you use the same Id as an existing Synchronizer object
+ * registration, the new one will take priority over one provided by the
+ * `synchronizersById` prop.
+ *
+ * Note that other components that consume a Synchronizer object registered like
+ * this should defend against it being undefined at first. On the first render,
+ * the other component will likely not yet have completed the registration. In
+ * the example below, we use the null-safe `useSynchronizer('petSynchronizer')?`
+ * to do this.
+ * @param synchronizerId The Id of the Synchronizer object to be registered with
+ * the Provider.
+ * @param synchronizer The Synchronizer object to be registered.
+ * @example
+ * This example creates a Provider context. A child component registers a
+ * Synchronizer object into it which is then consumable by a peer child
+ * component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+ * import {
+ *   Provider,
+ *   useCreateStore,
+ *   useCreateSynchronizer,
+ *   useProvideSynchronizer,
+ *   useSynchronizer,
+ * } from 'tinybase/ui-react';
+ *
+ * const App = () => (
+ *   <Provider>
+ *     <RegisterSynchronizer />
+ *     <ConsumeSynchronizer />
+ *   </Provider>
+ * );
+ * const RegisterSynchronizer = () => {
+ *   const store = useCreateStore(() =>
+ *     createMergeableStore().setCell('pets', 'fido', 'color', 'brown'),
+ *   );
+ *   const synchronizer = useCreateSynchronizer(
+ *     store,
+ *     createLocalSynchronizer,
+ *   );
+ *   useProvideSynchronizer('petSynchronizer', synchronizer);
+ *   return null;
+ * };
+ * const ConsumeSynchronizer = () => (
+ *   <span>{useSynchronizer('petSynchronizer')?.getStatus()}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ *
+ * // ... // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>0</span>'
+ * ```
+ * @category Synchronizer hooks
+ * @since v5.3.0
+ */
   useProvideSynchronizer: (
     synchronizerId: Id,
     synchronizer: Synchronizer<Schemas> | undefined,