[middleware] Upward cascade exception

jamesgpearce · jamesgpearce · commit 792ced5a9b7e · 2026-03-06T13:32:01.000+13:00
diff --git a/.gitignore b/.gitignore
@@ -7,4 +7,5 @@ node_modules
 npm-debug.log
 .partykit
 .vscode
-tinybase.code-workspace
+*.code-workspace
+*.tsbuildinfo
diff --git a/site/guides/04_using_middleware.md b/site/guides/04_using_middleware.md
@@ -45,16 +45,16 @@ value. The meaning of this return value depends on the type of callback:
 
 The full list of `willSet*` callbacks you can register is as follows:
 
-| Callback         | Parameters                   | Called                       | Return               |
-| ---------------- | ---------------------------- | ---------------------------- | -------------------- |
-| willSetContent   | content                      | When setContent is called.   | Content or undefined |
-| willSetTables    | tables                       | When setTables is called.    | Tables or undefined  |
-| willSetTable     | tableId, table               | When setTable is called.     | Table or undefined   |
-| willSetRow       | tableId, rowId, row          | When setRow is called.       | Row or undefined     |
-| willSetCell      | tableId, rowId, cellId, cell | When setCell is called.      | Cell or undefined    |
-| willSetValues    | values                       | When setValues is called.    | Values or undefined  |
-| willSetValue     | valueId, value               | When setValue is called.     | Value or undefined   |
-| willApplyChanges | changes                      | When applyChanges is called. | Changes or undefined |
+| Callback         | Parameters                   | Called                            | Return               |
+| ---------------- | ---------------------------- | --------------------------------- | -------------------- |
+| willSetContent   | content                      | When setContent is called.        | Content or undefined |
+| willSetTables    | tables                       | When setTables is called.         | Tables or undefined  |
+| willSetTable     | tableId, table               | When setTable is called.          | Table or undefined   |
+| willSetRow       | tableId, rowId, row          | When setRow or setCell is called. | Row or undefined     |
+| willSetCell      | tableId, rowId, cellId, cell | When setCell is called.           | Cell or undefined    |
+| willSetValues    | values                       | When setValues is called.         | Values or undefined  |
+| willSetValue     | valueId, value               | When setValue is called.          | Value or undefined   |
+| willApplyChanges | changes                      | When applyChanges is called.      | Changes or undefined |
 
 Finally, the full list of `willDel*` callbacks you can register is as follows:
 
@@ -89,42 +89,51 @@ callback cancels the operation, subsequent `willSet*` callbacks will not be
 called. 
 
 ```js
-middleware.addWillSetRowCallback((tableId, rowId, row) => {
-  console.log('Timestamp row');
-  return {...row, timestamp: Date.now()}; 
-});
-middleware.addWillSetRowCallback((tableId, rowId, row) => {
-  console.log('Cancel setting row');
-  return undefined; 
-});
-middleware.addWillSetRowCallback((tableId, rowId, row) => {
-  console.log('Defaulting pet to be alive');
-  return {...row, alive: true}; 
-});
+middleware
+  .addWillSetRowCallback((_tableId, _rowId, row) => ({...row, step1: true}))
+  .addWillSetRowCallback((_tableId, _rowId, row) => ({...row, step2: true}));
 
-store.setRow('pets', 'fido', {'species': 'dog'});
-// -> 'Timestamp row'
-// -> 'Cancel setting row'
-// (Callback 3 is not called because Callback 2 cancels the operation)
+store.setRow('pets', 'fido', {species: 'dog'});
+console.log(store.getRow('pets', 'fido'));
+// -> {species: 'dog', step1: true, step2: true}
+```
 
-console.log(store.getTable('pets'));
+Returning `undefined` from a callback cancels the entire operation, and
+subsequent callbacks will not be called:
+
+```js
+middleware.addWillSetRowCallback((tableId, _rowId, row) =>
+  tableId === 'readonly' ? undefined : row,
+);
+
+store.setRow('employees', 'alice', {role: 'admin'});
+console.log(store.getRow('employees', 'alice'));
+// -> {role: 'admin', step1: true, step2: true}
+
+store.setRow('readonly', 'r1', {data: 'test'});
+console.log(store.getTable('readonly'));
 // -> {}
 ```
 
 Similarly, if a `willDel*` callback cancels the delete operation, subsequent
 `willDel*` callbacks will not be called. In other words, a callback cannot
 re-enable a delete operation that has been cancelled by a previous callback.
 
-A less granular operation on the Store (e.g. setting a Table, which will call
-`willSetTable`) will also then call more granular callbacks (e.g. `willSetRow`,
-`willSetCell`) for each relevant Row and Cell. BUT a more granular operation
-(e.g. setting a Cell, which will call `willSetCell`) will NOT call less granular
-callbacks (e.g. `willSetRow`, `willSetTable`, `willSetContent` and so on).
+In terms of cascading, a less granular operation on the Store (e.g. setting a
+Table, which will call `willSetTable`) will also then call more granular
+callbacks (e.g. `willSetRow`, `willSetCell`) for each relevant Row and Cell.
+
+BUT there is one important exception to this rule though! Calling `setCell`
+will also fire `willSetRow` (receiving existing cells merged with the new cell),
+in addition to the `willSetCell` calls for each Cell in the Row. In other words,
+The entire resulting Row is applied as though `setRow` had been called with it.
+
+This is to allow for row- or schema-level validation and transformation to be
+applied even when only `setCell` calls are being made.
 
-This might seem strange since, in a way, the Row, Table, and Content were
-technically being updated. But the key is to think about the actual method that
-was called on the Store, and then expect callbacks for only more granular
-elements from there.
+Note that `setCell` does not fire `willSetTable`, `willSetTables`, or
+`willSetContent` though. The 'upwards' cascade only goes as far as `willSetRow`
+for `setCell` calls.
 
 ## Complex Object Callbacks
 
diff --git a/src/@types/middleware/docs.js b/src/@types/middleware/docs.js
@@ -77,6 +77,15 @@
  * Multiple WillSetRowCallback functions can be registered and they will be
  * called sequentially, the Row being updated successively. If any callback
  * returns `undefined`, the chain short-circuits and the Row will not be set.
+ *
+ * This callback fires both when setRow is called with a whole Row, and when
+ * setCell is called for a single Cell. When fired from setCell, the Row passed
+ * to the callback is a prospective row containing the existing Cell values
+ * merged with the new Cell value. The entire returned Row is then applied as
+ * though setRow had been called with it: cells present in the returned Row are
+ * written (each also passing through willSetCell), and cells absent from the
+ * returned Row that were present in the existing Row will be deleted. Return
+ * `undefined` to cancel the operation entirely.
  * @param tableId The Id of the Table being written to.
  * @param rowId The Id of the Row being set.
  * @param row The Row object about to be set.
@@ -490,6 +499,15 @@
    * write. Multiple callbacks can be registered and they are called
    * sequentially, each receiving the (possibly transformed) row from the
    * previous callback.
+   *
+   * This callback fires both when a whole Row is set with the setRow method,
+   * _and_ when a single Cell is set with the setCell method. When called from
+   * setCell, the callback receives a prospective row consisting of the existing
+   * Cell values merged with the new Cell value. The entire returned Row is then
+   * applied as though setRow had been called: all cells in the returned Row are
+   * written (each also passing through willSetCell), and any cells absent from
+   * the returned Row that existed before will be deleted. Return `undefined` to
+   * cancel the operation entirely.
    * @param callback The WillSetRowCallback to register.
    * @returns A reference to the Middleware object, for chaining.
    * @example
@@ -539,6 +557,32 @@
    *
    * middleware.destroy();
    * ```
+   * @example
+   * This example shows the callback firing when setCell is called,
+   * automatically stamping an 'updated' timestamp onto the row each time any
+   * cell in it is written.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setRow('pets', 'fido', {species: 'dog'});
+   *
+   * middleware.addWillSetRowCallback((_tableId, _rowId, row) => ({
+   *   ...row,
+   *   updated: Date.now(),
+   * }));
+   *
+   * store.setCell('pets', 'fido', 'legs', 4);
+   * console.log(store.getCell('pets', 'fido', 'legs'));
+   * // -> 4
+   * console.log(typeof store.getCell('pets', 'fido', 'updated'));
+   * // -> 'number'
+   *
+   * middleware.destroy();
+   * ```
    * @category Configuration
    * @since v8.0.0
    */
diff --git a/src/middleware/index.ts b/src/middleware/index.ts
@@ -178,6 +178,7 @@ export const createMiddleware = getCreateFunction(
       willDelValues,
       willDelValue,
       willApplyChanges,
+      () => willSetRowCallbacks.length > 0,
     );
 
     return middleware;
diff --git a/src/store/index.ts b/src/store/index.ts
@@ -189,13 +189,15 @@ type ProtectedMethods = [
     willDelValues: () => boolean,
     willDelValue: (valueId: Id) => boolean,
     willApplyChanges: (changes: Changes) => Changes | undefined,
+    hasWillSetRowCallbacks: () => boolean,
   ) => void,
   setOrDelCell: (
     tableId: Id,
     rowId: Id,
     cellId: Id,
     cell: CellOrUndefined,
     skipMiddleware?: boolean,
+    skipRowMiddleware?: boolean,
   ) => Store,
   setOrDelValue: (
     valueId: Id,
@@ -258,6 +260,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willDelValues?: () => boolean,
     willDelValue?: (valueId: Id) => boolean,
     willApplyChanges?: (changes: Changes) => Changes | undefined,
+    hasWillSetRowCallbacks?: () => boolean,
   ] = [];
   let internalListeners: [
     preStartTransaction?: () => void,
@@ -573,10 +576,18 @@ export const createStore: typeof createStoreDecl = (): Store => {
     cellId: Id,
     cell: CellOrUndefined,
     skipMiddleware?: boolean,
+    skipRowMiddleware?: boolean,
   ) =>
     isUndefined(cell)
       ? delCell(tableId, rowId, cellId, true, skipMiddleware)
-      : setCell(tableId, rowId, cellId, cell, skipMiddleware);
+      : setCell(
+          tableId,
+          rowId,
+          cellId,
+          cell,
+          skipMiddleware,
+          skipRowMiddleware,
+        );
 
   const setOrDelValues = (values: Values) =>
     objIsEmpty(values) ? delValues() : setValues(values);
@@ -697,6 +708,37 @@ export const createStore: typeof createStoreDecl = (): Store => {
       objIsEqual,
     ) as RowMap;
 
+  const applyRowDirectly = (
+    tableId: Id,
+    tableMap: TableMap,
+    rowId: Id,
+    row: Row,
+    skipMiddleware?: boolean,
+  ): void => {
+    mapMatch(
+      mapEnsure(tableMap, rowId, () => {
+        rowIdsChanged(tableId, rowId, 1);
+        return mapNew();
+      }),
+      row,
+      (rowMap, cellId, cell) =>
+        ifNotUndefined(
+          getValidatedCell(tableId, rowId, cellId, cell as Cell),
+          (validCell) =>
+            setValidCell(
+              tableId,
+              rowId,
+              rowMap,
+              cellId,
+              validCell,
+              skipMiddleware,
+            ),
+        ),
+      (rowMap, cellId) =>
+        delValidCell(tableId, tableMap, rowId, rowMap, cellId, true),
+    );
+  };
+
   const setValidCell = (
     tableId: Id,
     rowId: Id,
@@ -1556,6 +1598,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     cellId: Id,
     cell: Cell | MapCell,
     skipMiddleware?: boolean,
+    skipRowMiddleware?: boolean,
   ): Store =>
     fluentTransaction(
       (tableId, rowId, cellId) =>
@@ -1566,15 +1609,49 @@ export const createStore: typeof createStoreDecl = (): Store => {
             cellId,
             isFunction(cell) ? cell(getCell(tableId, rowId, cellId)) : cell,
           ),
-          (validCell) =>
-            setCellIntoNewRow(
-              tableId,
-              getOrCreateTable(tableId),
-              rowId,
-              cellId,
-              validCell,
-              skipMiddleware,
-            ),
+          (validCell) => {
+            const tableMap = getOrCreateTable(tableId);
+            ifNotUndefined(
+              skipMiddleware || skipRowMiddleware || !middleware[14]?.()
+                ? undefined
+                : middleware[3],
+              (willSetRow) => {
+                const existingRowMap = mapGet(tableMap, rowId);
+                const prospectiveRow: Row = {
+                  ...(existingRowMap
+                    ? mapToObj<Cell>(existingRowMap)
+                    : {}),
+                  [cellId]: validCell,
+                };
+                ifNotUndefined(
+                  whileMutating(() =>
+                    willSetRow(
+                      tableId,
+                      rowId,
+                      structuredClone(prospectiveRow),
+                    ),
+                  ),
+                  (row) =>
+                    applyRowDirectly(
+                      tableId,
+                      tableMap,
+                      rowId,
+                      row,
+                      skipMiddleware,
+                    ),
+                );
+              },
+              () =>
+                setCellIntoNewRow(
+                  tableId,
+                  tableMap,
+                  rowId,
+                  cellId,
+                  validCell,
+                  skipMiddleware,
+                ),
+            );
+          },
         ),
       tableId,
       rowId,
@@ -1636,6 +1713,8 @@ export const createStore: typeof createStoreDecl = (): Store => {
                           rowId,
                           cellId,
                           cell as CellOrUndefined,
+                          undefined,
+                          true,
                         ),
                       ),
                 ),
@@ -2042,6 +2121,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willDelValues: () => boolean,
     willDelValue: (valueId: Id) => boolean,
     willApplyChanges: (changes: Changes) => Changes | undefined,
+    hasWillSetRowCallbacks: () => boolean,
   ) =>
     (middleware = [
       willSetContent,
@@ -2058,6 +2138,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
       willDelValues,
       willDelValue,
       willApplyChanges,
+      hasWillSetRowCallbacks,
     ]);
 
   const setInternalListeners = (
diff --git a/test/unit/core/other/middleware.test.ts b/test/unit/core/other/middleware.test.ts
