mvc-kit 2.12.0 → 2.12.1

package/src/PersistentCollection.test.ts

@@ -0,0 +1,649 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { PersistentCollection } from './PersistentCollection';
+import { singleton, teardownAll } from './singleton';
+
+interface Todo {
+  id: string;
+  text: string;
+  done: boolean;
+}
+
+// ── In-memory mock adapter ──
+
+class MockStore<T extends { id: string | number }> {
+  data = new Map<T['id'], T>();
+
+  getAll(): T[] {
+    return [...this.data.values()];
+  }
+  get(id: T['id']): T | null {
+    return this.data.get(id) ?? null;
+  }
+  set(items: T[]): void {
+    for (const item of items) {
+      this.data.set(item.id, item);
+    }
+  }
+  remove(ids: T['id'][]): void {
+    for (const id of ids) {
+      this.data.delete(id);
+    }
+  }
+  clear(): void {
+    this.data.clear();
+  }
+}
+
+let mockStore: MockStore<Todo>;
+
+class TestPersistentCollection extends PersistentCollection<Todo> {
+  protected readonly storageKey = 'test-todos';
+
+  protected persistGet(id: Todo['id']): Todo | null {
+    return mockStore.get(id);
+  }
+  protected persistGetAll(): Todo[] {
+    return mockStore.getAll();
+  }
+  protected persistSet(items: Todo[]): void {
+    mockStore.set(items);
+  }
+  protected persistRemove(ids: Todo['id'][]): void {
+    mockStore.remove(ids);
+  }
+  protected persistClear(): void {
+    mockStore.clear();
+  }
+}
+
+describe('PersistentCollection', () => {
+  beforeEach(() => {
+    teardownAll();
+    mockStore = new MockStore();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // ── Hydration ──
+
+  describe('hydration', () => {
+    it('loads data from storage via hydrate()', async () => {
+      mockStore.set([
+        { id: '1', text: 'Stored', done: false },
+        { id: '2', text: 'Also stored', done: true },
+      ]);
+
+      const collection = new TestPersistentCollection();
+      expect(collection.hydrated).toBe(false);
+
+      const items = await collection.hydrate();
+
+      expect(collection.hydrated).toBe(true);
+      expect(items).toHaveLength(2);
+      expect(collection.length).toBe(2);
+      expect(collection.get('1')!.text).toBe('Stored');
+      collection.dispose();
+    });
+
+    it('hydrate() is idempotent — second call returns current items', async () => {
+      mockStore.set([{ id: '1', text: 'Stored', done: false }]);
+
+      const collection = new TestPersistentCollection();
+      await collection.hydrate();
+
+      // Add another item after hydration
+      collection.add({ id: '2', text: 'New', done: false });
+
+      // Second hydrate returns current state (not re-reading storage)
+      const items = await collection.hydrate();
+      expect(items).toHaveLength(2);
+      collection.dispose();
+    });
+
+    it('hydrate() does not trigger persist calls (skip-save)', async () => {
+      const persistSetSpy = vi.fn();
+      const persistClearSpy = vi.fn();
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-hydrate';
+        protected persistGet(id: Todo['id']): Todo | null {
+          return mockStore.get(id);
+        }
+        protected persistGetAll(): Todo[] {
+          return mockStore.getAll();
+        }
+        protected persistSet(items: Todo[]): void {
+          persistSetSpy(items);
+          mockStore.set(items);
+        }
+        protected persistRemove(ids: Todo['id'][]): void {
+          mockStore.remove(ids);
+        }
+        protected persistClear(): void {
+          persistClearSpy();
+          mockStore.clear();
+        }
+      }
+
+      mockStore.set([{ id: '1', text: 'Stored', done: false }]);
+      const collection = new SpyCollection();
+      await collection.hydrate();
+
+      // Flush any pending timers
+      vi.runAllTimers();
+
+      expect(persistSetSpy).not.toHaveBeenCalled();
+      expect(persistClearSpy).not.toHaveBeenCalled();
+      collection.dispose();
+    });
+
+    it('handles storage errors during hydrate gracefully', async () => {
+      const errorSpy = vi.fn();
+
+      class ErrorCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'error-hydrate';
+        protected onPersistError = errorSpy;
+        protected persistGet(): Todo | null { return null; }
+        protected persistGetAll(): Todo[] { throw new Error('Storage read failed'); }
+        protected persistSet(): void {}
+        protected persistRemove(): void {}
+        protected persistClear(): void {}
+      }
+
+      const collection = new ErrorCollection();
+      const items = await collection.hydrate();
+
+      expect(collection.hydrated).toBe(true);
+      expect(items).toHaveLength(0);
+      expect(errorSpy).toHaveBeenCalledWith(expect.any(Error));
+      collection.dispose();
+    });
+  });
+
+  // ── Per-item save (delta tracking) ──
+
+  describe('delta tracking', () => {
+    it('add() persists only the new items', () => {
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-add';
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection();
+      collection.add({ id: '1', text: 'First', done: false });
+      vi.runAllTimers();
+
+      expect(persistSetSpy).toHaveBeenCalledWith([{ id: '1', text: 'First', done: false }]);
+      collection.dispose();
+    });
+
+    it('remove() persists only the removed IDs', () => {
+      const persistRemoveSpy = vi.fn((ids: Todo['id'][]) => mockStore.remove(ids));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-remove';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { mockStore.set(items); }
+        protected persistRemove(ids: Todo['id'][]) { persistRemoveSpy(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection([
+        { id: '1', text: 'First', done: false },
+        { id: '2', text: 'Second', done: true },
+      ]);
+      collection.remove('1');
+      vi.runAllTimers();
+
+      expect(persistRemoveSpy).toHaveBeenCalledWith(['1']);
+      collection.dispose();
+    });
+
+    it('update() persists only the updated item', () => {
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-update';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection([{ id: '1', text: 'Original', done: false }]);
+      collection.update('1', { text: 'Updated' });
+      vi.runAllTimers();
+
+      expect(persistSetSpy).toHaveBeenCalledWith([
+        expect.objectContaining({ id: '1', text: 'Updated', done: false }),
+      ]);
+      collection.dispose();
+    });
+
+    it('upsert() persists changed/new items', () => {
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-upsert';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection([
+        { id: '1', text: 'Original', done: false },
+      ]);
+      collection.upsert(
+        { id: '1', text: 'Changed', done: false },
+        { id: '2', text: 'New', done: true },
+      );
+      vi.runAllTimers();
+
+      expect(persistSetSpy).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          { id: '1', text: 'Changed', done: false },
+          { id: '2', text: 'New', done: true },
+        ]),
+      );
+      collection.dispose();
+    });
+
+    it('reset() triggers persistClear + persistSet with all new items', () => {
+      const persistClearSpy = vi.fn(() => mockStore.clear());
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-reset';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { persistClearSpy(); }
+      }
+
+      const collection = new SpyCollection([{ id: '1', text: 'Old', done: false }]);
+      collection.reset([
+        { id: '2', text: 'New1', done: false },
+        { id: '3', text: 'New2', done: true },
+      ]);
+      vi.runAllTimers();
+
+      expect(persistClearSpy).toHaveBeenCalled();
+      expect(persistSetSpy).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          { id: '2', text: 'New1', done: false },
+          { id: '3', text: 'New2', done: true },
+        ]),
+      );
+      collection.dispose();
+    });
+
+    it('clear() triggers persistClear', () => {
+      const persistClearSpy = vi.fn(() => mockStore.clear());
+      const persistSetSpy = vi.fn();
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-clear';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { persistClearSpy(); }
+      }
+
+      const collection = new SpyCollection([{ id: '1', text: 'Item', done: false }]);
+      collection.clear();
+      vi.runAllTimers();
+
+      expect(persistClearSpy).toHaveBeenCalled();
+      expect(persistSetSpy).not.toHaveBeenCalled();
+      collection.dispose();
+    });
+  });
+
+  // ── Debounce coalescing ──
+
+  describe('debounce', () => {
+    it('coalesces rapid mutations into a single flush', () => {
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+      const persistRemoveSpy = vi.fn((ids: Todo['id'][]) => mockStore.remove(ids));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        static override WRITE_DELAY = 100;
+        protected readonly storageKey = 'spy-debounce';
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { persistRemoveSpy(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection();
+
+      // Rapid mutations
+      collection.add({ id: '1', text: 'First', done: false });
+      collection.add({ id: '2', text: 'Second', done: false });
+      collection.remove('1');
+
+      // Nothing flushed yet
+      expect(persistSetSpy).not.toHaveBeenCalled();
+      expect(persistRemoveSpy).not.toHaveBeenCalled();
+
+      vi.runAllTimers();
+
+      // Net result: id=2 added, id=1 removed (was added then removed — cancel out)
+      expect(persistSetSpy).toHaveBeenCalledTimes(1);
+      expect(persistSetSpy).toHaveBeenCalledWith([{ id: '2', text: 'Second', done: false }]);
+      collection.dispose();
+    });
+
+    it('default WRITE_DELAY = 0 saves immediately', () => {
+      const persistSetSpy = vi.fn();
+
+      class ImmediateCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'immediate';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      const collection = new ImmediateCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      // Should have flushed immediately (no timer needed)
+      expect(persistSetSpy).toHaveBeenCalledTimes(1);
+      collection.dispose();
+    });
+  });
+
+  // ── Dispose flushes ──
+
+  describe('dispose', () => {
+    it('flushes pending save on dispose', () => {
+      const persistSetSpy = vi.fn();
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        static override WRITE_DELAY = 100;
+        protected readonly storageKey = 'spy-dispose';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      const collection = new SpyCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      // Not yet flushed (debounced)
+      expect(persistSetSpy).not.toHaveBeenCalled();
+
+      collection.dispose();
+
+      // Should have flushed on dispose
+      expect(persistSetSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ── clearStorage ──
+
+  describe('clearStorage', () => {
+    it('removes storage AND clears in-memory items', () => {
+      const persistClearSpy = vi.fn(() => mockStore.clear());
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-clearStorage';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet() { return null; }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { mockStore.set(items); }
+        protected persistRemove(ids: Todo['id'][]) { mockStore.remove(ids); }
+        protected persistClear() { persistClearSpy(); }
+      }
+
+      const collection = new SpyCollection([
+        { id: '1', text: 'Test', done: false },
+      ]);
+
+      collection.clearStorage();
+
+      expect(collection.length).toBe(0);
+      expect(persistClearSpy).toHaveBeenCalled();
+      collection.dispose();
+    });
+  });
+
+  // ── Error handling ──
+
+  describe('error handling', () => {
+    it('storage errors do not break the collection', () => {
+      class ErrorCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'error-write';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet() { throw new Error('Write failed'); }
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const collection = new ErrorCollection();
+
+      // Should not throw
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      expect(collection.length).toBe(1);
+      expect(collection.get('1')!.text).toBe('Test');
+      warnSpy.mockRestore();
+      collection.dispose();
+    });
+
+    it('onPersistError hook receives errors', () => {
+      const errorSpy = vi.fn();
+
+      class ErrorCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'error-hook';
+        protected onPersistError = errorSpy;
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet() { throw new Error('Write failed'); }
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      const collection = new ErrorCollection();
+      collection.add({ id: '1', text: 'Test', done: false });
+
+      expect(errorSpy).toHaveBeenCalledWith(expect.any(Error));
+      collection.dispose();
+    });
+  });
+
+  // ── DEV guards ──
+
+  describe('DEV guards', () => {
+    it('warns on duplicate storageKey across different classes', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      class CollectionA extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'shared-key';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet() {}
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      class CollectionB extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'shared-key';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet() {}
+        protected persistRemove() {}
+        protected persistClear() {}
+      }
+
+      const a = new CollectionA();
+      // Trigger _ensurePersistenceReady by mutating
+      a.add({ id: '1', text: 'A', done: false });
+      vi.runAllTimers();
+
+      const b = new CollectionB();
+      b.add({ id: '2', text: 'B', done: false });
+      vi.runAllTimers();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Duplicate storageKey'),
+      );
+
+      warnSpy.mockRestore();
+      a.dispose();
+      b.dispose();
+    });
+
+    it('warns on items access before hydrate()', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const collection = new TestPersistentCollection();
+
+      // Access items before hydrate
+      void collection.items;
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('before hydrate()'),
+      );
+
+      // Only warns once
+      void collection.items;
+
+      warnSpy.mockRestore();
+      collection.dispose();
+    });
+  });
+
+  // ── Optimistic rollback ──
+
+  describe('optimistic rollback', () => {
+    it('persists correctly after rollback', () => {
+      const persistSetSpy = vi.fn((items: Todo[]) => mockStore.set(items));
+      const persistRemoveSpy = vi.fn((ids: Todo['id'][]) => mockStore.remove(ids));
+
+      class SpyCollection extends PersistentCollection<Todo> {
+        protected readonly storageKey = 'spy-optimistic';
+        constructor(items: Todo[] = []) {
+          super(items);
+        }
+        protected persistGet(id: Todo['id']) { return mockStore.get(id); }
+        protected persistGetAll() { return mockStore.getAll(); }
+        protected persistSet(items: Todo[]) { persistSetSpy(items); }
+        protected persistRemove(ids: Todo['id'][]) { persistRemoveSpy(ids); }
+        protected persistClear() { mockStore.clear(); }
+      }
+
+      const collection = new SpyCollection([
+        { id: '1', text: 'Original', done: false },
+      ]);
+
+      // Flush initial state (no pending since constructor items don't trigger subscriber)
+      vi.runAllTimers();
+      persistSetSpy.mockClear();
+      persistRemoveSpy.mockClear();
+
+      const rollback = collection.optimistic(() => {
+        collection.remove('1');
+        collection.add({ id: '2', text: 'Optimistic', done: false });
+      });
+
+      // Flush optimistic state
+      vi.runAllTimers();
+      persistRemoveSpy.mockClear();
+      persistSetSpy.mockClear();
+
+      // Rollback
+      rollback();
+      vi.runAllTimers();
+
+      // After rollback, should persist the restored state:
+      // id=1 should be written back, id=2 should be removed
+      expect(persistSetSpy).toHaveBeenCalledWith([
+        expect.objectContaining({ id: '1', text: 'Original' }),
+      ]);
+      expect(persistRemoveSpy).toHaveBeenCalledWith(['2']);
+      collection.dispose();
+    });
+  });
+
+  // ── Singleton integration ──
+
+  describe('singleton integration', () => {
+    it('works with singleton() and teardownAll()', () => {
+      const collection = singleton(TestPersistentCollection);
+      collection.add({ id: '1', text: 'Test', done: false });
+      expect(collection.length).toBe(1);
+
+      teardownAll();
+      expect(collection.disposed).toBe(true);
+    });
+  });
+
+  // ── TTL sweep triggers persist ──
+
+  describe('TTL eviction triggers persist', () => {
+    it('evicted items are persisted as removes', () => {
+      const persistRemoveSpy = vi.fn();
+
+      class TTLCollection extends PersistentCollection<Todo> {
+        static override TTL = 100;
+        protected readonly storageKey = 'ttl-test';
+        protected persistGet() { return null; }
+        protected persistGetAll() { return []; }
+        protected persistSet() {}
+        protected persistRemove(ids: Todo['id'][]) { persistRemoveSpy(ids); }
+        protected persistClear() {}
+      }
+
+      const collection = new TTLCollection();
+      collection.add({ id: '1', text: 'Expiring', done: false });
+      persistRemoveSpy.mockClear();
+
+      // Advance past TTL
+      vi.advanceTimersByTime(150);
+
+      expect(persistRemoveSpy).toHaveBeenCalledWith(['1']);
+      expect(collection.length).toBe(0);
+      collection.dispose();
+    });
+  });
+});