[middleware] WillDelValuesCallback

Author: jamesgpearce

src/@types/middleware/docs.js

@@ -141,6 +141,21 @@
  * @since v8.0.0
  */
 /// WillDelValueCallback
+/**
+ * The WillDelValuesCallback type describes a function that is called before all
+ * Values are deleted from the Store.
+ *
+ * The callback takes no parameters. It returns `true` to allow the deletion, or
+ * `false` to prevent it.
+ *
+ * Multiple WillDelValuesCallback functions can be registered and they will be
+ * called sequentially. If any callback returns `false`, the chain
+ * short-circuits and the Values will not be deleted.
+ * @returns `true` to allow the deletion, `false` to prevent it.
+ * @category Callback
+ * @since v8.0.0
+ */
+/// WillDelValuesCallback
 /**
  * A Middleware object lets you intercept and validate writes to a Store.
  *
@@ -499,6 +514,39 @@
    * @since v8.0.0
    */
   /// Middleware.addWillDelValueCallback
+  /**
+   * The addWillDelValuesCallback method registers a WillDelValuesCallback that
+   * will be called before all Values 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 WillDelValuesCallback to register.
+   * @returns A reference to the Middleware object, for chaining.
+   * @example
+   * This example registers a callback that prevents deleting all Values from
+   * the pet store.
+   *
+   * ```js
+   * import {createMiddleware, createStore} from 'tinybase';
+   *
+   * const store = createStore();
+   * const middleware = createMiddleware(store);
+   *
+   * store.setValues({storeName: 'happy pets', limit: 50});
+   *
+   * middleware.addWillDelValuesCallback(() => false);
+   *
+   * store.delValues();
+   * console.log(store.getValues());
+   * // -> {storeName: 'happy pets', limit: 50}
+   *
+   * middleware.destroy();
+   * ```
+   * @category Configuration
+   * @since v8.0.0
+   */
+  /// Middleware.addWillDelValuesCallback
   /**
    * 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

@@ -47,6 +47,9 @@ export type WillDelRowCallback = (tableId: Id, rowId: Id) => boolean;
 /// WillDelValueCallback
 export type WillDelValueCallback = (valueId: Id) => boolean;
 
+/// WillDelValuesCallback
+export type WillDelValuesCallback = () => boolean;
+
 /// Middleware
 export interface Middleware {
   /// Middleware.getStore
@@ -73,6 +76,9 @@ export interface Middleware {
   /// Middleware.addWillDelValueCallback
   addWillDelValueCallback(callback: WillDelValueCallback): Middleware;
 
+  /// Middleware.addWillDelValuesCallback
+  addWillDelValuesCallback(callback: WillDelValuesCallback): Middleware;
+
   /// Middleware.destroy
   destroy(): void;
 }

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

@@ -102,6 +102,9 @@ export type WillDelValueCallback<
     : never,
 > = (...params: Params | [valueId: never]) => boolean;
 
+/// WillDelValuesCallback
+export type WillDelValuesCallback = () => boolean;
+
 /// Middleware
 export interface Middleware<in out Schemas extends OptionalSchemas> {
   /// Middleware.getStore
@@ -142,6 +145,11 @@ export interface Middleware<in out Schemas extends OptionalSchemas> {
     callback: WillDelValueCallback<Schemas[1]>,
   ): Middleware<Schemas>;
 
+  /// Middleware.addWillDelValuesCallback
+  addWillDelValuesCallback(
+    callback: WillDelValuesCallback,
+  ): Middleware<Schemas>;
+
   /// Middleware.destroy
   destroy(): void;
 }

src/middleware/index.ts

@@ -4,6 +4,7 @@ import type {
   WillDelCellCallback,
   WillDelRowCallback,
   WillDelValueCallback,
+  WillDelValuesCallback,
   WillSetCellCallback,
   WillSetRowCallback,
   WillSetValueCallback,
@@ -33,6 +34,7 @@ export const createMiddleware = getCreateFunction(
     const willDelCellCallbacks: WillDelCellCallback[] = [];
     const willDelRowCallbacks: WillDelRowCallback[] = [];
     const willDelValueCallbacks: WillDelValueCallback[] = [];
+    const willDelValuesCallbacks: WillDelValuesCallback[] = [];
 
     const willSetCell = (
       tableId: Id,
@@ -86,6 +88,9 @@ export const createMiddleware = getCreateFunction(
     const willDelValue = (valueId: Id): boolean =>
       arrayEvery(willDelValueCallbacks, (callback) => callback(valueId));
 
+    const willDelValues = (): boolean =>
+      arrayEvery(willDelValuesCallbacks, (callback) => callback());
+
     (store as any).setInternalWillSets(
       willSetCell,
       willSetValue,
@@ -94,6 +99,7 @@ export const createMiddleware = getCreateFunction(
       willSetRow,
       willSetValues,
       willDelRow,
+      willDelValues,
     );
 
     const getStore = (): Store => store;
@@ -129,6 +135,11 @@ export const createMiddleware = getCreateFunction(
       callback: WillDelValueCallback,
     ): Middleware => fluent(() => arrayPush(willDelValueCallbacks, callback));
 
+    const addWillDelValuesCallback = (
+      callback: WillDelValuesCallback,
+    ): Middleware =>
+      fluent(() => arrayPush(willDelValuesCallbacks, callback));
+
     const destroy = (): void => {};
 
     const middleware: Middleware = objFreeze({
@@ -140,6 +151,7 @@ export const createMiddleware = getCreateFunction(
       addWillDelCellCallback,
       addWillDelRowCallback,
       addWillDelValueCallback,
+      addWillDelValuesCallback,
       destroy,
     } as Middleware);
 

src/store/index.ts

@@ -175,6 +175,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetRow?: (tableId: Id, rowId: Id, row: Row) => Row | undefined,
     willSetValues?: (values: Values) => Values | undefined,
     willDelRow?: (tableId: Id, rowId: Id) => boolean,
+    willDelValues?: () => boolean,
   ] = [];
   let internalListeners: [
     preStartTransaction?: () => void,
@@ -1491,7 +1492,11 @@ export const createStore: typeof createStoreDecl = (): Store => {
     );
 
   const delValues = (): Store =>
-    fluentTransaction(() => setValidValues({}, true));
+    fluentTransaction(() =>
+      (internalWillSets[7]?.() ?? true)
+        ? setValidValues({}, true)
+        : 0,
+    );
 
   const delValue = (valueId: Id): Store =>
     fluentTransaction(
@@ -1777,6 +1782,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     willSetRow: (tableId: Id, rowId: Id, row: Row) => Row | undefined,
     willSetValues: (values: Values) => Values | undefined,
     willDelRow: (tableId: Id, rowId: Id) => boolean,
+    willDelValues: () => boolean,
   ) =>
     (internalWillSets = [
       willSetCell,
@@ -1786,6 +1792,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
       willSetRow,
       willSetValues,
       willDelRow,
+      willDelValues,
     ]);
 
   const setInternalListeners = (

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

@@ -1273,6 +1273,112 @@ describe('willDelValue', () => {
   });
 });
 
+describe('willDelValues', () => {
+  describe('allow', () => {
+    test('returning true allows delete', () => {
+      middleware.addWillDelValuesCallback(() => true);
+      store.setValues({v1: 'a', v2: 'b'});
+      store.delValues();
+      expect(store.getValues()).toEqual({});
+    });
+  });
+
+  describe('block', () => {
+    test('returning false blocks delete', () => {
+      middleware.addWillDelValuesCallback(() => false);
+      store.setValues({v1: 'a', v2: 'b'});
+      store.delValues();
+      expect(store.getValues()).toEqual({v1: 'a', v2: 'b'});
+    });
+  });
+
+  describe('chaining', () => {
+    test('all must return true to allow', () => {
+      middleware
+        .addWillDelValuesCallback(() => true)
+        .addWillDelValuesCallback(() => true);
+      store.setValues({v1: 'a'});
+      store.delValues();
+      expect(store.getValues()).toEqual({});
+    });
+
+    test('any returning false blocks', () => {
+      middleware
+        .addWillDelValuesCallback(() => true)
+        .addWillDelValuesCallback(() => false);
+      store.setValues({v1: 'a'});
+      store.delValues();
+      expect(store.getValues()).toEqual({v1: 'a'});
+    });
+
+    test('first blocks, second never called', () => {
+      const secondCalled = vi.fn();
+      middleware
+        .addWillDelValuesCallback(() => false)
+        .addWillDelValuesCallback(() => {
+          secondCalled();
+          return true;
+        });
+      store.setValues({v1: 'a'});
+      store.delValues();
+      expect(secondCalled).not.toHaveBeenCalled();
+      expect(store.getValues()).toEqual({v1: 'a'});
+    });
+  });
+
+  describe('entry points', () => {
+    test('called from delValues', () => {
+      const calls: number[] = [];
+      middleware.addWillDelValuesCallback(() => {
+        calls.push(1);
+        return true;
+      });
+      store.setValues({v1: 'a'});
+      store.delValues();
+      expect(calls).toEqual([1]);
+    });
+
+    test('not called from delValue', () => {
+      const calls: number[] = [];
+      middleware.addWillDelValuesCallback(() => {
+        calls.push(1);
+        return true;
+      });
+      store.setValues({v1: 'a', v2: 'b'});
+      store.delValue('v1');
+      expect(calls).toEqual([]);
+      expect(store.getValues()).toEqual({v2: 'b'});
+    });
+  });
+
+  describe('interaction with willDelValue', () => {
+    test('willDelValues blocks before willDelValue is called', () => {
+      const valueCalls = vi.fn();
+      middleware.addWillDelValuesCallback(() => false);
+      middleware.addWillDelValueCallback((...args) => {
+        valueCalls(...args);
+        return true;
+      });
+      store.setValues({v1: 'a', v2: 'b'});
+      store.delValues();
+      expect(valueCalls).not.toHaveBeenCalled();
+      expect(store.getValues()).toEqual({v1: 'a', v2: 'b'});
+    });
+
+    test('willDelValues allows, willDelValue still checked', () => {
+      const valueCalls: string[] = [];
+      middleware.addWillDelValuesCallback(() => true);
+      middleware.addWillDelValueCallback((valueId) => {
+        valueCalls.push(valueId);
+        return true;
+      });
+      store.setValues({v1: 'a', v2: 'b'});
+      store.delValues();
+      expect(valueCalls).toEqual(['v1', 'v2']);
+    });
+  });
+});
+
 describe('schema interaction', () => {
   describe('willSetCell not called for schema-rejected cells', () => {
     test('invalid cell type rejected before callback', () => {
@@ -1464,6 +1570,11 @@ describe('fluent API', () => {
     expect(result).toBe(middleware);
   });
 
+  test('addWillDelValuesCallback returns middleware', () => {
+    const result = middleware.addWillDelValuesCallback(() => true);
+    expect(result).toBe(middleware);
+  });
+
   test('full chained setup', () => {
     const result = middleware
       .addWillSetCellCallback((_tableId, _rowId, _cellId, cell) => cell)
@@ -1472,7 +1583,8 @@ describe('fluent API', () => {
       .addWillSetValuesCallback((values) => values)
       .addWillDelCellCallback(() => true)
       .addWillDelRowCallback(() => true)
-      .addWillDelValueCallback(() => true);
+      .addWillDelValueCallback(() => true)
+      .addWillDelValuesCallback(() => true);
     expect(result).toBe(middleware);
   });
 });

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

@@ -1094,6 +1094,8 @@ exports[`Types in middleware.ts > 187:4 1`] = `"This comparison appears to be un
 
 exports[`Types in middleware.ts > 199: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 > 211: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'."`;