tinybase 6.1.0-beta.5 → 6.1.1

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

@@ -86,6 +86,7 @@ import type {
   RowCountListener,
   RowIdsListener,
   RowListener,
+  SortedRowIdsArgs,
   SortedRowIdsListener,
   Store,
   Table,
@@ -1659,6 +1660,57 @@ export function useSortedRowIds(
   storeOrStoreId?: StoreOrStoreId,
 ): Ids;
 
+/**
+ * When called with an object as the first argument, the useSortedRowIds method
+ * destructures it to make it easier to skip optional parameters.
+ * @param args A SortedRowIdsArgs object containing the Id of the Table in the
+ * Store, and optional `cellId`, `descending`, `offset`, and `limit` parameters.
+ * @param storeOrStoreId The Store to be accessed: omit for the default context
+ * Store, provide an Id for a named context Store, or provide an explicit
+ * reference.
+ * @returns An array of the sorted Ids of every Row in the Table.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useSortedRowIds hook by reference. A change to the data in the Store
+ * re-renders the component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {useSortedRowIds} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const App = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useSortedRowIds({tableId: 'pets', cellId: 'species'}, store),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido"]</span>'
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido","cujo"]</span>'
+ * ```
+ * @category Store hooks
+ * @since v6.1.0
+ */
+export function useSortedRowIds(
+  args: SortedRowIdsArgs,
+  storeOrStoreId?: StoreOrStoreId,
+): Ids;
+
 /**
  * The useHasRow hook returns a boolean indicating whether a given Row exists in
  * the Store, and registers a listener so that any changes to that result will
@@ -4737,6 +4789,74 @@ export function useSortedRowIdsListener(
   storeOrStoreId?: StoreOrStoreId,
 ): void;
 
+/**
+ * When called with an object as the first argument, the useSortedRowIds method
+ * destructures it to make it easier to skip optional parameters.
+ * @param args A SortedRowIdsArgs object containing the Id of the Table in the
+ * Store, and optional `cellId`, `descending`, `offset`, and `limit` parameters.
+ * @param listener The function that will be called whenever the sorted Row Ids
+ * in the Table change.
+ * @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.
+ * @param mutator An optional boolean that indicates that the listener mutates
+ * Store data.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useSortedRowIdsListener hook to create a listener that
+ * is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Store.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider, useSortedRowIdsListener} from 'tinybase/ui-react';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useSortedRowIdsListener({tableId: 'pets', cellId: 'species'}, () =>
+ *     console.log('Sorted Row Ids changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * // -> 'Sorted Row Ids changed'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v6.1.0
+ */
+export function useSortedRowIdsListener(
+  args: SortedRowIdsArgs,
+  listener: SortedRowIdsListener,
+  listenerDeps?: React.DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
 /**
  * The useHasRowListener hook registers a listener function with the Store that
  * will be called when a Row is added to or removed from the Store.
@@ -6616,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;
 
 /**
@@ -7423,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,
@@ -8477,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;
 
 /**
@@ -10664,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,
@@ -11627,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,
@@ -11812,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,
@@ -12315,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,