mvc-kit 2.13.0 → 2.13.1

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);

package/examples/primitive/trackable.ts

@@ -0,0 +1,225 @@
+import { Trackable, ViewModel, bindPublicMethods } from 'mvc-kit';
+
+// Trackable: Base class for custom reactive objects
+//
+// Provides the subscribable + disposable + auto-bind foundation that
+// all composable helpers (Sorting, Selection, Feed, Pagination, Pending)
+// are built on. Extend it to build your own reactive objects that
+// integrate with ViewModel's auto-tracking system.
+//
+// What Trackable provides:
+//   - subscribe() / notify() for change notifications
+//   - dispose() / disposeSignal / addCleanup() for lifecycle
+//   - Auto-bound public methods (point-free callbacks)
+//
+// What Trackable does NOT provide:
+//   - State management (no set(), no state getter)
+//   - Computed getters / memoization
+//   - Async tracking (no vm.async)
+//   - init() lifecycle (implement Initializable yourself if needed)
+
+// --- Example 1: Custom RPC query wrapper ---
+
+interface RPCResponse<T> {
+  data: T;
+  success: boolean;
+  code: number;
+}
+
+class RPCQuery<Args, Data> extends Trackable {
+  private _data: Data | undefined = undefined;
+  private _loading = false;
+  private _error: string | null = null;
+  private _callCounter = 0;
+
+  // Computed getters — auto-tracked when read inside ViewModel getters
+  get data(): Data | undefined { return this._data; }
+  get loading(): boolean { return this._loading; }
+  get error(): string | null { return this._error; }
+
+  constructor(private _endpoint: string) {
+    super();
+  }
+
+  async call(args?: Args): Promise<RPCResponse<Data>> {
+    if (this.disposed) throw new Error('RPCQuery: call() after dispose');
+
+    const callId = ++this._callCounter;
+    this._loading = true;
+    this._error = null;
+    this.notify();
+
+    try {
+      // Simulate an RPC call
+      const response = await simulateRPC<Data>(this._endpoint, args);
+
+      // Stale-call guard: only apply if this is still the latest call
+      if (!this.disposed && callId === this._callCounter) {
+        this._data = response.data;
+        this._loading = false;
+        this._error = null;
+        this.notify();
+      }
+
+      return response;
+    } catch (err) {
+      if (!this.disposed && callId === this._callCounter) {
+        this._loading = false;
+        this._error = (err as Error).message;
+        this.notify();
+      }
+      throw err;
+    }
+  }
+
+  clear() {
+    this._data = undefined;
+    this._error = null;
+    this.notify();
+  }
+}
+
+// Simulate RPC
+async function simulateRPC<T>(_endpoint: string, _args?: unknown): Promise<RPCResponse<T>> {
+  await new Promise(r => setTimeout(r, 100));
+  return { data: [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }] as T, success: true, code: 200 };
+}
+
+// --- Basic usage ---
+
+const query = new RPCQuery<{ search: string }, { id: string; name: string }[]>('Users.Search');
+
+// Subscribe to changes
+query.subscribe(() => {
+  console.log(`Query state: loading=${query.loading}, data=${query.data?.length ?? 0} items, error=${query.error}`);
+});
+
+console.log('Loading:', query.loading); // false
+console.log('Data:', query.data);       // undefined
+
+await query.call({ search: 'alice' });
+// Query state: loading=true, data=0 items, error=null
+// Query state: loading=false, data=2 items, error=null
+
+console.log('Data after call:', query.data); // [{ id: '1', name: 'Alice' }, ...]
+
+// --- Method binding (point-free) ---
+
+const { call, clear, dispose } = query;
+// These work without wrapper functions — auto-bound by Trackable
+clear(); // Resets data
+
+// --- Dispose lifecycle ---
+
+console.log('Disposed:', query.disposed);          // false
+console.log('Signal aborted:', query.disposeSignal.aborted); // false
+
+dispose();
+
+console.log('Disposed:', query.disposed);          // true
+console.log('Signal aborted:', query.disposeSignal.aborted); // true
+
+// --- Example 2: ViewModel auto-tracking integration ---
+
+interface User {
+  id: string;
+  name: string;
+}
+
+class UsersViewModel extends ViewModel {
+  // RPCQuery as a property — auto-tracked by ViewModel's dependency system
+  readonly users = new RPCQuery<void, User[]>('Users.List');
+
+  // This getter auto-invalidates when users.notify() fires
+  get userCount(): number {
+    return this.users.data?.length ?? 0;
+  }
+
+  get isLoading(): boolean {
+    return this.users.loading;
+  }
+
+  get userNames(): string[] {
+    return (this.users.data ?? []).map(u => u.name);
+  }
+
+  async onInit() {
+    await this.users.call();
+  }
+}
+
+const vm = new UsersViewModel();
+vm.init();
+
+// After init, the RPCQuery fires and getters update automatically
+await new Promise(r => setTimeout(r, 200));
+
+console.log('User count:', vm.userCount); // 2
+console.log('User names:', vm.userNames); // ['Alice', 'Bob']
+
+vm.dispose();
+
+// --- Example 3: addCleanup for external subscriptions ---
+
+class LivePrice extends Trackable {
+  private _price = 0;
+
+  get price(): number { return this._price; }
+
+  constructor(symbol: string) {
+    super();
+
+    // Simulate a WebSocket price subscription
+    const interval = setInterval(() => {
+      this._price = Math.round(Math.random() * 10000) / 100;
+      this.notify();
+    }, 1000);
+
+    // addCleanup runs on dispose — auto-cleanup
+    this.addCleanup(() => {
+      clearInterval(interval);
+      console.log(`Unsubscribed from ${symbol} price feed`);
+    });
+  }
+
+  protected onDispose() {
+    console.log('LivePrice disposed');
+  }
+}
+
+const btcPrice = new LivePrice('BTC');
+
+const unsub = btcPrice.subscribe(() => {
+  console.log(`BTC: $${btcPrice.price}`);
+});
+
+// Let it tick a couple times
+await new Promise(r => setTimeout(r, 2500));
+
+btcPrice.dispose(); // Clears interval, logs "Unsubscribed...", logs "LivePrice disposed"
+unsub(); // Safe to call after dispose — no-op
+
+// --- Example 4: bindPublicMethods standalone utility ---
+//
+// For classes that don't extend Trackable but still want point-free methods.
+
+class Formatter {
+  constructor(private locale: string) {
+    bindPublicMethods(this);
+  }
+
+  formatCurrency(amount: number): string {
+    return new Intl.NumberFormat(this.locale, { style: 'currency', currency: 'USD' }).format(amount);
+  }
+
+  formatDate(date: Date): string {
+    return new Intl.DateTimeFormat(this.locale).format(date);
+  }
+}
+
+const fmt = new Formatter('en-US');
+
+// Destructured methods work — bound by bindPublicMethods
+const { formatCurrency, formatDate } = fmt;
+console.log(formatCurrency(1234.56));       // $1,234.56
+console.log(formatDate(new Date(2025, 0, 1))); // 1/1/2025

package/examples/primitive/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": false,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": [],
+    "baseUrl": ".",
+    "paths": {
+      "mvc-kit": ["../../src/index.ts"]
+    }
+  },
+  "include": ["."]
+}