tinybase 3.2.0-beta.0 → 3.3.0

package/lib/types/store.d.ts

@@ -319,6 +319,20 @@ export type TableCallback = (
   forEachRow: (rowCallback: RowCallback) => void,
 ) => void;
 
+/**
+ * The TableCellCallback type describes a function that takes a Cell's Id and
+ * the count of times it appears across a whole Table.
+ *
+ * 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 = (cellId: Id, 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.
@@ -498,10 +512,18 @@ export type TablesListener = (
  *
  * 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 = (store: Store) => void;
+export type TableIdsListener = (
+  store: Store,
+  getIdChanges: GetIdChanges | undefined,
+) => void;
 
 /**
  * The TableListener type describes a function that is used to listen to changes
@@ -530,6 +552,29 @@ export type TableListener = (
   getCellChange: GetCellChange | 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.
+ *
+ * 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 = (
+  store: Store,
+  tableId: Id,
+  getIdChanges: GetIdChanges | undefined,
+) => void;
+
 /**
  * The RowIdsListener type describes a function that is used to listen to
  * changes to the Row Ids in a Table.
@@ -540,11 +585,20 @@ 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 = (store: Store, tableId: Id) => void;
+export type RowIdsListener = (
+  store: Store,
+  tableId: Id,
+  getIdChanges: GetIdChanges | undefined,
+) => void;
 
 /**
  * The SortedRowIdsListener type describes a function that is used to listen to
@@ -620,12 +674,22 @@ 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 = (store: Store, tableId: Id, rowId: Id) => void;
+export type CellIdsListener = (
+  store: Store,
+  tableId: Id,
+  rowId: Id,
+  getIdChanges: GetIdChanges | undefined,
+) => void;
 
 /**
  * The CellListener type describes a function that is used to listen to changes
@@ -699,10 +763,18 @@ export type ValuesListener = (
  *
  * 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 = (store: Store) => void;
+export type ValueIdsListener = (
+  store: Store,
+  getIdChanges: GetIdChanges | undefined,
+) => void;
 
 /**
  * The ValueListener type describes a function that is used to listen to changes
@@ -742,10 +814,10 @@ export type ValueListener = (
  * The InvalidCellListener type describes a function that is used to listen to
  * attempts to set invalid data to a Cell.
  *
- * 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
@@ -772,11 +844,11 @@ export type InvalidCellListener = (
  * The InvalidValueListener type describes a function that is used to listen to
  * attempts to set invalid data to a Value.
  *
- * 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,
@@ -794,6 +866,23 @@ export type InvalidValueListener = (
   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 = () => {[id: Id]: 1 | -1};
+
 /**
  * The GetCellChange type describes a function that returns information about
  * any Cell's changes during a transaction.
@@ -989,6 +1078,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.
    */
@@ -1129,6 +1223,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|
@@ -1221,16 +1316,16 @@ export type StoreListenerStats = {
 export interface Store {
   //
   /**
-   * 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.
    *
    * Note that this returns a copy of, rather than a reference to the underlying
    * 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({
@@ -1318,6 +1413,43 @@ export interface Store {
    */
   getTable(tableId: Id): Table;
 
+  /**
+   * The getTableCellIds method returns the Ids of every Cell used across the
+   * whole Table.
+   *
+   * 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: Id): Ids;
+
   /**
    * The getRowIds method returns the Ids of every Row in a given Table.
    *
@@ -1371,7 +1503,7 @@ export interface Store {
    *
    * @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.
@@ -1497,7 +1629,7 @@ export interface Store {
   getRow(tableId: Id, rowId: Id): Row;
 
   /**
-   * 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.
    *
    * Note that this returns a copy of, rather than a reference, to the list of
@@ -1519,8 +1651,8 @@ export interface Store {
    * // -> ['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'}}});
@@ -1569,9 +1701,9 @@ export interface Store {
    * 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});
@@ -1579,7 +1711,7 @@ export interface Store {
    * // -> {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
@@ -1687,6 +1819,32 @@ export interface Store {
    */
   hasTable(tableId: Id): boolean;
 
+  /**
+   * The hasTableCell method returns a boolean indicating whether a given Cell
+   * exists anywhere in a Table, not just in a specific Row.
+   *
+   * @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: Id, cellId: Id): boolean;
+
   /**
    * The hasRow method returns a boolean indicating whether a given Row exists
    * in the Store.
@@ -1710,7 +1868,7 @@ export interface Store {
 
   /**
    * The hasCell method returns a boolean indicating whether a given Cell exists
-   * in the Store.
+   * in a given Row in a given Table.
    *
    * @param tableId The Id of a possible Table in the Store.
    * @param rowId The Id of a possible Row in the Table.
@@ -1964,7 +2122,8 @@ export interface Store {
   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 method will cause listeners to be called for any Table, Row, Cell, or
    * Id changes resulting from it.
@@ -1982,7 +2141,7 @@ export interface Store {
    *
    * @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({
@@ -1993,8 +2152,8 @@ export interface Store {
    * // -> {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'}}});
@@ -2131,8 +2290,17 @@ export interface Store {
    * 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.
@@ -2163,7 +2331,7 @@ export interface Store {
    * ```
    * @category Setter
    */
-  addRow(tableId: Id, row: Row): Id | undefined;
+  addRow(tableId: Id, row: Row, reuseRowIds?: boolean): Id | undefined;
 
   /**
    * The setPartialRow method takes an object and sets partial data of a single
@@ -2541,7 +2709,7 @@ export interface Store {
    * // -> {}
    * ```
    * @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
@@ -3281,6 +3449,36 @@ export interface Store {
    */
   forEachTable(tableCallback: TableCallback): void;
 
+  /**
+   * The forEachTableCell method takes a function that it will then call for
+   * each Cell used across the whole Table.
+   *
+   * 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: Id, tableCellCallback: TableCellCallback): void;
+
   /**
    * The forEachRow method takes a function that it will then call for each Row
    * in a specified Table.
@@ -3593,6 +3791,111 @@ export interface Store {
     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.
+   *
+   * 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(
+    tableId: IdOrNull,
+    listener: TableCellIdsListener,
+    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.
@@ -3721,7 +4024,7 @@ export interface Store {
    *
    * @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.
@@ -3767,7 +4070,7 @@ export interface Store {
    * 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
@@ -4872,6 +5175,51 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addStartTransactionListener method registers a listener function with
+   * the Store that will be called at the start of a transaction.
+   *
+   * 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): Id;
+
   /**
    * The addWillFinishTransactionListener method registers a listener function
    * with the Store that will be called just before other non-mutating listeners
@@ -4892,6 +5240,11 @@ export interface Store {
    * 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
@@ -4985,6 +5338,9 @@ export interface Store {
    * 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
@@ -5143,7 +5499,7 @@ export interface Store {
    * ```
    * @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

package/lib/types/tools.d.ts

@@ -433,7 +433,7 @@ export interface Tools {
    * // -> `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
@@ -454,7 +454,7 @@ export interface Tools {
    * // -> '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