[middleware] WillDelTablesCallback

Author: jamesgpearce

src/@types/middleware/docs.js

@@ -210,6 +210,21 @@
  * @since v8.0.0
  */
 /// WillDelValuesCallback
+/**
+ * The WillDelTablesCallback type describes a function that is called before all
+ * Tables are deleted from the Store.
+ *
+ * The callback takes no parameters. It returns `true` to allow the deletion, or
+ * `false` to prevent it.
+ *
+ * Multiple WillDelTablesCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Tables will not be deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+/// WillDelTablesCallback
 /**
  * A Middleware object lets you intercept and validate writes to a Store.
  *
@@ -769,6 +784,39 @@
    * @since v8.0.0
    */
   /// Middleware.addWillDelValuesCallback
+  /**
+   * The addWillDelTablesCallback method registers a WillDelTablesCallback that
+   * will be called before all Tables are 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 WillDelTablesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting all Tables from
+   * the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setTables({pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}});
+   *
+   * middleware.addWillDelTablesCallback(() => false);
+   *
+   * store.delTables();
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  /// Middleware.addWillDelTablesCallback
   /**
    * The destroy method should be called when this Middleware object is no
    * longer used. It removes all hooks and listeners from the Store, and

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

@@ -61,6 +61,9 @@ export type WillDelRowCallback = (tableId: Id, rowId: Id) => boolean;
 /// WillDelValueCallback
 export type WillDelValueCallback = (valueId: Id) => boolean;
 
+/// WillDelTablesCallback
+export type WillDelTablesCallback = () => boolean;
+
 /// WillDelValuesCallback
 export type WillDelValuesCallback = () => boolean;
 
@@ -99,6 +102,9 @@ export interface Middleware {
   /// Middleware.addWillDelValueCallback
   addWillDelValueCallback(callback: WillDelValueCallback): Middleware;
 
+  /// Middleware.addWillDelTablesCallback
+  addWillDelTablesCallback(callback: WillDelTablesCallback): Middleware;
+
   /// Middleware.addWillDelValuesCallback
   addWillDelValuesCallback(callback: WillDelValuesCallback): Middleware;
 

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

@@ -133,6 +133,9 @@ export type WillDelValueCallback<
     : never,
 > = (...params: Params | [valueId: never]) => boolean;
 
+/// WillDelTablesCallback
+export type WillDelTablesCallback = () => boolean;
+
 /// WillDelValuesCallback
 export type WillDelValuesCallback = () => boolean;
 
@@ -191,6 +194,11 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
     callback: WillDelValueCallback<Schemas[1]>,
   ): Middleware<Schemas>;
 
+  /// Middleware.addWillDelTablesCallback
+  addWillDelTablesCallback(
+    callback: WillDelTablesCallback,
+  ): Middleware<Schemas>;
+
   /// Middleware.addWillDelValuesCallback
   addWillDelValuesCallback(
     callback: WillDelValuesCallback,

src/middleware/index.ts

@@ -5,6 +5,7 @@ import type {
   WillDelRowCallback,
   WillDelTableCallback,
   WillDelValueCallback,
+  WillDelTablesCallback,
   WillDelValuesCallback,
   WillSetCellCallback,
   WillSetRowCallback,
@@ -40,6 +41,7 @@ export const createMiddleware = getCreateFunction(
     const willSetValuesCallbacks: WillSetValuesCallback[] = [];
     const willDelCellCallbacks: WillDelCellCallback[] = [];
     const willDelTableCallbacks: WillDelTableCallback[] = [];
+    const willDelTablesCallbacks: WillDelTablesCallback[] = [];
     const willDelRowCallbacks: WillDelRowCallback[] = [];
     const willDelValueCallbacks: WillDelValueCallback[] = [];
     const willDelValuesCallbacks: WillDelValuesCallback[] = [];
@@ -122,6 +124,9 @@ export const createMiddleware = getCreateFunction(
     const willDelValue = (valueId: Id): boolean =>
       arrayEvery(willDelValueCallbacks, (callback) => callback(valueId));
 
+    const willDelTables = (): boolean =>
+      arrayEvery(willDelTablesCallbacks, (callback) => callback());
+
     const willDelValues = (): boolean =>
       arrayEvery(willDelValuesCallbacks, (callback) => callback());
 
@@ -137,6 +142,7 @@ export const createMiddleware = getCreateFunction(
       willSetTable,
       willDelTable,
       willSetTables,
+      willDelTables,
     );
 
     const getStore = (): Store => store;
@@ -183,6 +189,11 @@ export const createMiddleware = getCreateFunction(
     ): Middleware =>
       fluent(() => arrayPush(willDelTableCallbacks, callback));
 
+    const addWillDelTablesCallback = (
+      callback: WillDelTablesCallback,
+    ): Middleware =>
+      fluent(() => arrayPush(willDelTablesCallbacks, callback));
+
     const addWillDelValueCallback = (
       callback: WillDelValueCallback,
     ): Middleware => fluent(() => arrayPush(willDelValueCallbacks, callback));
@@ -204,6 +215,7 @@ export const createMiddleware = getCreateFunction(
       addWillSetValuesCallback,
       addWillDelCellCallback,
       addWillDelTableCallback,
+      addWillDelTablesCallback,
       addWillDelRowCallback,
       addWillDelValueCallback,
       addWillDelValuesCallback,

src/store/index.ts

@@ -179,6 +179,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetTable?: (tableId: Id, table: Table) => Table | undefined,
     willDelTable?: (tableId: Id) => boolean,
     willSetTables?: (tables: Tables) => Tables | undefined,
+    willDelTables?: () => boolean,
   ] = [];
   let internalListeners: [
     preStartTransaction?: () => void,
@@ -1489,7 +1490,12 @@ export const createStore: typeof createStoreDecl = (): Store => {
     });
 
   const delTables = (): Store =>
-    fluentTransaction(() => setValidTables({}, true));
+    fluentTransaction(
+      () =>
+        (internalWillSets[11]?.() ?? true)
+          ? setValidTables({}, true)
+          : 0,
+    );
 
   const delTable = (tableId: Id): Store =>
     fluentTransaction(
@@ -1822,6 +1828,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetTable: (tableId: Id, table: Table) => Table | undefined,
     willDelTable: (tableId: Id) => boolean,
     willSetTables: (tables: Tables) => Tables | undefined,
+    willDelTables: () => boolean,
   ) =>
     (internalWillSets = [
       willSetCell,
@@ -1835,6 +1842,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
       willSetTable,
       willDelTable,
       willSetTables,
+      willDelTables,
     ]);
 
   const setInternalListeners = (

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

@@ -1851,6 +1851,130 @@ describe('willDelTable', () => {
   });
 });
 
+describe('willDelTables', () => {
+  describe('allow', () => {
+    test('returning true allows delete', () => {
+      middleware.addWillDelTablesCallback(() => true);
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTables();
+      expect(store.getTables()).toEqual({});
+    });
+  });
+
+  describe('block', () => {
+    test('returning false blocks delete', () => {
+      middleware.addWillDelTablesCallback(() => 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'}},
+      });
+    });
+  });
+
+  describe('chaining', () => {
+    test('all must return true to allow', () => {
+      middleware
+        .addWillDelTablesCallback(() => true)
+        .addWillDelTablesCallback(() => true);
+      store.setTables({t1: {r1: {c1: 'a'}}});
+      store.delTables();
+      expect(store.getTables()).toEqual({});
+    });
+
+    test('any returning false blocks', () => {
+      middleware
+        .addWillDelTablesCallback(() => true)
+        .addWillDelTablesCallback(() => false);
+      store.setTables({t1: {r1: {c1: 'a'}}});
+      store.delTables();
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'a'}}});
+    });
+
+    test('first blocks, second never called', () => {
+      const secondCalled = vi.fn();
+      middleware
+        .addWillDelTablesCallback(() => false)
+        .addWillDelTablesCallback(() => {
+          secondCalled();
+          return true;
+        });
+      store.setTables({t1: {r1: {c1: 'a'}}});
+      store.delTables();
+      expect(secondCalled).not.toHaveBeenCalled();
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'a'}}});
+    });
+  });
+
+  describe('entry points', () => {
+    test('called from delTables', () => {
+      const calls: number[] = [];
+      middleware.addWillDelTablesCallback(() => {
+        calls.push(1);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}});
+      store.delTables();
+      expect(calls).toEqual([1]);
+    });
+
+    test('not called from delTable', () => {
+      const calls: number[] = [];
+      middleware.addWillDelTablesCallback(() => {
+        calls.push(1);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTable('t1');
+      expect(calls).toEqual([]);
+      expect(store.getTables()).toEqual({t2: {r1: {c1: 'b'}}});
+    });
+
+    test('not called from setTables', () => {
+      const calls: number[] = [];
+      middleware.addWillDelTablesCallback(() => {
+        calls.push(1);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}});
+      calls.length = 0;
+      store.setTables({t2: {r1: {c1: 'b'}}});
+      expect(calls).toEqual([]);
+    });
+  });
+
+  describe('interaction with willDelTable', () => {
+    test('willDelTables blocks before willDelTable is called', () => {
+      const tableCalls = vi.fn();
+      middleware.addWillDelTablesCallback(() => false);
+      middleware.addWillDelTableCallback((...args) => {
+        tableCalls(...args);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTables();
+      expect(tableCalls).not.toHaveBeenCalled();
+      expect(store.getTables()).toEqual({
+        t1: {r1: {c1: 'a'}},
+        t2: {r1: {c1: 'b'}},
+      });
+    });
+
+    test('willDelTables allows, willDelTable still checked', () => {
+      const tableCalls: string[] = [];
+      middleware.addWillDelTablesCallback(() => true);
+      middleware.addWillDelTableCallback((tableId) => {
+        tableCalls.push(tableId);
+        return true;
+      });
+      store.setTables({t1: {r1: {c1: 'a'}}, t2: {r1: {c1: 'b'}}});
+      store.delTables();
+      expect(tableCalls).toEqual(['t1', 't2']);
+    });
+  });
+});
+
 describe('willDelValue', () => {
   describe('allow', () => {
     test('returning true allows delete', () => {

test/unit/core/types/__snapshots__/types.test.tsx.snap

@@ -1066,12 +1066,14 @@ exports[`Types in middleware.ts > 237:4 1`] = `"This comparison appears to be un
 
 exports[`Types in middleware.ts > 249:17 1`] = `"Property 't2' does not exist on type 'Tables<{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, false>'."`;
 
-exports[`Types in middleware.ts > 258:4 1`] = `"This comparison appears to be unintentional because the types '"v1" | "v1d"' and '"v2"' have no overlap."`;
+exports[`Types in middleware.ts > 261:17 1`] = `"Property 't2' does not exist on type 'Tables<{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, false>'."`;
 
-exports[`Types in middleware.ts > 270:17 1`] = `"Property 't2' does not exist on type 'Tables<{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, false>'."`;
+exports[`Types in middleware.ts > 270:4 1`] = `"This comparison appears to be unintentional because the types '"v1" | "v1d"' and '"v2"' have no overlap."`;
 
 exports[`Types in middleware.ts > 282:17 1`] = `"Property 't2' does not exist on type 'Tables<{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, false>'."`;
 
+exports[`Types in middleware.ts > 294:17 1`] = `"Property 't2' does not exist on type 'Tables<{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, false>'."`;
+
 exports[`Types in persisters.ts > 24:37 1`] = `"Argument of type '[{ t1: { r1: { c2: number; }; }; }, {}]' is not assignable to parameter of type 'Content<[{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, { ...; }], true> | (() => Content<...>) | undefined'."`;
 
 exports[`Types in persisters.ts > 25:25 1`] = `"Argument of type '[{ t1: { r1: { c1: string; }; }; }, {}]' is not assignable to parameter of type 'Content<[{ readonly t0: { readonly c0: { readonly type: "number"; }; }; readonly t1: { readonly c1: { readonly type: "number"; }; readonly c1d: { readonly type: "string"; readonly default: ""; }; }; }, { ...; }], true> | (() => Content<...>) | undefined'."`;

test/unit/core/types/middleware.ts

@@ -92,9 +92,7 @@ middlewareWithSchema.getStore().getTables().t2; // !
     return _table;
   });
 
-  middlewareWithSchema.addWillSetTableCallback(
-    (_tableId, table) => table,
-  );
+  middlewareWithSchema.addWillSetTableCallback((_tableId, table) => table);
   middlewareWithSchema.addWillSetTableCallback(() => undefined);
 
   middlewareWithSchema
@@ -250,6 +248,18 @@ middlewareWithSchema.getStore().getTables().t2; // !
     .getTables().t2; // !
 };
 
+// addWillDelTablesCallback
+() => {
+  middlewareWithSchema
+    .addWillDelTablesCallback(() => true)
+    .getStore()
+    .getTables().t1;
+  middlewareWithSchema
+    .addWillDelTablesCallback(() => true)
+    .getStore()
+    .getTables().t2; // !
+};
+
 // addWillDelValueCallback
 () => {
   middlewareWithSchema.addWillDelValueCallback((valueId) => {