mvc-kit 2.12.0 → 2.12.1

package/src/Collection.test.ts

@@ -0,0 +1,1559 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Collection } from './Collection';
+import { singleton, teardownAll } from './singleton';
+
+interface Todo {
+  id: string;
+  text: string;
+  done: boolean;
+}
+
+interface User {
+  id: number;
+  name: string;
+  age: number;
+}
+
+describe('Collection', () => {
+  describe('initialization', () => {
+    it('initializes empty by default', () => {
+      const collection = new Collection<Todo>();
+      expect(collection.items).toEqual([]);
+      expect(collection.length).toBe(0);
+    });
+
+    it('initializes with provided items', () => {
+      const items = [
+        { id: '1', text: 'Buy milk', done: false },
+        { id: '2', text: 'Walk dog', done: true },
+      ];
+      const collection = new Collection<Todo>(items);
+      expect(collection.items).toHaveLength(2);
+      expect(collection.length).toBe(2);
+    });
+
+    it('items array is frozen', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      expect(Object.isFrozen(collection.items)).toBe(true);
+    });
+
+    it('state is alias for items', () => {
+      const items = [{ id: '1', text: 'Test', done: false }];
+      const collection = new Collection<Todo>(items);
+      expect(collection.state).toBe(collection.items);
+    });
+
+    it('starts not disposed', () => {
+      const collection = new Collection<Todo>();
+      expect(collection.disposed).toBe(false);
+    });
+  });
+
+  describe('add()', () => {
+    it('adds single item', () => {
+      const collection = new Collection<Todo>();
+      collection.add({ id: '1', text: 'Test', done: false });
+      expect(collection.items).toHaveLength(1);
+      expect(collection.get('1')).toEqual({ id: '1', text: 'Test', done: false });
+    });
+
+    it('adds multiple items', () => {
+      const collection = new Collection<Todo>();
+      collection.add(
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: true }
+      );
+      expect(collection.length).toBe(2);
+    });
+
+    it('notifies listeners', () => {
+      const collection = new Collection<Todo>();
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(listener).toHaveBeenCalledWith(
+        [{ id: '1', text: 'Test', done: false }],
+        []
+      );
+    });
+
+    it('does not notify when adding empty', () => {
+      const collection = new Collection<Todo>();
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.add();
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('skips items with existing IDs', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.add({ id: '1', text: 'Duplicate', done: true });
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('First');
+    });
+
+    it('mixed new + existing in batch — only new appended', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.add(
+        { id: '1', text: 'Dup', done: true },
+        { id: '2', text: 'Second', done: false },
+      );
+
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')!.text).toBe('First');
+      expect(collection.get('2')!.text).toBe('Second');
+    });
+
+    it('no notification when all items already exist', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.add({ id: '1', text: 'Dup', done: true });
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('deduplicates within batch', () => {
+      const collection = new Collection<Todo>();
+
+      collection.add(
+        { id: '1', text: 'First', done: false },
+        { id: '1', text: 'Second', done: true },
+      );
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('First');
+    });
+  });
+
+  describe('upsert()', () => {
+    it('adds new item (appended)', () => {
+      const collection = new Collection<Todo>();
+      collection.upsert({ id: '1', text: 'Test', done: false });
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')).toEqual({ id: '1', text: 'Test', done: false });
+    });
+
+    it('replaces existing item in-place (position preserved)', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.upsert({ id: '2', text: 'Updated', done: true });
+
+      expect(collection.length).toBe(3);
+      expect(collection.items[1]).toEqual({ id: '2', text: 'Updated', done: true });
+    });
+
+    it('mixed new + existing in one call', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.upsert(
+        { id: '1', text: 'Updated', done: true },
+        { id: '2', text: 'New', done: false },
+      );
+
+      expect(collection.length).toBe(2);
+      expect(collection.items[0]).toEqual({ id: '1', text: 'Updated', done: true });
+      expect(collection.items[1]).toEqual({ id: '2', text: 'New', done: false });
+    });
+
+    it('full replacement (not partial merge)', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'Original', done: false },
+      ]);
+
+      collection.upsert({ id: '1', text: 'Replaced', done: true });
+
+      const item = collection.get('1')!;
+      expect(item.text).toBe('Replaced');
+      expect(item.done).toBe(true);
+    });
+
+    it('notifies listeners once for mixed batch', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.upsert(
+        { id: '1', text: 'Updated', done: true },
+        { id: '2', text: 'New', done: false },
+      );
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('no notification on empty args', () => {
+      const collection = new Collection<Todo>();
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.upsert();
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('no notification when all items reference-identical', () => {
+      const item = { id: '1', text: 'Test', done: false };
+      const collection = new Collection<Todo>([item]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.upsert(item);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('duplicate IDs in input — last wins', () => {
+      const collection = new Collection<Todo>();
+
+      collection.upsert(
+        { id: '1', text: 'First', done: false },
+        { id: '1', text: 'Last', done: true },
+      );
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('Last');
+    });
+
+    it('index consistency after upsert', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.upsert(
+        { id: '1', text: 'Updated', done: true },
+        { id: '2', text: 'New', done: false },
+      );
+
+      expect(collection.has('1')).toBe(true);
+      expect(collection.has('2')).toBe(true);
+      expect(collection.get('1')!.text).toBe('Updated');
+      expect(collection.get('2')!.text).toBe('New');
+    });
+
+    it('throws on disposed', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      expect(() => collection.upsert({ id: '1', text: 'Test', done: false })).toThrow(
+        'Cannot upsert on disposed Collection'
+      );
+    });
+
+    it('items array frozen after upsert', () => {
+      const collection = new Collection<Todo>();
+      collection.upsert({ id: '1', text: 'Test', done: false });
+      expect(Object.isFrozen(collection.items)).toBe(true);
+    });
+
+    it('works inside optimistic() callback (rollback restores)', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.upsert(
+          { id: '1', text: 'Updated', done: true },
+          { id: '2', text: 'New', done: false },
+        );
+      });
+
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')!.text).toBe('Updated');
+
+      rollback();
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('First');
+      expect(collection.has('2')).toBe(false);
+    });
+
+    it('works with numeric IDs', () => {
+      const collection = new Collection<User>();
+      collection.upsert(
+        { id: 1, name: 'Alice', age: 30 },
+        { id: 2, name: 'Bob', age: 25 },
+      );
+
+      expect(collection.length).toBe(2);
+
+      collection.upsert({ id: 1, name: 'Alice Updated', age: 31 });
+
+      expect(collection.length).toBe(2);
+      expect(collection.get(1)!.name).toBe('Alice Updated');
+      expect(collection.items[0].id).toBe(1); // position preserved
+    });
+  });
+
+  describe('remove()', () => {
+    it('removes single item by id', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: true },
+      ]);
+
+      collection.remove('1');
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')).toBeUndefined();
+      expect(collection.get('2')).toBeDefined();
+    });
+
+    it('removes multiple items', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: true },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.remove('1', '3');
+
+      expect(collection.length).toBe(1);
+      expect(collection.items[0].id).toBe('2');
+    });
+
+    it('notifies listeners', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.remove('1');
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not notify when id not found', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.remove('999');
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('does not notify when removing empty', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.remove();
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('update()', () => {
+    it('updates item by id', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+
+      collection.update('1', { done: true });
+
+      expect(collection.get('1')).toEqual({ id: '1', text: 'Test', done: true });
+    });
+
+    it('preserves id even if included in changes', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+
+      collection.update('1', { id: '999' as string, text: 'Updated' });
+
+      expect(collection.get('1')).toBeDefined();
+      expect(collection.get('1')!.text).toBe('Updated');
+    });
+
+    it('notifies listeners', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.update('1', { done: true });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not notify when id not found', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.update('999', { done: true });
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('does not notify when values unchanged', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.update('1', { done: false });
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('reset()', () => {
+    it('replaces all items', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.reset([
+        { id: '2', text: 'Second', done: true },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')).toBeUndefined();
+      expect(collection.get('2')).toBeDefined();
+    });
+
+    it('notifies listeners', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.reset([{ id: '2', text: 'New', done: true }]);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('clear()', () => {
+    it('removes all items', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: true },
+      ]);
+
+      collection.clear();
+
+      expect(collection.length).toBe(0);
+      expect(collection.items).toEqual([]);
+    });
+
+    it('notifies listeners', () => {
+      const collection = new Collection<Todo>([{ id: '1', text: 'Test', done: false }]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.clear();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not notify when already empty', () => {
+      const collection = new Collection<Todo>();
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.clear();
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('optimistic()', () => {
+    it('returns a rollback function', () => {
+      const collection = new Collection<Todo>();
+      const rollback = collection.optimistic(() => {});
+      expect(typeof rollback).toBe('function');
+    });
+
+    it('callback mutations apply immediately', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      expect(collection.get('1')!.done).toBe(true);
+    });
+
+    it('callback mutations notify listeners normally', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('rollback restores items to pre-callback state', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+        collection.remove('2');
+      });
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.done).toBe(true);
+
+      rollback();
+
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')!.done).toBe(false);
+      expect(collection.get('2')).toBeDefined();
+    });
+
+    it('rollback restores index correctly (has/get consistency)', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.remove('1');
+        collection.add({ id: '3', text: 'Third', done: true });
+      });
+
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('3')).toBe(true);
+
+      rollback();
+
+      expect(collection.has('1')).toBe(true);
+      expect(collection.has('3')).toBe(false);
+      expect(collection.get('1')).toEqual({ id: '1', text: 'First', done: false });
+    });
+
+    it('rollback notifies listeners', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      listener.mockClear();
+      rollback();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      // Called with (restored items, pre-rollback items)
+      expect(listener).toHaveBeenCalledWith(
+        [{ id: '1', text: 'First', done: false }],
+        [{ id: '1', text: 'First', done: true }]
+      );
+    });
+
+    it('rollback is idempotent', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      listener.mockClear();
+      rollback();
+      rollback();
+      rollback();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('rollback is no-op when disposed', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      collection.dispose();
+      expect(() => rollback()).not.toThrow();
+    });
+
+    it('throws when called on disposed collection', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+
+      expect(() => collection.optimistic(() => {})).toThrow(
+        'Cannot perform optimistic update on disposed Collection'
+      );
+    });
+
+    it('multiple CRUD operations in callback all rollback together', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+        collection.update('2', { text: 'Modified' });
+        collection.add({ id: '3', text: 'Third', done: true });
+      });
+
+      expect(collection.length).toBe(3);
+
+      rollback();
+
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')!.done).toBe(false);
+      expect(collection.get('2')!.text).toBe('Second');
+      expect(collection.has('3')).toBe(false);
+    });
+
+    it('rollback after additional mutations restores pre-optimistic state', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.update('1', { done: true });
+      });
+
+      // Additional mutation after optimistic
+      collection.add({ id: '2', text: 'Extra', done: false });
+      expect(collection.length).toBe(2);
+
+      rollback();
+
+      // Restores to pre-optimistic snapshot, discarding the extra add
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.done).toBe(false);
+      expect(collection.has('2')).toBe(false);
+    });
+
+    it('nested optimistic calls capture independent snapshots', () => {
+      const collection = new Collection<Todo>([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      const rollback1 = collection.optimistic(() => {
+        collection.update('1', { text: 'Outer' });
+      });
+
+      const rollback2 = collection.optimistic(() => {
+        collection.update('1', { text: 'Inner' });
+      });
+
+      expect(collection.get('1')!.text).toBe('Inner');
+
+      // Rolling back inner restores to after outer
+      rollback2();
+      expect(collection.get('1')!.text).toBe('Outer');
+
+      // Rolling back outer restores original
+      rollback1();
+      expect(collection.get('1')!.text).toBe('First');
+    });
+
+    it('works with empty collection', () => {
+      const collection = new Collection<Todo>();
+
+      const rollback = collection.optimistic(() => {
+        collection.add({ id: '1', text: 'Test', done: false });
+      });
+
+      expect(collection.length).toBe(1);
+
+      rollback();
+
+      expect(collection.length).toBe(0);
+    });
+  });
+
+  describe('query methods', () => {
+    const users: User[] = [
+      { id: 1, name: 'Alice', age: 30 },
+      { id: 2, name: 'Bob', age: 25 },
+      { id: 3, name: 'Charlie', age: 35 },
+    ];
+
+    describe('get()', () => {
+      it('returns item by id', () => {
+        const collection = new Collection<User>(users);
+        expect(collection.get(2)).toEqual({ id: 2, name: 'Bob', age: 25 });
+      });
+
+      it('returns undefined for unknown id', () => {
+        const collection = new Collection<User>(users);
+        expect(collection.get(999)).toBeUndefined();
+      });
+    });
+
+    describe('has()', () => {
+      it('returns true when item exists', () => {
+        const collection = new Collection<User>(users);
+        expect(collection.has(1)).toBe(true);
+      });
+
+      it('returns false when item does not exist', () => {
+        const collection = new Collection<User>(users);
+        expect(collection.has(999)).toBe(false);
+      });
+    });
+
+    describe('find()', () => {
+      it('returns first matching item', () => {
+        const collection = new Collection<User>(users);
+        const result = collection.find(u => u.age > 28);
+        expect(result).toEqual({ id: 1, name: 'Alice', age: 30 });
+      });
+
+      it('returns undefined when no match', () => {
+        const collection = new Collection<User>(users);
+        const result = collection.find(u => u.age > 100);
+        expect(result).toBeUndefined();
+      });
+    });
+
+    describe('filter()', () => {
+      it('returns matching items', () => {
+        const collection = new Collection<User>(users);
+        const result = collection.filter(u => u.age >= 30);
+        expect(result).toHaveLength(2);
+        expect(result.map(u => u.name)).toEqual(['Alice', 'Charlie']);
+      });
+
+      it('returns empty array when no match', () => {
+        const collection = new Collection<User>(users);
+        const result = collection.filter(u => u.age > 100);
+        expect(result).toEqual([]);
+      });
+    });
+
+    describe('sorted()', () => {
+      it('returns sorted copy', () => {
+        const collection = new Collection<User>(users);
+        const result = collection.sorted((a, b) => a.age - b.age);
+        expect(result.map(u => u.name)).toEqual(['Bob', 'Alice', 'Charlie']);
+      });
+
+      it('does not modify original', () => {
+        const collection = new Collection<User>(users);
+        collection.sorted((a, b) => a.age - b.age);
+        expect(collection.items[0].name).toBe('Alice');
+      });
+    });
+
+    describe('map()', () => {
+      it('transforms items', () => {
+        const collection = new Collection<User>(users);
+        const names = collection.map(u => u.name);
+        expect(names).toEqual(['Alice', 'Bob', 'Charlie']);
+      });
+    });
+  });
+
+  describe('subscriptions', () => {
+    it('unsubscribe function works', () => {
+      const collection = new Collection<Todo>();
+      const listener = vi.fn();
+      const unsubscribe = collection.subscribe(listener);
+
+      collection.add({ id: '1', text: 'Test', done: false });
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      collection.add({ id: '2', text: 'Test 2', done: true });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('dispose', () => {
+    it('sets disposed to true', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      expect(collection.disposed).toBe(true);
+    });
+
+    it('throws on add after dispose', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      expect(() => collection.add({ id: '1', text: 'Test', done: false })).toThrow(
+        'Cannot add to disposed Collection'
+      );
+    });
+
+    it('throws on remove after dispose', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      expect(() => collection.remove('1')).toThrow(
+        'Cannot remove from disposed Collection'
+      );
+    });
+
+    it('returns no-op on subscribe after dispose', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      const unsub = collection.subscribe(() => {});
+      expect(typeof unsub).toBe('function');
+      expect(() => unsub()).not.toThrow();
+    });
+
+    it('is idempotent', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      collection.dispose();
+      expect(collection.disposed).toBe(true);
+    });
+  });
+
+  describe('singleton integration', () => {
+    beforeEach(() => {
+      teardownAll();
+    });
+
+    it('can be used with singleton registry', () => {
+      class TodoCollection extends Collection<Todo> {}
+
+      const c1 = singleton(TodoCollection);
+      const c2 = singleton(TodoCollection);
+      expect(c1).toBe(c2);
+    });
+  });
+
+  describe('signal and addCleanup', () => {
+    it('signal returns an AbortSignal', () => {
+      const collection = new Collection<Todo>();
+      expect(collection.disposeSignal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('returns the same signal on multiple accesses', () => {
+      const collection = new Collection<Todo>();
+      const s1 = collection.disposeSignal;
+      const s2 = collection.disposeSignal;
+      expect(s1).toBe(s2);
+    });
+
+    it('signal is not aborted before dispose', () => {
+      const collection = new Collection<Todo>();
+      expect(collection.disposeSignal.aborted).toBe(false);
+    });
+
+    it('signal is aborted after dispose', () => {
+      const collection = new Collection<Todo>();
+      const signal = collection.disposeSignal;
+      collection.dispose();
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('signal is aborted before onDispose runs', () => {
+      let wasAbortedDuringDispose = false;
+      class CheckCollection extends Collection<Todo> {
+        protected onDispose(): void {
+          wasAbortedDuringDispose = this.disposeSignal.aborted;
+        }
+      }
+      const collection = new CheckCollection();
+      collection.disposeSignal; // force lazy creation
+      collection.dispose();
+      expect(wasAbortedDuringDispose).toBe(true);
+    });
+
+    it('addCleanup fires on dispose', () => {
+      let cleaned = false;
+      class CleanupCollection extends Collection<Todo> {
+        setup() {
+          this.addCleanup(() => { cleaned = true; });
+        }
+      }
+      const collection = new CleanupCollection();
+      collection.setup();
+      expect(cleaned).toBe(false);
+      collection.dispose();
+      expect(cleaned).toBe(true);
+    });
+
+    it('dispose works without accessing signal (lazy, zero cost)', () => {
+      const collection = new Collection<Todo>();
+      collection.dispose();
+      expect(collection.disposed).toBe(true);
+    });
+  });
+
+  describe('onDispose hook', () => {
+    it('calls onDispose on dispose (bug fix)', () => {
+      let called = false;
+      class DisposeCollection extends Collection<Todo> {
+        protected onDispose(): void {
+          called = true;
+        }
+      }
+      const collection = new DisposeCollection();
+      collection.dispose();
+      expect(called).toBe(true);
+    });
+
+    it('onDispose called only once even with multiple dispose calls', () => {
+      let callCount = 0;
+      class CountingCollection extends Collection<Todo> {
+        protected onDispose(): void {
+          callCount++;
+        }
+      }
+      const collection = new CountingCollection();
+      collection.dispose();
+      collection.dispose();
+      collection.dispose();
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('MAX_SIZE (capacity eviction)', () => {
+    class CappedCollection extends Collection<Todo> {
+      static MAX_SIZE = 3;
+    }
+
+    it('evicts oldest (FIFO) when add exceeds capacity', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.add({ id: '4', text: 'Fourth', done: false });
+
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('4')).toBe(true);
+      expect(collection.items[0].id).toBe('2');
+      expect(collection.items[2].id).toBe('4');
+    });
+
+    it('evicts on upsert when new items push over limit', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.upsert(
+        { id: '4', text: 'Fourth', done: false },
+        { id: '5', text: 'Fifth', done: false },
+      );
+
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('2')).toBe(false);
+      expect(collection.has('3')).toBe(true);
+      expect(collection.has('4')).toBe(true);
+      expect(collection.has('5')).toBe(true);
+    });
+
+    it('upsert replacing existing items does not trigger eviction', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.upsert({ id: '2', text: 'Updated', done: true });
+
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(true);
+      expect(collection.get('2')!.text).toBe('Updated');
+    });
+
+    it('reset() truncates to MAX_SIZE', () => {
+      const collection = new CappedCollection();
+
+      collection.reset([
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+        { id: '3', text: 'C', done: false },
+        { id: '4', text: 'D', done: false },
+        { id: '5', text: 'E', done: false },
+      ]);
+
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('2')).toBe(false);
+      expect(collection.items[0].id).toBe('3');
+    });
+
+    it('no eviction when under capacity', () => {
+      const collection = new CappedCollection();
+
+      collection.add(
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      );
+
+      expect(collection.length).toBe(2);
+      expect(collection.has('1')).toBe(true);
+      expect(collection.has('2')).toBe(true);
+    });
+
+    it('MAX_SIZE = 0 is unlimited (default behavior)', () => {
+      const collection = new Collection<Todo>();
+
+      for (let i = 0; i < 100; i++) {
+        collection.add({ id: String(i), text: `Item ${i}`, done: false });
+      }
+
+      expect(collection.length).toBe(100);
+    });
+
+    it('single notification for add + eviction', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      collection.add({ id: '4', text: 'Fourth', done: false });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('index stays consistent after eviction', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+      ]);
+
+      collection.add({ id: '4', text: 'Fourth', done: false });
+
+      expect(collection.get('1')).toBeUndefined();
+      expect(collection.get('4')).toEqual({ id: '4', text: 'Fourth', done: false });
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('4')).toBe(true);
+    });
+
+    it('constructor truncates initial items to MAX_SIZE', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+        { id: '3', text: 'C', done: false },
+        { id: '4', text: 'D', done: false },
+        { id: '5', text: 'E', done: false },
+      ]);
+
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('2')).toBe(false);
+      expect(collection.items[0].id).toBe('3');
+    });
+
+    it('evicts multiple items at once when adding batch over limit', () => {
+      const collection = new CappedCollection([
+        { id: '1', text: 'First', done: false },
+      ]);
+
+      collection.add(
+        { id: '2', text: 'Second', done: false },
+        { id: '3', text: 'Third', done: false },
+        { id: '4', text: 'Fourth', done: false },
+        { id: '5', text: 'Fifth', done: false },
+      );
+
+      expect(collection.length).toBe(3);
+      expect(collection.items[0].id).toBe('3');
+      expect(collection.items[2].id).toBe('5');
+    });
+  });
+
+  describe('TTL (time-to-live eviction)', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    class TTLCollection extends Collection<Todo> {
+      static TTL = 1000; // 1 second
+    }
+
+    it('items auto-removed after TTL expires', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      expect(collection.length).toBe(1);
+
+      vi.advanceTimersByTime(1000);
+
+      expect(collection.length).toBe(0);
+    });
+
+    it('subscribers notified on TTL sweep', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      const listener = vi.fn();
+      collection.subscribe(listener);
+
+      vi.advanceTimersByTime(1000);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(listener).toHaveBeenCalledWith([], [{ id: '1', text: 'Test', done: false }]);
+    });
+
+    it('timer rescheduled after partial sweep', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'First', done: false });
+
+      vi.advanceTimersByTime(500);
+      collection.add({ id: '2', text: 'Second', done: false });
+
+      // First item expires at 1000ms
+      vi.advanceTimersByTime(500);
+      expect(collection.length).toBe(1);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('2')).toBe(true);
+
+      // Second item expires at 1500ms
+      vi.advanceTimersByTime(500);
+      expect(collection.length).toBe(0);
+    });
+
+    it('no timer/timestamps when TTL = 0 (default)', () => {
+      const collection = new Collection<Todo>();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      // Access private field for zero-overhead verification
+      expect((collection as any)._timestamps).toBeNull();
+      expect((collection as any)._evictionTimer).toBeNull();
+    });
+
+    it('upsert() refreshes timestamp', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      // Wait 800ms, then upsert to refresh
+      vi.advanceTimersByTime(800);
+      collection.upsert({ id: '1', text: 'Refreshed', done: false });
+
+      // Original would have expired at 1000ms, but refresh extends it
+      vi.advanceTimersByTime(200);
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('Refreshed');
+
+      // Expires at 800 + 1000 = 1800ms total
+      vi.advanceTimersByTime(800);
+      expect(collection.length).toBe(0);
+    });
+
+    it('update() does NOT refresh timestamp', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      vi.advanceTimersByTime(800);
+      collection.update('1', { done: true });
+
+      // Still expires at original 1000ms
+      vi.advanceTimersByTime(200);
+      expect(collection.length).toBe(0);
+    });
+
+    it('clear() cancels timer + clears timestamps', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      collection.clear();
+
+      expect((collection as any)._evictionTimer).toBeNull();
+      expect((collection as any)._timestamps.size).toBe(0);
+
+      // Timer fire is harmless (no items to sweep)
+      vi.advanceTimersByTime(1000);
+      expect(collection.length).toBe(0);
+    });
+
+    it('reset() resets all timestamps', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Old', done: false });
+
+      vi.advanceTimersByTime(800);
+      collection.reset([
+        { id: '1', text: 'Reset', done: false },
+        { id: '2', text: 'New', done: false },
+      ]);
+
+      // Old timestamp was at 0ms, would expire at 1000ms
+      // Reset refreshes to 800ms, so expires at 1800ms
+      vi.advanceTimersByTime(200);
+      expect(collection.length).toBe(2);
+
+      vi.advanceTimersByTime(800);
+      expect(collection.length).toBe(0);
+    });
+
+    it('dispose() cancels timer', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      collection.dispose();
+
+      expect((collection as any)._evictionTimer).toBeNull();
+    });
+
+    it('timer fire after dispose is no-op', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      // Manually store timer reference, then dispose
+      collection.dispose();
+
+      // Even if a timer somehow fires, no crash
+      expect(() => vi.advanceTimersByTime(2000)).not.toThrow();
+    });
+
+    it('constructor sets up timestamps for initial items', () => {
+      const collection = new TTLCollection([
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+      ]);
+
+      expect((collection as any)._timestamps).toBeInstanceOf(Map);
+      expect((collection as any)._timestamps.size).toBe(2);
+
+      vi.advanceTimersByTime(1000);
+      expect(collection.length).toBe(0);
+    });
+
+    it('remove() cleans up timestamps', () => {
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'A', done: false });
+      collection.add({ id: '2', text: 'B', done: false });
+
+      collection.remove('1');
+
+      expect((collection as any)._timestamps.has('1')).toBe(false);
+      expect((collection as any)._timestamps.has('2')).toBe(true);
+    });
+  });
+
+  describe('onEvict hook', () => {
+    it('called with candidates before capacity eviction', () => {
+      const evictCalls: { items: Todo[]; reason: string }[] = [];
+
+      class HookCollection extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        protected onEvict(items: Todo[], reason: 'capacity' | 'ttl') {
+          evictCalls.push({ items: [...items], reason });
+        }
+      }
+
+      const collection = new HookCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      collection.add({ id: '3', text: 'Third', done: false });
+
+      expect(evictCalls).toHaveLength(1);
+      expect(evictCalls[0].reason).toBe('capacity');
+      expect(evictCalls[0].items).toHaveLength(1);
+      expect(evictCalls[0].items[0].id).toBe('1');
+    });
+
+    it('called with expired items before TTL eviction', () => {
+      vi.useFakeTimers();
+      const evictCalls: { items: Todo[]; reason: string }[] = [];
+
+      class HookTTLCollection extends Collection<Todo> {
+        static TTL = 1000;
+        protected onEvict(items: Todo[], reason: 'capacity' | 'ttl') {
+          evictCalls.push({ items: [...items], reason });
+        }
+      }
+
+      const collection = new HookTTLCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      vi.advanceTimersByTime(1000);
+
+      expect(evictCalls).toHaveLength(1);
+      expect(evictCalls[0].reason).toBe('ttl');
+      expect(evictCalls[0].items[0].id).toBe('1');
+
+      vi.useRealTimers();
+    });
+
+    it('returning false vetoes eviction', () => {
+      class VetoCollection extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        protected onEvict() {
+          return false as const;
+        }
+      }
+
+      const collection = new VetoCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      collection.add({ id: '3', text: 'Third', done: false });
+
+      // All items kept despite MAX_SIZE = 2
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(true);
+      expect(collection.has('3')).toBe(true);
+    });
+
+    it('returning T[] subset evicts only those', () => {
+      class FilterCollection extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        protected onEvict(items: Todo[]) {
+          // Only evict done items
+          return items.filter(i => i.done);
+        }
+      }
+
+      const collection = new FilterCollection([
+        { id: '1', text: 'First', done: true },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      collection.add({ id: '3', text: 'Third', done: false });
+
+      // Only id=1 (done) was evicted
+      expect(collection.length).toBe(2);
+      expect(collection.has('1')).toBe(false);
+      expect(collection.has('2')).toBe(true);
+      expect(collection.has('3')).toBe(true);
+    });
+
+    it('returning void proceeds with all candidates', () => {
+      class VoidCollection extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        protected onEvict() {
+          // void return
+        }
+      }
+
+      const collection = new VoidCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: false },
+      ]);
+
+      collection.add({ id: '3', text: 'Third', done: false });
+
+      expect(collection.length).toBe(2);
+      expect(collection.has('1')).toBe(false);
+    });
+
+    it('DEV warning when veto causes >2x MAX_SIZE', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      class BigVetoCollection extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        protected onEvict() {
+          return false as const;
+        }
+      }
+
+      const collection = new BigVetoCollection([
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+      ]);
+
+      // Add items to exceed 2x MAX_SIZE (2*2=4, need >4)
+      collection.add({ id: '3', text: 'C', done: false });
+      collection.add({ id: '4', text: 'D', done: false });
+      collection.add({ id: '5', text: 'E', done: false });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Collection exceeded 2x MAX_SIZE')
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it('TTL veto keeps items alive', () => {
+      vi.useFakeTimers();
+
+      class TTLVetoCollection extends Collection<Todo> {
+        static TTL = 1000;
+        protected onEvict() {
+          return false as const;
+        }
+      }
+
+      const collection = new TTLVetoCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      vi.advanceTimersByTime(1000);
+
+      expect(collection.length).toBe(1);
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('MAX_SIZE + TTL interactions', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('both enforced independently', () => {
+      class BothCollection extends Collection<Todo> {
+        static MAX_SIZE = 3;
+        static TTL = 1000;
+      }
+
+      const collection = new BothCollection();
+      collection.add(
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+        { id: '3', text: 'C', done: false },
+      );
+
+      // Capacity eviction
+      collection.add({ id: '4', text: 'D', done: false });
+      expect(collection.length).toBe(3);
+      expect(collection.has('1')).toBe(false);
+
+      // TTL eviction
+      vi.advanceTimersByTime(1000);
+      expect(collection.length).toBe(0);
+    });
+
+    it('optimistic rollback restores evicted items + timestamps', () => {
+      class CappedTTL extends Collection<Todo> {
+        static MAX_SIZE = 2;
+        static TTL = 1000;
+      }
+
+      const collection = new CappedTTL([
+        { id: '1', text: 'A', done: false },
+        { id: '2', text: 'B', done: false },
+      ]);
+
+      const rollback = collection.optimistic(() => {
+        collection.add({ id: '3', text: 'C', done: false });
+      });
+
+      // Capacity evicted id=1
+      expect(collection.length).toBe(2);
+      expect(collection.has('1')).toBe(false);
+
+      rollback();
+
+      // Restored
+      expect(collection.length).toBe(2);
+      expect(collection.has('1')).toBe(true);
+      expect(collection.has('2')).toBe(true);
+      expect(collection.has('3')).toBe(false);
+
+      // TTL still works after rollback
+      vi.advanceTimersByTime(1000);
+      expect(collection.length).toBe(0);
+    });
+  });
+
+  describe('zero-overhead verification', () => {
+    it('no _timestamps Map for default Collection', () => {
+      const collection = new Collection<Todo>();
+      collection.add({ id: '1', text: 'Test', done: false });
+      expect((collection as any)._timestamps).toBeNull();
+    });
+
+    it('no timer for default Collection', () => {
+      const collection = new Collection<Todo>();
+      collection.add({ id: '1', text: 'Test', done: false });
+      expect((collection as any)._evictionTimer).toBeNull();
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const collection = new Collection<Todo>();
+      const { add, remove, get, has } = collection;
+      add({ id: '1', text: 'Test', done: false });
+      expect(collection.length).toBe(1);
+      expect(has('1')).toBe(true);
+      expect(get('1')).toEqual({ id: '1', text: 'Test', done: false });
+      remove('1');
+      expect(collection.length).toBe(0);
+    });
+
+    it('methods work as React-style callbacks', () => {
+      const collection = new Collection<Todo>();
+      const callback: (...items: Todo[]) => void = collection.add;
+      callback({ id: '1', text: 'Test', done: false });
+      expect(collection.length).toBe(1);
+    });
+
+    it('subclass methods are also bound', () => {
+      class TodoCollection extends Collection<Todo> {
+        completed(): Todo[] { return this.filter(t => t.done); }
+      }
+      const col = new TodoCollection();
+      const { completed, add } = col;
+      add({ id: '1', text: 'Test', done: true });
+      expect(completed()).toEqual([{ id: '1', text: 'Test', done: true }]);
+    });
+
+    it('multi-level inheritance chain binds all levels', () => {
+      class BaseCollection extends Collection<Todo> {
+        baseMethod(): number { return this.length; }
+      }
+      class LeafCollection extends BaseCollection {
+        leafMethod(): string { return `count: ${this.length}`; }
+      }
+      const col = new LeafCollection();
+      const { add, baseMethod, leafMethod } = col;
+      add({ id: '1', text: 'Test', done: false });
+      expect(baseMethod()).toBe(1);
+      expect(leafMethod()).toBe('count: 1');
+    });
+
+    it('most-derived override wins in subclass chain', () => {
+      class TrackingCollection extends Collection<Todo> {
+        addCount = 0;
+        override add(...items: Todo[]): void {
+          this.addCount += items.length;
+          super.add(...items);
+        }
+      }
+      const col = new TrackingCollection();
+      const { add } = col;
+      add({ id: '1', text: 'Test', done: false });
+      expect(col.addCount).toBe(1);
+      expect(col.length).toBe(1);
+    });
+  });
+});