mvc-kit 2.12.0 → 2.12.2

package/src/Pending.ts

@@ -0,0 +1,390 @@
+import { classifyError, isAbortError } from './errors';
+import type { AppError } from './errors';
+import { Trackable } from './Trackable';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+// ── Types ─────────────────────────────────────────────────────────
+
+/** Frozen snapshot of a single pending operation's state. */
+export interface PendingOperation<Meta = unknown> {
+  readonly status: 'active' | 'retrying' | 'failed';
+  readonly operation: string;
+  readonly attempts: number;
+  readonly maxRetries: number;
+  readonly error: string | null;
+  readonly errorCode: AppError['code'] | null;
+  readonly nextRetryAt: number | null;
+  readonly createdAt: number;
+  readonly meta: Meta | null;
+}
+
+/** A PendingOperation snapshot paired with its key, for iteration. */
+export interface PendingEntry<K extends string | number, Meta = unknown>
+  extends PendingOperation<Meta> {
+  readonly id: K;
+}
+
+/** Mutable internal state for a pending operation. */
+interface InternalOp<K, Meta> {
+  id: K;
+  operation: string;
+  execute: (signal: AbortSignal) => Promise<void>;
+  status: PendingOperation['status'];
+  attempts: number;
+  error: string | null;
+  errorCode: AppError['code'] | null;
+  nextRetryAt: number | null;
+  createdAt: number;
+  abortController: AbortController;
+  retryTimer: ReturnType<typeof setTimeout> | null;
+  meta: Meta | null;
+}
+
+// ── Pending ───────────────────────────────────────────────────────
+
+/**
+ * Per-item operation queue with retry and status tracking.
+ * Tracks operations by key with exponential backoff retry on transient errors.
+ * Subscribable — auto-tracked when used as a ViewModel/Resource property.
+ */
+export class Pending<K extends string | number = string | number, Meta = unknown> extends Trackable {
+  // ── Static config (Channel pattern — override via subclass) ──
+
+  /** Maximum number of retry attempts before marking as failed. */
+  static MAX_RETRIES = 5;
+  /** Base delay (ms) for retry backoff. */
+  static RETRY_BASE = 1000;
+  /** Maximum delay cap (ms) for retry backoff. */
+  static RETRY_MAX = 30000;
+  /** Exponential backoff multiplier for retry delay. */
+  static RETRY_FACTOR = 2;
+
+  // ── Private state ──
+
+  private _operations = new Map<K, InternalOp<K, Meta>>();
+  private _snapshots = new Map<K, PendingOperation<Meta>>();
+  private _entriesCache: readonly PendingEntry<K, Meta>[] | null = null;
+
+  constructor() {
+    super();
+  }
+
+  // ── Readable state (reactive — auto-tracked by ViewModel getters) ──
+
+  /** Get the frozen status snapshot for an operation by ID, or null if not found. */
+  getStatus(id: K): PendingOperation<Meta> | null {
+    return this._snapshots.get(id) ?? null;
+  }
+
+  /** Whether an operation exists for the given ID. */
+  has(id: K): boolean {
+    return this._operations.has(id);
+  }
+
+  /** Number of operations (all statuses). */
+  get count(): number {
+    return this._operations.size;
+  }
+
+  /** Whether any operations are in-flight (active or retrying). */
+  get hasPending(): boolean {
+    for (const op of this._operations.values()) {
+      if (op.status !== 'failed') return true;
+    }
+    return false;
+  }
+
+  /** Whether any operations are in a failed state. */
+  get hasFailed(): boolean {
+    for (const op of this._operations.values()) {
+      if (op.status === 'failed') return true;
+    }
+    return false;
+  }
+
+  /** Number of operations in a failed state. */
+  get failedCount(): number {
+    let n = 0;
+    for (const op of this._operations.values()) {
+      if (op.status === 'failed') n++;
+    }
+    return n;
+  }
+
+  /** All operations as a frozen array of entries (id + snapshot). Cached until next mutation. */
+  get entries(): readonly PendingEntry<K, Meta>[] {
+    if (this._entriesCache === null) {
+      const result: PendingEntry<K, Meta>[] = [];
+      for (const [id, snapshot] of this._snapshots) {
+        result.push(Object.freeze({ ...snapshot, id }));
+      }
+      this._entriesCache = Object.freeze(result) as readonly PendingEntry<K, Meta>[];
+    }
+    return this._entriesCache;
+  }
+
+  // ── Core API ──
+
+  /**
+   * Enqueue an operation for the given ID. Fire-and-forget (synchronous return).
+   * If the same ID already has a pending operation, it is superseded (aborted).
+   */
+  enqueue(id: K, operation: string, execute: (signal: AbortSignal) => Promise<void>, meta?: Meta): void {
+    if (this.disposed) {
+      if (__DEV__) {
+        console.warn('[mvc-kit] Pending.enqueue() called after dispose — ignored.');
+      }
+      return;
+    }
+
+    // Supersede existing operation for this ID
+    const existing = this._operations.get(id);
+    if (existing) {
+      existing.abortController.abort();
+      if (existing.retryTimer !== null) {
+        clearTimeout(existing.retryTimer);
+      }
+    }
+
+    const op: InternalOp<K, Meta> = {
+      id,
+      operation,
+      execute,
+      status: 'active',
+      attempts: 0,
+      error: null,
+      errorCode: null,
+      nextRetryAt: null,
+      createdAt: Date.now(),
+      abortController: new AbortController(),
+      retryTimer: null,
+      meta: meta ?? null,
+    };
+
+    this._operations.set(id, op);
+    this._snapshot(op);
+    this.notify();
+
+    // Schedule processing via microtask (allows batching multiple enqueues)
+    queueMicrotask(() => this._process(id));
+  }
+
+  // ── Controls ──
+
+  /** Retry a failed operation. No-op if the operation is not in 'failed' status. */
+  retry(id: K): void {
+    if (this.disposed) {
+      if (__DEV__) {
+        console.warn('[mvc-kit] Pending.retry() called after dispose — ignored.');
+      }
+      return;
+    }
+
+    const op = this._operations.get(id);
+    if (!op || op.status !== 'failed') return;
+
+    op.attempts = 0;
+    op.error = null;
+    op.errorCode = null;
+    op.nextRetryAt = null;
+    op.abortController = new AbortController();
+    this._process(id);
+  }
+
+  /** Retry all failed operations. */
+  retryAll(): void {
+    if (this.disposed) {
+      if (__DEV__) {
+        console.warn('[mvc-kit] Pending.retryAll() called after dispose — ignored.');
+      }
+      return;
+    }
+
+    const failedIds: K[] = [];
+    for (const op of this._operations.values()) {
+      if (op.status === 'failed') failedIds.push(op.id);
+    }
+    for (const id of failedIds) {
+      this.retry(id);
+    }
+  }
+
+  /** Cancel an in-flight operation by ID. Aborts the signal, clears timers, and removes it. */
+  cancel(id: K): void {
+    const op = this._operations.get(id);
+    if (!op) return;
+
+    op.abortController.abort();
+    if (op.retryTimer !== null) {
+      clearTimeout(op.retryTimer);
+    }
+    this._operations.delete(id);
+    this._snapshots.delete(id);
+    this.notify();
+  }
+
+  /** Cancel all operations. */
+  cancelAll(): void {
+    for (const op of this._operations.values()) {
+      op.abortController.abort();
+      if (op.retryTimer !== null) {
+        clearTimeout(op.retryTimer);
+      }
+    }
+    this._operations.clear();
+    this._snapshots.clear();
+    this.notify();
+  }
+
+  /** Remove a failed operation without retrying. No-op if the operation is not in 'failed' status. */
+  dismiss(id: K): void {
+    const op = this._operations.get(id);
+    if (!op || op.status !== 'failed') return;
+
+    this._operations.delete(id);
+    this._snapshots.delete(id);
+    this.notify();
+  }
+
+  /** Remove all failed operations without retrying. */
+  dismissAll(): void {
+    const failedIds: K[] = [];
+    for (const op of this._operations.values()) {
+      if (op.status === 'failed') failedIds.push(op.id);
+    }
+    if (failedIds.length === 0) return;
+    for (const id of failedIds) {
+      this._operations.delete(id);
+      this._snapshots.delete(id);
+    }
+    this.notify();
+  }
+
+  // ── Hooks (overridable in subclass) ──
+
+  /**
+   * Determines whether an error is retryable. Override in a subclass to customize.
+   * Default: retries on network, timeout, and server_error codes.
+   * @protected
+   */
+  protected isRetryable(error: unknown): boolean {
+    const code = classifyError(error).code;
+    return code === 'network' || code === 'timeout' || code === 'server_error';
+  }
+
+  /** Called when an operation succeeds. Override in a subclass for side effects. @protected */
+  protected onConfirmed?(id: K, operation: string): void;
+  /** Called when an operation fails permanently. Override in a subclass for side effects. @protected */
+  protected onFailed?(id: K, operation: string, error: unknown): void;
+
+  // ── Lifecycle ──
+
+  /** Dispose: cancels all operations, then runs Trackable cleanup. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.cancelAll();
+    super.dispose();
+  }
+
+  // ── Notification override ──
+
+  /** @internal Invalidates entries cache before notifying subscribers. */
+  protected notify(): void {
+    this._entriesCache = null;
+    super.notify();
+  }
+
+  // ── Internals ──
+
+  private _snapshot(op: InternalOp<K, Meta>): void {
+    const ctor = this.constructor as typeof Pending;
+    this._snapshots.set(op.id, Object.freeze({
+      status: op.status,
+      operation: op.operation,
+      attempts: op.attempts,
+      maxRetries: ctor.MAX_RETRIES,
+      error: op.error,
+      errorCode: op.errorCode,
+      nextRetryAt: op.nextRetryAt,
+      createdAt: op.createdAt,
+      meta: op.meta,
+    }));
+  }
+
+  private _process(id: K): void {
+    const op = this._operations.get(id);
+    if (!op || this.disposed) return;
+
+    // Set active status
+    op.status = 'active';
+    op.attempts++;
+    op.error = null;
+    op.errorCode = null;
+    op.nextRetryAt = null;
+    this._snapshot(op);
+    this.notify();
+
+    op.execute(op.abortController.signal).then(
+      () => {
+        // Identity check: ignore if this op was superseded or cancelled
+        if (this._operations.get(id) !== op) return;
+        const operation = op.operation;
+        this._operations.delete(id);
+        this._snapshots.delete(id);
+        this.notify();
+        this.onConfirmed?.(id, operation);
+      },
+      (error: unknown) => {
+        // Identity check: ignore if this op was superseded or cancelled
+        if (this._operations.get(id) !== op) return;
+
+        // AbortError — remove silently (cancel or supersede)
+        if (isAbortError(error)) {
+          this._operations.delete(id);
+          this._snapshots.delete(id);
+          this.notify();
+          return;
+        }
+
+        const ctor = this.constructor as typeof Pending;
+        const classified = classifyError(error);
+
+        // Check if retryable and under max retries
+        if (this.isRetryable(error) && op.attempts < ctor.MAX_RETRIES) {
+          op.status = 'retrying';
+          const delay = this._calculateDelay(op.attempts - 1);
+          op.nextRetryAt = Date.now() + delay;
+          op.error = classified.message;
+          op.errorCode = classified.code;
+          this._snapshot(op);
+          this.notify();
+
+          op.retryTimer = setTimeout(() => {
+            op.retryTimer = null;
+            this._process(id);
+          }, delay);
+        } else {
+          // Non-retryable or max retries exceeded
+          op.status = 'failed';
+          op.error = classified.message;
+          op.errorCode = classified.code;
+          op.nextRetryAt = null;
+          this._snapshot(op);
+          this.notify();
+          this.onFailed?.(id, op.operation, error);
+        }
+      },
+    );
+  }
+
+  /** Computes retry backoff delay with jitter (Channel formula). @private */
+  private _calculateDelay(attempt: number): number {
+    const ctor = this.constructor as typeof Pending;
+    const capped = Math.min(
+      ctor.RETRY_BASE * Math.pow(ctor.RETRY_FACTOR, attempt),
+      ctor.RETRY_MAX,
+    );
+    return Math.random() * capped;
+  }
+}

package/src/PersistentCollection.md

@@ -0,0 +1,183 @@
+# PersistentCollection
+
+Abstract base for Collections that persist to external storage. Extends `Collection<T>` with delta tracking, debounced writes, and hydration.
+
+## Hierarchy
+
+```
+Collection<T>
+└── PersistentCollection<T>          (abstract — src/PersistentCollection.ts)
+    ├── WebStorageCollection<T>      (mvc-kit/web — localStorage/sessionStorage)
+    ├── IndexedDBCollection<T>       (mvc-kit/web — IndexedDB)
+    └── NativeCollection<T>          (mvc-kit/react-native — configurable backend)
+```
+
+## When to Use
+
+Use a PersistentCollection subclass when a singleton Collection should cache/repopulate from browser storage or device storage across sessions. Typical use cases:
+- Shopping carts (WebStorageCollection)
+- Offline message caches (IndexedDBCollection)
+- User preferences (NativeCollection)
+
+**Don't persist** ephemeral UI state (search results, selections) or high-churn data — persistence adds I/O overhead on every mutation.
+
+## Abstract Members (Subclasses Implement)
+
+```typescript
+protected abstract readonly storageKey: string;
+protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;
+protected abstract persistGetAll(): T[] | Promise<T[]>;
+protected abstract persistSet(items: T[]): void | Promise<void>;
+protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;
+protected abstract persistClear(): void | Promise<void>;
+```
+
+## Static Config
+
+```typescript
+static WRITE_DELAY = 0;  // Debounce ms for saves. 0 = immediate (default).
+```
+
+## Public API
+
+```typescript
+hydrate(): Promise<T[]>;                 // Load from storage, idempotent
+get hydrated(): boolean;                 // Whether storage data has been loaded
+clearStorage(): void | Promise<void>;    // Remove from storage AND clear in-memory
+```
+
+## Serialization Hooks
+
+```typescript
+protected serialize(items: T[]): string;              // Default: JSON.stringify
+protected deserialize(raw: string): T[];             // Default: JSON.parse
+```
+
+Used by string-based adapters (WebStorage, NativeCollection). IndexedDB uses structured cloning directly.
+
+## Error Handling
+
+```typescript
+protected onPersistError?(error: unknown): void;
+```
+
+Storage errors are caught internally. In DEV mode, errors are logged via `console.warn`. Override `onPersistError` for custom error handling.
+
+## Internal Mechanics
+
+### Delta Tracking
+
+PersistentCollection self-subscribes via `this.subscribe()`. The subscriber diffs `(current, prev)` to determine added, updated, and removed items using a Map-based O(n) comparison. Reference equality identifies unchanged items.
+
+| Collection Mutation | Persist Operation |
+|---|---|
+| `add(items)` | `persistSet(new items)` |
+| `upsert(items)` | `persistSet(changed/new items)` |
+| `update(id, changes)` | `persistSet([updated item])` |
+| `remove(ids)` | `persistRemove(removed IDs)` |
+| `reset(items)` | `persistClear()` + `persistSet(all new items)` |
+| `clear()` | `persistClear()` |
+
+### Debounce + Flush
+
+By default, `WRITE_DELAY = 0` flushes immediately (synchronously for sync adapters, microtask for async). Override to a positive value (e.g., `static override WRITE_DELAY = 100`) to coalesce rapid mutations into a single write — useful for high-frequency updates like drag-and-drop or real-time collaboration.
+
+### Hydration
+
+- **Sync adapters** (WebStorageCollection): Auto-hydrate lazily on first access. No `hydrate()` call needed.
+- **Async adapters** (IndexedDBCollection, NativeCollection): Require manual `hydrate()` call, typically in ViewModel's `onInit()`.
+
+`hydrate()` is idempotent — subsequent calls return current items.
+
+### Dispose
+
+Flushes any pending saves before calling `super.dispose()`.
+
+## Concrete Adapters
+
+### WebStorageCollection (`mvc-kit/web`)
+
+localStorage/sessionStorage. Auto-hydrates on first access. Blob strategy (full state as single JSON string).
+
+```typescript
+import { WebStorageCollection } from 'mvc-kit/web';
+
+class CartCollection extends WebStorageCollection<CartItem> {
+  protected readonly storageKey = 'cart';
+}
+
+class SessionCart extends WebStorageCollection<CartItem> {
+  static override STORAGE = 'session' as const;
+  protected readonly storageKey = 'session-cart';
+}
+```
+
+### IndexedDBCollection (`mvc-kit/web`)
+
+IndexedDB with per-item storage. Requires manual `hydrate()`. Each collection gets its own object store.
+
+```typescript
+import { IndexedDBCollection } from 'mvc-kit/web';
+
+class MessagesCollection extends IndexedDBCollection<Message> {
+  protected readonly storageKey = 'messages';
+  static MAX_SIZE = 500;
+}
+
+// ViewModel must call hydrate()
+class MessagesVM extends ViewModel {
+  private collection = singleton(MessagesCollection);
+  async onInit() {
+    await this.collection.hydrate();
+    if (this.collection.length === 0) this.load();
+  }
+}
+```
+
+### NativeCollection (`mvc-kit/react-native`)
+
+Configurable async key-value backend. Requires manual `hydrate()`. Blob strategy.
+
+```typescript
+import { NativeCollection } from 'mvc-kit/react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// Once at app startup:
+NativeCollection.configure({
+  getItem: (key) => AsyncStorage.getItem(key),
+  setItem: (key, value) => AsyncStorage.setItem(key, value),
+  removeItem: (key) => AsyncStorage.removeItem(key),
+});
+
+// Then:
+class TodosCollection extends NativeCollection<Todo> {
+  protected readonly storageKey = 'todos';
+}
+```
+
+Per-class override for edge cases (e.g., one collection uses SecureStore):
+
+```typescript
+class SecureCollection extends NativeCollection<Secret> {
+  protected readonly storageKey = 'secrets';
+  protected async getItem(key: string) { return SecureStore.getItem(key); }
+  protected async setItem(key: string, value: string) { await SecureStore.setItem(key, value); }
+  protected async removeItem(key: string) { await SecureStore.removeItem(key); }
+}
+```
+
+## Gotchas
+
+1. **Async hydration**: For IndexedDB and NativeCollection, `hydrate()` must be called manually (typically in ViewModel's `onInit()`). DEV warning fires on `items` access before hydration.
+2. **Non-singleton persistence**: Every mount triggers a full read and every mutation triggers a write. Use non-singleton only for lightweight, infrequently-changing data.
+3. **Optimistic timing**: With immediate writes (default), optimistic state is persisted before the server round-trip completes. If the app crashes between the write and rollback, storage will contain the optimistic data. If this matters, consider `static override WRITE_DELAY = 100` to delay the write past typical rollback timing.
+4. **WebStorage quota**: localStorage has a ~5MB limit. DEV warning on `QuotaExceededError`. Use IndexedDBCollection for larger datasets.
+
+## Method Binding
+
+All public methods are auto-bound in the constructor. You can pass them point-free as callbacks without losing `this` context:
+
+```tsx
+const { add, upsert } = collection;
+channel.on("update", upsert); // point-free works
+```