tinybase 5.2.2 → 5.3.0-beta.1

package/@types/ui-react/index.d.cts

@@ -5902,6 +5902,76 @@ export function useMetricsOrMetricsById(
   metricsOrMetricsId?: MetricsOrMetricsId,
 ): Metrics | undefined;
 
+/**
+ * The useProvideMetrics hook is used to add a Metrics object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCreateMetrics,
+ *   useCreateStore,
+ *   useMetrics,
+ *   useProvideMetrics,
+ * } from 'tinybase/ui-react';
+ * import {createMetrics, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
+ */
+export function useProvideMetrics(metricsId: Id, metrics: Metrics): void;
+
 /**
  * The useMetricIds hook gets an array of the Metric Ids registered with a
  * Metrics object, and registers a listener so that any changes to that result
@@ -6454,6 +6524,9 @@ export function useIndexesOrIndexesById(
   indexesOrIndexesId?: IndexesOrIndexesId,
 ): Indexes | undefined;
 
+// useProvideIndexes
+export function useProvideIndexes(indexesId: Id, indexes: Indexes): void;
+
 /**
  * The useIndexIds hook gets an array of the Index Ids registered with an
  * Indexes object, and registers a listener so that any changes to that result
@@ -7258,6 +7331,12 @@ export function useRelationshipsOrRelationshipsById(
   relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId,
 ): Relationships | undefined;
 
+// useProvideRelationships
+export function useProvideRelationships(
+  relationshipsId: Id,
+  relationships: Relationships,
+): void;
+
 /**
  * The useRelationshipIds hook gets an array of the Relationship Ids registered
  * with a Relationships object, and registers a listener so that any changes to
@@ -8306,6 +8385,9 @@ export function useQueriesOrQueriesById(
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): Queries | undefined;
 
+// useProvideQueries
+export function useProvideQueries(queriesId: Id, queries: Queries): void;
+
 /**
  * The useQueryIds hook gets an array of the Query Ids registered with a Queries
  * object, and registers a listener so that any changes to that result will
@@ -10486,10 +10568,87 @@ export function useCheckpoints(id?: Id): Checkpoints | undefined;
  * @category Checkpoints hooks
  * @since v4.1.0
  */
+/**
+ * The useProvideCheckpoints hook is used to add a Checkpoints object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCheckpoints,
+ *   useCreateCheckpoints,
+ *   useCreateStore,
+ *   useProvideCheckpoints,
+ * } from 'tinybase/ui-react';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
+ */
 export function useCheckpointsOrCheckpointsById(
   checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId,
 ): Checkpoints | undefined;
 
+// useProvideCheckpoints
+export function useProvideCheckpoints(
+  checkpointsId: Id,
+  checkpoints: Checkpoints,
+): void;
+
 /**
  * The useCheckpointIds hook returns an array of the checkpoint Ids being
  * managed by this Checkpoints object, and registers a listener so that any

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

@@ -5902,6 +5902,76 @@ export function useMetricsOrMetricsById(
   metricsOrMetricsId?: MetricsOrMetricsId,
 ): Metrics | undefined;
 
+/**
+ * The useProvideMetrics hook is used to add a Metrics object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCreateMetrics,
+ *   useCreateStore,
+ *   useMetrics,
+ *   useProvideMetrics,
+ * } from 'tinybase/ui-react';
+ * import {createMetrics, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
+ */
+export function useProvideMetrics(metricsId: Id, metrics: Metrics): void;
+
 /**
  * The useMetricIds hook gets an array of the Metric Ids registered with a
  * Metrics object, and registers a listener so that any changes to that result
@@ -6454,6 +6524,9 @@ export function useIndexesOrIndexesById(
   indexesOrIndexesId?: IndexesOrIndexesId,
 ): Indexes | undefined;
 
+// useProvideIndexes
+export function useProvideIndexes(indexesId: Id, indexes: Indexes): void;
+
 /**
  * The useIndexIds hook gets an array of the Index Ids registered with an
  * Indexes object, and registers a listener so that any changes to that result
@@ -7258,6 +7331,12 @@ export function useRelationshipsOrRelationshipsById(
   relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId,
 ): Relationships | undefined;
 
+// useProvideRelationships
+export function useProvideRelationships(
+  relationshipsId: Id,
+  relationships: Relationships,
+): void;
+
 /**
  * The useRelationshipIds hook gets an array of the Relationship Ids registered
  * with a Relationships object, and registers a listener so that any changes to
@@ -8306,6 +8385,9 @@ export function useQueriesOrQueriesById(
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): Queries | undefined;
 
+// useProvideQueries
+export function useProvideQueries(queriesId: Id, queries: Queries): void;
+
 /**
  * The useQueryIds hook gets an array of the Query Ids registered with a Queries
  * object, and registers a listener so that any changes to that result will
@@ -10486,10 +10568,87 @@ export function useCheckpoints(id?: Id): Checkpoints | undefined;
  * @category Checkpoints hooks
  * @since v4.1.0
  */
+/**
+ * The useProvideCheckpoints hook is used to add a Checkpoints object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCheckpoints,
+ *   useCreateCheckpoints,
+ *   useCreateStore,
+ *   useProvideCheckpoints,
+ * } from 'tinybase/ui-react';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
+ */
 export function useCheckpointsOrCheckpointsById(
   checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId,
 ): Checkpoints | undefined;
 
+// useProvideCheckpoints
+export function useProvideCheckpoints(
+  checkpointsId: Id,
+  checkpoints: Checkpoints,
+): void;
+
 /**
  * The useCheckpointIds hook returns an array of the checkpoint Ids being
  * managed by this Checkpoints object, and registers a listener so that any

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

@@ -6802,6 +6802,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     metricsOrMetricsId?: MetricsOrMetricsId<Schemas>,
   ) => Metrics<Schemas> | undefined;
 
+  // useProvideMetrics
+  useProvideMetrics: (metricsId: Id, metrics: Metrics<Schemas>) => void;
+
   /**
  * The useMetricIds hook gets an array of the Metric Ids registered with a
  * Metrics object, and registers a listener so that any changes to that result
@@ -7404,6 +7407,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
   ) => Indexes<Schemas> | undefined;
 
+  // useProvideIndexes
+  useProvideIndexes: (indexesId: Id, indexes: Indexes<Schemas>) => void;
+
   /**
  * The useIndexIds hook gets an array of the Index Ids registered with an
  * Indexes object, and registers a listener so that any changes to that result
@@ -8280,6 +8286,12 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId<Schemas>,
   ) => Relationships<Schemas> | undefined;
 
+  // useProvideRelationships
+  useProvideRelationships: (
+    relationshipsId: Id,
+    relationships: Relationships<Schemas>,
+  ) => void;
+
   /**
  * The useRelationshipIds hook gets an array of the Relationship Ids registered
  * with a Relationships object, and registers a listener so that any changes to
@@ -9426,6 +9438,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
   ) => Queries<Schemas> | undefined;
 
+  // useProvideQueries
+  useProvideQueries: (queriesId: Id, queries: Queries<Schemas>) => void;
+
   /**
  * The useQueryIds hook gets an array of the Query Ids registered with a Queries
  * object, and registers a listener so that any changes to that result will
@@ -11811,11 +11826,88 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * ```
  * @category Checkpoints hooks
  * @since v4.1.0
+ */
+/**
+ * The useProvideCheckpoints hook is used to add a Checkpoints object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCheckpoints,
+ *   useCreateCheckpoints,
+ *   useCreateStore,
+ *   useProvideCheckpoints,
+ * } from 'tinybase/ui-react';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
  */
   useCheckpointsOrCheckpointsById: (
     checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId<Schemas>,
   ) => Checkpoints<Schemas> | undefined;
 
+  // useProvideCheckpoints
+  useProvideCheckpoints: (
+    checkpointsId: Id,
+    checkpoints: Checkpoints<Schemas>,
+  ) => void;
+
   /**
  * The useCheckpointIds hook returns an array of the checkpoint Ids being
  * managed by this Checkpoints object, and registers a listener so that any

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

@@ -6802,6 +6802,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     metricsOrMetricsId?: MetricsOrMetricsId<Schemas>,
   ) => Metrics<Schemas> | undefined;
 
+  // useProvideMetrics
+  useProvideMetrics: (metricsId: Id, metrics: Metrics<Schemas>) => void;
+
   /**
  * The useMetricIds hook gets an array of the Metric Ids registered with a
  * Metrics object, and registers a listener so that any changes to that result
@@ -7404,6 +7407,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     indexesOrIndexesId?: IndexesOrIndexesId<Schemas>,
   ) => Indexes<Schemas> | undefined;
 
+  // useProvideIndexes
+  useProvideIndexes: (indexesId: Id, indexes: Indexes<Schemas>) => void;
+
   /**
  * The useIndexIds hook gets an array of the Index Ids registered with an
  * Indexes object, and registers a listener so that any changes to that result
@@ -8280,6 +8286,12 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId<Schemas>,
   ) => Relationships<Schemas> | undefined;
 
+  // useProvideRelationships
+  useProvideRelationships: (
+    relationshipsId: Id,
+    relationships: Relationships<Schemas>,
+  ) => void;
+
   /**
  * The useRelationshipIds hook gets an array of the Relationship Ids registered
  * with a Relationships object, and registers a listener so that any changes to
@@ -9426,6 +9438,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
   ) => Queries<Schemas> | undefined;
 
+  // useProvideQueries
+  useProvideQueries: (queriesId: Id, queries: Queries<Schemas>) => void;
+
   /**
  * The useQueryIds hook gets an array of the Query Ids registered with a Queries
  * object, and registers a listener so that any changes to that result will
@@ -11811,11 +11826,88 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * ```
  * @category Checkpoints hooks
  * @since v4.1.0
+ */
+/**
+ * The useProvideCheckpoints hook is used to add a Checkpoints object by Id to a
+ * Provider component, but imperatively from a component within it.
+ *
+ * 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 {
+ *   Provider,
+ *   useCheckpoints,
+ *   useCreateCheckpoints,
+ *   useCreateStore,
+ *   useProvideCheckpoints,
+ * } from 'tinybase/ui-react';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * 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
  */
   useCheckpointsOrCheckpointsById: (
     checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId<Schemas>,
   ) => Checkpoints<Schemas> | undefined;
 
+  // useProvideCheckpoints
+  useProvideCheckpoints: (
+    checkpointsId: Id,
+    checkpoints: Checkpoints<Schemas>,
+  ) => void;
+
   /**
  * The useCheckpointIds hook returns an array of the checkpoint Ids being
  * managed by this Checkpoints object, and registers a listener so that any