mvc-kit 2.13.0 → 2.13.1

package/examples/primitive/feed.ts

@@ -0,0 +1,162 @@
+import { Feed } from 'mvc-kit';
+
+// Feed: Cursor-based pagination for infinite scroll / load-more
+//
+// A subscribable helper that accumulates items across pages using
+// cursor-based server pagination. Tracks cursor position, hasMore
+// status, and the growing item list.
+//
+// Designed to be a property on a ViewModel — auto-tracked so
+// ViewModel getters that read feed state recompute automatically.
+//
+// Typical flow:
+//   1. ViewModel calls API with feed.cursor
+//   2. API returns { items, hasMore, cursor }
+//   3. ViewModel calls feed.appendPage(result)
+//   4. Repeat until hasMore is false
+
+// --- Entity type ---
+
+interface Post {
+  id: string;
+  title: string;
+  createdAt: string;
+}
+
+// --- Simulated API ---
+
+function fakeFetchPosts(cursor: string | null): {
+  items: Post[];
+  hasMore: boolean;
+  cursor: string;
+} {
+  const pages: Record<string, { items: Post[]; hasMore: boolean; cursor: string }> = {
+    initial: {
+      items: [
+        { id: '1', title: 'First post', createdAt: '2024-01-01' },
+        { id: '2', title: 'Second post', createdAt: '2024-01-02' },
+        { id: '3', title: 'Third post', createdAt: '2024-01-03' },
+      ],
+      hasMore: true,
+      cursor: 'page2',
+    },
+    page2: {
+      items: [
+        { id: '4', title: 'Fourth post', createdAt: '2024-01-04' },
+        { id: '5', title: 'Fifth post', createdAt: '2024-01-05' },
+      ],
+      hasMore: true,
+      cursor: 'page3',
+    },
+    page3: {
+      items: [
+        { id: '6', title: 'Sixth post', createdAt: '2024-01-06' },
+      ],
+      hasMore: false,
+      cursor: 'end',
+    },
+  };
+
+  const key = cursor ?? 'initial';
+  return pages[key]!;
+}
+
+// --- Basic usage ---
+
+const feed = new Feed<Post>();
+
+// Subscribe to feed state changes
+feed.subscribe(() => {
+  console.log(`Feed: ${feed.count} items, hasMore=${feed.hasMore}, cursor=${feed.cursor}`);
+});
+
+// Initial state
+console.log('Cursor:', feed.cursor);   // null
+console.log('Has more:', feed.hasMore); // true
+console.log('Items:', feed.count);      // 0
+
+// --- Load first page ---
+
+const page1 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page1);
+
+console.log('After page 1:', feed.count);   // 3
+console.log('Cursor:', feed.cursor);         // 'page2'
+console.log('Has more:', feed.hasMore);      // true
+
+// --- Load next page (items accumulate) ---
+
+const page2 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page2);
+
+console.log('After page 2:', feed.count);   // 5
+console.log('Cursor:', feed.cursor);         // 'page3'
+
+// --- Load final page ---
+
+const page3 = fakeFetchPosts(feed.cursor);
+feed.appendPage(page3);
+
+console.log('After page 3:', feed.count);   // 6
+console.log('Has more:', feed.hasMore);      // false (no more pages)
+
+// Access all accumulated items
+console.log('All items:', feed.items.map(p => p.title));
+
+// --- Prepend (for chat UIs / newest-first feeds) ---
+
+const chatFeed = new Feed<Post>();
+
+chatFeed.appendPage({
+  items: [
+    { id: 'c1', title: 'Latest message', createdAt: '2024-01-10' },
+    { id: 'c2', title: 'Previous message', createdAt: '2024-01-09' },
+  ],
+  hasMore: true,
+  cursor: 'older',
+});
+
+// Prepend older messages at the top (e.g., scrolling up in a chat)
+chatFeed.prependPage({
+  items: [
+    { id: 'c3', title: 'Oldest message', createdAt: '2024-01-08' },
+  ],
+  hasMore: false,
+  cursor: 'start',
+});
+
+console.log('Chat order:', chatFeed.items.map(p => p.title));
+// ['Oldest message', 'Latest message', 'Previous message']
+
+// --- Push items without affecting cursor ---
+
+feed.push({ id: '7', title: 'Optimistic post', createdAt: '2024-01-07' });
+console.log('After push:', feed.count); // 7
+
+// --- Filter items ---
+
+feed.filter(p => p.id !== '7'); // remove the optimistic post
+console.log('After filter:', feed.count); // 6
+
+// --- Pull-to-refresh (replacePage) ---
+
+feed.replacePage({
+  items: [
+    { id: 'r1', title: 'Refreshed post 1', createdAt: '2024-02-01' },
+    { id: 'r2', title: 'Refreshed post 2', createdAt: '2024-02-02' },
+  ],
+  hasMore: true,
+  cursor: 'refreshed-page2',
+});
+console.log('After replacePage:', feed.count); // 2 (replaced all)
+
+// --- setResult (update cursor/hasMore only) ---
+
+feed.setResult({ hasMore: false, cursor: 'final' });
+console.log('After setResult hasMore:', feed.hasMore); // false
+console.log('Items unchanged:', feed.count);           // 2
+
+// --- Reset ---
+
+feed.reset();
+console.log('After reset:', feed.count, feed.cursor, feed.hasMore); // 0, null, true

package/examples/primitive/model.ts

@@ -0,0 +1,82 @@
+import { Model } from 'mvc-kit';
+
+// Model: Reactive entity with validation and dirty tracking
+
+interface UserFormState {
+  name: string;
+  email: string;
+  age: number;
+}
+
+class UserFormModel extends Model<UserFormState> {
+  setName(name: string) {
+    this.set({ name });
+  }
+
+  setEmail(email: string) {
+    this.set({ email });
+  }
+
+  setAge(age: number) {
+    this.set({ age });
+  }
+
+  // Override to provide validation logic
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+
+    if (!state.name.trim()) {
+      errors.name = 'Name is required';
+    }
+
+    if (!state.email.includes('@')) {
+      errors.email = 'Invalid email address';
+    }
+
+    if (state.age < 0 || state.age > 150) {
+      errors.age = 'Age must be between 0 and 150';
+    }
+
+    return errors;
+  }
+}
+
+// --- Usage ---
+
+const form = new UserFormModel({ name: '', email: '', age: 0 });
+
+// Subscribe to state changes
+form.subscribe((state) => {
+  console.log('Form state:', state);
+});
+
+// Check validation
+console.log('Initial valid:', form.valid); // false
+console.log('Initial errors:', form.errors); // { name: 'Name is required', email: 'Invalid email...' }
+
+// Update fields
+form.setName('John Doe');
+form.setEmail('john@example.com');
+form.setAge(30);
+
+console.log('After updates valid:', form.valid); // true
+console.log('After updates errors:', form.errors); // {}
+
+// Dirty tracking - check if state differs from committed baseline
+console.log('Is dirty:', form.dirty); // true (differs from initial state)
+
+// Commit - mark current state as the new baseline
+form.commit();
+console.log('After commit dirty:', form.dirty); // false
+
+// Make more changes
+form.setName('Jane Doe');
+console.log('After change dirty:', form.dirty); // true
+
+// Rollback - revert to committed state
+form.rollback();
+console.log('After rollback name:', form.state.name); // 'John Doe'
+console.log('After rollback dirty:', form.dirty); // false
+
+// Cleanup
+form.dispose();

package/examples/primitive/pagination.ts

@@ -0,0 +1,91 @@
+import { Pagination } from 'mvc-kit';
+
+// Pagination: Page-based state with array slicing pipeline
+//
+// A subscribable helper that manages page/pageSize state and slices
+// arrays accordingly. Designed to be a property on a ViewModel —
+// auto-tracked so ViewModel getters that read pagination state
+// recompute automatically.
+
+// --- Sample data ---
+
+const allItems = Array.from({ length: 47 }, (_, i) => ({
+  id: String(i + 1),
+  title: `Item ${i + 1}`,
+}));
+
+// --- Basic usage ---
+
+const pagination = new Pagination(); // default pageSize: 10
+
+// Subscribe to page changes
+pagination.subscribe(() => {
+  console.log(`Page ${pagination.page} of ${pagination.pageCount(allItems.length)}`);
+});
+
+// Read current state
+console.log('Page:', pagination.page);       // 1
+console.log('Page size:', pagination.pageSize); // 10
+
+// --- Apply slice pipeline ---
+
+const page1 = pagination.apply(allItems);
+console.log('Page 1 items:', page1.length); // 10
+console.log('First:', page1[0].title);      // 'Item 1'
+console.log('Last:', page1[9].title);       // 'Item 10'
+
+// --- Navigation ---
+
+pagination.nextPage();
+const page2 = pagination.apply(allItems);
+console.log('Page 2 first:', page2[0].title); // 'Item 11'
+
+pagination.nextPage();
+pagination.nextPage();
+pagination.nextPage(); // page 5 (last page)
+
+const lastPage = pagination.apply(allItems);
+console.log('Last page items:', lastPage.length); // 7 (47 - 40)
+console.log('Last page first:', lastPage[0].title); // 'Item 41'
+
+// --- Boundary checks ---
+
+console.log('Page count:', pagination.pageCount(allItems.length)); // 5
+console.log('Has next:', pagination.hasNext(allItems.length));     // false (on last page)
+console.log('Has prev:', pagination.hasPrev());                    // true
+
+pagination.prevPage();
+console.log('After prevPage:', pagination.page); // 4
+
+// prevPage on page 1 is a no-op
+pagination.setPage(1);
+pagination.prevPage();
+console.log('After prevPage on page 1:', pagination.page); // 1
+
+// --- Change page size ---
+
+pagination.setPageSize(20); // resets to page 1 automatically
+console.log('New page size:', pagination.pageSize);                 // 20
+console.log('Page after resize:', pagination.page);                 // 1
+console.log('New page count:', pagination.pageCount(allItems.length)); // 3
+
+const bigPage = pagination.apply(allItems);
+console.log('Items on resized page:', bigPage.length); // 20
+
+// --- Navigate to specific page ---
+
+pagination.setPage(3);
+const thirdPage = pagination.apply(allItems);
+console.log('Page 3 items:', thirdPage.length); // 7 (47 - 40)
+
+// --- Custom initial page size ---
+
+const smallPages = new Pagination({ pageSize: 5 });
+console.log('Custom page size:', smallPages.pageSize);                    // 5
+console.log('Custom page count:', smallPages.pageCount(allItems.length)); // 10
+
+// --- Reset ---
+
+pagination.setPage(3);
+pagination.reset(); // resets to page 1
+console.log('After reset page:', pagination.page); // 1

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