tinybase 1.3.6 → 2.0.0-beta.2

package/lib/store.d.ts

@@ -94,7 +94,7 @@ export type Cell = string | number | boolean;
  *
  * This is used when describing a Cell that is present _or_ that is not present
  * - such as when it has been deleted, or when describing a previous state where
- * the Cell value has since been added.
+ *   the Cell value has since been added.
  *
  * @category Store
  */
@@ -284,6 +284,35 @@ export type TableListener = (
  */
 export type RowIdsListener = (store: Store, tableId: Id) => void;
 
+/**
+ * The SortedRowIdsListener type describes a function that is used to listen to
+ * changes to sorted Row Ids in a Table.
+ *
+ * A SortedRowIdsListener is provided when using the addSortedRowIdsListener
+ * method. See that method for specific examples.
+ *
+ * When called, a SortedRowIdsListener is given a reference to the Store, the Id
+ * of the Table whose Row Ids sorting changed, the Cell Id being used to sort
+ * them, and whether descending or not. It also receives the sorted array of Ids
+ * itself, so that you can use them in the listener without the additional cost
+ * of an explicit call to getSortedRowIds.
+ *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table whose sorted Row Ids changed.
+ * @param cellId The Id of the Cell whose values were used for the sorting.
+ * @param descending Whether the sorting was in descending order.
+ * @param sortedRowIds The sorted Row Ids themselves.
+ * @category Listener
+ * @since v2.0.0
+ */
+export type SortedRowIdsListener = (
+  store: Store,
+  tableId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  sortedRowIds: Ids,
+) => void;
+
 /**
  * The RowListener type describes a function that is used to listen to changes
  * to a Row.
@@ -327,7 +356,6 @@ export type RowListener = (
  * @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.
- * changes.
  * @category Listener
  */
 export type CellIdsListener = (store: Store, tableId: Id, rowId: Id) => void;
@@ -421,9 +449,9 @@ export type GetCellChange = (tableId: Id, rowId: Id, cellId: Id) => CellChange;
  * The CellChange type describes a Cell's changes during a transaction.
  *
  * This is returned by the GetCellChange function that is provided to every
- * listener when called. This array contains the previous value of a Cell
- * before the current transaction, the new value after it, and a convenience
- * flag that indicates that the value has changed.
+ * listener when called. This array contains the previous value of a Cell before
+ * the current transaction, the new value after it, and a convenience flag that
+ * indicates that the value has changed.
  *
  * @category Listener
  */
@@ -540,9 +568,9 @@ export type ChangedCells = {
  * the transaction method. See that method for specific examples.
  *
  * This type is a nested structure of Table, Row, and Cell objects, much like
- * the Tables object, but one for which Cell values are listed in array
- * (much like the InvalidCellListener type) so that multiple failed attempts to
- * change a Cell during the transaction are described.
+ * the Tables object, but one for which Cell values are listed in array (much
+ * like the InvalidCellListener type) so that multiple failed attempts to change
+ * a Cell during the transaction are described.
  *
  * @category Transaction
  * @since v1.2.0
@@ -568,39 +596,43 @@ export type InvalidCells = {
  */
 export type StoreListenerStats = {
   /**
-   * The number of TablesListeners registered with the Store.
+   * The number of TablesListener functions registered with the Store.
    */
   tables?: number;
   /**
-   * The number of TableIdsListeners registered with the Store.
+   * The number of TableIdsListener functions registered with the Store.
    */
   tableIds?: number;
   /**
-   * The number of TableListeners registered with the Store.
+   * The number of TableListener functions registered with the Store.
    */
   table?: number;
   /**
-   * The number of RowIdsListeners registered with the Store.
+   * The number of RowIdsListener functions registered with the Store.
    */
   rowIds?: number;
   /**
-   * The number of RowListeners registered with the Store.
+   * The number of SortedRowIdsListener functions registered with the Store.
+   */
+  sortedRowIds?: number;
+  /**
+   * The number of RowListener functions registered with the Store.
    */
   row?: number;
   /**
-   * The number of CellIdsListeners registered with the Store.
+   * The number of CellIdsListener functions registered with the Store.
    */
   cellIds?: number;
   /**
-   * The number of CellListeners registered with the Store.
+   * The number of CellListener functions registered with the Store.
    */
   cell?: number;
   /**
-   * The number of InvalidCellListeners registered with the Store.
+   * The number of InvalidCellListener functions registered with the Store.
    */
   invalidCell?: number;
   /**
-   * The number of TransactionListeners registered with the Store.
+   * The number of TransactionListener functions registered with the Store.
    */
   transaction?: number;
 };
@@ -667,6 +699,7 @@ export type StoreListenerStats = {
  * |Table Ids|getTableIds|-|-|addTableIdsListener|
  * |Table|getTable|setTable|delTable|addTableListener|
  * |Row Ids|getRowIds|-|-|addRowIdsListener|
+ * |Row Ids (sorted)|getSortedRowIds|-|-|addSortedRowIdsListener|
  * |Row|getRow|setRow|delRow|addRowListener|
  * |Cell Ids|getCellIds|-|-|addCellIdsListener|
  * |Cell|getCell|setCell|delCell|addCellListener|
@@ -794,9 +827,9 @@ export interface Store {
    * The getTableIds method returns the Ids of every Table in the Store.
    *
    * 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. Although
-   * the order of Ids have no meaning, this method is expected to return them in
-   * the order in which each Table was added.
+   * Ids, so changes made to the list are not made to the Store itself. Since
+   * v2.0.0, the order is significant: this method will return the Ids in the
+   * order in which each Table was added.
    *
    * @returns An array of the Ids of every Table in the Store.
    * @example
@@ -861,9 +894,9 @@ export interface Store {
    * The getRowIds method returns the Ids of every Row in a given 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. Although
-   * the order of Ids have no meaning, this method is expected to return them in
-   * the order in which each Row was added.
+   * Ids, so changes made to the list are not made to the Store itself. Since
+   * v2.0.0, the order is significant: this method will return the Ids in the
+   * order in which each Row was added.
    *
    * @param tableId The Id of the Table in the Store.
    * @returns An array of the Ids of every Row in the Table.
@@ -893,6 +926,82 @@ export interface Store {
    */
   getRowIds(tableId: Id): Ids;
 
+  /**
+   * The getSortedRowIds method returns the Ids of every Row in a given Table,
+   * sorted according to the values in a specified Cell.
+   *
+   * The sorting of the rows is alphanumeric, and you can indicate whether it
+   * should be in descending order.
+   *
+   * Note that every call to this method will perform the sorting afresh - there
+   * is no caching of the results - and so you are advised to memoize the
+   * results yourself, especially when the Table is large. For a performant
+   * approach to tracking the sorted Row Ids when they change, use the
+   * addSortedRowIdsListener method.
+   *
+   * If the Table does not exist, an empty array is returned.
+   *
+   * @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.
+   * @param descending Whether the sorting should be in descending order.
+   * @returns An array of the sorted Ids of every Row in the Table.
+   * @example
+   * This example retrieves sorted Row Ids in a Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', 'species'));
+   * // -> ['felix', 'fido']
+   * ```
+   * @example
+   * This example retrieves sorted Row Ids in a Table in reverse order.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *     cujo: {species: 'wolf'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', 'species', true));
+   * // -> ['cujo', 'fido', 'felix']
+   * ```
+   * @example
+   * This example retrieves Row Ids sorted by their own value, since the
+   * `cellId` parameter is undefined.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *     cujo: {species: 'wolf'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets'));
+   * // -> ['cujo', 'felix', 'fido']
+   * ```
+   * @example
+   * This example retrieves the sorted Row Ids of a Table that does not exist,
+   * returning an empty array.
+   *
+   * ```js
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * console.log(store.getSortedRowIds('employees'));
+   * // -> []
+   * ```
+   * @category Getter
+   * @since v2.0.0
+   */
+  getSortedRowIds(tableId: Id, cellId?: Id, descending?: boolean): Ids;
+
   /**
    * The getRow method returns an object containing the entire data of a single
    * Row in a given Table.
@@ -935,9 +1044,9 @@ export interface Store {
    * given 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. Although
-   * the order of Ids have no meaning, this method is expected to return them in
-   * the order in which each Row was added.
+   * Ids, so changes made to the list are not made to the Store itself. Since
+   * v2.0.0, the order is significant: this method will return the Ids in the
+   * order in which each Cell was added.
    *
    * @param tableId The Id of the Table in the Store.
    * @param rowId The Id of the Row in the Table.
@@ -968,17 +1077,13 @@ export interface Store {
   getCellIds(tableId: Id, rowId: Id): Ids;
 
   /**
-   * The getCell method returns an object containing the value of a single Cell
-   * in a given Row, in a given Table.
-   *
-   * 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.
+   * The getCell method returns the value of a single Cell in a given Row, in a
+   * given Table.
    *
    * @param tableId The Id of the Table in the Store.
    * @param rowId The Id of the Row in the Table.
    * @param cellId The Id of the Cell in the Row.
-   * @returns The value of the Cell.
+   * @returns The value of the Cell, or `undefined`.
    * @example
    * This example retrieves a single Cell.
    *
@@ -2100,12 +2205,19 @@ export interface Store {
    * The addTableIdsListener method registers a listener function with the Store
    * that will be called whenever the Table Ids in the Store change.
    *
-   * Such a listener is only called when a Table is added or removed. To listen
-   * to all changes in the Store, use the addTablesListener method.
-   *
    * The provided listener is a TableIdsListener function, and will be called
    * with a reference to the Store.
    *
+   * By default, such a listener is only called when a Table is added or
+   * removed. To listen to all changes in the Store, use the addTablesListener
+   * method.
+   *
+   * Since v2.0.0, you can use the optional `trackReorder` parameter to
+   * additionally track when the set of Ids has not changed, but the order has -
+   * for example when a Table from the middle of the Store is removed and then
+   * added back within the same transaction. This behavior is disabled by
+   * default due to the potential performance cost of detecting such changes.
+   *
    * 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
@@ -2116,6 +2228,9 @@ export interface Store {
    *
    * @param listener The function that will be called whenever the Table Ids in
    * the Store change.
+   * @param trackReorder An optional boolean that indicates that the listener
+   * should be called if the set of Ids remains the same but their order
+   * changes.
    * @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
@@ -2145,7 +2260,8 @@ export interface Store {
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addTableIdsListener(
    *   (store) => store.setCell('meta', 'update', 'store', true),
-   *   true,
+   *   false, // track reorder
+   *   true, // mutator
    * );
    *
    * store.setTable('species', {dog: {price: 5}});
@@ -2156,21 +2272,25 @@ export interface Store {
    * ```
    * @category Listener
    */
-  addTableIdsListener(listener: TableIdsListener, mutator?: boolean): Id;
+  addTableIdsListener(
+    listener: TableIdsListener,
+    trackReorder?: boolean,
+    mutator?: boolean,
+  ): Id;
 
   /**
    * The addTableListener method registers a listener function with the Store
    * that will be called whenever data in a Table changes.
    *
-   * 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).
-   *
    * The provided listener is a TableListener function, and will be called with
    * a reference to the Store, the Id of the Table that changed, and a
    * GetCellChange function in case you need to inspect any changes that
    * occurred.
    *
+   * 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
@@ -2259,14 +2379,21 @@ export interface Store {
    * The addRowIdsListener method registers a listener function with the Store
    * that will be called whenever the Row Ids in a Table change.
    *
-   * Such a listener is only called when a Row is added or removed. To listen to
-   * all changes in the Table, use the addTableListener method.
+   * The provided listener is a RowIdsListener 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 Row is added or removed.
+   * 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 `null`).
+   * method's first parameter) or changes to any Table (by providing a `null`
+   * wildcard).
    *
-   * The provided listener is a RowIdsListener function, and will be called with
-   * a reference to the Store and the Id of the Table that changed.
+   * Since v2.0.0, you can use the optional `trackReorder` parameter to
+   * additionally track when the set of Ids has not changed, but the order has -
+   * for example when a Row from the middle of the Table is removed and then
+   * added back within the same transaction. This behavior is disabled by
+   * default due to the potential performance cost of detecting such changes.
    *
    * 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
@@ -2279,6 +2406,9 @@ export interface Store {
    * @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 Row Ids in
    * the Table change.
+   * @param trackReorder An optional boolean that indicates that the listener
+   * should be called if the set of Ids remains the same but their order
+   * changes.
    * @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
@@ -2301,6 +2431,36 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @example
+   * This example registers a listener that responds to a change of order in the
+   * rows of a specific Table, even though the set of Ids themselves has not
+   * changed.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * const listenerId = store.addRowIdsListener(
+   *   'pets',
+   *   (store) => {
+   *     console.log('Row Ids or order for pets table changed');
+   *     console.log(store.getRowIds('pets'));
+   *   },
+   *   true, // track reorder
+   * );
+   *
+   * store.transaction(() => {
+   *   store.delRow('pets', 'fido');
+   *   store.setRow('pets', 'fido', {species: 'dog'});
+   * });
+   * // -> 'Row Ids or order for pets table changed'
+   * // -> ['felix', 'fido']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
    * This example registers a listener that responds to any change to the Row
    * Ids of any Table.
    *
@@ -2329,7 +2489,8 @@ export interface Store {
    * const listenerId = store.addRowIdsListener(
    *   'pets',
    *   (store, tableId) => store.setCell('meta', 'update', tableId, true),
-   *   true,
+   *   false, // track reorder
+   *   true, // mutator
    * );
    *
    * store.setRow('pets', 'felix', {species: 'cat'});
@@ -2343,6 +2504,175 @@ export interface Store {
   addRowIdsListener(
     tableId: IdOrNull,
     listener: RowIdsListener,
+    trackReorder?: boolean,
+    mutator?: boolean,
+  ): Id;
+
+  /**
+   * The addSortedRowIdsListener method registers a listener function with the
+   * Store that will be called whenever sorted Row Ids in a Table change.
+   *
+   * The provided listener is a SortedRowIdsListener function, and will be
+   * called with a reference to the Store, the Id of the Table whose Row Ids
+   * sorting changed, the Cell Id being used to sort them, and whether
+   * descending or not. It also receives the sorted array of Ids itself, so that
+   * you can use them in the listener without the additional cost of an explicit
+   * call to getSortedRowIds.
+   *
+   * Such a listener is called when a Row is added or removed, but also when a
+   * value in the specified Cell (somewhere in the Table) has changed enough to
+   * change the sorting of the Row Ids.
+   *
+   * Unlike most other listeners, you cannot provide wildcards (due to the cost
+   * of detecting changes to the sorting). You can only listen to a single
+   * specified Table, sorted by a single specified Cell.
+   *
+   * 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.
+   * @param cellId The Id of the Cell whose values are used for the sorting, or
+   * `undefined` to by sort the Row Id itself.
+   * @param descending Whether the sorting should be in descending order.
+   * @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 sorted
+   * Row Ids of a specific Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     cujo: {species: 'wolf'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', 'species', false));
+   * // -> ['felix', 'cujo']
+   *
+   * const listenerId = store.addSortedRowIdsListener(
+   *   'pets',
+   *   'species',
+   *   false,
+   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *     console.log(`Sorted Row Ids for ${tableId} table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'fido', {species: 'dog'});
+   * // -> 'Sorted Row Ids for pets table changed'
+   * // -> ['felix', 'fido', 'cujo']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any change to the sorted
+   * Row Ids of a specific Table. The Row Ids are sorted by their own value,
+   * since the `cellId` parameter is explicitly undefined.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', undefined, false));
+   * // -> ['felix', 'fido']
+   *
+   * const listenerId = store.addSortedRowIdsListener(
+   *   'pets',
+   *   undefined,
+   *   false,
+   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *     console.log(`Sorted Row Ids for ${tableId} table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'cujo', {species: 'wolf'});
+   * // -> 'Sorted Row Ids for pets table changed'
+   * // -> ['cujo', 'felix', 'fido']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to a change in the sorting
+   * of the rows of a specific Table, even though the set of Ids themselves has
+   * not changed.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {species: 'dog'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', 'species', false));
+   * // -> ['felix', 'fido']
+   *
+   * const listenerId = store.addSortedRowIdsListener(
+   *   'pets',
+   *   'species',
+   *   false,
+   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *     console.log(`Sorted Row Ids for ${tableId} table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   *
+   * store.setCell('pets', 'felix', 'species', 'tiger');
+   * // -> 'Sorted Row Ids for pets table changed'
+   * // -> ['fido', 'felix']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any change to the sorted
+   * Row Ids of a specific Table, and which also mutates the Store itself.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     cujo: {species: 'wolf'},
+   *     felix: {species: 'cat'},
+   *   },
+   * });
+   * const listenerId = store.addSortedRowIdsListener(
+   *   'pets',
+   *   'species',
+   *   false,
+   *   (store, tableId) => store.setCell('meta', 'sorted', tableId, true),
+   *   true, // mutator
+   * );
+   *
+   * store.setRow('pets', 'fido', {species: 'dog'});
+   * console.log(store.getTable('meta'));
+   * // -> {sorted: {pets: true}}
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   * @since v2.0.0
+   */
+  addSortedRowIdsListener(
+    tableId: Id,
+    cellId: Id | undefined,
+    descending: boolean,
+    listener: SortedRowIdsListener,
     mutator?: boolean,
   ): Id;
 
@@ -2350,6 +2680,11 @@ export interface Store {
    * The addRowListener method registers a listener function with the Store that
    * will be called whenever data in a Row changes.
    *
+   * The provided listener is a RowListener function, and will be called with a
+   * reference to the Store, the Id of the Table that changed, the Id of the Row
+   * that changed, and a GetCellChange function in case you need to inspect any
+   * changes that occurred.
+   *
    * You can either listen to a single Row (by specifying the Table Id and Row
    * Id as the method's first two parameters) or changes to any Row (by
    * providing `null` wildcards).
@@ -2359,11 +2694,6 @@ export interface Store {
    * Table, any Row in a specific Table, a specific Row in any Table, or any Row
    * in any Table.
    *
-   * The provided listener is a RowListener function, and will be called with a
-   * reference to the Store, the Id of the Table that changed, the Id of the Row
-   * that changed, and a GetCellChange function in case you need to inspect any
-   * changes that occurred.
-   *
    * 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
@@ -2460,21 +2790,27 @@ export interface Store {
    * The addCellIdsListener method registers a listener function with the Store
    * that will be called whenever the Cell Ids in a Row change.
    *
-   * Such a listener is only called when a Cell is added or removed. To listen
-   * to all changes in the Row, use the addRowListener method.
+   * The provided listener is a CellIdsListener function, and will be called
+   * with a reference to the Store, the Id of the Table, and the Id of the Row
+   * that changed.
+   *
+   * By default, such a listener is only called when a Cell is added or removed.
+   * To listen to all changes in the Row, use the addRowListener method.
    *
    * You can either listen to a single Row (by specifying the Table Id and Row
    * Id as the method's first two parameters) or changes to any Row (by
-   * providing `null`).
+   * providing a `null` wildcard).
    *
    * Both, either, or neither of the `tableId` and `rowId` parameters can be
    * wildcarded with `null`. You can listen to a specific Row in a specific
    * Table, any Row in a specific Table, a specific Row in any Table, or any Row
    * in any Table.
    *
-   * The provided listener is a CellIdsListener function, and will be called
-   * with a reference to the Store, the Id of the Table, and the Id of the Row
-   * that changed.
+   * Since v2.0.0, you can use the optional `trackReorder` parameter to
+   * additionally track when the set of Ids has not changed, but the order has -
+   * for example when a Cell from the middle of the Row is removed and then
+   * added back within the same transaction. This behavior is disabled by
+   * default due to the potential performance cost of detecting such changes.
    *
    * 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
@@ -2488,6 +2824,9 @@ export interface Store {
    * @param rowId The Id of the Row to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Cell Ids in
    * the Row change.
+   * @param trackReorder An optional boolean that indicates that the listener
+   * should be called if the set of Ids remains the same but their order
+   * changes.
    * @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
@@ -2544,7 +2883,8 @@ export interface Store {
    *   'fido',
    *   (store, tableId, rowId) =>
    *     store.setCell('meta', 'update', `${tableId}_${rowId}`, true),
-   *   true,
+   *   false, // track reorder
+   *   true, // mutator
    * );
    *
    * store.setCell('pets', 'fido', 'color', 'brown');
@@ -2559,6 +2899,7 @@ export interface Store {
     tableId: IdOrNull,
     rowId: IdOrNull,
     listener: CellIdsListener,
+    trackReorder?: boolean,
     mutator?: boolean,
   ): Id;
 
@@ -2566,6 +2907,12 @@ export interface Store {
    * The addCellListener method registers a listener function with the Store
    * that will be called whenever data in a Cell changes.
    *
+   * The provided listener is a CellListener function, and will be called with a
+   * reference to the Store, the Id of the Table that changed, the Id of the Row
+   * that changed, the Id of the Cell that changed, the new Cell value, the old
+   * Cell value, and a GetCellChange function in case you need to inspect any
+   * changes that occurred.
+   *
    * You can either listen to a single Cell (by specifying the Table Id, Row Id,
    * and Cell Id as the method's first three parameters) or changes to any Cell
    * (by providing `null` wildcards).
@@ -2575,12 +2922,6 @@ export interface Store {
    * Row in a specific Table, any Cell in any Row in any Table, for example - or
    * every other combination of wildcards.
    *
-   * The provided listener is a CellListener function, and will be called with a
-   * reference to the Store, the Id of the Table that changed, the Id of the Row
-   * that changed, the Id of the Cell that changed, the new Cell value, the old
-   * Cell value, and a GetCellChange function in case you need to inspect any
-   * changes that occurred.
-   *
    * 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
@@ -2687,6 +3028,14 @@ export interface Store {
    * Store that will be called whenever invalid data was attempted to be written
    * to a Cell.
    *
+   * The provided listener is an InvalidCellListener function, and will be
+   * called with a reference to the Store, the Id of the Table, the Id of the
+   * Row, and the Id of Cell that were 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 attempts to set the
+   * Cell within a single transaction, this is an array containing each attempt,
+   * chronologically.
+   *
    * You can either listen to a single Cell (by specifying the Table Id, Row Id,
    * and Cell Id as the method's first three parameters) or invalid attempts to
    * change any Cell (by providing `null` wildcards).
@@ -2696,14 +3045,6 @@ export interface Store {
    * Row in a specific Table, any Cell in any Row in any Table, for example - or
    * every other combination of wildcards.
    *
-   * The provided listener is an InvalidCellListener function, and will be
-   * called with a reference to the Store, the Id of the Table, the Id of the
-   * Row, and the Id of Cell that were 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 attempts to set the
-   * Cell within a single transaction, this is an array containing each attempt,
-   * chronologically.
-   *
    * 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