mvc-kit 2.12.0 → 2.12.1

package/src/Resource.test.ts

@@ -0,0 +1,786 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Resource } from './Resource';
+import { Collection } from './Collection';
+import { HttpError } from './errors';
+import { singleton, teardownAll } from './singleton';
+
+type Item = { id: number; name: string };
+
+const alice: Item = { id: 1, name: 'Alice' };
+const bob: Item = { id: 2, name: 'Bob' };
+const charlie: Item = { id: 3, name: 'Charlie' };
+
+beforeEach(() => {
+  teardownAll();
+  vi.restoreAllMocks();
+});
+
+// ── Category A: Basic Collection Behavior (no injection) ──────
+
+describe('Resource — basic Collection behavior', () => {
+  class TestResource extends Resource<Item> {}
+
+  it('starts empty by default', () => {
+    const r = new TestResource();
+    expect(r.items).toEqual([]);
+    expect(r.length).toBe(0);
+  });
+
+  it('accepts initial items array', () => {
+    const r = new TestResource([alice, bob]);
+    expect(r.items).toEqual([alice, bob]);
+    expect(r.length).toBe(2);
+  });
+
+  it('add works', () => {
+    const r = new TestResource();
+    r.add(alice);
+    expect(r.items).toEqual([alice]);
+    r.add(bob, charlie);
+    expect(r.items).toEqual([alice, bob, charlie]);
+  });
+
+  it('upsert works', () => {
+    const r = new TestResource([alice]);
+    const updated = { id: 1, name: 'Alice Updated' };
+    r.upsert(updated, bob);
+    expect(r.items).toEqual([updated, bob]);
+  });
+
+  it('update works', () => {
+    const r = new TestResource([alice]);
+    r.update(1, { name: 'Updated' });
+    expect(r.get(1)?.name).toBe('Updated');
+  });
+
+  it('remove works', () => {
+    const r = new TestResource([alice, bob]);
+    r.remove(1);
+    expect(r.items).toEqual([bob]);
+  });
+
+  it('reset works', () => {
+    const r = new TestResource([alice]);
+    r.reset([bob, charlie]);
+    expect(r.items).toEqual([bob, charlie]);
+  });
+
+  it('clear works', () => {
+    const r = new TestResource([alice, bob]);
+    r.clear();
+    expect(r.items).toEqual([]);
+  });
+
+  it('get/has work', () => {
+    const r = new TestResource([alice]);
+    expect(r.get(1)).toBe(alice);
+    expect(r.has(1)).toBe(true);
+    expect(r.has(99)).toBe(false);
+  });
+
+  it('find/filter/sorted/map work', () => {
+    const r = new TestResource([bob, alice]);
+    expect(r.find(i => i.id === 1)).toBe(alice);
+    expect(r.filter(i => i.id > 1)).toEqual([bob]);
+    expect(r.sorted((a, b) => a.id - b.id)).toEqual([alice, bob]);
+    expect(r.map(i => i.name)).toEqual(['Bob', 'Alice']);
+  });
+
+  it('subscribe fires on mutations', () => {
+    const r = new TestResource();
+    const listener = vi.fn();
+    r.subscribe(listener);
+    r.add(alice);
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it('state is alias for items', () => {
+    const r = new TestResource([alice]);
+    expect(r.state).toBe(r.items);
+  });
+
+  it('dispose cleans up', () => {
+    const r = new TestResource();
+    r.dispose();
+    expect(r.disposed).toBe(true);
+    expect(() => r.add(alice)).toThrow();
+  });
+
+  it('optimistic works', () => {
+    const r = new TestResource([alice]);
+    const rollback = r.optimistic(() => {
+      r.remove(1);
+    });
+    expect(r.items).toEqual([]);
+    rollback();
+    expect(r.items).toEqual([alice]);
+  });
+
+  it('MAX_SIZE inherited from Collection works', () => {
+    class LimitedResource extends Resource<Item> {
+      static MAX_SIZE = 2;
+    }
+    const r = new LimitedResource([alice, bob, charlie]);
+    // FIFO eviction: alice evicted
+    expect(r.length).toBe(2);
+    expect(r.has(1)).toBe(false);
+  });
+
+  it('TTL inherited from Collection works', async () => {
+    class ExpiringResource extends Resource<Item> {
+      static TTL = 50;
+    }
+    const r = new ExpiringResource([alice]);
+    expect(r.length).toBe(1);
+    await new Promise(resolve => setTimeout(resolve, 100));
+    expect(r.length).toBe(0);
+    r.dispose();
+  });
+});
+
+// ── Category B: External Collection Injection ─────────────────
+
+describe('Resource — external Collection injection', () => {
+  it('constructor accepts Collection instance', () => {
+    const col = new Collection<Item>([alice, bob]);
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    expect(r.items).toEqual([alice, bob]);
+  });
+
+  it('items/state/length read from external', () => {
+    const col = new Collection<Item>([alice]);
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    expect(r.items).toBe(col.items);
+    expect(r.state).toBe(col.state);
+    expect(r.length).toBe(col.length);
+  });
+
+  it('mutation methods mutate the external collection', () => {
+    const col = new Collection<Item>();
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+
+    r.add(alice);
+    expect(col.items).toEqual([alice]);
+
+    r.upsert({ id: 1, name: 'Updated' });
+    expect(col.get(1)?.name).toBe('Updated');
+
+    r.add(bob);
+    r.update(2, { name: 'Bob Updated' });
+    expect(col.get(2)?.name).toBe('Bob Updated');
+
+    r.remove(1);
+    expect(col.has(1)).toBe(false);
+
+    r.reset([charlie]);
+    expect(col.items).toEqual([charlie]);
+
+    r.clear();
+    expect(col.items).toEqual([]);
+  });
+
+  it('query methods read from external', () => {
+    const col = new Collection<Item>([alice, bob]);
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+
+    expect(r.get(1)).toBe(col.get(1));
+    expect(r.has(1)).toBe(true);
+    expect(r.find(i => i.id === 2)).toBe(bob);
+    expect(r.filter(i => i.id > 0)).toEqual(col.filter(i => i.id > 0));
+    expect(r.sorted((a, b) => a.id - b.id)).toEqual(col.sorted((a, b) => a.id - b.id));
+    expect(r.map(i => i.name)).toEqual(col.map(i => i.name));
+  });
+
+  it('subscribe delegates to external', () => {
+    const col = new Collection<Item>();
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    const listener = vi.fn();
+    r.subscribe(listener);
+    col.add(alice);
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it('dispose does NOT dispose external collection', () => {
+    const col = new Collection<Item>([alice]);
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    r.dispose();
+    expect(r.disposed).toBe(true);
+    expect(col.disposed).toBe(false);
+    expect(col.items).toEqual([alice]);
+    // External collection still works after resource disposal
+    col.add(bob);
+    expect(col.length).toBe(2);
+  });
+
+  it('external collection changes are visible through Resource getters', () => {
+    const col = new Collection<Item>();
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    col.add(alice);
+    expect(r.items).toEqual([alice]);
+    expect(r.length).toBe(1);
+  });
+
+  it('optimistic delegates to external', () => {
+    const col = new Collection<Item>([alice]);
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    const rollback = r.optimistic(() => {
+      r.remove(1);
+    });
+    expect(col.items).toEqual([]);
+    rollback();
+    expect(col.items).toEqual([alice]);
+  });
+
+  it('DEV warning when MAX_SIZE/TTL set with external collection', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const col = new Collection<Item>();
+    class BadResource extends Resource<Item> {
+      static MAX_SIZE = 10;
+    }
+    new BadResource(col);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('MAX_SIZE or TTL set but uses an injected Collection')
+    );
+  });
+
+  it('subscribe returns no-op after resource disposal', () => {
+    const col = new Collection<Item>();
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+    r.dispose();
+    const unsub = r.subscribe(vi.fn());
+    expect(typeof unsub).toBe('function');
+    // Should be no-op, no error
+    unsub();
+  });
+});
+
+// ── Category C: Lifecycle ─────────────────────────────────────
+
+describe('Resource — lifecycle', () => {
+  it('init() calls onInit()', async () => {
+    const initSpy = vi.fn();
+    class TestResource extends Resource<Item> {
+      onInit() { initSpy(); }
+    }
+    const r = new TestResource();
+    r.init();
+    expect(initSpy).toHaveBeenCalledOnce();
+  });
+
+  it('init() supports async onInit()', async () => {
+    let loaded = false;
+    class TestResource extends Resource<Item> {
+      async onInit() {
+        await Promise.resolve();
+        loaded = true;
+      }
+    }
+    const r = new TestResource();
+    await r.init();
+    expect(loaded).toBe(true);
+  });
+
+  it('init() is idempotent', () => {
+    const initSpy = vi.fn();
+    class TestResource extends Resource<Item> {
+      onInit() { initSpy(); }
+    }
+    const r = new TestResource();
+    r.init();
+    r.init();
+    expect(initSpy).toHaveBeenCalledOnce();
+  });
+
+  it('dispose() calls onDispose()', () => {
+    const disposeSpy = vi.fn();
+    class TestResource extends Resource<Item> {
+      onDispose() { disposeSpy(); }
+    }
+    const r = new TestResource();
+    r.dispose();
+    expect(disposeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('dispose() is idempotent', () => {
+    const disposeSpy = vi.fn();
+    class TestResource extends Resource<Item> {
+      onDispose() { disposeSpy(); }
+    }
+    const r = new TestResource();
+    r.dispose();
+    r.dispose();
+    expect(disposeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('disposeSignal fires on dispose', () => {
+    const r = new (class extends Resource<Item> {})();
+    const abortListener = vi.fn();
+    r.disposeSignal.addEventListener('abort', abortListener);
+    r.dispose();
+    expect(abortListener).toHaveBeenCalledOnce();
+  });
+
+  it('addCleanup functions run on dispose', () => {
+    const cleanup = vi.fn();
+    class TestResource extends Resource<Item> {
+      onInit() {
+        this.addCleanup(cleanup);
+      }
+    }
+    const r = new TestResource();
+    r.init();
+    r.dispose();
+    expect(cleanup).toHaveBeenCalledOnce();
+  });
+
+  it('initialized returns false before init, true after', () => {
+    const r = new (class extends Resource<Item> {})();
+    expect(r.initialized).toBe(false);
+    r.init();
+    expect(r.initialized).toBe(true);
+  });
+
+  it('init() no-ops after dispose', () => {
+    const initSpy = vi.fn();
+    class TestResource extends Resource<Item> {
+      onInit() { initSpy(); }
+    }
+    const r = new TestResource();
+    r.dispose();
+    r.init();
+    expect(initSpy).not.toHaveBeenCalled();
+  });
+});
+
+// ── Category D: Async Tracking ────────────────────────────────
+
+describe('Resource — async tracking', () => {
+  it('methods get loading/error tracking after init()', async () => {
+    let resolve!: () => void;
+    class TestResource extends Resource<Item> {
+      async load() {
+        await new Promise<void>(r => { resolve = r; });
+        this.reset([alice]);
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    expect(r.async.load.loading).toBe(false);
+    const p = r.load();
+    expect(r.async.load.loading).toBe(true);
+    resolve();
+    await p;
+    expect(r.async.load.loading).toBe(false);
+    expect(r.items).toEqual([alice]);
+  });
+
+  it('error captures message and errorCode on failure', async () => {
+    class TestResource extends Resource<Item> {
+      async load() {
+        throw new HttpError(404, 'Not found');
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    await r.load().catch(() => {});
+    expect(r.async.load.error).toBe('Not found');
+    expect(r.async.load.errorCode).toBe('not_found');
+  });
+
+  it('concurrent calls: loading stays true until all resolve', async () => {
+    const resolvers: (() => void)[] = [];
+    class TestResource extends Resource<Item> {
+      async load() {
+        await new Promise<void>(r => { resolvers.push(r); });
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    const pA = r.load();
+    const pB = r.load();
+
+    expect(r.async.load.loading).toBe(true);
+
+    resolvers[0]();
+    await pA;
+    // Still loading because second call is pending
+    expect(r.async.load.loading).toBe(true);
+
+    resolvers[1]();
+    await pB;
+    expect(r.async.load.loading).toBe(false);
+  });
+
+  it('AbortError silently swallowed', async () => {
+    class TestResource extends Resource<Item> {
+      async load() {
+        const err = new Error('Aborted');
+        err.name = 'AbortError';
+        throw err;
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    // Should not throw
+    const result = await r.load();
+    expect(result).toBeUndefined();
+    expect(r.async.load.loading).toBe(false);
+    expect(r.async.load.error).toBeNull();
+  });
+
+  it('non-abort errors re-thrown from wrapper', async () => {
+    class TestResource extends Resource<Item> {
+      async load() {
+        throw new Error('Boom');
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    await expect(r.load()).rejects.toThrow('Boom');
+    expect(r.async.load.error).toBe('Boom');
+  });
+
+  it('sync methods auto-pruned on first call', () => {
+    class TestResource extends Resource<Item> {
+      doSync() {
+        return 42;
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    // First call — triggers pruning
+    expect(r.doSync()).toBe(42);
+    // Second call — bound original, no wrapper overhead
+    expect(r.doSync()).toBe(42);
+    // Verify it's no longer tracked
+    expect('doSync' in r.async).toBe(false);
+  });
+
+  it('subscribeAsync fires on async state changes', async () => {
+    let resolve!: () => void;
+    class TestResource extends Resource<Item> {
+      async load() {
+        await new Promise<void>(r => { resolve = r; });
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    const listener = vi.fn();
+    r.subscribeAsync(listener);
+
+    const p = r.load();
+    expect(listener).toHaveBeenCalledTimes(1); // loading: true
+
+    resolve();
+    await p;
+    expect(listener).toHaveBeenCalledTimes(2); // loading: false
+  });
+
+  it('async proxy returns DEFAULT_TASK_STATE for unknown keys', () => {
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource();
+    r.init();
+
+    const state = (r.async as any).nonExistent;
+    expect(state.loading).toBe(false);
+    expect(state.error).toBeNull();
+    expect(state.errorCode).toBeNull();
+  });
+
+  it('disposed: method calls return undefined (DEV warning)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    class TestResource extends Resource<Item> {
+      async load() {
+        this.reset([alice]);
+      }
+    }
+    const r = new TestResource();
+    r.init();
+    r.dispose();
+
+    const result = await r.load();
+    expect(result).toBeUndefined();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('"load" called after dispose')
+    );
+  });
+
+  it('ghost detection warns about pending ops after dispose (DEV)', async () => {
+    vi.useFakeTimers();
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    class TestResource extends Resource<Item> {
+      static GHOST_TIMEOUT = 100;
+      async load() {
+        await new Promise(() => {}); // Never resolves
+      }
+    }
+    const r = new TestResource();
+    r.init();
+
+    r.load();
+    r.dispose();
+
+    vi.advanceTimersByTime(200);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('Ghost async operation detected: "load"')
+    );
+
+    vi.useRealTimers();
+  });
+
+  it('reserved keys: cannot override async', () => {
+    expect(() => {
+      class BadResource extends Resource<Item> {
+        get async(): any { return {}; }
+      }
+      new BadResource();
+    }).toThrow('"async" is a reserved property');
+  });
+
+  it('reserved keys: cannot override subscribeAsync', () => {
+    expect(() => {
+      class BadResource extends Resource<Item> {
+        subscribeAsync(): any { return () => {}; }
+      }
+      new BadResource();
+    }).toThrow('"subscribeAsync" is a reserved property');
+  });
+
+  it('methods called before init() work but have no wrapping', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    class TestResource extends Resource<Item> {
+      doSync() { return 42; }
+    }
+    const r = new TestResource();
+
+    // Method works fine before init (no wrapping)
+    expect(r.doSync()).toBe(42);
+    // No DEV warning before init because method isn't wrapped
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+// ── Category E: Async Tracking + External Collection ──────────
+
+describe('Resource — async tracking with external Collection', () => {
+  it('async methods that mutate external collection get proper tracking', async () => {
+    const col = new Collection<Item>();
+    let resolve!: () => void;
+
+    class TestResource extends Resource<Item> {
+      async loadAll() {
+        await new Promise<void>(r => { resolve = r; });
+        this.reset([alice, bob]);
+      }
+    }
+    const r = new TestResource(col);
+    r.init();
+
+    const p = r.loadAll();
+    expect(r.async.loadAll.loading).toBe(true);
+    expect(col.items).toEqual([]); // Not loaded yet
+
+    resolve();
+    await p;
+    expect(r.async.loadAll.loading).toBe(false);
+    expect(col.items).toEqual([alice, bob]); // Loaded into external
+    expect(r.items).toEqual([alice, bob]); // Visible through resource
+  });
+
+  it('multiple async methods have independent tracking', async () => {
+    const col = new Collection<Item>();
+    let resolveA!: () => void;
+    let resolveB!: () => void;
+
+    class TestResource extends Resource<Item> {
+      async loadAll() {
+        await new Promise<void>(r => { resolveA = r; });
+        this.reset([alice, bob]);
+      }
+      async loadOne() {
+        await new Promise<void>(r => { resolveB = r; });
+        this.add(charlie);
+      }
+    }
+    const r = new TestResource(col);
+    r.init();
+
+    const pA = r.loadAll();
+    const pB = r.loadOne();
+
+    expect(r.async.loadAll.loading).toBe(true);
+    expect(r.async.loadOne.loading).toBe(true);
+
+    resolveA();
+    await pA;
+    expect(r.async.loadAll.loading).toBe(false);
+    expect(r.async.loadOne.loading).toBe(true);
+
+    resolveB();
+    await pB;
+    expect(r.async.loadOne.loading).toBe(false);
+  });
+});
+
+// ── Category F: Integration ───────────────────────────────────
+
+describe('Resource — integration', () => {
+  it('subscribeAsync duck-typing matches useInstance expectations', () => {
+    const r = new (class extends Resource<Item> {})();
+    expect(typeof r.subscribeAsync).toBe('function');
+    // useInstance duck-types: typeof obj.subscribeAsync === 'function'
+  });
+
+  it('singleton integration: teardownAll disposes resource', () => {
+    class TestResource extends Resource<Item> {}
+    const r = singleton(TestResource);
+    expect(r.disposed).toBe(false);
+    teardownAll();
+    expect(r.disposed).toBe(true);
+  });
+
+  it('data persists in resource across singleton() calls', () => {
+    class TestResource extends Resource<Item> {}
+    const r1 = singleton(TestResource);
+    r1.add(alice);
+    const r2 = singleton(TestResource);
+    expect(r1).toBe(r2);
+    expect(r2.items).toEqual([alice]);
+  });
+
+  it('isInitializable guard detects Resource', () => {
+    const r = new (class extends Resource<Item> {})();
+    // Duck-type check: has init() method
+    expect(typeof (r as any).init).toBe('function');
+    expect('init' in r).toBe(true);
+  });
+
+  it('resource implements Subscribable interface', () => {
+    const r = new (class extends Resource<Item> {})();
+    expect(typeof r.subscribe).toBe('function');
+    expect('state' in r).toBe(true);
+    expect('disposed' in r).toBe(true);
+    expect('disposeSignal' in r).toBe(true);
+    expect(typeof r.dispose).toBe('function');
+  });
+
+  it('ViewModel auto-tracking via subscribe works', () => {
+    const r = new (class extends Resource<Item> {})();
+    const listener = vi.fn();
+    const unsub = r.subscribe(listener);
+    r.add(alice);
+    expect(listener).toHaveBeenCalledOnce();
+    unsub();
+    r.add(bob);
+    expect(listener).toHaveBeenCalledOnce(); // Not called again
+  });
+
+  it('external collection subscription survives resource disposal', () => {
+    const col = new Collection<Item>();
+    class TestResource extends Resource<Item> {}
+    const r = new TestResource(col);
+
+    const listener = vi.fn();
+    const unsub = r.subscribe(listener);
+
+    // Mutation through resource
+    r.add(alice);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Dispose resource
+    r.dispose();
+
+    // Direct mutation on external — listener was registered on external
+    // so it still fires
+    col.add(bob);
+    expect(listener).toHaveBeenCalledTimes(2);
+
+    // Clean up
+    unsub();
+  });
+});
+
+describe('Resource — method binding', () => {
+  class TestResource extends Resource<Item> {}
+
+  it('destructured methods work point-free before init()', () => {
+    const resource = new TestResource();
+    const { add, remove } = resource;
+    add(alice);
+    expect(resource.length).toBe(1);
+    remove(1);
+    expect(resource.length).toBe(0);
+  });
+
+  it('methods work after init() replaces them with async wrappers', async () => {
+    const resource = new TestResource();
+    await resource.init();
+    const { add } = resource;
+    add(alice);
+    expect(resource.length).toBe(1);
+  });
+
+  it('method reference captured before init() still works after init()', async () => {
+    const resource = new TestResource();
+    const addRef = resource.add;
+    await resource.init();
+    addRef(alice);
+    expect(resource.length).toBe(1);
+  });
+
+  it('subclass methods are bound through the inheritance chain', () => {
+    class ItemResource extends Resource<Item> {
+      findByName(name: string): Item | undefined {
+        return this.find(i => i.name === name);
+      }
+    }
+    const r = new ItemResource([alice, bob]);
+    const { findByName } = r;
+    expect(findByName('Alice')).toEqual(alice);
+  });
+
+  it('most-derived override wins when subclass overrides Collection method', () => {
+    class TrackingResource extends Resource<Item> {
+      addCount = 0;
+      override add(...items: Item[]): void {
+        this.addCount += items.length;
+        super.add(...items);
+      }
+    }
+    const r = new TrackingResource();
+    const { add } = r;
+    add(alice, bob);
+    expect(r.addCount).toBe(2);
+    expect(r.length).toBe(2);
+  });
+
+  it('subclass async methods work point-free after init()', async () => {
+    class AsyncResource extends Resource<Item> {
+      async loadAll() {
+        this.reset([alice, bob, charlie]);
+      }
+    }
+    const r = new AsyncResource();
+    await r.init();
+    const { loadAll } = r;
+    await loadAll();
+    expect(r.length).toBe(3);
+  });
+});