tinybase 3.2.0-beta.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;
 
 /**
@@ -1253,10 +1381,10 @@ export type ValueListener<
  * ) => void;
  * ```
  *
- * A InvalidCellListener is provided when using the addInvalidCellListener
+ * An InvalidCellListener is provided when using the addInvalidCellListener
  * method. See that method for specific examples.
  *
- * When called, a InvalidCellListener is given a reference to the Store, the Id
+ * When called, an InvalidCellListener is given a reference to the Store, the Id
  * of the Table, the Id of the Row, and the Id of Cell that was being attempted
  * to be changed. It is also given the invalid value of the Cell, which could
  * have been of absolutely any type. Since there could have been multiple failed
@@ -1293,11 +1421,11 @@ export type InvalidCellListener<Schemas extends OptionalSchemas> = (
  * ) => void;
  * ```
  *
- * A InvalidValueListener is provided when using the addInvalidValueListener
+ * An InvalidValueListener is provided when using the addInvalidValueListener
  * method. See that method for specific examples.
  *
- * When called, a InvalidValueListener is given a reference to the Store and the
- * Id of Value that was being attempted to be changed. It is also given the
+ * When called, an InvalidValueListener is given a reference to the Store and
+ * the Id of Value that was being attempted to be changed. It is also given the
  * invalid value of the Value, which could have been of absolutely any type.
  * Since there could have been multiple failed attempts to set the Value within
  * a single transaction, this is an array containing each attempt,
@@ -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|
@@ -1811,8 +1964,8 @@ export type StoreListenerStats = {
  */
 export interface Store<in out Schemas extends OptionalSchemas> {
   /**
-   * The getTables method returns a Tables object containing the entire data of
-   * the Store.
+   * The getTables method returns a Tables object containing the entire tabular
+   * data of the Store.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -1824,9 +1977,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * data, so changes made to the returned object are not made to the Store
    * itself.
    *
-   * @returns A Tables object containing the entire data of the Store.
+   * @returns A Tables object containing the tabular data of the Store.
    * @example
-   * This example retrieves the data in a Store.
+   * This example retrieves the tabular data in a Store.
    *
    * ```js
    * const store = createStore().setTables({
@@ -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.
    *
@@ -1999,7 +2197,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *
    * @param tableId The Id of the Table in the Store.
    * @param cellId The Id of the Cell whose values are used for the sorting, or
-   * `undefined` to by sort the Row Id itself.
+   * `undefined` to sort by the Row Id itself.
    * @param descending Whether the sorting should be in descending order.
    * @param offset The number of Row Ids to skip for pagination purposes, if
    * any.
@@ -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'}}});
@@ -2234,9 +2432,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * data, so changes made to the returned object are not made to the Store
    * itself.
    *
-   * @returns An object containing the entire data of the Values.
+   * @returns An object containing the set of keyed Values in the Store.
    * @example
-   * This example retrieves the keyed Values data in a Store.
+   * This example retrieves the set of keyed Values in the Store.
    *
    * ```js
    * const store = createStore().setValues({open: true, employees: 3});
@@ -2244,7 +2442,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * // -> {open: true, employees: 3}
    * ```
    * @example
-   * This example retrieves a Values from a Store that has none, returning an
+   * This example retrieves Values from a Store that has none, returning an
    * empty object.
    *
    * ```js
@@ -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:
    *
@@ -2671,7 +2904,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   getSchemaJson(): Json;
 
   /**
-   * The setTables method takes an object and sets the entire data of the Store.
+   * The setTables method takes an object and sets the entire tabular data of
+   * the Store.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -2695,7 +2929,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *
    * @param tables The data of the Store to be set.
    * @example
-   * This example sets the data of a Store.
+   * This example sets the tabular data of a Store.
    *
    * ```js
    * const store = createStore().setTables({
@@ -2706,8 +2940,8 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * // -> {pets: {fido: {species: 'dog'}}, species: {dog: {price: 5}}}
    * ```
    * @example
-   * This example attempts to set the data of an existing Store with partly
-   * invalid, and then completely invalid, Tables objects.
+   * This example attempts to set the tabular data of an existing Store with
+   * partly invalid, and then completely invalid, Tables objects.
    *
    * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
@@ -2851,7 +3085,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * addRow(tableId: Id, row: Row): Id | undefined;
+   * addRow(tableId: Id, row: Row, reuseRowIds?: boolean): Id | undefined;
    * ```
    *
    * This method will cause listeners to be called for any Table, Row, Cell, or
@@ -2869,8 +3103,17 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * Row is added to the Table. However it is likely to be a string
    * representation of an increasing integer.
    *
+   * The `reuseRowIds` parameter defaults to `true`, which means that if you
+   * delete a Row and then add another, the Id will be re-used - unless you
+   * delete the entire Table, in which case all Row Ids will reset. Otherwise,
+   * if you specify `reuseRowIds` to be `false`, then the Id will be a
+   * monotonically increasing string representation of an increasing integer,
+   * regardless of any you may have previously deleted.
+   *
    * @param tableId The Id of the Table in the Store.
    * @param row The data of a single Row to be added.
+   * @param reuseRowIds Whether Ids should be recycled from previously deleted
+   * Row objects, defaulting to `true`.
    * @returns A reference to the Store.
    * @example
    * This example adds a single Row.
@@ -2904,6 +3147,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   addRow<TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId,
     row: Row<Schemas[0], TableId, true>,
+    reuseRowIds?: boolean,
   ): Id | undefined;
 
   /**
@@ -3347,7 +3591,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * // -> {}
    * ```
    * @example
-   * This example attempts to set the the tabular and keyed value contents of a
+   * This example attempts to set both the tabular and keyed value contents of a
    * Store from an invalid serialization.
    *
    * ```js
@@ -4209,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.
@@ -4571,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.
@@ -4723,7 +5123,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    *
    * @param tableId The Id of the Table to listen to.
    * @param cellId The Id of the Cell whose values are used for the sorting, or
-   * `undefined` to by sort the Row Id itself.
+   * `undefined` to sort by the Row Id itself.
    * @param descending Whether the sorting should be in descending order.
    * @param offset The number of Row Ids to skip for pagination purposes, if
    * any.
@@ -4769,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
@@ -5982,6 +6382,57 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addStartTransactionListener method registers a listener function with
+   * the Store that will be called at the start of a transaction.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addStartTransactionListener(listener: TransactionListener): Id;
+   * ```
+   *
+   * The provided TransactionListener will receive a reference to the Store and
+   * two booleans to indicate whether Cell or Value data has been touched during
+   * the transaction. Since this is called at the start, they will both be
+   * `false`!
+   *
+   * Note that a TransactionListener added to the Store with this method can
+   * mutate the Store, and its changes will be treated as part of the
+   * transaction that is starting.
+   *
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @example
+   * This example registers a listener that is called at start end of the
+   * transaction, just before its listeners will be called.
+   *
+   * ```js
+   * const store = createStore()
+   *   .setTables({
+   *     pets: {fido: {species: 'dog', color: 'brown'}},
+   *   })
+   *   .setValues({open: true, employees: 3});
+   * const listenerId = store.addStartTransactionListener(
+   *   (store, cellsTouched, valuesTouched) => {
+   *     console.log('Transaction started');
+   *   },
+   * );
+   *
+   * store.transaction(() =>
+   *   store.setCell('pets', 'fido', 'color', 'brown').setValue('employees', 3),
+   * );
+   * // -> 'Transaction started'
+   *
+   * store.callListener(listenerId);
+   * // -> 'Transaction started'
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   * @since v3.2.0
+   */
+  addStartTransactionListener(listener: TransactionListener<Schemas>): Id;
+
   /**
    * The addWillFinishTransactionListener method registers a listener function
    * with the Store that will be called just before other non-mutating listeners
@@ -6008,6 +6459,11 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * value of `cellsTouched` and `valuesTouched` in the listener will be `false`
    * because all changes have been reverted.
    *
+   * Note that a TransactionListener added to the Store with this method can
+   * mutate the Store itself, and its changes will be treated as part of the
+   * transaction that is starting (and may fire non-mutating listeners after
+   * this).
+   *
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the
@@ -6107,6 +6563,9 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * value of `cellsTouched` and `valuesTouched` in the listener will be `false`
    * because all changes have been reverted.
    *
+   * Note that a TransactionListener added to the Store with this method
+   * _cannot_ mutate the Store itself, and attempts to do so will fail silently.
+   *
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the
@@ -6271,7 +6730,7 @@ export interface Store<in out Schemas extends OptionalSchemas> {
    * ```
    * @example
    * This example registers listeners for the end of transactions, and for
-   * invalid Cells. The are explicitly called, meaninglessly. The former
+   * invalid Cells. They are explicitly called, meaninglessly. The former
    * receives empty arguments. The latter is not called at all.
    *
    * ```js