tinybase 6.1.0-beta.5 → 6.1.1

package/@types/persisters/index.d.ts

@@ -1307,6 +1307,88 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    */
   isAutoSaving(): boolean;
 
+  /**
+   * The startAutoPersist method is a convenience method that starts both
+   * automatic loading and saving of the Store data.
+   *
+   * This simply runs the startAutoLoad and startAutoSave methods in sequence,
+   * and returns a Promise that resolves when both have completed.
+   *
+   * This method can take `initialContent` to pass to the startAutoLoad method.
+   * See its documentation for more details.
+   *
+   * If for some reason you want to start saving _before_ you start loading,
+   * pass true as the second parameter.
+   * @param initialContent An optional Content object used when the underlying
+   * storage has not previously been populated.
+   * @param startSaveFirst Whether to start saving before loading, defaulting to
+   * false.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example This example creates a Persister and starts automatically loading
+   * and saving.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+   *
+   * const persister = createSessionPersister(createStore(), 'pets');
+   *
+   * await persister.startAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> true
+   * console.log(persister.isAutoLoading());
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Lifecycle
+   * @since v6.1.0
+   */
+  startAutoPersisting(
+    initialContent?: Content | (() => Content),
+    startSaveFirst?: boolean,
+  ): Promise<this>;
+
+  /**
+   * The stopAutoPersist method is a convenience method that stops both
+   * automatic loading and saving of the Store data.
+   *
+   * This simply runs the stopAutoLoad and stopAutoSave methods in sequence, and
+   * returns a Promise that resolves when both have completed.
+   *
+   * If for some reason you want to stop saving _before_ you stop loading, pass
+   * true as the second parameter.
+   * @param stopSaveFirst Whether to stop saving before loading, defaulting to
+   * false.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example This example creates a Persister and starts, then stops,
+   * automatically loading and saving.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+   *
+   * const persister = createSessionPersister(createStore(), 'pets');
+   *
+   * await persister.startAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> true
+   * console.log(persister.isAutoLoading());
+   * // -> true
+   *
+   * await persister.stopAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> false
+   * console.log(persister.isAutoLoading());
+   * // -> false
+   *
+   * persister.destroy();
+   * ```
+   * @category Lifecycle
+   * @since v6.1.0
+   */
+  stopAutoPersisting(stopSaveFirst?: boolean): Promise<this>;
+
   /**
    * The getStatus method lets you find out if the Persister is currently in the
    * process of loading or saving content.

package/@types/persisters/with-schemas/index.d.ts

@@ -1400,6 +1400,97 @@ export interface Persister<
    */
   isAutoSaving(): boolean;
 
+  /**
+   * The startAutoPersist method is a convenience method that starts both
+   * automatic loading and saving of the Store data.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * startAutoPersisting(
+   *   initialContent?: Content | (() => Content),
+   *   startSaveFirst?: boolean,
+   * ): Promise<this>;
+   * ```
+   *
+   * This simply runs the startAutoLoad and startAutoSave methods in sequence,
+   * and returns a Promise that resolves when both have completed.
+   *
+   * This method can take `initialContent` to pass to the startAutoLoad method.
+   * See its documentation for more details.
+   *
+   * If for some reason you want to start saving _before_ you start loading,
+   * pass true as the second parameter.
+   * @param initialContent An optional Content object used when the underlying
+   * storage has not previously been populated.
+   * @param startSaveFirst Whether to start saving before loading, defaulting to
+   * false.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example This example creates a Persister and starts automatically loading
+   * and saving.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+   *
+   * const persister = createSessionPersister(createStore(), 'pets');
+   *
+   * await persister.startAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> true
+   * console.log(persister.isAutoLoading());
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Lifecycle
+   * @since v6.1.0
+   */
+  startAutoPersisting(
+    initialContent?: Content<Schemas, true> | (() => Content<Schemas, true>),
+    startSaveFirst?: boolean,
+  ): Promise<this>;
+
+  /**
+   * The stopAutoPersist method is a convenience method that stops both
+   * automatic loading and saving of the Store data.
+   *
+   * This simply runs the stopAutoLoad and stopAutoSave methods in sequence, and
+   * returns a Promise that resolves when both have completed.
+   *
+   * If for some reason you want to stop saving _before_ you stop loading, pass
+   * true as the second parameter.
+   * @param stopSaveFirst Whether to stop saving before loading, defaulting to
+   * false.
+   * @returns A Promise containing a reference to the Persister object.
+   * @example This example creates a Persister and starts, then stops,
+   * automatically loading and saving.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
+   *
+   * const persister = createSessionPersister(createStore(), 'pets');
+   *
+   * await persister.startAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> true
+   * console.log(persister.isAutoLoading());
+   * // -> true
+   *
+   * await persister.stopAutoPersisting();
+   * console.log(persister.isAutoSaving());
+   * // -> false
+   * console.log(persister.isAutoLoading());
+   * // -> false
+   *
+   * persister.destroy();
+   * ```
+   * @category Lifecycle
+   * @since v6.1.0
+   */
+  stopAutoPersisting(stopSaveFirst?: boolean): Promise<this>;
+
   /**
    * The getStatus method lets you find out if the Persister is currently in the
    * process of loading or saving content.

package/@types/store/index.d.ts

@@ -576,6 +576,50 @@ export type ChangedValueIds = {[valueId: Id]: IdAddedOrRemoved};
  */
 export type DoRollback = (store: Store) => boolean;
 
+/**
+ * The SortedRowIdsArgs type describes the arguments used to sort Row Ids using
+ * the getSortedRowIds method.
+ *
+ * It's an object containing the Id of the Table in the Store, and optional
+ * `cellId`, `descending`, `offset`, and `limit` parameters. See the
+ * getSortedRowIds method for specific examples.
+ * @category Store
+ * @since v6.1.0
+ */
+export type SortedRowIdsArgs = {
+  /**
+   * The Id of the Table in the Store, required.
+   * @category Argument
+   * @since v6.1.0
+   */
+  tableId: Id;
+  /**
+   * The optional Id of the Cell whose values are used for the sorting, defaults
+   * to sorting by the Row Id itself.
+   * @category Argument
+   * @since v6.1.0
+   */
+  cellId?: Id;
+  /**
+   * Whether the sorting should be in descending order, defaulting to false.
+   * @category Argument
+   * @since v6.1.0
+   */
+  descending?: boolean;
+  /**
+   * The number of Row Ids to skip for pagination purposes, defaulting to 0.
+   * @category Argument
+   * @since v6.1.0
+   */
+  offset?: number;
+  /**
+   * The maximum number of Row Ids to return, defaulting to all.
+   * @category Argument
+   * @since v6.1.0
+   */
+  limit?: number;
+};
+
 /**
  * The TransactionListener type describes a function that is used to listen to
  * the completion of a transaction for the Store.
@@ -2120,7 +2164,7 @@ export interface Store {
    * any.
    * @param limit The maximum number of Row Ids to return, or `undefined` for
    * all.
-   * @returns An array of the sorted Ids of every Row in the Table.
+   * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
    * This example retrieves sorted Row Ids in a Table.
    *
@@ -2212,6 +2256,34 @@ export interface Store {
     limit?: number,
   ): Ids;
 
+  /**
+   * When called with one object argument, the getSortedRowIds 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.
+   * @returns An array of the sorted Ids of appropriate Rows in the Table.
+   * @example
+   * This example retrieves the first sorted Row Id in a Table.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *     cujo: {species: 'wolf'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds({tableId: 'pets', limit: 1}));
+   * // -> ['cujo']
+   * ```
+   * @category Getter
+   * @since v6.1.0
+   */
+  getSortedRowIds(args: SortedRowIdsArgs): Ids;
+
   /**
    * The getRow method returns an object containing the entire data of a single
    * Row in a given Table.
@@ -5673,6 +5745,56 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * When called with an object as the first argument, the
+   * addSortedRowIdsListener 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 mutator An optional boolean that indicates that the listener mutates
+   * Store data.
+   * @returns A unique Id for the listener that can later be used to call it
+   * explicitly, or to remove it.
+   * @example
+   * This example registers a listener that responds to any change to the first
+   * of the sorted Row Ids of a specific Table.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTables({
+   *   pets: {fido: {price: 6}, felix: {price: 5}},
+   * });
+   *
+   * const listenerId = store.addSortedRowIdsListener(
+   *   {tableId: 'pets', limit: 1},
+   *   (store, tableId, cellId, descending, offset, limit, sortedRowIds) => {
+   *     console.log(`First sorted Row Id for ${tableId} table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   * console.log(store.getSortedRowIds({tableId: 'pets', limit: 1}));
+   * // -> ['felix']
+   *
+   * store.setRow('pets', 'carnaby', {price: 4.5});
+   * // -> 'First sorted Row Id for pets table changed'
+   * // -> ['carnaby']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   * @since v6.1.0
+   */
+  addSortedRowIdsListener(
+    args: SortedRowIdsArgs,
+    listener: SortedRowIdsListener<this>,
+    mutator?: boolean,
+  ): Id;
+
   /**
    * The addHasRowListener method registers a listener function with the Store
    * that will be called when a Row is added to or removed from the Store.

package/@types/store/with-schemas/index.d.ts

@@ -896,6 +896,56 @@ export type DoRollback<Schemas extends OptionalSchemas> = (
   store: Store<Schemas>,
 ) => boolean;
 
+/**
+ * The SortedRowIdsArgs type describes the arguments used to sort Row Ids using
+ * the getSortedRowIds method.
+ *
+ * It's an object containing the Id of the Table in the Store, and optional
+ * `cellId`, `descending`, `offset`, and `limit` parameters. See the
+ * getSortedRowIds method for specific examples.
+ * @category Store
+ * @since v6.1.0
+ */
+export type SortedRowIdsArgs<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellIdOrUndefined extends CellIdFromSchema<Schema, TableId> | undefined =
+    | CellIdFromSchema<Schema, TableId>
+    | undefined,
+> = {
+  /**
+   * The Id of the Table in the Store, required.
+   * @category Argument
+   * @since v6.1.0
+   */
+  tableId: TableId;
+  /**
+   * The optional Id of the Cell whose values are used for the sorting, defaults
+   * to sorting by the Row Id itself.
+   * @category Argument
+   * @since v6.1.0
+   */
+  cellId?: CellIdOrUndefined;
+  /**
+   * Whether the sorting should be in descending order, defaulting to false.
+   * @category Argument
+   * @since v6.1.0
+   */
+  descending?: boolean;
+  /**
+   * The number of Row Ids to skip for pagination purposes, defaulting to 0.
+   * @category Argument
+   * @since v6.1.0
+   */
+  offset?: number;
+  /**
+   * The maximum number of Row Ids to return, defaulting to all.
+   * @category Argument
+   * @since v6.1.0
+   */
+  limit?: number;
+};
+
 /**
  * The TransactionListener type describes a function that is used to listen to
  * the completion of a transaction for the Store.
@@ -1346,18 +1396,15 @@ export type RowIdsListener<
 export type SortedRowIdsListener<
   Schemas extends OptionalSchemas,
   TableId extends TableIdFromSchema<Schemas[0]>,
-  CellId extends CellIdFromSchema<Schemas[0], TableId> | undefined,
-  Descending extends boolean,
-  Offset extends number,
-  Limit extends number | undefined,
+  CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
   Store extends StoreAlias<Schemas> = StoreAlias<Schemas>,
 > = (
   store: Store,
   tableId: TableId,
-  cellId: CellId,
-  descending: Descending,
-  offset: Offset,
-  limit: Limit,
+  cellId: CellIdOrUndefined,
+  descending: boolean,
+  offset: number,
+  limit: number | undefined,
   sortedRowIds: Ids,
 ) => void;
 
@@ -3145,7 +3192,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * any.
    * @param limit The maximum number of Row Ids to return, or `undefined` for
    * all.
-   * @returns An array of the sorted Ids of every Row in the Table.
+   * @returns An array of the sorted Ids of appropriate Rows in the Table.
    * @example
    * This example retrieves sorted Row Ids in a Table.
    *
@@ -3237,6 +3284,42 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     limit?: number,
   ): Ids;
 
+  /**
+   * When called with one object argument, the getSortedRowIds 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.
+   * @returns An array of the sorted Ids of appropriate Rows in the Table.
+   * @example
+   * This example retrieves the first sorted Row Id in a Table.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getSortedRowIds(args: SortedRowIdsArgs): Ids;
+   * ```
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *     cujo: {species: 'wolf'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds({tableId: 'pets', limit: 1}));
+   * // -> ['cujo']
+   * ```
+   * @category Getter
+   * @since v6.1.0
+   */
+  getSortedRowIds<TableId extends TableIdFromSchema<Schemas[0]>>(
+    args: SortedRowIdsArgs<Schemas[0], TableId>,
+  ): Ids;
+
   /**
    * The getRow method returns an object containing the entire data of a single
    * Row in a given Table.
@@ -7140,24 +7223,76 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   addSortedRowIdsListener<
     TableId extends TableIdFromSchema<Schemas[0]>,
     CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
-    Descending extends boolean,
-    Offset extends number,
-    Limit extends number | undefined,
   >(
     tableId: TableId,
     cellId: CellIdOrUndefined,
-    descending: Descending,
-    offset: Offset,
-    limit: Limit,
-    listener: SortedRowIdsListener<
-      Schemas,
-      TableId,
-      CellIdOrUndefined,
-      Descending,
-      Offset,
-      Limit,
-      this
-    >,
+    descending: boolean,
+    offset: number,
+    limit: number | undefined,
+    listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined, this>,
+    mutator?: boolean,
+  ): Id;
+
+  /**
+   * When called with an object as the first argument, the
+   * addSortedRowIdsListener 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 mutator An optional boolean that indicates that the listener mutates
+   * Store data.
+   * @returns A unique Id for the listener that can later be used to call it
+   * explicitly, or to remove it.
+   * @example
+   * This example registers a listener that responds to any change to the first
+   * of the sorted Row Ids of a specific Table.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addSortedRowIdsListener(
+   *   args: SortedRowIdsArgs,
+   *   listener: SortedRowIdsListener<this>,
+   *   mutator?: boolean,
+   * ): Id;
+   * ```
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   *
+   * const store = createStore().setTables({
+   *   pets: {fido: {price: 6}, felix: {price: 5}},
+   * });
+   *
+   * const listenerId = store.addSortedRowIdsListener(
+   *   {tableId: 'pets', limit: 1},
+   *   (store, tableId, cellId, descending, offset, limit, sortedRowIds) => {
+   *     console.log(`First sorted Row Id for ${tableId} table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   * console.log(store.getSortedRowIds({tableId: 'pets', limit: 1}));
+   * // -> ['felix']
+   *
+   * store.setRow('pets', 'carnaby', {price: 4.5});
+   * // -> 'First sorted Row Id for pets table changed'
+   * // -> ['carnaby']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   * @since v6.1.0
+   */
+  addSortedRowIdsListener<
+    TableId extends TableIdFromSchema<Schemas[0]>,
+    CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
+  >(
+    args: SortedRowIdsArgs<Schemas[0], TableId, CellIdOrUndefined>,
+    listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined, this>,
     mutator?: boolean,
   ): Id;