mvc-kit 2.12.0 → 2.12.1

package/src/Trackable.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Trackable } from './Trackable';
+import { ViewModel } from './ViewModel';
+import { teardownAll } from './singleton';
+
+// ── Test subclass ──
+
+class Counter extends Trackable {
+  private _count = 0;
+
+  get count() { return this._count; }
+
+  increment() {
+    this._count++;
+    this.notify();
+  }
+
+  decrement() {
+    this._count--;
+    this.notify();
+  }
+
+  registerCleanup(fn: () => void) {
+    this.addCleanup(fn);
+  }
+}
+
+class WithOnDispose extends Trackable {
+  disposed_hook_called = false;
+
+  protected onDispose(): void {
+    this.disposed_hook_called = true;
+  }
+}
+
+// ── Tests ──
+
+describe('Trackable', () => {
+  beforeEach(() => {
+    teardownAll();
+  });
+
+  describe('construction', () => {
+    it('starts not disposed', () => {
+      const t = new Counter();
+      expect(t.disposed).toBe(false);
+    });
+
+    it('can be instantiated directly (concrete class)', () => {
+      const t = new Trackable();
+      expect(t.disposed).toBe(false);
+    });
+  });
+
+  describe('subscribe / notify', () => {
+    it('fires callback on notify', () => {
+      const c = new Counter();
+      const listener = vi.fn();
+      c.subscribe(listener);
+      c.increment();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('fires multiple subscribers', () => {
+      const c = new Counter();
+      const a = vi.fn();
+      const b = vi.fn();
+      c.subscribe(a);
+      c.subscribe(b);
+      c.increment();
+      expect(a).toHaveBeenCalledTimes(1);
+      expect(b).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const c = new Counter();
+      const listener = vi.fn();
+      const unsub = c.subscribe(listener);
+      c.increment();
+      expect(listener).toHaveBeenCalledTimes(1);
+      unsub();
+      c.increment();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('no-op when no listeners', () => {
+      const c = new Counter();
+      // Should not throw
+      c.increment();
+      expect(c.count).toBe(1);
+    });
+  });
+
+  describe('dispose', () => {
+    it('sets disposed to true', () => {
+      const t = new Counter();
+      t.dispose();
+      expect(t.disposed).toBe(true);
+    });
+
+    it('is idempotent', () => {
+      const cleanup = vi.fn();
+      const c = new Counter();
+      c.registerCleanup(cleanup);
+      c.dispose();
+      c.dispose();
+      expect(cleanup).toHaveBeenCalledTimes(1);
+    });
+
+    it('clears listeners on dispose', () => {
+      const c = new Counter();
+      const listener = vi.fn();
+      c.subscribe(listener);
+      c.dispose();
+      // notify after dispose should not fire
+      // (accessing protected method via subclass for testing)
+      c.increment();
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('calls onDispose hook', () => {
+      const t = new WithOnDispose();
+      t.dispose();
+      expect(t.disposed_hook_called).toBe(true);
+    });
+
+    it('runs cleanups in registration order', () => {
+      const order: number[] = [];
+      const c = new Counter();
+      c.registerCleanup(() => order.push(1));
+      c.registerCleanup(() => order.push(2));
+      c.registerCleanup(() => order.push(3));
+      c.dispose();
+      expect(order).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe('addCleanup', () => {
+    it('registers and runs on dispose', () => {
+      const cleanup = vi.fn();
+      const c = new Counter();
+      c.registerCleanup(cleanup);
+      expect(cleanup).not.toHaveBeenCalled();
+      c.dispose();
+      expect(cleanup).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('disposeSignal', () => {
+    it('returns an AbortSignal', () => {
+      const t = new Counter();
+      expect(t.disposeSignal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('returns the same reference on repeat access', () => {
+      const t = new Counter();
+      const s1 = t.disposeSignal;
+      const s2 = t.disposeSignal;
+      expect(s1).toBe(s2);
+    });
+
+    it('is not aborted initially', () => {
+      const t = new Counter();
+      expect(t.disposeSignal.aborted).toBe(false);
+    });
+
+    it('is aborted after dispose', () => {
+      const t = new Counter();
+      const signal = t.disposeSignal;
+      t.dispose();
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('fires abort event on dispose', () => {
+      const t = new Counter();
+      const handler = vi.fn();
+      t.disposeSignal.addEventListener('abort', handler);
+      t.dispose();
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('method binding', () => {
+    it('auto-binds public methods for point-free usage', () => {
+      const c = new Counter();
+      const { increment, decrement } = c;
+      increment();
+      increment();
+      decrement();
+      expect(c.count).toBe(1);
+    });
+
+    it('auto-binds subscribe and dispose', () => {
+      const c = new Counter();
+      const { subscribe, dispose } = c;
+      const listener = vi.fn();
+      subscribe(listener);
+      c.increment();
+      expect(listener).toHaveBeenCalledTimes(1);
+      dispose();
+      expect(c.disposed).toBe(true);
+    });
+  });
+
+  describe('ViewModel auto-tracking', () => {
+    it('invalidates ViewModel getter when Trackable notifies', () => {
+      let computeCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly counter = new Counter();
+
+        get doubled() {
+          computeCount++;
+          return this.counter.count * 2;
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      expect(vm.doubled).toBe(0);
+      expect(computeCount).toBe(1);
+
+      // Cached — no recompute
+      expect(vm.doubled).toBe(0);
+      expect(computeCount).toBe(1);
+
+      // Mutate Trackable → invalidates getter
+      vm.counter.increment();
+      expect(vm.doubled).toBe(2);
+      expect(computeCount).toBe(2);
+
+      vm.dispose();
+    });
+  });
+});

package/src/Trackable.ts

@@ -0,0 +1,129 @@
+import type { Disposable } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+
+const PROTECTED_KEYS = new Set(['addCleanup', 'notify']);
+
+/**
+ * Base class for custom reactive objects that integrate with ViewModel's
+ * auto-tracking system. Provides subscribable notifications, disposal
+ * lifecycle, and automatic method binding.
+ *
+ * Any object with a `subscribe()` method is auto-tracked by ViewModel
+ * getters. Trackable gives you that plus cleanup infrastructure and
+ * point-free methods — the same building blocks used by Sorting,
+ * Selection, Feed, Pagination, and Pending.
+ *
+ * Use Trackable when integrating third-party SDKs, custom query objects,
+ * or any reactive state that doesn't fit ViewModel's state/getter model.
+ *
+ * @example
+ * ```ts
+ * class RPCQuery<Data> extends Trackable {
+ *   private _data: Data | undefined;
+ *   private _loading = false;
+ *
+ *   get data() { return this._data; }
+ *   get loading() { return this._loading; }
+ *
+ *   async call(): Promise<void> {
+ *     this._loading = true;
+ *     this.notify();
+ *     this._data = await fetchData();
+ *     this._loading = false;
+ *     this.notify();
+ *   }
+ * }
+ *
+ * // Used as a ViewModel property — auto-tracked:
+ * class UsersVM extends ViewModel {
+ *   readonly users = new RPCQuery<User[]>();
+ *   get userList() { return this.users.data ?? []; }
+ * }
+ * ```
+ */
+export class Trackable implements Disposable {
+  private _listeners: Set<() => void> | null = null;
+  private _disposed = false;
+  private _abortController: AbortController | null = null;
+  private _cleanups: (() => void)[] | null = null;
+
+  constructor() {
+    bindPublicMethods(this, Object.prototype, PROTECTED_KEYS);
+  }
+
+  // ── Disposable interface ──
+
+  /** Whether this instance has been disposed. */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /**
+   * Tear down the instance: abort the dispose signal, run all registered
+   * cleanups, clear subscribers, and call onDispose. Idempotent.
+   */
+  dispose(): void {
+    if (this._disposed) return;
+    this._disposed = true;
+    this._abortController?.abort();
+    if (this._cleanups) {
+      for (const fn of this._cleanups) fn();
+      this._cleanups = null;
+    }
+    this._listeners?.clear();
+    this.onDispose?.();
+  }
+
+  // ── Subscribable (notification-only, no state) ──
+
+  /**
+   * Subscribe to change notifications. The callback is invoked (with no
+   * arguments) whenever the subclass calls {@link notify}.
+   *
+   * This is the duck-typed contract that ViewModel's auto-tracking system
+   * recognizes — any object with a `subscribe` method is automatically
+   * tracked when accessed inside a ViewModel getter.
+   *
+   * @returns An unsubscribe function.
+   */
+  subscribe(cb: () => void): () => void {
+    if (!this._listeners) this._listeners = new Set();
+    this._listeners.add(cb);
+    return () => { this._listeners?.delete(cb); };
+  }
+
+  /**
+   * Notify all subscribers that state has changed. Call this after
+   * mutating internal state to trigger ViewModel getter invalidation
+   * and React re-renders.
+   * @protected
+   */
+  protected notify(): void {
+    if (this._listeners) {
+      for (const cb of this._listeners) cb();
+    }
+  }
+
+  // ── Protected utilities ──
+
+  /**
+   * Register a cleanup function to be called on {@link dispose}.
+   * Cleanups run in registration order.
+   * @protected
+   */
+  protected addCleanup(fn: () => void): void {
+    if (!this._cleanups) this._cleanups = [];
+    this._cleanups.push(fn);
+  }
+
+  /** Lifecycle hook called at the end of dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+}