tinybase 1.0.2 → 1.1.0-beta.0

package/lib/debug/store.d.ts

@@ -89,7 +89,7 @@ export type Row = {[cellId: Id]: Cell};
 export type Cell = string | number | boolean;
 
 /**
- * The TableCallback type describes a function that takes a Tables's Id and a
+ * The TableCallback type describes a function that takes a Table's Id and a
  * callback to loop over each Row within it.
  *
  * A TableCallback is provided when using the forEachTable method, so that you
@@ -332,6 +332,35 @@ export type CellListener = (
   getCellChange: GetCellChange | undefined,
 ) => void;
 
+/**
+ * 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
+ * method. See that method for specific examples.
+ *
+ * When called, a InvalidCellListener is given 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.
+ *
+ * @param store A reference to the Store that was being changed.
+ * @param tableId The Id of the Table that was being changed.
+ * @param rowId The Id of the Row that was being changed.
+ * @param cellId The Id of the Cell that was being changed.
+ * @param invalidCells An array of the values of the Cell that were invalid.
+ * @category Listener
+ */
+export type InvalidCellListener = (
+  store: Store,
+  tableId: Id,
+  rowId: Id,
+  cellId: Id,
+  invalidCells: any[],
+) => void;
+
 /**
  * The GetCellChange type describes a function that returns information about
  * any Cell's changes during a transaction.
@@ -545,6 +574,9 @@ export type StoreListenerStats = {
  * unique Id. And the setPartialRow method lets you update multiple Cell values
  * in a Row without affecting the others.
  *
+ * You can listen to attempts to write invalid data to a Cell with the
+ * addInvalidCellListener method.
+ *
  * The transaction method is used to wrap multiple changes to the Store so that
  * the relevant listeners only fire once.
  *
@@ -867,6 +899,26 @@ export interface Store {
    */
   getCell(tableId: Id, rowId: Id, cellId: Id): Cell | undefined;
 
+  /**
+   * The hasTables method returns a boolean indicating whether any Table objects
+   * exist in the Store.
+   *
+   * @returns Whether any Tables exist.
+   * @example
+   * This example shows simple existence checks.
+   *
+   * ```js
+   * const store = createStore();
+   * console.log(store.hasTables());
+   * // -> false
+   * store.setTables({pets: {fido: {species: 'dog'}}});
+   * console.log(store.hasTables());
+   * // -> true
+   * ```
+   * @category Getter
+   */
+  hasTables(): boolean;
+
   /**
    * The hasTable method returns a boolean indicating whether a given Table
    * exists in the Store.
@@ -1611,7 +1663,7 @@ export interface Store {
    *
    * This method is useful for iterating over the Table structure of the Store
    * in a functional style. The `tableCallback` parameter is a TableCallback
-   * function that will called with the Id of each Table, and with a function
+   * function that will be called with the Id of each Table, and with a function
    * that can then be used to iterate over each Row of the Table, should you
    * wish.
    *
@@ -1644,9 +1696,10 @@ export interface Store {
    *
    * This method is useful for iterating over the Row structure of the Table in
    * a functional style. The `rowCallback` parameter is a RowCallback function
-   * that will called with the Id of each Row, and with a function that can then
-   * be used to iterate over each Cell of the Row, should you wish.
+   * that will be called with the Id of each Row, and with a function that can
+   * then be used to iterate over each Cell of the Row, should you wish.
    *
+   * @param tableId The Id of the Table to iterate over.
    * @param rowCallback The function that should be called for every Row.
    * @example
    * This example iterates over each Row in a Table, and lists each Cell Id
@@ -1678,8 +1731,10 @@ export interface Store {
    *
    * This method is useful for iterating over the Cell structure of the Row in a
    * functional style. The `cellCallback` parameter is a CellCallback function
-   * that will called with the Id and value of each Cell.
+   * that will be called with the Id and value of each Cell.
    *
+   * @param tableId The Id of the Table containing the Row to iterate over.
+   * @param rowId The Id of the Row to iterate over.
    * @param cellCallback The function that should be called for every Cell.
    * @example
    * This example iterates over each Cell in a Row, and lists its value.
@@ -2348,6 +2403,133 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addInvalidCellListener method registers a listener function with the
+   * Store that will be called whenever invalid data was attempted to be written
+   * to a Cell.
+   *
+   * 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).
+   *
+   * All, some, or none of the `tableId`, `rowId`, and `cellId` parameters can
+   * be wildcarded with `null`. You can listen to a specific Cell in a specific
+   * 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
+   * 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 rowId The Id of the Row to listen to, or `null` as a wildcard.
+   * @param cellId The Id of the Cell to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever an attempt to
+   * write invalid data to the matching Cell was made.
+   * @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 invalid changes to a
+   * specific Cell.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   'pets',
+   *   'fido',
+   *   'color',
+   *   (store, tableId, rowId, cellId, invalidCells) => {
+   *     console.log('Invalid color cell in fido row in pets table');
+   *     console.log(invalidCells);
+   *   },
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * // -> 'Invalid color cell in fido row in pets table'
+   * // -> [{r: '96', g: '4B', b: '00'}]
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any invalid changes to
+   * any Cell.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   null,
+   *   null,
+   *   null,
+   *   (store, tableId, rowId, cellId) => {
+   *     console.log(
+   *       `Invalid ${cellId} cell in ${rowId} row in ${tableId} table`,
+   *     );
+   *   },
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * // -> 'Invalid color cell in fido row in pets table'
+   * store.setTable('sales', {fido: {date: new Date()}});
+   * // -> 'Invalid date cell in fido row in sales table'
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any changes to a
+   * specific Cell, and which also mutates the Store itself.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   'pets',
+   *   'fido',
+   *   'color',
+   *   (store, tableId, rowId, cellId, invalidCells) =>
+   *     store.setCell(
+   *       'meta',
+   *       'invalid_updates',
+   *       `${tableId}_${rowId}_${cellId}`,
+   *       JSON.stringify(invalidCells[0]),
+   *     ),
+   *   true,
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * console.log(store.getRow('meta', 'invalid_updates'));
+   * // -> {'pets_fido_color': '{"r":"96","g":"4B","b":"00"}'}
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addInvalidCellListener(
+    tableId: IdOrNull,
+    rowId: IdOrNull,
+    cellId: IdOrNull,
+    listener: InvalidCellListener,
+    mutator?: boolean,
+  ): Id;
+
   /**
    * The callListener method provides a way for you to manually provoke a
    * listener to be called, even if the underlying data hasn't changed.