tinybase 6.2.0-beta.0 → 6.2.0-beta.1

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

@@ -6736,7 +6736,81 @@ export function useIndexesOrIndexesById(
   indexesOrIndexesId?: IndexesOrIndexesId,
 ): Indexes | 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.
+ *
+ * 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
+ */
 export function useProvideIndexes(indexesId: Id, indexes: Indexes): void;
 
 /**
@@ -7543,7 +7617,89 @@ export function useRelationshipsOrRelationshipsById(
   relationshipsOrRelationshipsId?: RelationshipsOrRelationshipsId,
 ): Relationships | 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.
+ *
+ * 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
+ */
 export function useProvideRelationships(
   relationshipsId: Id,
   relationships: Relationships,
@@ -8597,7 +8753,82 @@ export function useQueriesOrQueriesById(
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): Queries | 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.
+ *
+ * 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
+ */
 export function useProvideQueries(queriesId: Id, queries: Queries): void;
 
 /**
@@ -10784,7 +11015,77 @@ export function useCheckpointsOrCheckpointsById(
   checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId,
 ): Checkpoints | 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.
+ *
+ * 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
+ */
 export function useProvideCheckpoints(
   checkpointsId: Id,
   checkpoints: Checkpoints,
@@ -11747,7 +12048,7 @@ export function useCreatePersister<
     store: PersistedStore<Persist>,
   ) => PersisterOrUndefined | Promise<PersisterOrUndefined>,
   createDeps?: React.DependencyList,
-  then?: (persister: Persister<Persist>) => Promise<void>,
+  then?: (persister: Persister<Persist>) => Promise<any>,
   thenDeps?: React.DependencyList,
   destroy?: (persister: Persister<Persist>) => void,
   destroyDeps?: React.DependencyList,
@@ -11932,7 +12233,80 @@ export function usePersisterOrPersisterById(
   persisterOrPersisterId?: PersisterOrPersisterId,
 ): AnyPersister | 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.
+ *
+ * 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
+ */
 export function useProvidePersister(
   persisterId: Id,
   persister: AnyPersister,
@@ -12435,7 +12809,81 @@ export function useSynchronizerOrSynchronizerById(
   synchronizerOrSynchronizerId?: SynchronizerOrSynchronizerId,
 ): Synchronizer | 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.
+ *
+ * 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
+ */
 export function useProvideSynchronizer(
   synchronizerId: Id,
   synchronizer: Synchronizer,

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

@@ -12964,7 +12964,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *     store: PersistedStore<Persist>,
  *   ) => PersisterOrUndefined | Promise<PersisterOrUndefined>,
  *   createDeps?: React.DependencyList,
- *   then?: (persister: Persister<Persist>) => Promise<void>,
+ *   then?: (persister: Persister<Persist>) => Promise<any>,
  *   thenDeps?: React.DependencyList,
  *   destroy?: (persister: Persister<Persist>) => void,
  *   destroyDeps?: React.DependencyList,
@@ -13161,9 +13161,11 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     PersisterOrUndefined extends Persister<Schemas, Persist> | undefined,
   >(
     store: PersistedStore<Schemas, Persist> | undefined,
-    create: (store: PersistedStore<Schemas, Persist>) => PersisterOrUndefined,
+    create: (
+      store: PersistedStore<Schemas, Persist>,
+    ) => PersisterOrUndefined | Promise<PersisterOrUndefined>,
     createDeps?: React.DependencyList,
-    then?: (persister: Persister<Schemas, Persist>) => Promise<void>,
+    then?: (persister: Persister<Schemas, Persist>) => Promise<any>,
     thenDeps?: React.DependencyList,
     destroy?: (persister: Persister<Schemas, Persist>) => void,
     destroyDeps?: React.DependencyList,