tinybase 3.2.0 → 3.3.0

package/lib/types/with-schemas/store.d.ts

@@ -481,6 +481,29 @@ export type TableCallback<
   Params1 extends any[] = Truncate<Params2>,
 > = ((...params: Params2) => void) | ((...params: Params1) => void);
 
+/**
+ * The TableCellCallback type describes a function that takes a Cell's Id and
+ * the count of times it appears across a whole Table.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (cellId: Id, count: number) => void;
+ * ```
+ *
+ * A TableCellCallback is provided when using the forEachTableCell method, so
+ * that you can do something based on every Cell used across a Table. See that
+ * method for specific examples.
+ *
+ * @param cellId The Id of the Cell that the callback can operate on.
+ * @param count The number of times this Cell is used across a whole Table.
+ * @category Callback
+ */
+export type TableCellCallback<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+> = (cellId: CellIdFromSchema<Schema, TableId>, count: number) => void;
+
 /**
  * The RowCallback type describes a function that takes a Row's Id and a
  * callback to loop over each Cell within it.
@@ -779,7 +802,10 @@ export type TablesListener<Schemas extends OptionalSchemas> = (
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * (store: Store) => void;
+ * (
+ *   store: Store,
+ *   getIdChanges: GetIdChanges | undefined,
+ * ) => void;
  * ```
  *
  * A TableIdsListener is provided when using the addTableIdsListener method. See
@@ -787,11 +813,17 @@ export type TablesListener<Schemas extends OptionalSchemas> = (
  *
  * When called, a TableIdsListener is given a reference to the Store.
  *
+ * Since v3.3, the listener is also passed a GetIdChanges function that can be
+ * used to query which Ids changed during the transaction.
+ *
  * @param store A reference to the Store that changed.
+ * @param getIdChanges A function that returns information about the Id changes,
+ * since v3.3.
  * @category Listener
  */
 export type TableIdsListener<Schemas extends OptionalSchemas> = (
   store: Store<Schemas>,
+  getIdChanges: GetIdChanges<TableIdFromSchema<Schemas[0]>> | undefined,
 ) => void;
 
 /**
@@ -836,6 +868,57 @@ export type TableListener<
   getCellChange: GetCellChange<Schemas[0]> | undefined,
 ) => void;
 
+/**
+ * The TableCellIdsListener type describes a function that is used to listen to
+ * changes to the Cell Ids that appear anywhere in a Table.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   store: Store,
+ *   tableId: Id,
+ *   getIdChanges: GetIdChanges | undefined,
+ * ) => void;
+ * ```
+ *
+ * A TableCellIdsListener is provided when using the addTableCellIdsListener
+ * method. See that method for specific examples.
+ *
+ * When called, a TableCellIdsListener is given a reference to the Store, the Id
+ * of the Table whose Cell Ids changed, and a GetIdChanges function that can be
+ * used to query which Ids changed during the transaction.
+ *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
+ * @param getIdChanges A function that returns information about the Id changes.
+ * @category Listener
+ * @since v3.3
+ */
+export type TableCellIdsListener<
+  Schemas extends OptionalSchemas,
+  TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,
+  Params extends any[] = (
+    TableIdOrNull extends null ? TableIdFromSchema<Schemas[0]> : TableIdOrNull
+  ) extends infer TableId
+    ? TableId extends TableIdFromSchema<Schemas[0]>
+      ? [
+          store: Store<Schemas>,
+          tableId: TableId,
+          getIdChanges: GetIdChanges<CellIdFromSchema<Schemas[0], TableId>>,
+        ]
+      : never
+    : never,
+  Params3 extends any[] =
+    | Params
+    | [store: never, tableId: never, getIdChanges: never],
+  Params2 extends any[] = Truncate<Params3>,
+  // Params1 extends any[] = Truncate<Params2>,
+> = Params extends any
+  ? ((...params: Params3) => void) | ((...params: Params2) => void)
+  : // | ((...params: Params1) => void)
+    never;
+
 /**
  * The RowIdsListener type describes a function that is used to listen to
  * changes to the Row Ids in a Table.
@@ -843,7 +926,11 @@ export type TableListener<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * (store: Store, tableId: Id) => void;
+ * (
+ *   store: Store,
+ *   tableId: Id,
+ *   getIdChanges: GetIdChanges | undefined,
+ * ) => void;
  * ```
  *
  * A RowIdsListener is provided when using the addRowIdsListener method. See
@@ -852,8 +939,13 @@ export type TableListener<
  * When called, a RowIdsListener is given a reference to the Store, and the Id
  * of the Table whose Row Ids changed.
  *
+ * Since v3.3, the listener is also passed a GetIdChanges function that can be
+ * used to query which Ids changed during the transaction.
+ *
  * @param store A reference to the Store that changed.
  * @param tableId The Id of the Table that changed.
+ * @param getIdChanges A function that returns information about the Id changes,
+ * since v3.3.
  * @category Listener
  */
 export type RowIdsListener<
@@ -864,6 +956,7 @@ export type RowIdsListener<
   tableId: TableIdOrNull extends null
     ? TableIdFromSchema<Schemas[0]>
     : TableIdOrNull,
+  getIdChanges: GetIdChanges<Id> | undefined,
 ) => void;
 
 /**
@@ -975,7 +1068,12 @@ export type RowListener<
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * (store: Store, tableId: Id, rowId: Id) => void;
+ * (
+ *   store: Store,
+ *   tableId: Id,
+ *   rowId: Id,
+ *   getIdChanges: GetIdChanges | undefined,
+ * ) => void;
  * ```
  *
  * A CellIdsListener is provided when using the addCellIdsListener method. See
@@ -984,22 +1082,43 @@ export type RowListener<
  * When called, a CellIdsListener is given a reference to the Store, the Id of
  * the Table that changed, and the Id of the Row whose Cell Ids changed.
  *
+ * Since v3.3, the listener is also passed a GetIdChanges function that can be
+ * used to query which Ids changed during the transaction.
+ *
  * @param store A reference to the Store that changed.
  * @param tableId The Id of the Table that changed.
  * @param rowId The Id of the Row that changed.
+ * @param getIdChanges A function that returns information about the Id changes,
+ * since v3.3.
  * @category Listener
  */
 export type CellIdsListener<
   Schemas extends OptionalSchemas,
   TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,
   RowIdOrNull extends IdOrNull,
-> = (
-  store: Store<Schemas>,
-  tableId: TableIdOrNull extends null
-    ? TableIdFromSchema<Schemas[0]>
-    : TableIdOrNull,
-  rowId: RowIdOrNull extends null ? Id : RowIdOrNull,
-) => void;
+  Params extends any[] = (
+    TableIdOrNull extends null ? TableIdFromSchema<Schemas[0]> : TableIdOrNull
+  ) extends infer TableId
+    ? TableId extends TableIdFromSchema<Schemas[0]>
+      ? [
+          store: Store<Schemas>,
+          tableId: TableId,
+          rowId: RowIdOrNull extends null ? Id : RowIdOrNull,
+          getIdChanges: GetIdChanges<CellIdFromSchema<Schemas[0], TableId>>,
+        ]
+      : never
+    : never,
+  Params4 extends any[] =
+    | Params
+    | [store: never, tableId: never, rowId: never, getIdChanges: never],
+  Params3 extends any[] = Truncate<Params4>,
+  // Params2 extends any[] = Truncate<Params3>,
+  // Params1 extends any[] = Truncate<Params2>,
+> = Params extends any
+  ? ((...params: Params4) => void) | ((...params: Params3) => void)
+  : //  | ((...params: Params2) => void)
+    // | ((...params: Params1) => void)
+    never;
 
 /**
  * The CellListener type describes a function that is used to listen to changes
@@ -1146,7 +1265,10 @@ export type ValuesListener<Schemas extends OptionalSchemas> = (
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * (store: Store) => void;
+ * (
+ *   store: Store,
+ *   getIdChanges: GetIdChanges | undefined,
+ * ) => void;
  * ```
  *
  * A ValueIdsListener is provided when using the addValueIdsListener method. See
@@ -1154,11 +1276,17 @@ export type ValuesListener<Schemas extends OptionalSchemas> = (
  *
  * When called, a ValueIdsListener is given a reference to the Store.
  *
+ * Since v3.3, the listener is also passed a GetIdChanges function that can be
+ * used to query which Ids changed during the transaction.
+ *
  * @param store A reference to the Store that changed.
+ * @param getIdChanges A function that returns information about the Id changes,
+ * since v3.3.
  * @category Listener
  */
 export type ValueIdsListener<Schemas extends OptionalSchemas> = (
   store: Store<Schemas>,
+  getIdChanges: GetIdChanges<ValueIdFromSchema<Schemas[1]>> | undefined,
 ) => void;
 
 /**
@@ -1315,6 +1443,25 @@ export type InvalidValueListener<Schemas extends OptionalSchemas> = (
   invalidValues: any[],
 ) => void;
 
+/**
+ * The GetIdChanges type describes a function that returns information about the
+ * changes to a set of Ids during a transaction.
+ *
+ * A GetIdChanges function is provided to every listener when called due Ids in
+ * the Store changing. It returns an object where each key is an Id that
+ * changed. The listener can then easily identify which Ids have been added
+ * (those with the value `1`), and which have been removed (those with the value
+ * `-1`).
+ *
+ * @returns An object keyed by Id with a numerical value. 1 means the Id was
+ * added, and 1 means it was removed.
+ * @category Listener
+ * @since v3.3
+ */
+export type GetIdChanges<ValidId extends Id> = () => {
+  [Id in ValidId]?: 1 | -1;
+};
+
 /**
  * The GetCellChange type describes a function that returns information about
  * any Cell's changes during a transaction.
@@ -1580,6 +1727,11 @@ export type StoreListenerStats = {
    * The number of TableListener functions registered with the Store.
    */
   table?: number;
+  /**
+   * The number of TableCellIdsListener functions registered with the Store,
+   * since v3.3.
+   */
+  tableCellIds?: number;
   /**
    * The number of RowIdsListener functions registered with the Store.
    */
@@ -1720,6 +1872,7 @@ export type StoreListenerStats = {
  * |Tables|getTables|setTables|delTables|addTablesListener|
  * |Table Ids|getTableIds|-|-|addTableIdsListener|
  * |Table|getTable|setTable|delTable|addTableListener|
+ * |Table Cell Ids|getTableCellIds|-|-|addTableCellIdsListener|
  * |Row Ids|getRowIds|-|-|addRowIdsListener|
  * |Row Ids (sorted)|getSortedRowIds|-|-|addSortedRowIdsListener|
  * |Row|getRow|setRow|delRow|addRowListener|
@@ -1928,6 +2081,51 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     tableId: TableId,
   ): Table<Schemas[0], TableId>;
 
+  /**
+   * The getTableCellIds method returns the Ids of every Cell used across the
+   * whole Table.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * getTableCellIds(tableId: Id): Ids;
+   * ```
+   *
+   * Note that this returns a copy of, rather than a reference, to the list of
+   * Ids, so changes made to the list are not made to the Store itself.
+   *
+   * @param tableId The Id of the Table in the Store.
+   * @returns An array of the Ids of every Cell used across the whole Table.
+   * @example
+   * This example retrieves the Cell Ids used across a whole Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog', color: 'brown'},
+   *     felix: {species: 'cat', legs: 4},
+   *     cujo: {dangerous: true},
+   *   },
+   * });
+   * console.log(store.getTableCellIds('pets'));
+   * // -> ['species', 'color', 'legs', 'dangerous']
+   * ```
+   * @example
+   * This example retrieves the Cell Ids used across a Table that does not
+   * exist, returning an empty array.
+   *
+   * ```js
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * console.log(store.getTableCellIds('species'));
+   * // -> []
+   * ```
+   * @category Getter
+   * @since v3.3
+   */
+  getTableCellIds<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+  ): CellIdFromSchema<Schemas[0], TableId>[];
+
   /**
    * The getRowIds method returns the Ids of every Row in a given Table.
    *
@@ -2134,7 +2332,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   ): Row<Schemas[0], TableId>;
 
   /**
-   * The getCellIds method returns the Ids of every Cell in a given Row, in a
+   * The getCellIds method returns the Ids of every Cell in a given Row in a
    * given Table.
    *
    * This has schema-based typing. The following is a simplified representation:
@@ -2162,8 +2360,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * // -> ['species', 'color']
    * ```
    * @example
-   * This example retrieves the Cell Ids of a Cell that does not exist,
-   * returning an empty array.
+   * This example retrieves the Cell Ids of a Row that does not exist, returning
+   * an empty array.
    *
    * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -2372,6 +2570,41 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    */
   hasTable(tableId: TableIdFromSchema<Schemas[0]>): boolean;
 
+  /**
+   * The hasTableCell method returns a boolean indicating whether a given Cell
+   * exists anywhere in a Table, not just in a specific Row.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * hasTableCell(tableId: Id, cellId: Id): boolean;
+   * ```
+   *
+   * @param tableId The Id of a possible Table in the Store.
+   * @param cellId The Id of a possible Cell in the Table.
+   * @returns Whether a Cell with that Id exists anywhere in that Table.
+   * @example
+   * This example shows two simple Cell existence checks.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog'}, felix: {legs: 4}},
+   * });
+   * console.log(store.hasTableCell('pets', 'species'));
+   * // -> true
+   * console.log(store.hasTableCell('pets', 'legs'));
+   * // -> true
+   * console.log(store.hasTableCell('pets', 'color'));
+   * // -> false
+   * ```
+   * @category Getter
+   * @since v3.3
+   */
+  hasTableCell<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    cellId: CellIdFromSchema<Schemas[0], TableId>,
+  ): boolean;
+
   /**
    * The hasRow method returns a boolean indicating whether a given Row exists
    * in the Store.
@@ -2401,7 +2634,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
 
   /**
    * The hasCell method returns a boolean indicating whether a given Cell exists
-   * in the Store.
+   * in a given Row in a given Table.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -4220,6 +4453,45 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    */
   forEachTable(tableCallback: TableCallback<Schemas[0]>): void;
 
+  /**
+   * The forEachTableCell method takes a function that it will then call for
+   * each Cell used across the whole Table.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * forEachTableCell(tableId: Id, tableCellCallback: TableCellCallback): void;
+   * ```
+   *
+   * This method is useful for iterating over the Cell structure of the Table in
+   * a functional style. The `tableCellCallback` parameter is a
+   * TableCellCallback function that will be called with the Id of each Cell and
+   * the count of Rows in the Table in which it appears.
+   *
+   * @param tableId The Id of the Table containing the Cells to iterate over.
+   * @param tableCellCallback The function that should be called for every Cell
+   * Id used across the whole Table.
+   * @example
+   * This example iterates over each Cell Id used across the whole Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog'}, felix: {species: 'cat', legs: 4}},
+   * });
+   * store.forEachTableCell('pets', (cellId, count) => {
+   *   console.log(`${cellId}: ${count}`);
+   * });
+   * // -> 'species: 2'
+   * // -> 'legs: 1'
+   * ```
+   * @category Iterator
+   * @since v3.3
+   */
+  forEachTableCell<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    tableCellCallback: TableCellCallback<Schemas[0], TableId>,
+  ): void;
+
   /**
    * The forEachRow method takes a function that it will then call for each Row
    * in a specified Table.
@@ -4582,6 +4854,123 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addTableCellIdsListener method registers a listener function with the
+   * Store that will be called whenever the Cell Ids that appear anywhere in a
+   * Table change.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addTableCellIdsListener(
+   *   tableId: IdOrNull,
+   *   listener: TableCellIdsListener,
+   *   mutator?: boolean,
+   * ): Id;
+   * ```
+   *
+   * The provided listener is a TableCellIdsListener function, and will be
+   * called with a reference to the Store and the Id of the Table that changed.
+   *
+   * By default, such a listener is only called when a Cell Id is added or
+   * removed from the whole of the Table. To listen to all changes in the Table,
+   * use the addTableListener method.
+   *
+   * You can either listen to a single Table (by specifying its Id as the
+   * method's first parameter) or changes to any Table (by providing a `null`
+   * wildcard).
+   *
+   * Use the optional mutator parameter to indicate that there is code in the
+   * listener that will mutate Store data. If set to `false` (or omitted), such
+   * mutations will be silently ignored. All relevant mutator listeners (with
+   * this flag set to `true`) are called _before_ any non-mutator listeners
+   * (since the latter may become relevant due to changes made in the former).
+   * The changes made by mutator listeners do not fire other mutating listeners,
+   * though they will fire non-mutator listeners.
+   *
+   * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Cell Ids that
+   * appear anywhere in a 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 Cell
+   * Ids that appear anywhere in a Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addTableCellIdsListener('pets', (store) => {
+   *   console.log('Cell Ids in pets table changed');
+   *   console.log(store.getTableCellIds('pets'));
+   * });
+   *
+   * store.setRow('pets', 'felix', {species: 'cat', legs: 4});
+   * // -> 'Cell Ids in pets table changed'
+   * // -> ['species', 'color', 'legs']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any change to the Cell
+   * Ids that appear anywhere in any Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   *   species: {dog: {price: 5}},
+   * });
+   * const listenerId = store.addTableCellIdsListener(
+   *   null,
+   *   (store, tableId) => {
+   *     console.log(`Cell Ids in ${tableId} table changed`);
+   *     console.log(store.getTableCellIds(tableId));
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'felix', {species: 'cat', legs: 4});
+   * // -> 'Cell Ids in pets table changed'
+   * // -> ['species', 'color', 'legs']
+   *
+   * store.setRow('species', 'cat', {price: 4, friendly: true});
+   * // -> 'Cell Ids in species table changed'
+   * // -> ['price', 'friendly']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to the Cell Ids that appear
+   * anywhere in a Table, and which also mutates the Store itself.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addTableCellIdsListener(
+   *   'pets',
+   *   (store, tableId) => store.setCell('meta', 'update', tableId, true),
+   *   true, // mutator
+   * );
+   *
+   * store.setRow('pets', 'felix', {species: 'cat', legs: 4});
+   * console.log(store.getTable('meta'));
+   * // -> {update: {pets: true}}
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addTableCellIdsListener<
+    TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,
+  >(
+    tableId: TableIdOrNull,
+    listener: TableCellIdsListener<Schemas, TableIdOrNull>,
+    mutator?: boolean,
+  ): Id;
+
   /**
    * The addRowIdsListener method registers a listener function with the Store
    * that will be called whenever the Row Ids in a Table change.
@@ -4780,7 +5169,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * store.delListener(listenerId);
    * ```
    * @example
-   * This 111example registers a listener that responds to any change to a
+   * This example registers a listener that responds to any change to a
    * paginated section of the sorted Row Ids of a specific Table.
    *
    * ```js

package/lib/types/with-schemas/tools.d.ts

@@ -432,7 +432,7 @@ export interface Tools<in out Schemas extends OptionalSchemas> {
    * // -> `export type Tables = {pets?: {[rowId: Id]: {price?: number}}};`
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[79]);
+   * console.log(tsLines[81]);
    * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
    * ```
    * @example
@@ -453,7 +453,7 @@ export interface Tools<in out Schemas extends OptionalSchemas> {
    * // -> 'export type Tables = {pets?: {[rowId: Id]: {price: number}}};'
    *
    * const tsLines = ts.split('\n');
-   * console.log(tsLines[81]);
+   * console.log(tsLines[83]);
    * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
    * ```
    * @category Modelling