[middleware] WillSetTableCallback

Author: jamesgpearce

src/@types/middleware/docs.js

@@ -32,6 +32,25 @@
  * @since v8.0.0
  */
 /// WillSetCellCallback
+/**
+ * The WillSetTableCallback type describes a function that is called before a
+ * Table is set in the Store.
+ *
+ * The callback receives the table Id and the Table object that is about to be
+ * set. It can return the Table (possibly transformed) to allow the write, or
+ * `undefined` to prevent the Table from being set.
+ *
+ * Multiple WillSetTableCallback functions can be registered and they will be
+ * called sequentially, the Table being updated successively. If any callback
+ * returns `undefined`, the chain short-circuits and the Table will not be set.
+ * @param tableId The Id of the Table being set.
+ * @param table The Table object about to be set.
+ * @returns The Table to use (possibly transformed), or `undefined` to prevent
+ * the write.
+ * @category Callback
+ * @since v8.0.0
+ */
+/// WillSetTableCallback
 /**
  * The WillSetRowCallback type describes a function that is called before a Row
  * is set in the Store.
@@ -259,6 +278,72 @@
    * @since v8.0.0
    */
   /// Middleware.addWillSetCellCallback
+  /**
+   * The addWillSetTableCallback method registers a WillSetTableCallback that
+   * will be called before any Table is set in the Store.
+   *
+   * The callback can transform the Table or return `undefined` to prevent the
+   * write. Multiple callbacks can be registered and they are called
+   * sequentially, each receiving the (possibly transformed) table from the
+   * previous callback.
+   * @param callback The WillSetTableCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that upper-cases string Cell values in
+   * rows set to the 'pets' table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTableCallback((tableId, table) =>
+   *   tableId === 'pets'
+   *     ? Object.fromEntries(
+   *         Object.entries(table).map(([rowId, row]) => [
+   *           rowId,
+   *           Object.fromEntries(
+   *             Object.entries(row).map(([k, v]) => [
+   *               k,
+   *               typeof v === 'string' ? v.toUpperCase() : v,
+   *             ]),
+   *           ),
+   *         ]),
+   *       )
+   *     : table,
+   * );
+   *
+   * store.setTable('pets', {fido: {species: 'dog'}, felix: {species: 'cat'}});
+   * console.log(store.getTable('pets'));
+   * // -> {fido: {species: 'DOG'}, felix: {species: 'CAT'}}
+   *
+   * middleware.destroy();
+   * ```
+   * @example
+   * This example registers a callback that prevents writes to the 'species'
+   * table.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * middleware.addWillSetTableCallback((tableId, table) =>
+   *   tableId === 'species' ? undefined : table,
+   * );
+   *
+   * store.setTable('species', {dog: {legs: 4, sound: 'woof'}});
+   * console.log(store.getTables());
+   * // -> {}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  /// Middleware.addWillSetTableCallback
   /**
    * The addWillSetRowCallback method registers a WillSetRowCallback that will
    * be called before any Row is set in the Store.

src/@types/middleware/index.d.ts

@@ -5,6 +5,7 @@ import type {
   CellOrUndefined,
   Row,
   Store,
+  Table,
   Value,
   ValueOrUndefined,
   Values,
@@ -18,6 +19,12 @@ export type WillSetCellCallback = (
   cell: Cell,
 ) => CellOrUndefined;
 
+/// WillSetTableCallback
+export type WillSetTableCallback = (
+  tableId: Id,
+  table: Table,
+) => Table | undefined;
+
 /// WillSetRowCallback
 export type WillSetRowCallback = (
   tableId: Id,
@@ -58,6 +65,9 @@ export interface Middleware {
   /// Middleware.addWillSetCellCallback
   addWillSetCellCallback(callback: WillSetCellCallback): Middleware;
 
+  /// Middleware.addWillSetTableCallback
+  addWillSetTableCallback(callback: WillSetTableCallback): Middleware;
+
   /// Middleware.addWillSetRowCallback
   addWillSetRowCallback(callback: WillSetRowCallback): Middleware;
 

src/@types/middleware/with-schemas/index.d.ts

@@ -12,6 +12,7 @@ import type {
   OptionalValuesSchema,
   Row,
   Store,
+  Table,
   Value,
   Values,
 } from '../../store/with-schemas/index.d.ts';
@@ -37,6 +38,18 @@ export type WillSetCellCallback<
   ...params: Params | [tableId: never, rowId: never, cellId: never, cell: never]
 ) => Params[3] | undefined;
 
+/// WillSetTableCallback
+export type WillSetTableCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId, table: Table<Schema, TableId>]
+      : never
+    : never,
+> = (
+  ...params: Params | [tableId: never, table: never]
+) => Params[1] | undefined;
+
 /// WillSetRowCallback
 export type WillSetRowCallback<
   Schema extends OptionalTablesSchema,
@@ -115,6 +128,11 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
     callback: WillSetCellCallback<Schemas[0]>,
   ): Middleware<Schemas>;
 
+  /// Middleware.addWillSetTableCallback
+  addWillSetTableCallback(
+    callback: WillSetTableCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
   /// Middleware.addWillSetRowCallback
   addWillSetRowCallback(
     callback: WillSetRowCallback<Schemas[0]>,

src/middleware/index.ts

@@ -7,6 +7,7 @@ import type {
   WillDelValuesCallback,
   WillSetCellCallback,
   WillSetRowCallback,
+  WillSetTableCallback,
   WillSetValueCallback,
   WillSetValuesCallback,
   createMiddleware as createMiddlewareDecl,
@@ -16,6 +17,7 @@ import type {
   CellOrUndefined,
   Row,
   Store,
+  Table,
   Value,
   ValueOrUndefined,
   Values,
@@ -28,6 +30,7 @@ import {isUndefined} from '../common/other.ts';
 export const createMiddleware = getCreateFunction(
   (store: Store): Middleware => {
     const willSetCellCallbacks: WillSetCellCallback[] = [];
+    const willSetTableCallbacks: WillSetTableCallback[] = [];
     const willSetRowCallbacks: WillSetRowCallback[] = [];
     const willSetValueCallbacks: WillSetValueCallback[] = [];
     const willSetValuesCallbacks: WillSetValuesCallback[] = [];
@@ -61,6 +64,19 @@ export const createMiddleware = getCreateFunction(
         row as Row | undefined,
       );
 
+    const willSetTable = (
+      tableId: Id,
+      table: Table,
+    ): Table | undefined =>
+      arrayReduce(
+        willSetTableCallbacks,
+        (current, callback) =>
+          isUndefined(current)
+            ? current
+            : callback(tableId, current as Table),
+        table as Table | undefined,
+      );
+
     const willSetValue = (valueId: Id, value: Value): ValueOrUndefined =>
       arrayReduce(
         willSetValueCallbacks,
@@ -100,6 +116,7 @@ export const createMiddleware = getCreateFunction(
       willSetValues,
       willDelRow,
       willDelValues,
+      willSetTable,
     );
 
     const getStore = (): Store => store;
@@ -116,6 +133,11 @@ export const createMiddleware = getCreateFunction(
     const addWillSetRowCallback = (callback: WillSetRowCallback): Middleware =>
       fluent(() => arrayPush(willSetRowCallbacks, callback));
 
+    const addWillSetTableCallback = (
+      callback: WillSetTableCallback,
+    ): Middleware =>
+      fluent(() => arrayPush(willSetTableCallbacks, callback));
+
     const addWillSetValueCallback = (
       callback: WillSetValueCallback,
     ): Middleware => fluent(() => arrayPush(willSetValueCallbacks, callback));
@@ -145,6 +167,7 @@ export const createMiddleware = getCreateFunction(
     const middleware: Middleware = objFreeze({
       getStore,
       addWillSetCellCallback,
+      addWillSetTableCallback,
       addWillSetRowCallback,
       addWillSetValueCallback,
       addWillSetValuesCallback,

src/store/index.ts

@@ -176,6 +176,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetValues?: (values: Values) => Values | undefined,
     willDelRow?: (tableId: Id, rowId: Id) => boolean,
     willDelValues?: () => boolean,
+    willSetTable?: (tableId: Id, table: Table) => Table | undefined,
   ] = [];
   let internalListeners: [
     preStartTransaction?: () => void,
@@ -471,18 +472,34 @@ export const createStore: typeof createStoreDecl = (): Store => {
       (_tables, tableId) => delValidTable(tableId),
     );
 
-  const setValidTable = (tableId: Id, table: Table): TableMap =>
-    mapMatch(
-      mapEnsure(tablesMap, tableId, () => {
-        tableIdsChanged(tableId, 1);
-        mapSet(tablePoolFunctions, tableId, getPoolFunctions());
-        mapSet(tableCellIds, tableId, mapNew());
-        return mapNew();
-      }),
-      table,
-      (tableMap, rowId, row) => setValidRow(tableId, tableMap, rowId, row),
-      (tableMap, rowId) => delValidRow(tableId, tableMap, rowId),
-    );
+  const setValidTable = (
+    tableId: Id,
+    table: Table,
+    forceDel?: boolean,
+  ): TableMap =>
+    ifNotUndefined(
+      forceDel
+        ? table
+        : ifNotUndefined(
+            internalWillSets[8],
+            (willSetTable) => willSetTable(tableId, table),
+            () => table,
+          ),
+      (validTable) =>
+        mapMatch(
+          mapEnsure(tablesMap, tableId, () => {
+            tableIdsChanged(tableId, 1);
+            mapSet(tablePoolFunctions, tableId, getPoolFunctions());
+            mapSet(tableCellIds, tableId, mapNew());
+            return mapNew();
+          }),
+          validTable,
+          (tableMap, rowId, row) =>
+            setValidRow(tableId, tableMap, rowId, row),
+          (tableMap, rowId) =>
+            delValidRow(tableId, tableMap, rowId),
+        ),
+    ) as TableMap;
 
   const setValidRow = (
     tableId: Id,
@@ -612,7 +629,8 @@ export const createStore: typeof createStoreDecl = (): Store => {
   const getOrCreateTable = (tableId: Id) =>
     mapGet(tablesMap, tableId) ?? setValidTable(tableId, {});
 
-  const delValidTable = (tableId: Id): TableMap => setValidTable(tableId, {});
+  const delValidTable = (tableId: Id): TableMap =>
+    setValidTable(tableId, {}, true);
 
   const delValidRow = (tableId: Id, tableMap: TableMap, rowId: Id): void => {
     if (internalWillSets[6]?.(tableId, rowId) ?? true) {
@@ -1783,6 +1801,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetValues: (values: Values) => Values | undefined,
     willDelRow: (tableId: Id, rowId: Id) => boolean,
     willDelValues: () => boolean,
+    willSetTable: (tableId: Id, table: Table) => Table | undefined,
   ) =>
     (internalWillSets = [
       willSetCell,
@@ -1793,6 +1812,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
       willSetValues,
       willDelRow,
       willDelValues,
+      willSetTable,
     ]);
 
   const setInternalListeners = (