tinybase 4.0.0-beta.0 → 4.0.0-beta.2

package/lib/types/tools.d.ts

@@ -7,7 +7,7 @@
  *
  * @packageDocumentation
  * @module tools
- * @since v2.2.0
+ * @since v2.2
  */
 
 import {Store, TablesSchema, ValuesSchema} from './store.d';
@@ -20,7 +20,7 @@ import {Id} from './common.d';
  * A StoreStats object is returned from the getStoreStats method.
  *
  * @category Statistics
- * @since v2.2.0
+ * @since v2.2
  */
 export type StoreStats = {
   /**
@@ -37,7 +37,7 @@ export type StoreStats = {
    */
   totalCells: number;
   /**
-   * The number of Value objects in the Store, since v3.0.0.
+   * The number of Value objects in the Store, since v3.0.
    */
   totalValues: number;
   /**
@@ -59,7 +59,7 @@ export type StoreStats = {
  * the getStoreStats method) when the `detail` flag is specified.
  *
  * @category Statistics
- * @since v2.2.0
+ * @since v2.2
  */
 export type StoreStatsDetail = {
   /**
@@ -73,7 +73,7 @@ export type StoreStatsDetail = {
  * single Table in the Store, and is used for debugging purposes.
  *
  * @category Statistics
- * @since v2.2.0
+ * @since v2.2
  */
 export type StoreStatsTableDetail = {
   /**
@@ -95,7 +95,7 @@ export type StoreStatsTableDetail = {
  * Store, and is used for debugging purposes.
  *
  * @category Statistics
- * @since v2.2.0
+ * @since v2.2
  */
 export type StoreStatsRowDetail = {
   /**
@@ -110,7 +110,7 @@ export type StoreStatsRowDetail = {
  *
  * @see Developer Tools guides
  * @category Tools
- * @since v2.2.0
+ * @since v2.2
  */
 export interface Tools {
   //
@@ -169,7 +169,7 @@ export interface Tools {
    * // -> {fido: {rowCells: 2}, felix: {rowCells: 2}, cujo: {rowCells: 2}}
    * ```
    * @category Statistics
-   * @since v2.2.0
+   * @since v2.2
    */
   getStoreStats(detail?: boolean): StoreStats;
 
@@ -233,7 +233,7 @@ export interface Tools {
    * // -> {type: 'boolean'}
    * ```
    * @category Modelling
-   * @since v3.0.0
+   * @since v3.0
    */
   getStoreTablesSchema(): TablesSchema;
 
@@ -272,13 +272,13 @@ export interface Tools {
    * // -> {open: {type: 'boolean'}, employees: {type: 'number'}}
    * ```
    * @category Modelling
-   * @since v3.0.0
+   * @since v3.0
    */
   getStoreValuesSchema(): ValuesSchema;
 
   /**
    * The getStoreApi method returns code-generated `.d.ts` and `.ts(x)` files
-   * that describe the schema of a Store and React bindings (since v3.1.0) in an
+   * that describe the schema of a Store and React bindings (since v3.1) in an
    * ORM style.
    *
    * If the Store does not already have an explicit TablesSchema or ValuesSchema
@@ -378,14 +378,14 @@ export interface Tools {
    * // -> 'getPetsTable: (): PetsTable => store.getTable(PETS) as PetsTable,'
    * ```
    * @category Modelling
-   * @since v2.2.0
+   * @since v2.2
    */
   getStoreApi(storeName: string): [string, string, string, string];
 
   /**
    * The getPrettyStoreApi method attempts to return prettified code-generated
    * `.d.ts` and `.ts(x)` files that describe the schema of a Store and React
-   * bindings (since v3.1.0) in an ORM style.
+   * bindings (since v3.1) in an ORM style.
    *
    * This is simply a wrapper around the getStoreApi method that attempts to
    * invoke the `prettier` module (which it hopes you have installed) to format
@@ -458,7 +458,7 @@ export interface Tools {
    * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
    * ```
    * @category Modelling
-   * @since v2.2.0
+   * @since v2.2
    */
   getPrettyStoreApi(
     storeName: string,
@@ -480,7 +480,7 @@ export interface Tools {
    * // -> 1
    * ```
    * @category Getter
-   * @since v3.0.0
+   * @since v3.0
    */
   getStore(): Store;
   //
@@ -528,7 +528,7 @@ export interface Tools {
  * // -> true
  * ```
  * @category Creation
- * @since v2.2.0
+ * @since v2.2
  */
 export function createTools(store: Store): Tools;
 //

package/lib/types/ui-react.d.ts

@@ -163,7 +163,7 @@ export type RelationshipsOrRelationshipsId = Relationships | Id;
  * parameter or a prop, allowing you to pass in either the Store or its Id.
  *
  * @category Identity
- * @since v2.0.0
+ * @since v2.0
  */
 export type QueriesOrQueriesId = Queries | Id;
 
@@ -767,7 +767,7 @@ export function useRowIds(tableId: Id, storeOrStoreId?: StoreOrStoreId): Ids;
  * // -> '<span>["felix","fido"]</span>'
  * ```
  * @category Store hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useSortedRowIds(
   tableId: Id,
@@ -1115,7 +1115,7 @@ export function useCell(
  * // -> '<span>{"open":true}</span>'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValues(storeOrStoreId?: StoreOrStoreId): Values;
 
@@ -1192,7 +1192,7 @@ export function useValues(storeOrStoreId?: StoreOrStoreId): Values;
  * // -> '<span>["open"]</span>'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValueIds(storeOrStoreId?: StoreOrStoreId): Ids;
 
@@ -1273,7 +1273,7 @@ export function useValueIds(storeOrStoreId?: StoreOrStoreId): Ids;
  * // -> '<span>true</span>'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValue(
   valueId: Id,
@@ -1929,7 +1929,7 @@ export function useSetCellCallback<Parameter>(
  * // -> '{"bubbles":true}'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useSetValuesCallback<Parameter>(
   getValues: (parameter: Parameter, store: Store) => Values,
@@ -2015,7 +2015,7 @@ export function useSetValuesCallback<Parameter>(
  * // -> '{"open":true,"bubbles":true}'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useSetPartialValuesCallback<Parameter>(
   getPartialValues: (parameter: Parameter, store: Store) => Values,
@@ -2101,7 +2101,7 @@ export function useSetPartialValuesCallback<Parameter>(
  * // -> '{"open":true,"bubbles":true}'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useSetValueCallback<Parameter>(
   valueId: Id,
@@ -2441,7 +2441,7 @@ export function useDelCellCallback(
  * // -> '{}'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useDelValuesCallback(
   storeOrStoreId?: StoreOrStoreId,
@@ -2506,7 +2506,7 @@ export function useDelValuesCallback(
  * // -> '{"employees":3}'
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useDelValueCallback(
   valueId: Id,
@@ -2843,7 +2843,7 @@ export function useRowIdsListener(
  * // -> 0
  * ```
  * @category Store hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useSortedRowIdsListener(
   tableId: Id,
@@ -3143,7 +3143,7 @@ export function useCellListener(
  * // -> 0
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValuesListener(
   listener: ValuesListener,
@@ -3207,7 +3207,7 @@ export function useValuesListener(
  * // -> 0
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValueIdsListener(
   listener: ValueIdsListener,
@@ -3274,7 +3274,7 @@ export function useValueIdsListener(
  * // -> 0
  * ```
  * @category Store hooks
- * @since v3.0.0
+ * @since v3.0
  */
 export function useValueListener(
   valueId: IdOrNull,
@@ -5113,7 +5113,7 @@ export function useLinkedRowIdsListener(
  * // -> '<span>brown</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useCreateQueries(
   store: Store,
@@ -5181,7 +5181,7 @@ export function useCreateQueries(
  * // -> '<span>0</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useQueries(id?: Id): Queries | undefined;
 
@@ -5298,7 +5298,7 @@ export function useQueries(id?: Id): Queries | undefined;
  * // -> '<span>{"fido":{"color":"brown"},"cujo":{"color":"black"}}</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultTable(
   queryId: Id,
@@ -5419,7 +5419,7 @@ export function useResultTable(
  * // -> '<span>["fido","cujo"]</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultRowIds(
   queryId: Id,
@@ -5568,7 +5568,7 @@ export function useResultRowIds(
  * // -> '<span>["cujo","fido"]</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultSortedRowIds(
   queryId: Id,
@@ -5696,7 +5696,7 @@ export function useResultSortedRowIds(
  * // -> '<span>{"color":"brown"}</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultRow(
   queryId: Id,
@@ -5827,7 +5827,7 @@ export function useResultRow(
  * // -> '<span>["species","color"]</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultCellIds(
   queryId: Id,
@@ -5954,7 +5954,7 @@ export function useResultCellIds(
  * // -> '<span>brown</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultCell(
   queryId: Id,
@@ -6032,7 +6032,7 @@ export function useResultCell(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultTableListener(
   queryId: IdOrNull,
@@ -6110,7 +6110,7 @@ export function useResultTableListener(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultRowIdsListener(
   queryId: IdOrNull,
@@ -6195,7 +6195,7 @@ export function useResultRowIdsListener(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultSortedRowIdsListener(
   queryId: Id,
@@ -6283,7 +6283,7 @@ export function useResultSortedRowIdsListener(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultRowListener(
   queryId: IdOrNull,
@@ -6368,7 +6368,7 @@ export function useResultRowListener(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultCellIdsListener(
   queryId: IdOrNull,
@@ -6455,7 +6455,7 @@ export function useResultCellIdsListener(
  * // -> 0
  * ```
  * @category Queries hooks
- * @since v2.0.0
+ * @since v2.0
  */
 export function useResultCellListener(
   queryId: IdOrNull,
@@ -7389,7 +7389,10 @@ export function useCheckpointListener(
  *   return <span>{JSON.stringify(useTables(store))}</span>;
  * };
  *
- * sessionStorage.setItem('pets', '{"pets":{"fido":{"species":"dog"}}}');
+ * sessionStorage.setItem(
+ *   'pets',
+ *   '[{"pets":{"fido":{"species":"dog"}}}, {}]',
+ * );
  *
  * const app = document.createElement('div');
  * const root = ReactDOMClient.createRoot(app);
@@ -7429,8 +7432,14 @@ export function useCheckpointListener(
  *   return <span>{JSON.stringify(useTables(store))}</span>;
  * };
  *
- * sessionStorage.setItem('fidoStore', '{"pets":{"fido":{"species":"dog"}}}');
- * sessionStorage.setItem('cujoStore', '{"pets":{"cujo":{"species":"dog"}}}');
+ * sessionStorage.setItem(
+ *   'fidoStore',
+ *   '[{"pets":{"fido":{"species":"dog"}}}, {}]',
+ * );
+ * sessionStorage.setItem(
+ *   'cujoStore',
+ *   '[{"pets":{"cujo":{"species":"dog"}}}, {}]',
+ * );
  *
  * const app = document.createElement('div');
  * const root = ReactDOMClient.createRoot(app);
@@ -7542,7 +7551,7 @@ export type TableProps = {
  * Table in a Store, such as the SortedTableView component.
  *
  * @category Props
- * @since v2.0.0
+ * @since v2.0
  */
 export type SortedTableProps = {
   /**
@@ -7669,7 +7678,7 @@ export type CellProps = {
  * Store, such as the ValuesView component.
  *
  * @category Props
- * @since v3.0.0
+ * @since v3.0
  */
 export type ValuesProps = {
   /**
@@ -7703,7 +7712,7 @@ export type ValuesProps = {
  * Row, such as the ValueView component.
  *
  * @category Props
- * @since v3.0.0
+ * @since v3.0
  */
 export type ValueProps = {
   /**
@@ -7954,7 +7963,7 @@ export type LinkedRowsProps = {
  * result Table, such as the ResultTableView component.
  *
  * @category Props
- * @since v2.0.0
+ * @since v2.0
  */
 export type ResultTableProps = {
   /**
@@ -7994,7 +8003,7 @@ export type ResultTableProps = {
  * sorted query result Table, such as the ResultSortedTableView component.
  *
  * @category Props
- * @since v2.0.0
+ * @since v2.0
  */
 export type ResultSortedTableProps = {
   /**
@@ -8051,7 +8060,7 @@ export type ResultSortedTableProps = {
  * query result Table, such as the ResultRowView component.
  *
  * @category Props
- * @since v2.0.0
+ * @since v2.0
  */
 export type ResultRowProps = {
   /**
@@ -8095,7 +8104,7 @@ export type ResultRowProps = {
  * Row of a result Table, such as the ResultCellView component.
  *
  * @category Props
- * @since v2.0.0
+ * @since v2.0
  */
 export type ResultCellProps = {
   /**
@@ -8300,12 +8309,12 @@ export type ProviderProps = {
   readonly relationshipsById?: {[relationshipsId: Id]: Relationships};
   /**
    * A default single Queries object that will be available within the Provider
-   * context, since v2.0.0.
+   * context, since v2.0.
    */
   readonly queries?: Queries;
   /**
    * An object containing multiple Queries objects that will be available within
-   * the Provider context by their Id, since v2.0.0.
+   * the Provider context by their Id, since v2.0.
    */
   readonly queriesById?: {[queriesId: Id]: Queries};
   /**
@@ -8759,7 +8768,7 @@ export function RowView(props: RowProps): ComponentReturnType;
  * // -> '<div><span>felix: cat</span><span><b>fido</b>: dog</span></div>'
  * ```
  * @category Store components
- * @since v2.0.0
+ * @since v2.0
  */
 export function SortedTableView(props: SortedTableProps): ComponentReturnType;
 
@@ -9070,7 +9079,7 @@ export function TablesView(props: TablesProps): ComponentReturnType;
  * // -> '<span></span>'
  * ```
  * @category Store components
- * @since v3.0.0
+ * @since v3.0
  */
 export function ValueView(props: ValueProps): ComponentReturnType;
 
@@ -9176,7 +9185,7 @@ export function ValueView(props: ValueProps): ComponentReturnType;
  * // -> '<div><span><b>open</b>: true</span><span>employees: 3</span></div>'
  * ```
  * @category Store components
- * @since v3.0.0
+ * @since v3.0
  */
 export function ValuesView(props: ValuesProps): ComponentReturnType;
 
@@ -10060,7 +10069,7 @@ export function LinkedRowsView(props: LinkedRowsProps): ComponentReturnType;
  * // -> '<span></span>'
  * ```
  * @category Queries components
- * @since v2.0.0
+ * @since v2.0
  */
 export function ResultCellView(props: ResultCellProps): ComponentReturnType;
 
@@ -10207,7 +10216,7 @@ export function ResultCellView(props: ResultCellProps): ComponentReturnType;
  * // -> '<div><span><b>species</b>: dog</span><span>color: brown</span></div>'
  * ```
  * @category Queries components
- * @since v2.0.0
+ * @since v2.0
  */
 export function ResultRowView(props: ResultRowProps): ComponentReturnType;
 
@@ -10345,7 +10354,7 @@ export function ResultRowView(props: ResultRowProps): ComponentReturnType;
  * // -> '<div><span>felix: black</span><span><b>fido</b>: brown</span></div>'
  * ```
  * @category Queries components
- * @since v2.0.0
+ * @since v2.0
  */
 export function ResultSortedTableView(
   props: ResultSortedTableProps,
@@ -10470,7 +10479,7 @@ export function ResultSortedTableView(
  * // -> '<div><span><b>fido</b>: brown</span><span>felix: black</span></div>'
  * ```
  * @category Queries components
- * @since v2.0.0
+ * @since v2.0
  */
 export function ResultTableView(props: ResultTableProps): ComponentReturnType;
 

package/lib/types/with-schemas/internal/ui-react.d.ts

@@ -753,12 +753,12 @@ export type ProviderProps<Schemas extends OptionalSchemas> = {
   readonly relationshipsById?: {[relationshipsId: Id]: Relationships<Schemas>};
   /**
    * A default single Queries object that will be available within the Provider
-   * context, since v2.0.0.
+   * context, since v2.0.
    */
   readonly queries?: Queries<Schemas>;
   /**
    * An object containing multiple Queries objects that will be available within
-   * the Provider context by their Id, since v2.0.0.
+   * the Provider context by their Id, since v2.0.
    */
   readonly queriesById?: {[queriesId: Id]: Queries<Schemas>};
   /**

package/lib/types/with-schemas/persister-browser.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The persister-browser module of the TinyBase project lets you save and load
+ * Store data to and from browser storage.
+ *
+ * Two entry points are provided, each of which returns a new Persister object
+ * that can load and save a Store:
+ *
+ * - The createSessionPersister function returns a Persister that uses the
+ *   browser's session storage.
+ * - The createLocalPersister function returns a Persister that uses the
+ *   browser's local storage.
+ *
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-browser
+ */
+
+import {OptionalSchemas, Store} from './store';
+import {Persister} from './persisters';
+
+/**
+ * The createSessionPersister function creates a Persister object that can
+ * persist the Store to the browser's session storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSessionPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `storageName` parameter which is unique to your application. This is the key
+ * that the browser uses to identify the storage location.
+ *
+ * @param store The Store to persist.
+ * @param storageName The unique key to identify the storage location.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to the
+ * browser's session storage.
+ *
+ * ```js
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSessionPersister(store, 'pets');
+ *
+ * await persister.save();
+ * console.log(sessionStorage.getItem('pets'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * persister.destroy();
+ * sessionStorage.clear();
+ * ```
+ * @category Creation
+ */
+export function createSessionPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  storageName: string,
+): Persister<Schemas>;
+
+/**
+ * The createLocalPersister function creates a Persister object that can
+ * persist the Store to the browser's local storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLocalPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `storageName` parameter which is unique to your application. This is the key
+ * that the browser uses to identify the storage location.
+ *
+ * @param store The Store to persist.
+ * @param storageName The unique key to identify the storage location.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to the
+ * browser's local storage.
+ *
+ * ```js
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createLocalPersister(store, 'pets');
+ *
+ * await persister.save();
+ * console.log(localStorage.getItem('pets'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * persister.destroy();
+ * localStorage.clear();
+ * ```
+ * @category Creation
+ */
+export function createLocalPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  storageName: string,
+): Persister<Schemas>;