mvc-kit 2.12.0 → 2.12.2

package/src/Feed.test.ts

@@ -0,0 +1,442 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Feed } from './Feed';
+import { ViewModel } from './ViewModel';
+
+describe('Feed', () => {
+  describe('initial state', () => {
+    it('defaults to cursor null and hasMore true', () => {
+      const f = new Feed();
+      expect(f.cursor).toBe(null);
+      expect(f.hasMore).toBe(true);
+    });
+
+    it('defaults to empty items', () => {
+      const f = new Feed<string>();
+      expect(f.items).toEqual([]);
+      expect(f.count).toBe(0);
+    });
+  });
+
+  describe('setResult', () => {
+    it('updates hasMore and cursor', () => {
+      const f = new Feed();
+      f.setResult({ hasMore: true, cursor: 'abc123' });
+      expect(f.cursor).toBe('abc123');
+      expect(f.hasMore).toBe(true);
+    });
+
+    it('sets cursor to null when omitted', () => {
+      const f = new Feed();
+      f.setResult({ hasMore: false });
+      expect(f.cursor).toBe(null);
+      expect(f.hasMore).toBe(false);
+    });
+
+    it('sets cursor to null when explicitly null', () => {
+      const f = new Feed();
+      f.setResult({ hasMore: false, cursor: null });
+      expect(f.cursor).toBe(null);
+    });
+
+    it('updates on subsequent calls', () => {
+      const f = new Feed();
+      f.setResult({ hasMore: true, cursor: 'page1' });
+      expect(f.cursor).toBe('page1');
+
+      f.setResult({ hasMore: true, cursor: 'page2' });
+      expect(f.cursor).toBe('page2');
+
+      f.setResult({ hasMore: false, cursor: 'page3' });
+      expect(f.cursor).toBe('page3');
+      expect(f.hasMore).toBe(false);
+    });
+
+    it('does NOT affect items (backward compat)', () => {
+      const f = new Feed<string>();
+      f.appendPage({ items: ['a'], hasMore: true, cursor: 'c1' });
+      f.setResult({ hasMore: false, cursor: 'c2' });
+      expect(f.items).toEqual(['a']);
+      expect(f.count).toBe(1);
+    });
+  });
+
+  describe('appendPage', () => {
+    it('accumulates items across calls', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2], hasMore: true, cursor: 'c1' });
+      expect(f.items).toEqual([1, 2]);
+      expect(f.count).toBe(2);
+
+      f.appendPage({ items: [3, 4], hasMore: false, cursor: 'c2' });
+      expect(f.items).toEqual([1, 2, 3, 4]);
+      expect(f.count).toBe(4);
+    });
+
+    it('updates cursor and hasMore', () => {
+      const f = new Feed<string>();
+      f.appendPage({ items: ['a'], hasMore: true, cursor: 'page1' });
+      expect(f.cursor).toBe('page1');
+      expect(f.hasMore).toBe(true);
+
+      f.appendPage({ items: ['b'], hasMore: false });
+      expect(f.cursor).toBe(null);
+      expect(f.hasMore).toBe(false);
+    });
+
+    it('returns frozen array (new reference on change)', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1], hasMore: true });
+      const ref1 = f.items;
+      expect(Object.isFrozen(ref1)).toBe(true);
+
+      f.appendPage({ items: [2], hasMore: false });
+      const ref2 = f.items;
+      expect(ref2).not.toBe(ref1);
+      expect(Object.isFrozen(ref2)).toBe(true);
+    });
+  });
+
+  describe('prependPage', () => {
+    it('adds items to front', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [3, 4], hasMore: true });
+      f.prependPage({ items: [1, 2], hasMore: false, cursor: 'c1' });
+      expect(f.items).toEqual([1, 2, 3, 4]);
+    });
+
+    it('updates cursor and hasMore', () => {
+      const f = new Feed<string>();
+      f.prependPage({ items: ['a'], hasMore: false, cursor: 'end' });
+      expect(f.cursor).toBe('end');
+      expect(f.hasMore).toBe(false);
+    });
+  });
+
+  describe('push', () => {
+    it('adds items without affecting cursor/hasMore', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2], hasMore: true, cursor: 'c1' });
+      f.push(3, 4);
+      expect(f.items).toEqual([1, 2, 3, 4]);
+      expect(f.cursor).toBe('c1');
+      expect(f.hasMore).toBe(true);
+    });
+
+    it('no-op when called with zero items', () => {
+      const f = new Feed<number>();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.push();
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('returns frozen array with new reference', () => {
+      const f = new Feed<string>();
+      f.push('a');
+      const ref1 = f.items;
+      expect(Object.isFrozen(ref1)).toBe(true);
+      f.push('b');
+      expect(f.items).not.toBe(ref1);
+    });
+
+    it('notifies subscribers', () => {
+      const f = new Feed<number>();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.push(1);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('filter', () => {
+    it('removes items that do not match the predicate', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3, 4, 5], hasMore: false });
+      f.filter(n => n > 2);
+      expect(f.items).toEqual([3, 4, 5]);
+      expect(f.count).toBe(3);
+    });
+
+    it('does not affect cursor or hasMore', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true, cursor: 'c1' });
+      f.filter(n => n !== 2);
+      expect(f.cursor).toBe('c1');
+      expect(f.hasMore).toBe(true);
+    });
+
+    it('is a no-op when nothing is filtered out', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true });
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.filter(() => true);
+      expect(listener).not.toHaveBeenCalled();
+      expect(f.count).toBe(3);
+    });
+
+    it('notifies subscribers when items are removed', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true });
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.filter(n => n !== 2);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns frozen array', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: false });
+      f.filter(n => n > 1);
+      expect(Object.isFrozen(f.items)).toBe(true);
+    });
+  });
+
+  describe('replacePage', () => {
+    it('replaces all items atomically', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true, cursor: 'c1' });
+      f.replacePage({ items: [10, 20], hasMore: false, cursor: 'c2' });
+      expect(f.items).toEqual([10, 20]);
+      expect(f.count).toBe(2);
+      expect(f.cursor).toBe('c2');
+      expect(f.hasMore).toBe(false);
+    });
+
+    it('fires single notification', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2], hasMore: true });
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.replacePage({ items: [3, 4], hasMore: false, cursor: 'end' });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('can replace with empty items', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true, cursor: 'c1' });
+      f.replacePage({ items: [], hasMore: false });
+      expect(f.items).toEqual([]);
+      expect(f.count).toBe(0);
+      expect(f.hasMore).toBe(false);
+      expect(f.cursor).toBe(null);
+    });
+
+    it('returns frozen array', () => {
+      const f = new Feed<number>();
+      f.replacePage({ items: [1, 2], hasMore: true });
+      expect(Object.isFrozen(f.items)).toBe(true);
+    });
+
+    it('produces new reference', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1], hasMore: true });
+      const ref1 = f.items;
+      f.replacePage({ items: [2], hasMore: false });
+      const ref2 = f.items;
+      expect(ref1).not.toBe(ref2);
+    });
+
+    it('ideal for pull-to-refresh pattern', () => {
+      const f = new Feed<string>();
+      // Initial load
+      f.appendPage({ items: ['old1', 'old2'], hasMore: true, cursor: 'page1' });
+      f.appendPage({ items: ['old3'], hasMore: false, cursor: 'page2' });
+      expect(f.count).toBe(3);
+
+      // Pull-to-refresh replaces everything
+      f.replacePage({ items: ['new1', 'new2'], hasMore: true, cursor: 'fresh' });
+      expect(f.items).toEqual(['new1', 'new2']);
+      expect(f.cursor).toBe('fresh');
+      expect(f.hasMore).toBe(true);
+    });
+  });
+
+  describe('reset', () => {
+    it('resets to initial state', () => {
+      const f = new Feed();
+      f.setResult({ hasMore: false, cursor: 'abc' });
+      f.reset();
+      expect(f.cursor).toBe(null);
+      expect(f.hasMore).toBe(true);
+    });
+
+    it('clears items', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1, 2, 3], hasMore: true, cursor: 'c1' });
+      expect(f.count).toBe(3);
+
+      f.reset();
+      expect(f.items).toEqual([]);
+      expect(f.count).toBe(0);
+      expect(f.hasMore).toBe(true);
+      expect(f.cursor).toBe(null);
+    });
+  });
+
+  describe('subscribe notifications', () => {
+    it('notifies on setResult', () => {
+      const f = new Feed();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.setResult({ hasMore: true, cursor: 'abc' });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on reset', () => {
+      const f = new Feed();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.reset();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on appendPage', () => {
+      const f = new Feed<number>();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.appendPage({ items: [1], hasMore: true });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on prependPage', () => {
+      const f = new Feed<number>();
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.prependPage({ items: [1], hasMore: true });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on replacePage', () => {
+      const f = new Feed<number>();
+      f.appendPage({ items: [1], hasMore: true });
+      const listener = vi.fn();
+      f.subscribe(listener);
+      f.replacePage({ items: [2, 3], hasMore: false });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const f = new Feed();
+      const listener = vi.fn();
+      const unsub = f.subscribe(listener);
+      unsub();
+      f.setResult({ hasMore: false });
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('auto-tracking integration', () => {
+    it('ViewModel getter invalidates when feed changes', () => {
+      let computeCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly feed = new Feed();
+
+        get hasMore() {
+          computeCount++;
+          return this.feed.hasMore;
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      expect(vm.hasMore).toBe(true);
+      expect(computeCount).toBe(1);
+
+      // Cached
+      vm.hasMore;
+      expect(computeCount).toBe(1);
+
+      // Change feed — getter should recompute
+      vm.feed.setResult({ hasMore: false });
+      expect(vm.hasMore).toBe(false);
+      expect(computeCount).toBe(2);
+
+      vm.dispose();
+    });
+
+    it('ViewModel subscribe fires when feed changes', () => {
+      class TestVM extends ViewModel {
+        readonly feed = new Feed();
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      const listener = vi.fn();
+      vm.subscribe(listener);
+
+      vm.feed.setResult({ hasMore: false, cursor: 'x' });
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      vm.dispose();
+    });
+
+    it('ViewModel getter invalidates when items change via appendPage', () => {
+      let computeCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly feed = new Feed<number>();
+
+        get itemCount() {
+          computeCount++;
+          return this.feed.items.length;
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      expect(vm.itemCount).toBe(0);
+      expect(computeCount).toBe(1);
+
+      vm.feed.appendPage({ items: [1, 2], hasMore: true });
+      expect(vm.itemCount).toBe(2);
+      expect(computeCount).toBe(2);
+
+      vm.dispose();
+    });
+
+    it('ViewModel getter invalidates when items change via replacePage', () => {
+      let computeCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly feed = new Feed<number>();
+
+        get itemCount() {
+          computeCount++;
+          return this.feed.items.length;
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      vm.feed.appendPage({ items: [1, 2], hasMore: true });
+      expect(vm.itemCount).toBe(2);
+      computeCount = 0;
+
+      // replacePage should invalidate the getter
+      vm.feed.replacePage({ items: [10, 20, 30], hasMore: false });
+      expect(vm.itemCount).toBe(3);
+      expect(computeCount).toBe(1);
+
+      vm.dispose();
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const feed = new Feed<{ id: string }>();
+      const { appendPage, reset, push } = feed;
+      appendPage({ items: [{ id: '1' }], hasMore: true, cursor: 'abc' });
+      expect(feed.count).toBe(1);
+      push({ id: '2' });
+      expect(feed.count).toBe(2);
+      reset();
+      expect(feed.count).toBe(0);
+    });
+  });
+});

package/src/Feed.ts

@@ -0,0 +1,101 @@
+import { Trackable } from './Trackable';
+
+/** Represents a page of items from a paginated API response. */
+export interface FeedPage<T> {
+  items: T[];
+  hasMore: boolean;
+  cursor?: string | null;
+}
+
+/**
+ * Cursor-based pagination state for server-side paginated feeds.
+ * Accumulates items across pages, tracks cursor position and hasMore flag.
+ * Subscribable — auto-tracked when used as a ViewModel property.
+ */
+export class Feed<T = unknown> extends Trackable {
+  private _cursor: string | null = null;
+  private _hasMore: boolean = true;
+  private _items: readonly T[] = Object.freeze([] as T[]);
+
+  constructor() {
+    super();
+  }
+
+  // ── Readable state ──
+
+  /** Current cursor position for the next page fetch, or null if at the beginning. */
+  get cursor(): string | null {
+    return this._cursor;
+  }
+
+  /** Whether more pages are available from the server. */
+  get hasMore(): boolean {
+    return this._hasMore;
+  }
+
+  /** Accumulated items across all loaded pages. */
+  get items(): readonly T[] {
+    return this._items;
+  }
+
+  /** Total number of accumulated items. */
+  get count(): number {
+    return this._items.length;
+  }
+
+  // ── Actions ──
+
+  /** Update cursor/hasMore only (backward-compatible, does NOT affect items). */
+  setResult(result: { hasMore: boolean; cursor?: string | null }): void {
+    this._hasMore = result.hasMore;
+    this._cursor = result.cursor ?? null;
+    this.notify();
+  }
+
+  /** Append page items and update cursor/hasMore. */
+  appendPage(page: FeedPage<T>): void {
+    this._items = Object.freeze([...this._items, ...page.items]);
+    this._hasMore = page.hasMore;
+    this._cursor = page.cursor ?? null;
+    this.notify();
+  }
+
+  /** Prepend page items and update cursor/hasMore. */
+  prependPage(page: FeedPage<T>): void {
+    this._items = Object.freeze([...page.items, ...this._items]);
+    this._hasMore = page.hasMore;
+    this._cursor = page.cursor ?? null;
+    this.notify();
+  }
+
+  /** Add items without affecting cursor/hasMore. */
+  push(...items: T[]): void {
+    if (items.length === 0) return;
+    this._items = Object.freeze([...this._items, ...items]);
+    this.notify();
+  }
+
+  /** Remove items that don't match the predicate. No-op if nothing is filtered out. */
+  filter(predicate: (item: T) => boolean): void {
+    const filtered = this._items.filter(predicate);
+    if (filtered.length === this._items.length) return;
+    this._items = Object.freeze(filtered);
+    this.notify();
+  }
+
+  /** Replace all items and update cursor/hasMore atomically. Ideal for pull-to-refresh. */
+  replacePage(page: FeedPage<T>): void {
+    this._items = Object.freeze([...page.items]);
+    this._hasMore = page.hasMore;
+    this._cursor = page.cursor ?? null;
+    this.notify();
+  }
+
+  /** Reset to initial empty state with hasMore=true. */
+  reset(): void {
+    this._cursor = null;
+    this._hasMore = true;
+    this._items = Object.freeze([] as T[]);
+    this.notify();
+  }
+}