tinybase 1.1.0-beta.1 → 1.2.0-beta.1

package/lib/debug/metrics.d.ts

@@ -37,7 +37,7 @@ export type Metric = number;
 export type MetricCallback = (metricId: Id, metric?: Metric) => void;
 
 /**
- * The Aggregate type describes a custom function that takes an array or numbers
+ * The Aggregate type describes a custom function that takes an array of numbers
  * and returns an aggregate that is used as a Metric.
  *
  * There are a number of common predefined aggregators, such as for counting,

package/lib/debug/store.d.ts

@@ -88,6 +88,18 @@ export type Row = {[cellId: Id]: Cell};
  */
 export type Cell = string | number | boolean;
 
+/**
+ * The CellOrUndefined type is a data structure representing the data in a
+ * single cell or the value `undefined`.
+ *
+ * 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.
+ *
+ * @category Store
+ */
+export type CellOrUndefined = Cell | undefined;
+
 /**
  * The TableCallback type describes a function that takes a Table's Id and a
  * callback to loop over each Row within it.
@@ -149,7 +161,7 @@ export type CellCallback = (cellId: Id, cell: Cell) => void;
  * @param cell The current value of the Cell to map to a new value.
  * @category Callback
  */
-export type MapCell = (cell: Cell | undefined) => Cell;
+export type MapCell = (cell: CellOrUndefined) => Cell;
 
 /**
  * The GetCell type describes a function that takes a Id and returns the Cell
@@ -162,7 +174,7 @@ export type MapCell = (cell: Cell | undefined) => Cell;
  * @param cellId The Id of the Cell to fetch the value for.
  * @category Callback
  */
-export type GetCell = (cellId: Id) => Cell | undefined;
+export type GetCell = (cellId: Id) => CellOrUndefined;
 
 /**
  * The TablesListener type describes a function that is used to listen to
@@ -390,8 +402,8 @@ export type GetCellChange = (tableId: Id, rowId: Id, cellId: Id) => CellChange;
  */
 export type CellChange = [
   changed: boolean,
-  oldCell: Cell | undefined,
-  newCell: Cell | undefined,
+  oldCell: CellOrUndefined,
+  newCell: CellOrUndefined,
 ];
 
 /**
@@ -461,6 +473,59 @@ export type CellSchema =
       default?: boolean;
     };
 
+/**
+ * The ChangedCells type describes the Cell values that have been changed during
+ * a transaction, primarily used so that you can indicate whether the
+ * transaction should be rolled back.
+ *
+ * A ChangedCells object is provided to the `doRollback` callback when using 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 which provides both the old and new Cell values in
+ * a two-part array. These are describing the state of each changed Cell in
+ * Store at the _start_ of the transaction, and by the _end_ of the transaction.
+ *
+ * Hence, an `undefined` value for the first item in the array means that the
+ * Cell was added during the transaction. An `undefined` value for the second
+ * item in the array means that the Cell was removed during the transaction. An
+ * array with two different Cell values indicates that it was changed. The
+ * two-part array will never contain two items of the same value (including two
+ * `undefined` values), even if, during the transaction, a Cell was changed to a
+ * different value and then changed back.
+ *
+ * @category Transaction
+ */
+export type ChangedCells = {
+  [tableId: Id]: {
+    [rowId: Id]: {
+      [cellId: Id]: [CellOrUndefined, CellOrUndefined];
+    };
+  };
+};
+/**
+ * The InvalidCells type describes the invalid Cell values that have been
+ * attempted during a transaction, primarily used so that you can indicate
+ * whether the transaction should be rolled back.
+ *
+ * An InvalidCells object is provided to the `doRollback` callback when using
+ * 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.
+ *
+ * @category Transaction
+ */
+export type InvalidCells = {
+  [tableId: Id]: {
+    [rowId: Id]: {
+      [cellId: Id]: any[];
+    };
+  };
+};
+
 /**
  * The StoreListenerStats type describes the number of listeners registered with
  * the Store, and can be used for debugging purposes.
@@ -897,7 +962,7 @@ export interface Store {
    * ```
    * @category Getter
    */
-  getCell(tableId: Id, rowId: Id, cellId: Id): Cell | undefined;
+  getCell(tableId: Id, rowId: Id, cellId: Id): CellOrUndefined;
 
   /**
    * The hasTables method returns a boolean indicating whether any Table objects
@@ -1603,7 +1668,15 @@ export interface Store {
    * Transactions can be nested. Relevant listeners will be called only when the
    * outermost one completes.
    *
+   * The second, optional parameter, `doRollback` is a callback that you can use
+   * to rollback the transaction if it did not complete to your satisfaction. It
+   * is called with `changedCells` and `invalidCells` parameters, which inform
+   * you of the net changes that have been made during the transaction, and any
+   * invalid attempts to do so, respectively.
+   *
    * @param actions The function to be executed as a transaction.
+   * @param doRollback An optional callback that should return `true` if you
+   * want to rollback the transaction at the end.
    * @returns Whatever value the provided transaction function returns.
    * @example
    * This example makes changes to two Cells, first outside, and secondly
@@ -1653,9 +1726,46 @@ export interface Store {
    * // -> undefined
    * // No net change during the transaction, so the listener is not called.
    * ```
-   * @category Setter
+   * @example
+   * This example makes multiple changes to the Store, including some attempts
+   * to update a Cell with invalid values. The `doRollback` callback receives
+   * information about the changes and invalid attempts, and then judges that
+   * the transaction should be rolled back to its original state.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   *
+   * store.transaction(
+   *   () => {
+   *     store.setCell('pets', 'fido', 'color', 'black');
+   *     store.setCell('pets', 'fido', 'eyes', ['left', 'right']);
+   *     store.setCell('pets', 'fido', 'info', {sold: null});
+   *   },
+   *   (changedCells, invalidCells) => {
+   *     console.log(store.getTables());
+   *     // -> {pets: {fido: {species: 'dog', color: 'black'}}}
+   *     console.log(changedCells);
+   *     // -> {pets: {fido: {color: ['brown', 'black']}}}
+   *     console.log(invalidCells);
+   *     // -> {pets: {fido: {eyes: [['left', 'right']], info: [{sold: null}]}}}
+   *     return invalidCells['pets'] != null;
+   *   },
+   * );
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
+   * ```
+   * @category Transaction
    */
-  transaction<Return>(actions: () => Return): Return;
+  transaction<Return>(
+    actions: () => Return,
+    doRollback?: (
+      changedCells: ChangedCells,
+      invalidCells: InvalidCells,
+    ) => boolean,
+  ): Return;
 
   /**
    * The forEachTable method takes a function that it will then call for each
@@ -2433,6 +2543,21 @@ export interface Store {
    * The changes made by mutator listeners do not fire other mutating listeners,
    * though they will fire non-mutator listeners.
    *
+   * Special note should be made for how the listener will be called when a
+   * Schema is present. The listener will be called:
+   *
+   * - if a Table is being updated that is not specified in the Schema
+   * - if a Cell is of the wrong type specified in the Schema
+   * - if a Cell is omitted and is not defaulted in the Schema
+   * - if an empty Row is provided and there are no Cell defaults in the Schema
+   *
+   * The listener will not be called if Cell that is defaulted in the Schema is
+   * not provided, as long as all of the Cells that are _not_ defaulted _are_
+   * provided.
+   *
+   * To help understand all of these schema-based conditions, please see the
+   * Schema example below.
+   *
    * @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.
@@ -2468,7 +2593,9 @@ export interface Store {
    * ```
    * @example
    * This example registers a listener that responds to any invalid changes to
-   * any Cell.
+   * any Cell - in a Store _without_ a Schema. Note also how it then responds to
+   * cases where an empty or invalid Row objects, or Table objects, or Tables
+   * objects are provided.
    *
    * ```js
    * const store = createStore().setTables({
@@ -2490,6 +2617,91 @@ export interface Store {
    * store.setTable('sales', {fido: {date: new Date()}});
    * // -> 'Invalid date cell in fido row in sales table'
    *
+   * store.setRow('pets', 'felix', {});
+   * // -> 'Invalid undefined cell in felix row in pets table'
+   *
+   * store.setRow('filter', 'name', /[a-z]?/);
+   * // -> 'Invalid undefined cell in name row in filter table'
+   *
+   * store.setRow('sales', '2021', {forecast: undefined});
+   * // -> 'Invalid forecast cell in 2021 row in sales table'
+   *
+   * store.addRow('filter', /[0-9]?/);
+   * // -> 'Invalid undefined cell in undefined row in filter table'
+   *
+   * store.setTable('raw', {});
+   * // -> 'Invalid undefined cell in undefined row in raw table'
+   *
+   * store.setTable('raw', ['row1', 'row2']);
+   * // -> 'Invalid undefined cell in undefined row in raw table'
+   *
+   * store.setTables(['table1', 'table2']);
+   * // -> 'Invalid undefined cell in undefined row in undefined table'
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any invalid changes to
+   * any Cell - in a Store _with_ a Schema. Note how it responds to cases where
+   * missing parameters are provided for optional, and defaulted Cell values in
+   * a Row.
+   *
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     color: {type: 'string', default: 'unknown'},
+   *   },
+   * });
+   *
+   * const listenerId = store.addInvalidCellListener(
+   *   null,
+   *   null,
+   *   null,
+   *   (store, tableId, rowId, cellId) => {
+   *     console.log(
+   *       `Invalid ${cellId} cell in ${rowId} row in ${tableId} table`,
+   *     );
+   *   },
+   * );
+   *
+   * store.setRow('sales', 'fido', {price: 5});
+   * // -> 'Invalid price cell in fido row in sales table'
+   * // The listener is called, because the sales Table is not in the schema
+   *
+   * store.setRow('pets', 'felix', {species: true});
+   * // -> 'Invalid species cell in felix row in pets table'
+   * // The listener is called, because species is invalid...
+   * console.log(store.getRow('pets', 'felix'));
+   * // -> {color: 'unknown'}
+   * // ...even though a Row was set with the default value
+   *
+   * store.setRow('pets', 'fido', {color: 'brown'});
+   * // -> 'Invalid species cell in fido row in pets table'
+   * // The listener is called, because species is missing and not defaulted...
+   * console.log(store.getRow('pets', 'fido'));
+   * // -> {color: 'brown'}
+   * // ...even though a Row was set
+   *
+   * store.setRow('pets', 'rex', {species: 'dog'});
+   * console.log(store.getRow('pets', 'rex'));
+   * // -> {species: 'dog', color: 'unknown'}
+   * // The listener is not called, because color is defaulted
+   *
+   * store.delTables().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     color: {type: 'string'},
+   *   },
+   * });
+   *
+   * store.setRow('pets', 'cujo', {});
+   * // -> 'Invalid species cell in cujo row in pets table'
+   * // -> 'Invalid color cell in cujo row in pets table'
+   * // -> 'Invalid undefined cell in cujo row in pets table'
+   * // The listener is called multiple times, because neither Cell is defaulted
+   * // and the Row as a whole is empty
+   *
    * store.delListener(listenerId);
    * ```
    * @example