tinybase 1.0.4 → 1.1.0-beta.2

package/lib/debug/relationships.js

@@ -7,6 +7,8 @@ const arrayLength = (array) => array.length;
 const arrayIsEmpty = (array) => arrayLength(array) == 0;
 const arrayReduce = (array, cb, initial) => array.reduce(cb, initial);
 const arrayFromSecond = (ids) => ids.slice(1);
+const arrayPush = (array, value) => array.push(value);
+const arrayPop = (array) => array.pop();
 
 const isUndefined = (thing) => thing == void 0;
 const ifNotUndefined = (value, then, otherwise) =>
@@ -52,6 +54,7 @@ const getDefinableFunctions = (store, getDefaultThing, validateRowValue) => {
   const storeListenerIds = mapNew();
   const getStore = () => store;
   const getThingIds = () => mapKeys(tableIds);
+  const forEachThing = (cb) => mapForEach(things, cb);
   const hasThing = (id) => collHas(things, id);
   const getTableId = (id) => mapGet(tableIds, id);
   const getThing = (id) => mapGet(things, id);
@@ -142,6 +145,7 @@ const getDefinableFunctions = (store, getDefaultThing, validateRowValue) => {
   return [
     getStore,
     getThingIds,
+    forEachThing,
     hasThing,
     getTableId,
     getThing,
@@ -194,7 +198,7 @@ const getListenerFunctions = (getThing) => {
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
     thing ??= getThing();
-    const id = listenerPool.pop() ?? '' + nextId++;
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
     return id;
@@ -215,7 +219,7 @@ const getListenerFunctions = (getThing) => {
         forDeepSet(collDel)(deepSet, id, ...idOrNulls);
         mapSet(allListeners, id);
         if (arrayLength(listenerPool) < 1e3) {
-          listenerPool.push(id);
+          arrayPush(listenerPool, id);
         }
         return idOrNulls;
       },
@@ -249,6 +253,7 @@ const createRelationships = getCreateFunction((store) => {
   const [
     getStore,
     getRelationshipIds,
+    forEachRelationshipImpl,
     hasRelationship,
     getLocalTableId,
     getRelationship,
@@ -363,6 +368,12 @@ const createRelationships = getCreateFunction((store) => {
     );
     return relationships;
   };
+  const forEachRelationship = (relationshipCallback) =>
+    forEachRelationshipImpl((relationshipId) =>
+      relationshipCallback(relationshipId, (rowCallback) =>
+        store.forEachRow(getLocalTableId(relationshipId), rowCallback),
+      ),
+    );
   const delRelationshipDefinition = (relationshipId) => {
     mapSet(remoteTableIds, relationshipId);
     delDefinition(relationshipId);
@@ -403,6 +414,7 @@ const createRelationships = getCreateFunction((store) => {
     delRelationshipDefinition,
     getStore,
     getRelationshipIds,
+    forEachRelationship,
     hasRelationship,
     getLocalTableId,
     getRemoteTableId,

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.
  *
@@ -1631,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.
    *
@@ -1664,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
@@ -1698,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.
@@ -2368,6 +2403,235 @@ 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.
+   *
+   * 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.
+   * @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 - 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({
+   *   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.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
+   * 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.