feat: add onDisposeValue

Author: crimx

src/readable.ts

@@ -143,6 +143,11 @@ export class ReadableImpl<TValue = any> implements BatchTask {
    */
   private _weakRefSelf_?: WeakRef<ReadableImpl<TValue>>;
 
+  /**
+   * @internal
+   */
+  private _onDisposeValue_?: (oldValue: TValue) => void;
+
   public constructor(
     resolveValue: (self: ReadableImpl<TValue>) => TValue,
     config?: Config<TValue>,
@@ -152,6 +157,7 @@ export class ReadableImpl<TValue = any> implements BatchTask {
     this.equal_ = (config?.equal ?? strictEqual) || undefined;
     this.name = config?.name;
     this.deps_ = deps;
+    this._onDisposeValue_ = config?.onDisposeValue;
   }
 
   /** @internal */
@@ -192,6 +198,9 @@ export class ReadableImpl<TValue = any> implements BatchTask {
       }
       this.deps_.clear();
     }
+    if (this._onDisposeValue_ && !strictEqual(this._value_, UNIQUE_VALUE)) {
+      this._onDisposeValue_(this._value_);
+    }
   }
 
   public get(): TValue {
@@ -212,8 +221,12 @@ export class ReadableImpl<TValue = any> implements BatchTask {
         try {
           const value = this._resolveValue_(this);
           if (!this.equal_?.(value, this._value_)) {
+            const oldValue = this._value_;
             this._value_ = value;
             this._version_ = (this._version_ + 1) | 0;
+            if (this._onDisposeValue_ && !strictEqual(oldValue, UNIQUE_VALUE) && !strictEqual(oldValue, value)) {
+              this._onDisposeValue_(oldValue);
+            }
           }
         } catch (e) {
           this._valueMaybeDirty_ = true;

src/typings.ts

@@ -13,6 +13,16 @@ export interface Config<TValue = any> {
    * Name for debugging.
    */
   readonly name?: string;
+  /**
+   * A callback invoked when a value is needed to be disposed.
+   *
+   * A value is considered for disposal when:
+   * - it is replaced by another value (a new value is set).
+   * - the Readable is disposed.
+   *
+   * @param oldValue The value that is needed to be disposed.
+   */
+  readonly onDisposeValue?: (oldValue: TValue) => void;
 }
 
 export type Disposer = () => void;

test/readable.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 
-import { compute, writable } from "../src";
+import { compute, readable, writable } from "../src";
 
 describe("readable", () => {
   describe("unsubscribe", () => {
@@ -105,4 +105,72 @@ describe("readable", () => {
       expect(JSON.stringify(a)).toBe("null");
     });
   });
+
+  describe("toDisposeValue", () => {
+    it("should call onDisposeValue when value changes", async () => {
+      const onDisposeValue = vi.fn();
+      const obj1 = { a: 1 };
+      const obj2 = { a: 2 };
+      const obj3 = { a: 3 };
+
+      const [v$, set] = readable(obj1, { onDisposeValue });
+      expect(v$.value).toBe(obj1);
+      expect(onDisposeValue).toBeCalledTimes(0);
+
+      set(obj1);
+      expect(v$.value).toBe(obj1);
+      expect(onDisposeValue).toBeCalledTimes(0);
+
+      set(obj2);
+      expect(v$.value).toBe(obj2);
+      expect(onDisposeValue).toBeCalledTimes(1);
+      expect(onDisposeValue).lastCalledWith(obj1);
+
+      set(obj2);
+      expect(v$.value).toBe(obj2);
+      expect(onDisposeValue).toBeCalledTimes(1);
+
+      set(obj3);
+      expect(v$.value).toBe(obj3);
+      expect(onDisposeValue).toBeCalledTimes(2);
+      expect(onDisposeValue).lastCalledWith(obj2);
+
+      v$.dispose();
+      expect(onDisposeValue).toBeCalledTimes(3);
+      expect(onDisposeValue).lastCalledWith(obj3);
+    });
+
+    it("should call onDisposeValue when value changes (equal: false)", async () => {
+      const onDisposeValue = vi.fn();
+      const obj1 = { a: 1 };
+      const obj2 = { a: 2 };
+      const obj3 = { a: 3 };
+
+      const [v$, set] = readable(obj1, { onDisposeValue, equal: false });
+      expect(v$.value).toBe(obj1);
+      expect(onDisposeValue).toBeCalledTimes(0);
+
+      set(obj1);
+      expect(v$.value).toBe(obj1);
+      expect(onDisposeValue).toBeCalledTimes(0);
+
+      set(obj2);
+      expect(v$.value).toBe(obj2);
+      expect(onDisposeValue).toBeCalledTimes(1);
+      expect(onDisposeValue).lastCalledWith(obj1);
+
+      set(obj2);
+      expect(v$.value).toBe(obj2);
+      expect(onDisposeValue).toBeCalledTimes(1);
+
+      set(obj3);
+      expect(v$.value).toBe(obj3);
+      expect(onDisposeValue).toBeCalledTimes(2);
+      expect(onDisposeValue).lastCalledWith(obj2);
+
+      v$.dispose();
+      expect(onDisposeValue).toBeCalledTimes(3);
+      expect(onDisposeValue).lastCalledWith(obj3);
+    });
+  });
 });