mvc-kit 2.12.0 → 2.12.2

package/src/singleton.ts

@@ -0,0 +1,70 @@
+import type { Disposable } from './types';
+
+// Using 'any' for registry types to avoid variance issues with generics
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDisposableClass = new (...args: any[]) => Disposable;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const registry = new Map<AnyDisposableClass, Disposable>();
+
+/**
+ * Get-or-create a singleton instance for the given class.
+ * Returns the existing instance if one exists and is not disposed; otherwise creates a new one.
+ *
+ * If the class defines `static DEFAULT_STATE`, it is used as the constructor argument
+ * when no args are passed — eliminating repeated object literals at every call site.
+ */
+export function singleton<T extends Disposable>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown },
+): T;
+export function singleton<T extends Disposable, Args extends unknown[]>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): T;
+export function singleton<T extends Disposable>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE?: unknown },
+  ...args: unknown[]
+): T {
+  const existing = registry.get(Class as AnyDisposableClass);
+
+  if (existing && !existing.disposed) {
+    return existing as T;
+  }
+
+  const instance = (args.length === 0 && 'DEFAULT_STATE' in Class)
+    ? new Class(Class.DEFAULT_STATE)
+    : new Class(...args);
+
+  registry.set(Class as AnyDisposableClass, instance);
+  return instance;
+}
+
+/**
+ * Check if a singleton instance exists for a class.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function hasSingleton(Class: new (...args: any[]) => Disposable): boolean {
+  const existing = registry.get(Class);
+  return existing !== undefined && !existing.disposed;
+}
+
+/**
+ * Disposes and removes the singleton instance for the given class.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function teardown(Class: new (...args: any[]) => Disposable): void {
+  const instance = registry.get(Class);
+  if (instance) {
+    instance.dispose();
+    registry.delete(Class);
+  }
+}
+
+/**
+ * Disposes all singletons and clears the registry. Typically used in test cleanup.
+ */
+export function teardownAll(): void {
+  for (const instance of registry.values()) {
+    instance.dispose();
+  }
+  registry.clear();
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+import type { AppError } from './errors';
+
+/**
+ * Listener callback type for state change notifications.
+ */
+export type Listener<S> = (state: S, prev: S) => void;
+
+/**
+ * Updater function type for functional state updates.
+ */
+export type Updater<S> = (prev: S) => Partial<S>;
+
+/**
+ * Validation errors mapped by field key.
+ */
+export type ValidationErrors<S> = Partial<Record<keyof S, string>>;
+
+/**
+ * Async method tracking state. Frozen snapshots are stored per method key.
+ */
+export interface TaskState {
+  readonly loading: boolean;
+  readonly error: string | null;
+  readonly errorCode: AppError['code'] | null;
+}
+
+/**
+ * Interface for objects that can be disposed.
+ */
+export interface Disposable {
+  readonly disposed: boolean;
+  readonly disposeSignal: AbortSignal;
+  dispose(): void;
+}
+
+/**
+ * Interface for objects with async-safe initialization lifecycle.
+ */
+export interface Initializable {
+  readonly initialized: boolean;
+  init(): void | Promise<void>;
+}
+
+/**
+ * Interface for reactive subscribable state containers.
+ */
+export interface Subscribable<S> extends Disposable {
+  state: S;
+  subscribe(listener: Listener<S>): () => void;
+}
+
+/**
+ * Structural type for event sources (Channel and EventBus both match).
+ * Exported as a public utility type. `listenTo` uses an inline structural
+ * type instead to avoid generic-to-generic variance issues.
+ */
+export interface EventSource<E extends Record<string, any>> {
+  on<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
+}
+
+/**
+ * Extracts the payload type for a specific event from an event source.
+ * Uses the `_types` phantom field (present on EventBus and Channel) for exact
+ * payload lookup. Falls back to conditional inference for structural sources.
+ */
+export type EventPayload<Source, Event> =
+  Source extends { readonly _types: infer E extends Record<string, any> }
+    ? Event extends keyof E ? E[Event] : never
+    : Source extends { on(event: Event, handler: (payload: infer P) => void): any }
+      ? P : never;

package/src/walkPrototypeChain.ts

@@ -0,0 +1,22 @@
+/**
+ * Walk the prototype chain from `instance`'s class up to (but not including)
+ * `stopAt`. Calls `visitor` for each own property descriptor found.
+ *
+ * Shared utility — used by ViewModel's _processMembers(), wrapAsyncMethods(),
+ * ViewModel/Resource's _guardReservedKeys(), and bindPublicMethods().
+ */
+export function walkPrototypeChain(
+  instance: object,
+  stopAt: object,
+  visitor: (key: string, desc: PropertyDescriptor, proto: object) => void,
+): void {
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== stopAt) {
+    const descriptors = Object.getOwnPropertyDescriptors(proto);
+    for (const [key, desc] of Object.entries(descriptors)) {
+      if (key === 'constructor') continue;
+      visitor(key, desc, proto);
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+}

package/src/web/IndexedDBCollection.test.ts

@@ -0,0 +1,235 @@
+// @vitest-environment jsdom
+import 'fake-indexeddb/auto';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { IndexedDBCollection } from './IndexedDBCollection';
+import { closeAllConnections, deleteDatabase } from './idb';
+import { teardownAll } from '../singleton';
+
+interface Message {
+  id: string;
+  text: string;
+  ts: number;
+}
+
+// Use WRITE_DELAY = 0 so flushes happen immediately (no setTimeout needed).
+// Still need a tick for the async IDB promises to resolve.
+const tick = (ms = 20) => new Promise((r) => setTimeout(r, ms));
+
+class MessagesCollection extends IndexedDBCollection<Message> {
+  protected readonly storageKey = 'messages';
+}
+
+class OtherCollection extends IndexedDBCollection<Message> {
+  protected readonly storageKey = 'other';
+}
+
+describe('IndexedDBCollection', () => {
+  beforeEach(async () => {
+    teardownAll();
+    closeAllConnections();
+    await deleteDatabase('mvc-kit');
+    await deleteDatabase('custom-db');
+  });
+
+  afterEach(() => {
+    closeAllConnections();
+  });
+
+  describe('hydration', () => {
+    it('loads persisted data via hydrate()', async () => {
+      // First: create and populate
+      const c1 = new MessagesCollection();
+      c1.add(
+        { id: '1', text: 'Hello', ts: 100 },
+        { id: '2', text: 'World', ts: 200 },
+      );
+      await tick();
+      c1.dispose();
+      closeAllConnections();
+
+      // Second: hydrate from storage
+      const c2 = new MessagesCollection();
+      const items = await c2.hydrate();
+
+      expect(c2.hydrated).toBe(true);
+      expect(items).toHaveLength(2);
+      expect(c2.get('1')!.text).toBe('Hello');
+      expect(c2.get('2')!.text).toBe('World');
+      c2.dispose();
+    });
+
+    it('hydrate() is idempotent', async () => {
+      const c = new MessagesCollection();
+      c.add({ id: '1', text: 'Test', ts: 100 });
+      await tick();
+
+      await c.hydrate();
+      c.add({ id: '2', text: 'New', ts: 200 });
+      const items = await c.hydrate();
+
+      // Second call returns current state, not re-reading
+      expect(items).toHaveLength(2);
+      c.dispose();
+    });
+  });
+
+  describe('per-item writes', () => {
+    it('add persists individual items', async () => {
+      const c = new MessagesCollection();
+      c.add({ id: '1', text: 'Hello', ts: 100 });
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.length).toBe(1);
+      expect(c2.get('1')!.text).toBe('Hello');
+      c2.dispose();
+    });
+
+    it('remove deletes individual items from store', async () => {
+      const c = new MessagesCollection();
+      c.add(
+        { id: '1', text: 'A', ts: 100 },
+        { id: '2', text: 'B', ts: 200 },
+      );
+      await tick();
+
+      c.remove('1');
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.length).toBe(1);
+      expect(c2.get('2')!.text).toBe('B');
+      c2.dispose();
+    });
+
+    it('update persists the changed item', async () => {
+      const c = new MessagesCollection();
+      c.add({ id: '1', text: 'Original', ts: 100 });
+      await tick();
+
+      c.update('1', { text: 'Updated' });
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.get('1')!.text).toBe('Updated');
+      c2.dispose();
+    });
+  });
+
+  describe('bulk operations', () => {
+    it('reset clears store and writes all new items', async () => {
+      const c = new MessagesCollection();
+      c.add({ id: '1', text: 'Old', ts: 100 });
+      await tick();
+
+      c.reset([
+        { id: '2', text: 'New1', ts: 200 },
+        { id: '3', text: 'New2', ts: 300 },
+      ]);
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.length).toBe(2);
+      expect(c2.has('1')).toBe(false);
+      expect(c2.get('2')!.text).toBe('New1');
+      c2.dispose();
+    });
+  });
+
+  describe('multiple collections', () => {
+    it('different collections use different object stores in same DB', async () => {
+      const msgs = new MessagesCollection();
+      const other = new OtherCollection();
+
+      msgs.add({ id: '1', text: 'Message', ts: 100 });
+      await tick(); // Let msgs flush before other opens a new store
+      other.add({ id: '1', text: 'Other', ts: 200 });
+      await tick();
+
+      msgs.dispose();
+      other.dispose();
+      closeAllConnections();
+
+      const msgs2 = new MessagesCollection();
+      const other2 = new OtherCollection();
+      await msgs2.hydrate();
+      await other2.hydrate();
+
+      expect(msgs2.get('1')!.text).toBe('Message');
+      expect(other2.get('1')!.text).toBe('Other');
+
+      msgs2.dispose();
+      other2.dispose();
+    });
+  });
+
+  describe('custom DB_NAME', () => {
+    it('uses custom database name', async () => {
+      class CustomDBCollection extends IndexedDBCollection<Message> {
+        static override DB_NAME = 'custom-db';
+        protected readonly storageKey = 'custom-store';
+      }
+
+      const c = new CustomDBCollection();
+      c.add({ id: '1', text: 'Custom', ts: 100 });
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new CustomDBCollection();
+      await c2.hydrate();
+      expect(c2.get('1')!.text).toBe('Custom');
+      c2.dispose();
+    });
+  });
+
+  describe('clearStorage', () => {
+    it('clears the object store and in-memory items', async () => {
+      const c = new MessagesCollection();
+      c.add({ id: '1', text: 'Test', ts: 100 });
+      await tick();
+
+      await c.clearStorage();
+      expect(c.length).toBe(0);
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.length).toBe(0);
+      c2.dispose();
+    });
+  });
+
+  describe('persistGet', () => {
+    it('returns single item by ID via hydrate', async () => {
+      const c = new MessagesCollection();
+      c.add(
+        { id: '1', text: 'A', ts: 100 },
+        { id: '2', text: 'B', ts: 200 },
+      );
+      await tick();
+      c.dispose();
+      closeAllConnections();
+
+      const c2 = new MessagesCollection();
+      await c2.hydrate();
+      expect(c2.get('1')!.text).toBe('A');
+      expect(c2.get('2')!.text).toBe('B');
+      expect(c2.get('3')).toBeUndefined();
+      c2.dispose();
+    });
+  });
+});

package/src/web/IndexedDBCollection.ts

@@ -0,0 +1,66 @@
+import { PersistentCollection } from '../PersistentCollection';
+import { getStore, idbGetAll, idbGet, idbPut, idbDelete, idbClear } from './idb';
+
+/**
+ * PersistentCollection backed by IndexedDB. Stores items individually by `id`
+ * in a dedicated object store (named by `storageKey`).
+ *
+ * **Requires manual `hydrate()` call** (async storage).
+ * Typically called in ViewModel's `onInit()`.
+ *
+ * Uses per-item strategy: each item is stored as a separate entry in the object store.
+ * No JSON serialization needed — IndexedDB uses structured cloning.
+ *
+ * ```ts
+ * class MessagesCollection extends IndexedDBCollection<Message> {
+ *   protected readonly storageKey = 'messages';
+ * }
+ *
+ * // In ViewModel:
+ * async onInit() {
+ *   await this.collection.hydrate();
+ *   if (this.collection.length === 0) this.load();
+ * }
+ * ```
+ */
+export abstract class IndexedDBCollection<
+  T extends { id: string | number },
+> extends PersistentCollection<T> {
+  /** IndexedDB database name. Override to use a separate database. */
+  static DB_NAME = 'mvc-kit';
+
+  private get _dbName(): string {
+    return (this.constructor as typeof IndexedDBCollection).DB_NAME;
+  }
+
+  private _getStore(mode: IDBTransactionMode) {
+    return getStore(this._dbName, this.storageKey, mode);
+  }
+
+  // ── Persist interface (per-item strategy) ──
+
+  protected async persistGetAll(): Promise<T[]> {
+    const store = await this._getStore('readonly');
+    return idbGetAll<T>(store);
+  }
+
+  protected async persistGet(id: T['id']): Promise<T | null> {
+    const store = await this._getStore('readonly');
+    return idbGet<T>(store, id as IDBValidKey);
+  }
+
+  protected async persistSet(items: T[]): Promise<void> {
+    const store = await this._getStore('readwrite');
+    return idbPut(store, items);
+  }
+
+  protected async persistRemove(ids: T['id'][]): Promise<void> {
+    const store = await this._getStore('readwrite');
+    return idbDelete(store, ids as IDBValidKey[]);
+  }
+
+  protected async persistClear(): Promise<void> {
+    const store = await this._getStore('readwrite');
+    return idbClear(store);
+  }
+}

package/src/web/WebStorageCollection.test.ts

@@ -0,0 +1,214 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { WebStorageCollection } from './WebStorageCollection';
+import { teardownAll } from '../singleton';
+
+interface CartItem {
+  id: string;
+  name: string;
+  qty: number;
+}
+
+class CartCollection extends WebStorageCollection<CartItem> {
+  protected readonly storageKey = 'cart';
+}
+
+class SessionCartCollection extends WebStorageCollection<CartItem> {
+  static override STORAGE = 'session' as const;
+  protected readonly storageKey = 'session-cart';
+}
+
+describe('WebStorageCollection', () => {
+  beforeEach(() => {
+    teardownAll();
+    localStorage.clear();
+    sessionStorage.clear();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('auto-hydration', () => {
+    it('loads data from localStorage on first access', () => {
+      localStorage.setItem('cart', JSON.stringify([
+        { id: '1', name: 'Widget', qty: 2 },
+        { id: '2', name: 'Gadget', qty: 1 },
+      ]));
+
+      const collection = new CartCollection();
+
+      // Hydration is lazy — triggered by first access
+      expect(collection.length).toBe(2);
+      expect(collection.hydrated).toBe(true);
+      expect(collection.get('1')!.name).toBe('Widget');
+      collection.dispose();
+    });
+
+    it('starts empty when no stored data', () => {
+      const collection = new CartCollection();
+      expect(collection.length).toBe(0);
+      expect(collection.hydrated).toBe(true);
+      collection.dispose();
+    });
+  });
+
+  describe('persistence (blob strategy)', () => {
+    it('mutations persist to localStorage', () => {
+      const collection = new CartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+      vi.runAllTimers();
+
+      const stored = JSON.parse(localStorage.getItem('cart')!);
+      expect(stored).toEqual([{ id: '1', name: 'Widget', qty: 2 }]);
+      collection.dispose();
+    });
+
+    it('writes full state (blob) on each flush', () => {
+      const collection = new CartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+      vi.runAllTimers();
+
+      collection.add({ id: '2', name: 'Gadget', qty: 1 });
+      vi.runAllTimers();
+
+      const stored = JSON.parse(localStorage.getItem('cart')!);
+      expect(stored).toHaveLength(2);
+      collection.dispose();
+    });
+
+    it('remove persists correctly', () => {
+      const collection = new CartCollection();
+      collection.add(
+        { id: '1', name: 'Widget', qty: 2 },
+        { id: '2', name: 'Gadget', qty: 1 },
+      );
+      vi.runAllTimers();
+
+      collection.remove('1');
+      vi.runAllTimers();
+
+      const stored = JSON.parse(localStorage.getItem('cart')!);
+      expect(stored).toEqual([{ id: '2', name: 'Gadget', qty: 1 }]);
+      collection.dispose();
+    });
+
+    it('clear removes from localStorage', () => {
+      const collection = new CartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+      vi.runAllTimers();
+      expect(localStorage.getItem('cart')).not.toBeNull();
+
+      collection.clear();
+      vi.runAllTimers();
+
+      expect(localStorage.getItem('cart')).toBeNull();
+      collection.dispose();
+    });
+  });
+
+  describe('sessionStorage', () => {
+    it('STORAGE = session uses sessionStorage', () => {
+      const collection = new SessionCartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+      vi.runAllTimers();
+
+      expect(sessionStorage.getItem('session-cart')).not.toBeNull();
+      expect(localStorage.getItem('session-cart')).toBeNull();
+
+      const stored = JSON.parse(sessionStorage.getItem('session-cart')!);
+      expect(stored).toEqual([{ id: '1', name: 'Widget', qty: 2 }]);
+      collection.dispose();
+    });
+
+    it('auto-hydrates from sessionStorage', () => {
+      sessionStorage.setItem('session-cart', JSON.stringify([
+        { id: '1', name: 'Widget', qty: 3 },
+      ]));
+
+      const collection = new SessionCartCollection();
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.qty).toBe(3);
+      collection.dispose();
+    });
+  });
+
+  describe('JSON round-trip', () => {
+    it('preserves data through serialize/deserialize cycle', () => {
+      const collection = new CartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 99 });
+      vi.runAllTimers();
+      collection.dispose();
+
+      // Recreate from storage
+      const collection2 = new CartCollection();
+      expect(collection2.get('1')).toEqual({ id: '1', name: 'Widget', qty: 99 });
+      collection2.dispose();
+    });
+  });
+
+  describe('error handling', () => {
+    it('handles QuotaExceededError gracefully', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const errorSpy = vi.fn();
+      let shouldThrow = false;
+
+      class QuotaCollection extends WebStorageCollection<CartItem> {
+        protected readonly storageKey = 'quota-test';
+        protected onPersistError = errorSpy;
+        protected override persistSet(items: CartItem[]): void {
+          if (shouldThrow) {
+            const err = new DOMException('Quota exceeded', 'QuotaExceededError');
+            warnSpy.call(console,
+              `[mvc-kit] QuotaExceededError writing to "${this.storageKey}". ` +
+              `Consider using IndexedDBCollection for larger datasets.`,
+            );
+            throw err;
+          }
+          super.persistSet(items);
+        }
+      }
+
+      const collection = new QuotaCollection();
+      shouldThrow = true;
+
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+
+      expect(errorSpy).toHaveBeenCalled();
+      expect(collection.length).toBe(1); // In-memory still works
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('QuotaExceededError'));
+
+      warnSpy.mockRestore();
+      collection.dispose();
+    });
+
+    it('handles corrupted JSON in storage', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      localStorage.setItem('cart', 'not-valid-json{{{');
+
+      const collection = new CartCollection();
+      expect(collection.length).toBe(0);
+      expect(collection.hydrated).toBe(true);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Corrupted data'));
+
+      warnSpy.mockRestore();
+      collection.dispose();
+    });
+  });
+
+  describe('clearStorage', () => {
+    it('removes storage AND clears in-memory', () => {
+      const collection = new CartCollection();
+      collection.add({ id: '1', name: 'Widget', qty: 2 });
+      vi.runAllTimers();
+
+      collection.clearStorage();
+
+      expect(collection.length).toBe(0);
+      expect(localStorage.getItem('cart')).toBeNull();
+      collection.dispose();
+    });
+  });
+});