mvc-kit 2.13.0 → 2.13.2

package/examples/primitive/pending.ts

@@ -0,0 +1,189 @@
+import { Pending, Resource, singleton, teardownAll } from 'mvc-kit';
+
+// Pending: Per-item operation queue with retry and status tracking
+//
+// A subscribable helper that manages async operations per item ID,
+// with automatic exponential backoff retries for transient errors.
+// Designed to live on a singleton Resource (NOT on a ViewModel).
+//
+// Typical use case: sending messages, submitting forms, processing
+// items where each operation needs individual retry/cancel controls.
+
+// --- Entity types ---
+
+interface Message {
+  id: string;
+  text: string;
+  senderId: string;
+}
+
+// --- Resource with Pending ---
+
+class MessagesResource extends Resource<Message> {
+  // Pending lives on the Resource so it survives ViewModel unmounts
+  readonly sending = new Pending<string>();
+
+  async send(message: Message) {
+    // enqueue: fire-and-forget with automatic retry on failure
+    this.sending.enqueue(
+      message.id,          // unique key for this operation
+      'send',              // operation name (for display/debugging)
+      async () => {        // the execute callback
+        await fakeSend(message);
+        this.add(message); // add to collection on success
+      },
+    );
+  }
+
+  protected onDispose() {
+    this.sending.dispose();
+  }
+}
+
+// --- Basic Pending usage (standalone) ---
+
+const pending = new Pending<string>();
+
+// Subscribe to status changes
+pending.subscribe(() => {
+  console.log(`Pending: ${pending.count} operations, failed=${pending.failedCount}`);
+});
+
+// Enqueue an operation
+pending.enqueue(
+  'task-1',
+  'upload',
+  async () => {
+    // Simulated async work
+    await delay(100);
+    console.log('Upload complete!');
+  },
+);
+
+console.log('Has pending:', pending.hasPending); // true
+
+// Check individual status
+const status = pending.getStatus('task-1');
+console.log('Status:', status?.status);     // 'active'
+console.log('Attempts:', status?.attempts); // 1
+
+// Wait for completion
+await delay(200);
+console.log('After completion count:', pending.count); // 0 (removed on success)
+
+// --- Retry behavior ---
+
+let failCount = 0;
+const retryPending = new Pending<string>();
+
+retryPending.subscribe(() => {
+  const entry = retryPending.getStatus('flaky-op');
+  if (entry) {
+    console.log(`Flaky op: status=${entry.status}, attempts=${entry.attempts}`);
+  }
+});
+
+retryPending.enqueue(
+  'flaky-op',
+  'sync',
+  async () => {
+    failCount++;
+    if (failCount < 3) {
+      // Transient errors (network, timeout, server_error) trigger retries
+      const err = new Error('Connection failed');
+      (err as any).code = 'network';
+      throw err;
+    }
+    console.log('Flaky operation succeeded on attempt', failCount);
+  },
+);
+
+// Wait for retries to complete
+await delay(5000);
+
+// --- Manual controls ---
+
+const controlPending = new Pending<string>();
+
+// Enqueue a long-running operation
+controlPending.enqueue(
+  'slow-task',
+  'process',
+  async () => {
+    await delay(10000); // very slow
+  },
+);
+
+// Cancel an in-flight operation
+controlPending.cancel('slow-task');
+console.log('After cancel:', controlPending.has('slow-task')); // false
+
+// Enqueue one that will fail
+controlPending.enqueue(
+  'will-fail',
+  'doomed',
+  async () => {
+    const err = new Error('Fatal error');
+    (err as any).code = 'validation'; // non-retryable error code
+    throw err;
+  },
+);
+
+await delay(200);
+
+console.log('Has failed:', controlPending.hasFailed);       // true
+console.log('Failed count:', controlPending.failedCount);    // 1
+
+// Dismiss a failed operation (remove without retrying)
+controlPending.dismiss('will-fail');
+console.log('After dismiss:', controlPending.count); // 0
+
+// --- Entries (iterate all operations) ---
+
+const listPending = new Pending<string>();
+
+listPending.enqueue('a', 'upload', () => delay(500));
+listPending.enqueue('b', 'upload', () => delay(500));
+listPending.enqueue('c', 'upload', () => delay(500));
+
+console.log('All entries:', listPending.entries.map(e => e.id)); // ['a', 'b', 'c']
+
+// Cancel all at once
+listPending.cancelAll();
+console.log('After cancelAll:', listPending.count); // 0
+
+// --- Resource integration pattern ---
+
+const resource = singleton(MessagesResource);
+await resource.init();
+
+// Send messages — each gets independent retry/cancel
+resource.send({ id: 'msg-1', text: 'Hello!', senderId: 'user-1' });
+resource.send({ id: 'msg-2', text: 'How are you?', senderId: 'user-1' });
+
+console.log('Sending count:', resource.sending.count);        // 2
+console.log('msg-1 status:', resource.sending.getStatus('msg-1')?.status); // 'active'
+
+await delay(200);
+
+console.log('Messages in collection:', resource.length); // 2 (both sent)
+console.log('Sending count after:', resource.sending.count); // 0
+
+// Cleanup
+pending.dispose();
+retryPending.dispose();
+controlPending.dispose();
+listPending.dispose();
+resource.dispose();
+teardownAll();
+
+// --- Helpers ---
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function fakeSend(message: Message): Promise<void> {
+  await delay(100);
+  console.log(`Sent: "${message.text}"`);
+}

package/examples/primitive/persistent-collection.ts

@@ -0,0 +1,116 @@
+import { PersistentCollection } from 'mvc-kit';
+
+// PersistentCollection: Collection + automatic storage persistence
+//
+// Abstract base class that extends Collection with delta tracking,
+// debounced writes, and hydration. Subclass it and implement the
+// persist* methods to connect to your storage backend.
+//
+// Concrete adapters are provided for common platforms:
+//   - WebStorageCollection  (mvc-kit/web)    — localStorage/sessionStorage
+//   - IndexedDBCollection   (mvc-kit/web)    — IndexedDB per-item storage
+//   - NativeCollection      (mvc-kit/react-native) — configurable backend
+//
+// This example shows the abstract contract. See the platform-specific
+// adapters for ready-to-use implementations.
+
+// --- Entity type ---
+
+interface CartItem {
+  id: string;
+  name: string;
+  quantity: number;
+  price: number;
+}
+
+// --- Custom PersistentCollection (in-memory storage for demo) ---
+
+// In-memory store simulating a storage backend
+const fakeStorage = new Map<string, string>();
+
+class CartCollection extends PersistentCollection<CartItem> {
+  // Unique key for this collection in storage
+  protected readonly storageKey = 'cart';
+
+  // --- Implement the abstract persist methods ---
+
+  protected persistGet(id: string): CartItem | null {
+    const raw = fakeStorage.get(this.storageKey);
+    if (!raw) return null;
+    const items: CartItem[] = this.deserialize(raw);
+    return items.find(i => i.id === id) ?? null;
+  }
+
+  protected persistGetAll(): CartItem[] {
+    const raw = fakeStorage.get(this.storageKey);
+    return raw ? this.deserialize(raw) : [];
+  }
+
+  protected persistSet(items: CartItem[]): void {
+    // Merge new/updated items into existing storage
+    const existing = this.persistGetAll();
+    const map = new Map(existing.map(i => [i.id, i]));
+    for (const item of items) {
+      map.set(item.id, item);
+    }
+    fakeStorage.set(this.storageKey, this.serialize([...map.values()]));
+    console.log('[Storage] Saved', map.size, 'items');
+  }
+
+  protected persistRemove(ids: string[]): void {
+    const existing = this.persistGetAll();
+    const filtered = existing.filter(i => !ids.includes(i.id));
+    fakeStorage.set(this.storageKey, this.serialize(filtered));
+    console.log('[Storage] Removed', ids.length, 'items');
+  }
+
+  protected persistClear(): void {
+    fakeStorage.delete(this.storageKey);
+    console.log('[Storage] Cleared');
+  }
+
+  // Optional: custom error handling for storage failures
+  protected onPersistError(error: unknown) {
+    console.error('[Storage] Persist failed:', error);
+  }
+}
+
+// --- Usage ---
+
+const cart = new CartCollection();
+
+// hydrate() loads data from storage into the collection.
+// Idempotent — safe to call multiple times.
+// For sync adapters (like WebStorageCollection), hydration is automatic.
+// For async adapters (IndexedDB, NativeCollection), call hydrate() manually.
+await cart.hydrate();
+
+console.log('Hydrated:', cart.hydrated); // true
+console.log('Items after hydrate:', cart.length); // 0 (empty storage)
+
+// Subscribe to changes
+cart.subscribe((items) => {
+  console.log(`Cart: ${items.length} items, total $${items.reduce((s, i) => s + i.price * i.quantity, 0).toFixed(2)}`);
+});
+
+// All Collection mutations automatically persist to storage
+cart.add(
+  { id: '1', name: 'Widget', quantity: 2, price: 9.99 },
+  { id: '2', name: 'Gizmo', quantity: 1, price: 24.99 },
+);
+
+// Verify storage was written
+console.log('Storage contents:', fakeStorage.get('cart'));
+
+// Update persists the change
+cart.update('1', { quantity: 5 });
+
+// Remove persists the deletion
+cart.remove('2');
+
+// clearStorage() removes from storage AND clears in-memory
+cart.clearStorage();
+console.log('After clearStorage:', cart.length); // 0
+
+// Cleanup — flushes any pending writes before disposing
+cart.dispose();

package/examples/primitive/resource.ts

@@ -0,0 +1,114 @@
+import { Resource, singleton, teardownAll } from 'mvc-kit';
+
+// Resource: Collection + async tracking + lifecycle
+//
+// Use Resource when you need a shared data cache with built-in
+// loading/error state for your API calls. It extends Collection
+// with init()/dispose() lifecycle and automatic async method tracking.
+//
+// If you already have a typed API client (tRPC, GraphQL codegen, etc.),
+// call it directly from the Resource — no Service wrapper needed.
+
+// --- Entity type ---
+
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+  category: string;
+}
+
+// --- Resource definition ---
+
+class ProductsResource extends Resource<Product> {
+  // All async methods are automatically tracked after init().
+  // Access loading/error state via resource.async.methodName
+
+  async loadAll() {
+    // Pass disposeSignal to cancel in-flight requests on teardown.
+    // In production, this would call your API client or fetch().
+    const products = await fakeFetch<Product[]>('/api/products', this.disposeSignal);
+    this.reset(products);
+  }
+
+  async loadByCategory(category: string) {
+    const products = await fakeFetch<Product[]>(
+      `/api/products?category=${category}`,
+      this.disposeSignal,
+    );
+    // upsert: add new items or replace existing ones by ID (preserves other items)
+    this.upsert(...products);
+  }
+
+  async create(data: Omit<Product, 'id'>) {
+    const product = await fakeFetch<Product>('/api/products', this.disposeSignal);
+    this.add(product);
+    return product;
+  }
+
+  // Lifecycle hook: called after init()
+  protected onInit() {
+    // Smart-init: only load if the collection is empty.
+    // Prevents redundant fetches when multiple consumers share the singleton.
+    if (this.length === 0) this.loadAll();
+  }
+}
+
+// --- Usage ---
+
+const products = singleton(ProductsResource);
+await products.init(); // wraps methods for async tracking, calls onInit()
+
+// Async tracking — no manual loading/error flags needed
+console.log('Loading:', products.async.loadAll.loading); // true (load started in onInit)
+
+// Wait for load to complete
+await products.loadAll();
+
+console.log('Loading:', products.async.loadAll.loading); // false
+console.log('Error:', products.async.loadAll.error); // null
+console.log('Total:', products.length); // 3
+
+// All Collection methods are available
+console.log('Items:', products.items);
+console.log('Get by id:', products.get('1')?.name);
+console.log('Filter:', products.filter(p => p.price > 20).length);
+
+// Subscribe to data changes (inherited from Collection)
+products.subscribe((items) => {
+  console.log(`Products changed: ${items.length} items`);
+});
+
+// Subscribe to async state changes (loading/error)
+products.subscribeAsync(() => {
+  console.log('Async state changed:', products.async.loadAll);
+});
+
+// Load more data — upsert merges without duplicates
+await products.loadByCategory('electronics');
+
+// Cleanup
+products.dispose();
+teardownAll();
+
+// --- Fake API helper ---
+
+function fakeFetch<T>(_url: string, signal?: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      resolve([
+        { id: '1', name: 'Widget', price: 9.99, category: 'gadgets' },
+        { id: '2', name: 'Gizmo', price: 24.99, category: 'gadgets' },
+        { id: '3', name: 'Doohickey', price: 49.99, category: 'electronics' },
+      ] as unknown as T);
+    }, 100);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  });
+}

package/examples/primitive/selection.ts

@@ -0,0 +1,96 @@
+import { Selection } from 'mvc-kit';
+
+// Selection: Key-based selection set with toggle and select-all
+//
+// A subscribable helper that manages a Set of selected keys. Designed
+// to be a property on a ViewModel — auto-tracked so ViewModel getters
+// that read selection state recompute automatically.
+//
+// Methods are auto-bound, so they can be passed point-free as callbacks
+// (e.g., onChange={selection.toggle}).
+
+// --- Entity type ---
+
+interface File {
+  id: string;
+  name: string;
+  size: number;
+}
+
+const files: File[] = [
+  { id: '1', name: 'report.pdf', size: 2400 },
+  { id: '2', name: 'photo.jpg', size: 5100 },
+  { id: '3', name: 'notes.txt', size: 120 },
+  { id: '4', name: 'backup.zip', size: 98000 },
+];
+
+const allIds = files.map(f => f.id);
+
+// --- Basic usage ---
+
+const selection = new Selection<string>();
+
+// Subscribe to selection changes
+selection.subscribe(() => {
+  console.log('Selected:', [...selection.selected]);
+});
+
+// Read current state
+console.log('Count:', selection.count);           // 0
+console.log('Has selection:', selection.hasSelection); // false
+
+// --- Toggle ---
+
+selection.toggle('1');
+console.log('After toggle 1:', selection.isSelected('1')); // true
+
+selection.toggle('3');
+console.log('Count:', selection.count); // 2
+
+selection.toggle('1'); // toggle off
+console.log('After toggle 1 again:', selection.isSelected('1')); // false
+console.log('Count:', selection.count); // 1
+
+// --- Select / Deselect ---
+
+selection.select('1', '2', '4');
+console.log('After select:', selection.count); // 4 (3 already had item 3)
+
+selection.deselect('2', '4');
+console.log('After deselect:', selection.count); // 2 (items 1 and 3)
+
+// --- Toggle all ---
+
+// If not all are selected, selects all
+selection.toggleAll(allIds);
+console.log('After toggleAll (select):', selection.count); // 4
+
+// If all are selected, deselects all
+selection.toggleAll(allIds);
+console.log('After toggleAll (deselect):', selection.count); // 0
+
+// --- Set (atomic replace) ---
+
+selection.set('2', '3');
+console.log('After set:', [...selection.selected]); // ['2', '3']
+
+// --- Filter items by selection ---
+
+selection.set('1', '4');
+const selectedFiles = selection.selectedFrom(files, f => f.id);
+console.log('Selected files:', selectedFiles.map(f => f.name));
+// ['report.pdf', 'backup.zip']
+
+// --- Point-free callbacks ---
+
+// Methods are auto-bound, so you can pass them directly:
+//   <input onChange={selection.toggle} />
+//   <button onClick={() => selection.toggleAll(allIds)} />
+const toggleFn = selection.toggle; // no .bind() needed
+toggleFn('3');
+console.log('After point-free toggle:', selection.isSelected('3')); // true
+
+// --- Clear ---
+
+selection.clear();
+console.log('After clear:', selection.count); // 0

package/examples/primitive/sorting.ts

@@ -0,0 +1,112 @@
+import { Sorting } from 'mvc-kit';
+
+// Sorting: Multi-column sort state with a comparator pipeline
+//
+// A subscribable helper that manages sort descriptors and applies them
+// to arrays. Designed to be a property on a ViewModel — auto-tracked
+// so ViewModel getters that read sorting state recompute automatically.
+//
+// Three-click cycle: unsorted → asc → desc → removed.
+
+// --- Entity type ---
+
+interface Employee {
+  id: string;
+  name: string;
+  department: string;
+  salary: number;
+  startDate: string;
+}
+
+const employees: Employee[] = [
+  { id: '1', name: 'Alice', department: 'Engineering', salary: 120000, startDate: '2020-03-15' },
+  { id: '2', name: 'Bob', department: 'Marketing', salary: 85000, startDate: '2021-06-01' },
+  { id: '3', name: 'Carol', department: 'Engineering', salary: 140000, startDate: '2019-01-10' },
+  { id: '4', name: 'Dave', department: 'Marketing', salary: 92000, startDate: '2022-09-20' },
+  { id: '5', name: 'Eve', department: 'Engineering', salary: 110000, startDate: '2023-02-01' },
+];
+
+// --- Basic usage ---
+
+const sorting = new Sorting<Employee>();
+
+// Subscribe to sort state changes
+sorting.subscribe(() => {
+  console.log('Sort changed:', sorting.sorts);
+});
+
+// Read current state
+console.log('Key:', sorting.key);           // null (no sort active)
+console.log('Direction:', sorting.direction); // 'asc' (default)
+
+// Toggle cycles: unsorted → asc → desc → removed
+sorting.toggle('name');
+console.log('After first toggle:', sorting.key, sorting.direction); // 'name', 'asc'
+
+sorting.toggle('name');
+console.log('After second toggle:', sorting.key, sorting.direction); // 'name', 'desc'
+
+sorting.toggle('name');
+console.log('After third toggle:', sorting.key); // null (removed)
+
+// --- Apply sort pipeline ---
+
+sorting.setSort('salary', 'desc');
+
+const bySalary = sorting.apply(employees);
+console.log('By salary (desc):', bySalary.map(e => `${e.name}: $${e.salary}`));
+// Carol: $140000, Alice: $120000, Eve: $110000, Dave: $92000, Bob: $85000
+
+// --- Query methods ---
+
+console.log('Is salary sorted:', sorting.isSorted('salary'));     // true
+console.log('Salary direction:', sorting.directionOf('salary'));   // 'desc'
+console.log('Name direction:', sorting.directionOf('name'));       // null (not sorted)
+
+// --- Multi-column sort ---
+
+// setSorts replaces all descriptors
+sorting.setSorts([
+  { key: 'department', direction: 'asc' },
+  { key: 'salary', direction: 'desc' },
+]);
+
+const multiSorted = sorting.apply(employees);
+console.log('Multi-sort (dept asc, salary desc):');
+multiSorted.forEach(e => console.log(`  ${e.department} — ${e.name}: $${e.salary}`));
+// Engineering — Carol: $140000
+// Engineering — Alice: $120000
+// Engineering — Eve: $110000
+// Marketing — Dave: $92000
+// Marketing — Bob: $85000
+
+console.log('Salary index in sort list:', sorting.indexOf('salary')); // 1
+
+// --- Custom comparator ---
+
+// Custom compareFn for special types (dates, locale-specific strings, etc.)
+sorting.setSort('startDate', 'asc');
+
+const byDate = sorting.apply(employees, (a, b, key, dir) => {
+  const aVal = a[key as keyof Employee];
+  const bVal = b[key as keyof Employee];
+  // Date strings sort correctly with localeCompare, but you could parse to Date
+  const cmp = String(aVal).localeCompare(String(bVal));
+  return dir === 'asc' ? cmp : -cmp;
+});
+console.log('By start date:', byDate.map(e => `${e.name} (${e.startDate})`));
+
+// --- Initial sorts via constructor ---
+
+const preConfigured = new Sorting<Employee>({
+  sorts: [{ key: 'name', direction: 'asc' }],
+});
+console.log('Pre-configured key:', preConfigured.key); // 'name'
+
+const sorted = preConfigured.apply(employees);
+console.log('Pre-sorted:', sorted.map(e => e.name)); // Alice, Bob, Carol, Dave, Eve
+
+// --- Reset ---
+
+sorting.reset();
+console.log('After reset key:', sorting.key); // null

package/examples/primitive/timer.ts

@@ -0,0 +1,58 @@
+import { ViewModel } from 'mvc-kit';
+
+// ViewModel: addCleanup pattern for resource management
+//
+// addCleanup() registers teardown callbacks that fire on dispose().
+// Use it for intervals, event listeners, or any resource that needs
+// explicit cleanup. React hooks (useLocal, useSingleton) auto-call
+// dispose() on unmount, so cleanups run automatically.
+
+interface TimerState {
+  elapsed: number;
+  running: boolean;
+}
+
+class TimerViewModel extends ViewModel<TimerState> {
+  private intervalId?: ReturnType<typeof setInterval>;
+
+  start() {
+    if (this.state.running) return;
+
+    this.set({ running: true });
+    this.intervalId = setInterval(() => {
+      this.set(prev => ({ elapsed: prev.elapsed + 1 }));
+    }, 1000);
+
+    // addCleanup registers a teardown callback that fires on dispose()
+    // Safe to call multiple times — clearInterval on an already-cleared ID is a no-op
+    this.addCleanup(() => clearInterval(this.intervalId));
+  }
+
+  stop() {
+    if (!this.state.running) return;
+
+    clearInterval(this.intervalId);
+    this.intervalId = undefined;
+    this.set({ running: false });
+  }
+
+  reset() {
+    this.stop();
+    this.set({ elapsed: 0 });
+  }
+}
+
+// Usage
+const timer = new TimerViewModel({ elapsed: 0, running: false });
+
+timer.subscribe((state) => {
+  console.log(`Timer: ${state.elapsed}s (${state.running ? 'running' : 'stopped'})`);
+});
+
+timer.start();
+
+// Stop after 5 seconds
+setTimeout(() => {
+  timer.stop();
+  timer.dispose();
+}, 5000);