[middleware] WillDelTableCallback

Author: jamesgpearce

src/@types/middleware/docs.js

@@ -127,6 +127,22 @@
  * @since v8.0.0
  */
 /// WillDelCellCallback
+/**
+ * The WillDelTableCallback type describes a function that is called before a
+ * Table is deleted from the Store.
+ *
+ * The callback receives the table Id of the Table about to be deleted. It
+ * returns `true` to allow the deletion, or `false` to prevent it.
+ *
+ * Multiple WillDelTableCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Table will not be deleted.
+ * @param tableId The Id of the Table being deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+/// WillDelTableCallback
 /**
  * The WillDelRowCallback type describes a function that is called before a
  * Row is deleted from the Store.
@@ -533,6 +549,39 @@
    * @since v8.0.0
    */
   /// Middleware.addWillDelCellCallback
+  /**
+   * The addWillDelTableCallback method registers a WillDelTableCallback that
+   * will be called before any Table is deleted from the Store.
+   *
+   * The callback returns `true` to allow the deletion or `false` to prevent
+   * it. Multiple callbacks can be registered and they are called sequentially.
+   * If any callback returns `false`, the deletion is prevented.
+   * @param callback The WillDelTableCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting the 'pets' table
+   * from the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setTable('pets', {fido: {species: 'dog'}, felix: {species: 'cat'}});
+   *
+   * middleware.addWillDelTableCallback((tableId) => tableId !== 'pets');
+   *
+   * store.delTable('pets');
+   * console.log(store.getTable('pets'));
+   * // -> {fido: {species: 'dog'}, felix: {species: 'cat'}}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  /// Middleware.addWillDelTableCallback
   /**
    * The addWillDelRowCallback method registers a WillDelRowCallback that will
    * be called before any Row is deleted from the Store.

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

@@ -48,6 +48,9 @@ export type WillDelCellCallback = (
   cellId: Id,
 ) => boolean;
 
+/// WillDelTableCallback
+export type WillDelTableCallback = (tableId: Id) => boolean;
+
 /// WillDelRowCallback
 export type WillDelRowCallback = (tableId: Id, rowId: Id) => boolean;
 
@@ -80,6 +83,9 @@ export interface Middleware {
   /// Middleware.addWillDelCellCallback
   addWillDelCellCallback(callback: WillDelCellCallback): Middleware;
 
+  /// Middleware.addWillDelTableCallback
+  addWillDelTableCallback(callback: WillDelTableCallback): Middleware;
+
   /// Middleware.addWillDelRowCallback
   addWillDelRowCallback(callback: WillDelRowCallback): Middleware;
 

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

@@ -95,6 +95,16 @@ export type WillDelCellCallback<
   ...params: Params | [tableId: never, rowId: never, cellId: never]
 ) => boolean;
 
+/// WillDelTableCallback
+export type WillDelTableCallback<
+  Schema extends OptionalTablesSchema,
+  Params extends any[] = TableIdFromSchema<Schema> extends infer TableId
+    ? TableId extends TableIdFromSchema<Schema>
+      ? [tableId: TableId]
+      : never
+    : never,
+> = (...params: Params | [tableId: never]) => boolean;
+
 /// WillDelRowCallback
 export type WillDelRowCallback<
   Schema extends OptionalTablesSchema,
@@ -153,6 +163,11 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
     callback: WillDelCellCallback<Schemas[0]>,
   ): Middleware<Schemas>;
 
+  /// Middleware.addWillDelTableCallback
+  addWillDelTableCallback(
+    callback: WillDelTableCallback<Schemas[0]>,
+  ): Middleware<Schemas>;
+
   /// Middleware.addWillDelRowCallback
   addWillDelRowCallback(
     callback: WillDelRowCallback<Schemas[0]>,

src/middleware/index.ts

@@ -3,6 +3,7 @@ import type {
   Middleware,
   WillDelCellCallback,
   WillDelRowCallback,
+  WillDelTableCallback,
   WillDelValueCallback,
   WillDelValuesCallback,
   WillSetCellCallback,
@@ -35,6 +36,7 @@ export const createMiddleware = getCreateFunction(
     const willSetValueCallbacks: WillSetValueCallback[] = [];
     const willSetValuesCallbacks: WillSetValuesCallback[] = [];
     const willDelCellCallbacks: WillDelCellCallback[] = [];
+    const willDelTableCallbacks: WillDelTableCallback[] = [];
     const willDelRowCallbacks: WillDelRowCallback[] = [];
     const willDelValueCallbacks: WillDelValueCallback[] = [];
     const willDelValuesCallbacks: WillDelValuesCallback[] = [];
@@ -101,6 +103,9 @@ export const createMiddleware = getCreateFunction(
     const willDelRow = (tableId: Id, rowId: Id): boolean =>
       arrayEvery(willDelRowCallbacks, (callback) => callback(tableId, rowId));
 
+    const willDelTable = (tableId: Id): boolean =>
+      arrayEvery(willDelTableCallbacks, (callback) => callback(tableId));
+
     const willDelValue = (valueId: Id): boolean =>
       arrayEvery(willDelValueCallbacks, (callback) => callback(valueId));
 
@@ -117,6 +122,7 @@ export const createMiddleware = getCreateFunction(
       willDelRow,
       willDelValues,
       willSetTable,
+      willDelTable,
     );
 
     const getStore = (): Store => store;
@@ -153,6 +159,11 @@ export const createMiddleware = getCreateFunction(
     const addWillDelRowCallback = (callback: WillDelRowCallback): Middleware =>
       fluent(() => arrayPush(willDelRowCallbacks, callback));
 
+    const addWillDelTableCallback = (
+      callback: WillDelTableCallback,
+    ): Middleware =>
+      fluent(() => arrayPush(willDelTableCallbacks, callback));
+
     const addWillDelValueCallback = (
       callback: WillDelValueCallback,
     ): Middleware => fluent(() => arrayPush(willDelValueCallbacks, callback));
@@ -172,6 +183,7 @@ export const createMiddleware = getCreateFunction(
       addWillSetValueCallback,
       addWillSetValuesCallback,
       addWillDelCellCallback,
+      addWillDelTableCallback,
       addWillDelRowCallback,
       addWillDelValueCallback,
       addWillDelValuesCallback,

src/store/index.ts

@@ -177,6 +177,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willDelRow?: (tableId: Id, rowId: Id) => boolean,
     willDelValues?: () => boolean,
     willSetTable?: (tableId: Id, table: Table) => Table | undefined,
+    willDelTable?: (tableId: Id) => boolean,
   ] = [];
   let internalListeners: [
     preStartTransaction?: () => void,
@@ -629,8 +630,12 @@ export const createStore: typeof createStoreDecl = (): Store => {
   const getOrCreateTable = (tableId: Id) =>
     mapGet(tablesMap, tableId) ?? setValidTable(tableId, {});
 
-  const delValidTable = (tableId: Id): TableMap =>
-    setValidTable(tableId, {}, true);
+  const delValidTable = (tableId: Id): TableMap => {
+    if (internalWillSets[9]?.(tableId) ?? true) {
+      return setValidTable(tableId, {}, true);
+    }
+    return mapGet(tablesMap, tableId) as TableMap;
+  };
 
   const delValidRow = (tableId: Id, tableMap: TableMap, rowId: Id): void => {
     if (internalWillSets[6]?.(tableId, rowId) ?? true) {
@@ -1802,6 +1807,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willDelRow: (tableId: Id, rowId: Id) => boolean,
     willDelValues: () => boolean,
     willSetTable: (tableId: Id, table: Table) => Table | undefined,
+    willDelTable: (tableId: Id) => boolean,
   ) =>
     (internalWillSets = [
       willSetCell,
@@ -1813,6 +1819,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
       willDelRow,
       willDelValues,
       willSetTable,
+      willDelTable,
     ]);
 
   const setInternalListeners = (

test/unit/core/other/middleware.test.ts

@@ -1408,6 +1408,173 @@ describe('willDelRow', () => {
   });
 });
 
+describe('willDelTable', () => {
+  describe('allow', () => {
+    test('returning true allows delete', () => {
+      middleware.addWillDelTableCallback(() => true);
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(store.getTable('t1')).toEqual({});
+      expect(store.getTables()).toEqual({});
+    });
+  });
+
+  describe('block', () => {
+    test('returning false blocks delete', () => {
+      middleware.addWillDelTableCallback(() => false);
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(store.getTable('t1')).toEqual({r1: {c1: 'a'}});
+    });
+
+    test('conditionally blocks', () => {
+      middleware.addWillDelTableCallback((tableId) => {
+        return tableId !== 'protected';
+      });
+      store.setTables({
+        t1: {r1: {c1: 'a'}},
+        protected: {r1: {c1: 'b'}},
+      });
+      store.delTable('t1');
+      store.delTable('protected');
+      expect(store.getTable('t1')).toEqual({});
+      expect(store.getTable('protected')).toEqual({r1: {c1: 'b'}});
+    });
+  });
+
+  describe('chaining', () => {
+    test('all must return true to allow', () => {
+      middleware
+        .addWillDelTableCallback(() => true)
+        .addWillDelTableCallback(() => true);
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(store.getTables()).toEqual({});
+    });
+
+    test('any returning false blocks', () => {
+      middleware
+        .addWillDelTableCallback(() => true)
+        .addWillDelTableCallback(() => false);
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(store.getTable('t1')).toEqual({r1: {c1: 'a'}});
+    });
+
+    test('first blocks, second never called', () => {
+      const secondCalled = vi.fn();
+      middleware
+        .addWillDelTableCallback(() => false)
+        .addWillDelTableCallback((...args) => {
+          secondCalled(...args);
+          return true;
+        });
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(secondCalled).not.toHaveBeenCalled();
+      expect(store.getTable('t1')).toEqual({r1: {c1: 'a'}});
+    });
+  });
+
+  describe('entry points', () => {
+    test('called from delTable', () => {
+      const calls: string[] = [];
+      middleware.addWillDelTableCallback((tableId) => {
+        calls.push(tableId);
+        return true;
+      });
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(calls).toEqual(['t1']);
+    });
+
+    test('called from delTables', () => {
+      const calls: string[] = [];
+      middleware.addWillDelTableCallback((tableId) => {
+        calls.push(tableId);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTables();
+      expect(calls).toEqual(['t1', 't2']);
+    });
+
+    test('not called from delRow', () => {
+      const calls: string[] = [];
+      middleware.addWillDelTableCallback((tableId) => {
+        calls.push(tableId);
+        return true;
+      });
+      store.setTable('t1', {r1: {c1: 'a'}, r2: {c1: 'b'}});
+      store.delRow('t1', 'r1');
+      expect(calls).toEqual([]);
+      expect(store.getTable('t1')).toEqual({r2: {c1: 'b'}});
+    });
+
+    test('block from delTables prevents table deletion', () => {
+      middleware.addWillDelTableCallback(() => false);
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTables();
+      expect(store.getTables()).toEqual({
+        t1: {r1: {c1: 'a'}},
+        t2: {r1: {c1: 'b'}},
+      });
+    });
+
+    test('called when setTables replaces existing tables', () => {
+      const delCalls: string[] = [];
+      middleware.addWillDelTableCallback((tableId) => {
+        delCalls.push(tableId);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      delCalls.length = 0;
+      store.setTables({t1: {r1: {c1: 'A'}}});
+      // t2 should be deleted
+      expect(delCalls).toEqual(['t2']);
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'A'}}});
+    });
+
+    test('block prevents removal of old tables during setTables', () => {
+      middleware.addWillDelTableCallback(() => false);
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.setTables({t1: {r1: {c1: 'A'}}});
+      // t2 should be preserved because delete was blocked
+      expect(store.getTables()).toEqual({
+        t1: {r1: {c1: 'A'}},
+        t2: {r1: {c1: 'b'}},
+      });
+    });
+  });
+
+  describe('interaction with willDelRow', () => {
+    test('willDelTable blocks before willDelRow is called', () => {
+      const rowCalls = vi.fn();
+      middleware.addWillDelTableCallback(() => false);
+      middleware.addWillDelRowCallback((...args) => {
+        rowCalls(...args);
+        return true;
+      });
+      store.setTable('t1', {r1: {c1: 'a'}});
+      store.delTable('t1');
+      expect(rowCalls).not.toHaveBeenCalled();
+      expect(store.getTable('t1')).toEqual({r1: {c1: 'a'}});
+    });
+
+    test('willDelTable allows, willDelRow still checked', () => {
+      const rowCalls: string[] = [];
+      middleware.addWillDelTableCallback(() => true);
+      middleware.addWillDelRowCallback((tableId, rowId) => {
+        rowCalls.push(`${tableId}/${rowId}`);
+        return true;
+      });
+      store.setTable('t1', {r1: {c1: 'a'}, r2: {c1: 'b'}});
+      store.delTable('t1');
+      expect(rowCalls).toEqual(['t1/r1', 't1/r2']);
+    });
+  });
+});
+
 describe('willDelValue', () => {
   describe('allow', () => {
     test('returning true allows delete', () => {
@@ -1825,6 +1992,11 @@ describe('fluent API', () => {
     expect(result).toBe(middleware);
   });
 
+  test('addWillDelTableCallback returns middleware', () => {
+    const result = middleware.addWillDelTableCallback(() => true);
+    expect(result).toBe(middleware);
+  });
+
   test('addWillDelValueCallback returns middleware', () => {
     const result = middleware.addWillDelValueCallback(() => true);
     expect(result).toBe(middleware);
@@ -1843,6 +2015,7 @@ describe('fluent API', () => {
       .addWillSetValueCallback((_valueId, value) => value)
       .addWillSetValuesCallback((values) => values)
       .addWillDelCellCallback(() => true)
+      .addWillDelTableCallback(() => true)
       .addWillDelRowCallback(() => true)
       .addWillDelValueCallback(() => true)
       .addWillDelValuesCallback(() => true);