mvc-kit 2.12.0 → 2.12.2

package/src/web/WebStorageCollection.ts

@@ -0,0 +1,116 @@
+import { PersistentCollection } from '../PersistentCollection';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+/**
+ * PersistentCollection backed by localStorage or sessionStorage.
+ * Auto-hydrates on first access (sync storage — no need for manual `hydrate()` call).
+ *
+ * Uses blob strategy: all items stored as a single JSON string under `storageKey`.
+ *
+ * ```ts
+ * class CartCollection extends WebStorageCollection<CartItem> {
+ *   protected readonly storageKey = 'cart';
+ * }
+ * ```
+ */
+export abstract class WebStorageCollection<
+  T extends { id: string | number },
+> extends PersistentCollection<T> {
+  /** Which Web Storage backend to use. Override to 'session' for sessionStorage. */
+  static STORAGE: 'local' | 'session' = 'local';
+
+  private _autoHydrated = false;
+
+  private get _storage(): Storage {
+    return (this.constructor as typeof WebStorageCollection).STORAGE === 'session'
+      ? sessionStorage
+      : localStorage;
+  }
+
+  private _ensureHydrated(): void {
+    if (this._autoHydrated) return;
+    this._autoHydrated = true;
+    this._hydrateSync();
+  }
+
+  // ── Override access points to trigger lazy hydration ──
+
+  get items(): T[] {
+    this._ensureHydrated();
+    return super.items;
+  }
+
+  get state(): T[] {
+    return this.items;
+  }
+
+  get length(): number {
+    this._ensureHydrated();
+    return super.length;
+  }
+
+  get(id: T['id']): T | undefined {
+    this._ensureHydrated();
+    return super.get(id);
+  }
+
+  has(id: T['id']): boolean {
+    this._ensureHydrated();
+    return super.has(id);
+  }
+
+  // ── Persist interface (blob strategy) ──
+
+  protected persistGetAll(): T[] {
+    const raw = this._storage.getItem(this.storageKey);
+    if (!raw) return [];
+    try {
+      return this.deserialize(raw);
+    } catch {
+      if (__DEV__) {
+        console.warn(
+          `[mvc-kit] Corrupted data in storage key "${this.storageKey}". Ignoring stored data.`,
+        );
+      }
+      return [];
+    }
+  }
+
+  protected persistGet(id: T['id']): T | null {
+    const all = this.persistGetAll();
+    return all.find((i) => i.id === id) ?? null;
+  }
+
+  protected persistSet(_items: T[]): void {
+    try {
+      this._storage.setItem(this.storageKey, this.serialize([...this.items]));
+    } catch (err) {
+      if (__DEV__ && err instanceof DOMException && err.name === 'QuotaExceededError') {
+        console.warn(
+          `[mvc-kit] QuotaExceededError writing to "${this.storageKey}". ` +
+            `Consider using IndexedDBCollection for larger datasets.`,
+        );
+      }
+      throw err;
+    }
+  }
+
+  protected persistRemove(_ids: T['id'][]): void {
+    try {
+      this._storage.setItem(this.storageKey, this.serialize([...this.items]));
+    } catch (err) {
+      if (__DEV__ && err instanceof DOMException && err.name === 'QuotaExceededError') {
+        console.warn(
+          `[mvc-kit] QuotaExceededError writing to "${this.storageKey}". ` +
+            `Consider using IndexedDBCollection for larger datasets.`,
+        );
+      }
+      throw err;
+    }
+  }
+
+  protected persistClear(): void {
+    this._storage.removeItem(this.storageKey);
+  }
+}

package/src/web/idb.ts

@@ -0,0 +1,184 @@
+/**
+ * Shared IndexedDB connection manager.
+ * Deduplicates indexedDB.open() calls and handles dynamic object store creation
+ * by bumping the DB version when a new storageKey is encountered.
+ */
+
+const _connections = new Map<string, IDBDatabase>();
+const _stores = new Map<string, Set<string>>(); // dbName → known store names
+let _openQueue: Promise<void> = Promise.resolve(); // Sequential open queue
+
+function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
+  // If we already have a connection with the required store, reuse it
+  const existing = _connections.get(dbName);
+  if (existing) {
+    if (existing.objectStoreNames.contains(storeName)) {
+      return Promise.resolve(existing);
+    }
+    // Need to add a new store — close and reopen with bumped version
+    existing.close();
+    _connections.delete(dbName);
+  }
+
+  // Track known stores
+  let stores = _stores.get(dbName);
+  if (!stores) {
+    stores = new Set();
+    _stores.set(dbName, stores);
+  }
+  stores.add(storeName);
+
+  // Serialize opens to prevent version conflicts
+  const result = _openQueue.then(() => doOpen(dbName, stores!));
+  _openQueue = result.then(() => {}, () => {}); // Absorb errors for the queue
+  return result;
+}
+
+function doOpen(dbName: string, stores: Set<string>): Promise<IDBDatabase> {
+  // Close existing cached connection if any (may have been opened by queued op)
+  const existingDb = _connections.get(dbName);
+  existingDb?.close();
+  _connections.delete(dbName);
+
+  // Probe current DB version (version-less open never triggers upgrade)
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const probe = indexedDB.open(dbName);
+    probe.onsuccess = () => {
+      const db = probe.result;
+      const version = db.version;
+
+      // Check if all required stores already exist
+      let needsUpgrade = false;
+      for (const name of stores) {
+        if (!db.objectStoreNames.contains(name)) {
+          needsUpgrade = true;
+          break;
+        }
+      }
+
+      if (!needsUpgrade) {
+        _connections.set(dbName, db);
+        resolve(db);
+        return;
+      }
+
+      // Need new stores — close and reopen with bumped version
+      db.close();
+      const upgrade = indexedDB.open(dbName, version + 1);
+      upgrade.onupgradeneeded = () => {
+        const udb = upgrade.result;
+        for (const name of stores) {
+          if (!udb.objectStoreNames.contains(name)) {
+            udb.createObjectStore(name, { keyPath: 'id' });
+          }
+        }
+      };
+      upgrade.onsuccess = () => {
+        _connections.set(dbName, upgrade.result);
+        resolve(upgrade.result);
+      };
+      upgrade.onerror = () => reject(upgrade.error);
+    };
+    probe.onerror = () => reject(probe.error);
+  });
+}
+
+/**
+ * Open a transaction and return the object store for the given database and store name.
+ */
+export function getStore(
+  dbName: string,
+  storeName: string,
+  mode: IDBTransactionMode,
+): Promise<IDBObjectStore> {
+  return openDB(dbName, storeName).then((db) => {
+    const tx = db.transaction(storeName, mode);
+    return tx.objectStore(storeName);
+  });
+}
+
+/**
+ * Retrieve all items from an IndexedDB object store.
+ */
+export function idbGetAll<T>(store: IDBObjectStore): Promise<T[]> {
+  return new Promise((resolve, reject) => {
+    const request = store.getAll();
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+/**
+ * Retrieve a single item by key from an IndexedDB object store.
+ */
+export function idbGet<T>(store: IDBObjectStore, id: IDBValidKey): Promise<T | null> {
+  return new Promise((resolve, reject) => {
+    const request = store.get(id);
+    request.onsuccess = () => resolve(request.result ?? null);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+/**
+ * Write (put) multiple items into an IndexedDB object store.
+ */
+export function idbPut<T>(store: IDBObjectStore, items: T[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = store.transaction;
+    for (const item of items) {
+      store.put(item);
+    }
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+/**
+ * Delete multiple items by key from an IndexedDB object store.
+ */
+export function idbDelete(store: IDBObjectStore, ids: IDBValidKey[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = store.transaction;
+    for (const id of ids) {
+      store.delete(id);
+    }
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+/**
+ * Clear all items from an IndexedDB object store.
+ */
+export function idbClear(store: IDBObjectStore): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = store.transaction;
+    store.clear();
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+/** Close all cached connections and delete all known databases. Used in test cleanup. */
+export function closeAllConnections(): void {
+  for (const db of _connections.values()) {
+    db.close();
+  }
+  _connections.clear();
+  _stores.clear();
+  _openQueue = Promise.resolve();
+}
+
+/** Delete a database by name. Returns a promise that resolves when deleted. */
+export function deleteDatabase(dbName: string): Promise<void> {
+  const existing = _connections.get(dbName);
+  existing?.close();
+  _connections.delete(dbName);
+  _stores.delete(dbName);
+
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(dbName);
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+}

package/src/web/index.ts

@@ -0,0 +1,2 @@
+export { WebStorageCollection } from './WebStorageCollection';
+export { IndexedDBCollection } from './IndexedDBCollection';

package/src/wrapAsyncMethods.ts

@@ -0,0 +1,249 @@
+import { isAbortError, classifyError } from './errors';
+import { walkPrototypeChain } from './walkPrototypeChain';
+import type { TaskState } from './types';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+const LOADING_TASK_STATE: TaskState = Object.freeze({ loading: true, error: null, errorCode: null });
+
+/** @internal Mutable internal async tracking state per method. */
+export interface InternalTaskState {
+  loading: boolean;
+  error: string | null;
+  errorCode: TaskState['errorCode'];
+  count: number;
+}
+
+/** @internal Configuration for the shared async method wrapping logic. */
+export interface AsyncTrackingContext {
+  instance: object;
+  stopPrototype: object;
+  reservedKeys: readonly string[];
+  lifecycleHooks: Set<string>;
+  isDisposed: () => boolean;
+  isInitialized: () => boolean;
+  asyncStates: Map<string, InternalTaskState>;
+  asyncSnapshots: Map<string, TaskState>;
+  asyncListeners: Set<() => void>;
+  notifyAsync: () => void;
+  addCleanup: (fn: () => void) => void;
+  ghostTimeout: number;
+  className: string;
+  activeOps: Map<string, number> | null;
+  /** Pre-scanned methods from class metadata cache. When provided, skips prototype walk. */
+  methods?: Array<{ key: string; fn: Function }>;
+}
+
+/**
+ * Shared async method wrapping logic used by both ViewModel and Resource.
+ * Walks the prototype chain, wraps methods with async tracking, and registers cleanup.
+ * Returns the list of wrapped method keys.
+ */
+export function wrapAsyncMethods(ctx: AsyncTrackingContext): string[] {
+  const {
+    instance,
+    stopPrototype,
+    reservedKeys,
+    lifecycleHooks,
+    isDisposed,
+    isInitialized,
+    asyncStates,
+    asyncSnapshots,
+    asyncListeners,
+    notifyAsync,
+    addCleanup,
+    ghostTimeout,
+    className,
+    activeOps,
+  } = ctx;
+
+  // Instance property reserved key check (DEV-only — prototype check in constructor catches most cases)
+  // Skip own properties that are bound methods from bindPublicMethods (the key
+  // also exists as a method on the prototype chain). Only reject class-field overrides.
+  if (__DEV__) {
+    for (const key of reservedKeys) {
+      if (Object.getOwnPropertyDescriptor(instance, key)?.value !== undefined) {
+        // Check if the prototype chain has a method with this name —
+        // if so, the own property is from bindPublicMethods, not a user override
+        let fromPrototype = false;
+        let proto = Object.getPrototypeOf(instance);
+        while (proto && proto !== Object.prototype) {
+          const desc = Object.getOwnPropertyDescriptor(proto, key);
+          if (desc && typeof desc.value === 'function') { fromPrototype = true; break; }
+          proto = Object.getPrototypeOf(proto);
+        }
+        if (!fromPrototype) {
+          throw new Error(
+            `[mvc-kit] "${key}" is a reserved property on ${className} and cannot be overridden.`
+          );
+        }
+      }
+    }
+  }
+
+  // Use pre-scanned methods from class metadata cache, or walk prototype chain
+  const methodEntries: Array<{ key: string; fn: Function }> = ctx.methods ?? (() => {
+    const result: Array<{ key: string; fn: Function }> = [];
+    const processed = new Set<string>();
+    walkPrototypeChain(instance, stopPrototype, (key, desc) => {
+      if (desc.get || desc.set) return;
+      if (typeof desc.value !== 'function') return;
+      if (key.startsWith('_')) return;
+      if (lifecycleHooks.has(key)) return;
+      if (processed.has(key)) return;
+      processed.add(key);
+      result.push({ key, fn: desc.value });
+    });
+    return result;
+  })();
+
+  const wrappedKeys: string[] = [];
+
+  for (const { key, fn: original } of methodEntries) {
+    let pruned = false;
+
+    const wrapper = function (this: any, ...args: unknown[]) {
+      // Disposed guard
+      if (isDisposed()) {
+        if (__DEV__) {
+          console.warn(`[mvc-kit] "${key}" called after dispose — ignored.`);
+        }
+        return undefined;
+      }
+
+      // Pre-init guard (DEV only — method still executes)
+      if (__DEV__ && !isInitialized()) {
+        console.warn(
+          `[mvc-kit] "${key}" called before init(). ` +
+          `Async tracking is active only after init().`
+        );
+      }
+
+      let result: unknown;
+      try {
+        result = original.apply(instance, args);
+      } catch (e) {
+        // Sync throw — not tracked as async
+        throw e;
+      }
+
+      // Sync detection: if not thenable, prune from async tracking
+      if (!result || typeof (result as any).then !== 'function') {
+        if (!pruned) {
+          pruned = true;
+          // Remove from async maps
+          asyncStates.delete(key);
+          asyncSnapshots.delete(key);
+          // Replace wrapper with bound original for zero overhead
+          (instance as any)[key] = original.bind(instance);
+        }
+        return result;
+      }
+
+      // ── Async tracking ──────────────────────────────────────
+      let internal = asyncStates.get(key);
+      if (!internal) {
+        internal = { loading: false, error: null, errorCode: null, count: 0 };
+        asyncStates.set(key, internal);
+      }
+
+      internal.count++;
+      internal.loading = true;
+      internal.error = null;
+      internal.errorCode = null;
+      asyncSnapshots.set(key, LOADING_TASK_STATE);
+      notifyAsync();
+
+      if (__DEV__ && activeOps) {
+        activeOps.set(key, (activeOps.get(key) ?? 0) + 1);
+      }
+
+      // Shared bookkeeping: decrement count, snapshot state, update DEV active ops
+      const finalizeOp = (errorMsg?: string | null, errorCode?: TaskState['errorCode']) => {
+        internal!.count--;
+        internal!.loading = internal!.count > 0;
+        if (errorMsg !== undefined) {
+          internal!.error = errorMsg;
+          internal!.errorCode = errorCode ?? null;
+        }
+        asyncSnapshots.set(
+          key,
+          Object.freeze({ loading: internal!.loading, error: internal!.error, errorCode: internal!.errorCode }),
+        );
+        notifyAsync();
+
+        if (__DEV__ && activeOps) {
+          const c = (activeOps.get(key) ?? 1) - 1;
+          if (c <= 0) activeOps.delete(key);
+          else activeOps.set(key, c);
+        }
+      };
+
+      return (result as Promise<unknown>).then(
+        (value) => {
+          if (!isDisposed()) finalizeOp();
+          return value;
+        },
+        (error) => {
+          // AbortError — silently swallow
+          if (isAbortError(error)) {
+            if (!isDisposed()) finalizeOp();
+            return undefined;
+          }
+
+          // Disposed — fizzle silently
+          if (isDisposed()) return undefined;
+
+          const classified = classifyError(error);
+          finalizeOp(classified.message, classified.code);
+
+          // Re-throw to preserve standard Promise rejection
+          throw error;
+        },
+      );
+    };
+
+    wrappedKeys.push(key);
+    (instance as any)[key] = wrapper;
+  }
+
+  // Register cleanup for disposal
+  if (wrappedKeys.length > 0) {
+    addCleanup(() => {
+      // Snapshot active ops for ghost check before clearing
+      const opsSnapshot = __DEV__ && activeOps ? new Map(activeOps) : null;
+
+      // Swap all wrapped methods to no-ops (with DEV warning)
+      for (const k of wrappedKeys) {
+        if (__DEV__) {
+          (instance as any)[k] = () => {
+            console.warn(`[mvc-kit] "${k}" called after dispose — ignored.`);
+            return undefined;
+          };
+        } else {
+          (instance as any)[k] = () => undefined;
+        }
+      }
+
+      // Clear async state
+      asyncListeners.clear();
+      asyncStates.clear();
+      asyncSnapshots.clear();
+
+      // DEV: schedule ghost check
+      if (__DEV__ && opsSnapshot && opsSnapshot.size > 0) {
+        setTimeout(() => {
+          for (const [key, count] of opsSnapshot) {
+            console.warn(
+              `[mvc-kit] Ghost async operation detected: "${key}" had ${count} ` +
+              `pending call(s) when the ${className} was disposed. ` +
+              `Consider using disposeSignal to cancel in-flight work.`
+            );
+          }
+        }, ghostTimeout);
+      }
+    });
+  }
+
+  return wrappedKeys;
+}