tinybase 9.4.0 → 9.5.0-beta.1

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

@@ -7098,7 +7098,52 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     metricsOrMetricsId?: MaybeAccessor<MetricsOrMetricsId<Schemas> | undefined>,
   ) => Accessor<Metrics<Schemas> | undefined>;
 
-  // useProvideMetrics
+  /**
+ * The useProvideMetrics primitive 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 primitive,
+ * 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 primitive 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.
+ * @param metricsId The Id of the Metrics object to be registered with the
+ * Provider.
+ * @param metrics The Metrics object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createMetrics, createStore} from 'tinybase';
+ * import {useProvideMetrics} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ *   const metrics = createMetrics(store).setMetricDefinition(
+ *     'petCount',
+ *     'pets',
+ *     'count',
+ *   );
+ *   useProvideMetrics('petMetrics', metrics);
+ *   console.log(metrics.getMetric('petCount'));
+ *   // -> 1
+ *   dispose();
+ * });
+ * ```
+ * @category Metrics primitives
+ * @since v8.3.0
+ */
   useProvideMetrics: (metricsId: Id, metrics: Metrics<Schemas>) => void;
 
   /**
@@ -7741,7 +7786,52 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     indexesOrIndexesId?: MaybeAccessor<IndexesOrIndexesId<Schemas> | undefined>,
   ) => Accessor<Indexes<Schemas> | undefined>;
 
-  // useProvideIndexes
+  /**
+ * The useProvideIndexes primitive 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 primitive,
+ * 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.
+ *
+ * An Indexes object added to the Provider context in this way will be available
+ * to other components within the context (using the useIndexes primitive 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.
+ * @param indexesId The Id of the Indexes object to be registered with the
+ * Provider.
+ * @param indexes The Indexes object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createIndexes, createStore} from 'tinybase';
+ * import {useProvideIndexes} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ *   const indexes = createIndexes(store).setIndexDefinition(
+ *     'petsByColor',
+ *     'pets',
+ *     'color',
+ *   );
+ *   useProvideIndexes('petIndexes', indexes);
+ *   console.log(JSON.stringify(indexes.getSliceIds('petsByColor')));
+ *   // -> '["brown"]'
+ *   dispose();
+ * });
+ * ```
+ * @category Indexes primitives
+ * @since v8.3.0
+ */
   useProvideIndexes: (indexesId: Id, indexes: Indexes<Schemas>) => void;
 
   /**
@@ -8662,7 +8752,56 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     >,
   ) => Accessor<Relationships<Schemas> | undefined>;
 
-  // useProvideRelationships
+  /**
+ * The useProvideRelationships primitive 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
+ * primitive, 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
+ * primitive 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.
+ * @param relationshipsId The Id of the Relationships object to be registered
+ * with the Provider.
+ * @param relationships The Relationships object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createRelationships, createStore} from 'tinybase';
+ * import {useProvideRelationships} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore()
+ *     .setTable('pets', {fido: {species: 'dog'}})
+ *     .setTable('species', {dog: {price: 5}});
+ *   const relationships = createRelationships(
+ *     store,
+ *   ).setRelationshipDefinition('petSpecies', 'pets', 'species', 'species');
+ *   useProvideRelationships('petRelationships', relationships);
+ *   console.log(relationships.getRemoteRowId('petSpecies', 'fido'));
+ *   // -> 'dog'
+ *   dispose();
+ * });
+ * ```
+ * @category Relationships primitives
+ * @since v8.3.0
+ */
   useProvideRelationships: (
     relationshipsId: Id,
     relationships: Relationships<Schemas>,
@@ -9790,7 +9929,57 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     queriesOrQueriesId?: MaybeAccessor<QueriesOrQueriesId<Schemas> | undefined>,
   ) => Accessor<Queries<Schemas> | undefined>;
 
-  // useProvideQueries
+  /**
+ * The useProvideQueries primitive 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 primitive,
+ * 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 primitive 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.
+ * @param queriesId The Id of the Queries object to be registered with the
+ * Provider.
+ * @param queries The Queries object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {useProvideQueries} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore().setRow('pets', 'fido', {
+ *     color: 'brown',
+ *     legs: 4,
+ *   });
+ *   const queries = createQueries(store).setQueryDefinition(
+ *     'brownLegs',
+ *     'pets',
+ *     ({select, where}) => {
+ *       select('legs');
+ *       where('color', 'brown');
+ *     },
+ *   );
+ *   useProvideQueries('petQueries', queries);
+ *   console.log(JSON.stringify(queries.getResultTable('brownLegs')));
+ *   // -> '{"fido":{"legs":4}}'
+ *   dispose();
+ * });
+ * ```
+ * @category Queries primitives
+ * @since v8.3.0
+ */
   useProvideQueries: (queriesId: Id, queries: Queries<Schemas>) => void;
 
   /**
@@ -12744,7 +12933,52 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     >,
   ) => Accessor<Checkpoints<Schemas> | undefined>;
 
-  // useProvideCheckpoints
+  /**
+ * The useProvideCheckpoints primitive 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
+ * primitive, 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
+ * primitive 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.
+ * @param checkpointsId The Id of the Checkpoints object to be registered with
+ * the Provider.
+ * @param checkpoints The Checkpoints object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createCheckpoints, createStore} from 'tinybase';
+ * import {useProvideCheckpoints} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ *   const checkpoints = createCheckpoints(store);
+ *   useProvideCheckpoints('petCheckpoints', checkpoints);
+ *   console.log(JSON.stringify(checkpoints.getCheckpointIds()));
+ *   // -> '[[],"0",[]]'
+ *   dispose();
+ * });
+ * ```
+ * @category Checkpoints primitives
+ * @since v8.3.0
+ */
   useProvideCheckpoints: (
     checkpointsId: Id,
     checkpoints: Checkpoints<Schemas>,
@@ -14110,7 +14344,54 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     >,
   ) => Accessor<Persister<Schemas, Persists.StoreOrMergeableStore> | undefined>;
 
-  // useProvidePersister
+  /**
+ * The useProvidePersister primitive 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 primitive,
+ * 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
+ * primitive 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.
+ * @param persisterId The Id of the Persister object to be registered with the
+ * Provider.
+ * @param persister The Persister object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createStore} from 'tinybase';
+ * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+ * import {useProvidePersister} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ *   const persister = createSessionPersister(store, 'pets');
+ *   useProvidePersister('petPersister', persister);
+ *   console.log(persister.getStatus());
+ *   // -> 0
+ *   persister.destroy();
+ *   dispose();
+ * });
+ * ```
+ * @category Persister primitives
+ * @since v8.3.0
+ */
   useProvidePersister: (
     persisterId: Id,
     persister: AnyPersister<Schemas> | undefined,
@@ -14681,7 +14962,59 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     >,
   ) => Accessor<Synchronizer<Schemas> | undefined>;
 
-  // useProvideSynchronizer
+  /**
+ * The useProvideSynchronizer primitive 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
+ * primitive, 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
+ * primitive 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.
+ * @param synchronizerId The Id of the Synchronizer object to be registered with
+ * the Provider.
+ * @param synchronizer The Synchronizer object to be registered.
+ * @example
+ * ```js
+ * import {createRoot} from 'solid-js';
+ * import {createMergeableStore} from 'tinybase';
+ * import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';
+ * import {useProvideSynchronizer} from 'tinybase/ui-solid';
+ *
+ * createRoot((dispose) => {
+ *   const store = createMergeableStore().setCell(
+ *     'pets',
+ *     'fido',
+ *     'color',
+ *     'brown',
+ *   );
+ *   const synchronizer = createLocalSynchronizer(store);
+ *   useProvideSynchronizer('petSynchronizer', synchronizer);
+ *   console.log(synchronizer.getStatus());
+ *   // -> 0
+ *   synchronizer.destroy();
+ *   dispose();
+ * });
+ * ```
+ * @category Synchronizer primitives
+ * @since v8.3.0
+ */
   useProvideSynchronizer: (
     synchronizerId: Id,
     synchronizer: Synchronizer<Schemas> | undefined,

package/@types/ui-solid-dom/index.d.ts

@@ -695,7 +695,7 @@ export type SortedTablePaginatorProps = {
  *
  * See the <TableInHtmlTable /> (Solid) demo for this component in action:
  *
- * ![TableInHtmlTable example](https://tinybase.org/shots/tableinhtmltable-solid-demo.png
+ * ![TableInHtmlTable example](https://beta.tinybase.org/shots/tableinhtmltable-solid-demo.png
  * "TableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -839,7 +839,7 @@ export function TableInHtmlTable(
  * See the <SortedTableInHtmlTable /> (Solid) demo for this component in
  * action:
  *
- * ![SortedTableInHtmlTable example](https://tinybase.org/shots/sortedtableinhtmltable-solid-demo.png
+ * ![SortedTableInHtmlTable example](https://beta.tinybase.org/shots/sortedtableinhtmltable-solid-demo.png
  * "SortedTableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -1010,7 +1010,7 @@ export function SortedTableInHtmlTable(
  *
  * See the <ValuesInHtmlTable /> (Solid) demo for this component in action:
  *
- * ![ValuesInHtmlTable example](https://tinybase.org/shots/valuesinhtmltable-solid-demo.png
+ * ![ValuesInHtmlTable example](https://beta.tinybase.org/shots/valuesinhtmltable-solid-demo.png
  * "ValuesInHtmlTable example")
  *
  * The component's props identify which Row to render based on Table Id, Row Id,
@@ -1139,7 +1139,7 @@ export function ValuesInHtmlTable(
  *
  * See the <SliceInHtmlTable /> (Solid) demo for this component in action:
  *
- * ![SliceInHtmlTable example](https://tinybase.org/shots/sliceinhtmltable-solid-demo.png
+ * ![SliceInHtmlTable example](https://beta.tinybase.org/shots/sliceinhtmltable-solid-demo.png
  * "SliceInHtmlTable example")
  *
  * The component's props identify which Slice to render based on Index Id, Slice
@@ -1295,7 +1295,7 @@ export function SliceInHtmlTable(
  * See the <RelationshipInHtmlTable /> (Solid) demo for this component in
  * action:
  *
- * ![RelationshipInHtmlTable example](https://tinybase.org/shots/relationshipinhtmltable-solid-demo.png
+ * ![RelationshipInHtmlTable example](https://beta.tinybase.org/shots/relationshipinhtmltable-solid-demo.png
  * "RelationshipInHtmlTable example")
  *
  * The component's props identify which Relationship to render based on
@@ -1469,7 +1469,7 @@ export function RelationshipInHtmlTable(
  * See the <ResultTableInHtmlTable /> (Solid) demo for this component in
  * action:
  *
- * ![ResultTableInHtmlTable example](https://tinybase.org/shots/resulttableinhtmltable-solid-demo.png
+ * ![ResultTableInHtmlTable example](https://beta.tinybase.org/shots/resulttableinhtmltable-solid-demo.png
  * "ResultTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1620,7 +1620,7 @@ export function ResultTableInHtmlTable(
  * See the <ResultSortedTableInHtmlTable /> (Solid) demo for this component in
  * action:
  *
- * ![ResultSortedTableInHtmlTable example](https://tinybase.org/shots/resultsortedtableinhtmltable-solid-demo.png
+ * ![ResultSortedTableInHtmlTable example](https://beta.tinybase.org/shots/resultsortedtableinhtmltable-solid-demo.png
  * "ResultSortedTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1792,7 +1792,7 @@ export function ResultSortedTableInHtmlTable(
  *
  * See the <EditableCellView /> (Solid) demo for this component in action:
  *
- * ![EditableCellView example](https://tinybase.org/shots/editablecellview-solid-demo.png
+ * ![EditableCellView example](https://beta.tinybase.org/shots/editablecellview-solid-demo.png
  * "EditableCellView example")
  *
  * The component's props identify which Cell to render based on Table Id, Row
@@ -1862,7 +1862,7 @@ export function EditableCellView(
  *
  * See the <EditableValueView /> (Solid) demo for this component in action:
  *
- * ![EditableValueView example](https://tinybase.org/shots/editablevalueview-solid-demo.png
+ * ![EditableValueView example](https://beta.tinybase.org/shots/editablevalueview-solid-demo.png
  * "EditableValueView example")
  *
  * The component's props identify which Value to render based on Table Id, Row
@@ -1932,7 +1932,7 @@ export function EditableValueView(
  * See the <SortedTableInHtmlTable /> (Solid) demo for this component in
  * action:
  *
- * ![SortedTablePaginator example](https://tinybase.org/shots/sortedtablepaginator-solid-demo.png
+ * ![SortedTablePaginator example](https://beta.tinybase.org/shots/sortedtablepaginator-solid-demo.png
  * "SortedTablePaginator example")
  *
  * The component displays 'previous' and 'next' buttons for paging through the