mvc-kit 2.12.0 → 2.12.1

package/src/react/use-singleton.ts

@@ -0,0 +1,69 @@
+import { useEffect } from 'react';
+import type { Subscribable, Disposable } from '../types';
+import { singleton } from '../singleton';
+import { useInstance } from './use-instance';
+import { isSubscribable, isSubscribeOnly, isInitializable } from './guards';
+import { useSubscribeOnly } from './use-subscribe-only';
+import type { StateOf } from './types';
+
+/**
+ * Get singleton Subscribable with DEFAULT_STATE — no constructor args needed.
+ */
+export function useSingleton<
+  T extends Subscribable<S> & Disposable, S = StateOf<T>,
+>(Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown }): [S, T];
+
+/**
+ * Get singleton Disposable with DEFAULT_STATE — no constructor args needed.
+ */
+export function useSingleton<T extends Disposable>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown },
+): T;
+
+/**
+ * Get singleton Subscribable instance and subscribe to its state.
+ * Returns [state, instance] tuple.
+ */
+export function useSingleton<
+  T extends Subscribable<S> & Disposable,
+  S = StateOf<T>,
+  Args extends unknown[] = unknown[]
+>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): [S, T];
+
+/**
+ * Get singleton Disposable instance (non-Subscribable).
+ * Returns the instance directly.
+ */
+export function useSingleton<T extends Disposable, Args extends unknown[] = unknown[]>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): T;
+
+// Implementation
+export function useSingleton<T extends Disposable, S = StateOf<T>, Args extends unknown[] = unknown[]>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): [S, T] | T {
+  const instance = singleton(Class, ...args);
+
+  useEffect(() => {
+    if (isInitializable(instance)) {
+      instance.init();
+    }
+  }, [instance]);
+
+  if (isSubscribable(instance)) {
+    const state = useInstance(instance) as S;
+    return [state, instance];
+  }
+
+  if (isSubscribeOnly(instance)) {
+    useSubscribeOnly(instance);
+    return instance;
+  }
+
+  return instance;
+}

package/src/react/use-subscribe-only.ts

@@ -0,0 +1,39 @@
+import { useSyncExternalStore, useRef } from 'react';
+
+interface SubscribeOnlyRef {
+  target: { subscribe(cb: () => void): () => void };
+  version: number;
+  subscribe: (onStoreChange: () => void) => () => void;
+  getSnapshot: () => number;
+}
+
+const SERVER_SNAPSHOT = () => 0;
+
+/**
+ * Subscribe to a notification-only object (has subscribe() but no state).
+ * Triggers React re-renders via version counter when the target notifies.
+ * @internal
+ */
+export function useSubscribeOnly(
+  target: { subscribe(cb: () => void): () => void },
+): void {
+  const ref = useRef<SubscribeOnlyRef | null>(null);
+
+  if (!ref.current || ref.current.target !== target) {
+    const version = { current: ref.current?.version ?? 0 };
+    ref.current = {
+      target,
+      version: version.current,
+      subscribe: (onStoreChange: () => void) => {
+        return target.subscribe(() => {
+          version.current++;
+          ref.current!.version = version.current;
+          onStoreChange();
+        });
+      },
+      getSnapshot: () => version.current,
+    };
+  }
+
+  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);
+}

package/src/react/use-teardown.md

@@ -0,0 +1,169 @@
+# useTeardown
+
+Teardown one or more [singleton](../singleton.md) instances when the component unmounts. Uses deferred disposal to safely handle React StrictMode's double-mount cycle.
+
+---
+
+## Signature
+
+```typescript
+function useTeardown(
+  ...Classes: Array<new (...args: unknown[]) => Disposable>
+): void
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `...Classes` | `Array<new (...args: unknown[]) => Disposable>` | One or more singleton classes to tear down on unmount. Any class registered via `singleton()` that implements the [Disposable](../types.ts) interface — [ViewModel](../ViewModel.md), [Service](../Service.md), [Collection](../Collection.md), [EventBus](../EventBus.md), [Channel](../Channel.md). |
+
+**Returns:** `void`
+
+---
+
+## How It Works
+
+`useTeardown` calls [`teardown(Class)`](../singleton.md) for each class when the component unmounts. Disposal is **deferred** via `setTimeout(0)` to survive React StrictMode's unmount-then-remount cycle.
+
+```
+Mount → mountedRef = true
+StrictMode unmount → mountedRef = false → setTimeout scheduled
+StrictMode remount → mountedRef = true (before timeout fires)
+Timeout fires → mountedRef is true → teardown skipped ✓
+
+Real unmount → mountedRef = false → setTimeout scheduled
+Timeout fires → mountedRef is still false → teardown(Class) called ✓
+```
+
+Key behaviors:
+
+- **Deferred disposal** — `teardown()` runs in a `setTimeout(0)`, not synchronously in the cleanup function. This gives StrictMode's remount a chance to set `mountedRef` back to `true` before the timeout fires.
+- **Idempotent** — If the singleton was already disposed or never created, `teardown()` is a no-op. No errors thrown.
+- **Multiple classes** — Pass any number of classes as arguments. Each is torn down independently.
+- **One-time effect** — The `useEffect` runs once on mount (empty deps array). Cleanup runs once on unmount.
+
+---
+
+## When to Use
+
+Use `useTeardown` when a component is the **owner boundary** for singleton state — the point in the tree where the singleton's lifecycle should end.
+
+Common scenarios:
+
+- A page component that creates a singleton ViewModel (via `useSingleton`) and wants the singleton cleaned up when the user navigates away
+- A layout shell that owns shared infrastructure singletons (EventBus, Channel) and should dispose them when the shell unmounts
+- A route boundary that needs to reset shared Collections when the feature area is exited
+
+```tsx
+function ChatPage() {
+  const [state, vm] = useSingleton(ChatViewModel, { messages: [] });
+  useTeardown(ChatViewModel, ChatChannel);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+When the user navigates away from `ChatPage`, both `ChatViewModel` and `ChatChannel` singletons are disposed and removed from the registry. The next time `ChatPage` mounts, `singleton(ChatViewModel)` creates a fresh instance.
+
+### When NOT to Use
+
+| Scenario | Why |
+|---|---|
+| Component-scoped ViewModels via `useLocal` | `useLocal` handles dispose automatically — no singleton involved |
+| Singletons that should outlive the component | If the singleton is shared app-wide (auth, theme), don't tear it down on page navigation |
+| Test cleanup | Use `teardownAll()` in `beforeEach` instead — see [Singleton: Test Cleanup](../singleton.md) |
+
+---
+
+## Usage
+
+### Single Singleton
+
+```tsx
+function DashboardPage() {
+  const [state, vm] = useSingleton(DashboardViewModel, { data: null });
+  useTeardown(DashboardViewModel);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+### Multiple Singletons
+
+Pass all classes in a single call:
+
+```tsx
+function ChatPage() {
+  const [state, vm] = useSingleton(ChatViewModel, { messages: [] });
+  useTeardown(ChatViewModel, ChatChannel, ChatCollection);
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+Each class is torn down independently — if one was already disposed, the others are still cleaned up.
+
+### Non-Existent Singletons
+
+If a class was never registered via `singleton()`, `useTeardown` is a no-op for that class. No error thrown:
+
+```tsx
+function Component() {
+  // CounterVM was never created as a singleton — safe, does nothing
+  useTeardown(CounterVM);
+  return null;
+}
+```
+
+---
+
+## StrictMode Safety
+
+React StrictMode double-mounts components in development to expose impure effects. `useTeardown` handles this correctly:
+
+1. **First mount** — `mountedRef` set to `true`
+2. **StrictMode unmount** — cleanup runs, `mountedRef` set to `false`, `setTimeout` scheduled
+3. **StrictMode remount** — `mountedRef` set back to `true` before the timeout fires
+4. **Timeout fires** — checks `mountedRef`, sees `true`, skips teardown
+
+The singleton survives the fake unmount. On a real unmount (no remount follows), the timeout fires with `mountedRef` still `false` and teardown proceeds.
+
+---
+
+## Best Practices
+
+**Place `useTeardown` in the same component that uses `useSingleton`.** The owner of the singleton subscription should be the owner of its teardown. This keeps lifecycle management colocated:
+
+```tsx
+// Good: colocated
+function ChatPage() {
+  const [state, vm] = useSingleton(ChatViewModel, { messages: [] });
+  useTeardown(ChatViewModel);
+  return <div>{/* ... */}</div>;
+}
+
+// Bad: teardown in a different component than the subscriber
+function ChatPage() {
+  const [state, vm] = useSingleton(ChatViewModel, { messages: [] });
+  return <ChatContent />;
+}
+function AppShell() {
+  useTeardown(ChatViewModel); // far from where it's used
+  return <Outlet />;
+}
+```
+
+**Don't tear down singletons that other mounted components depend on.** If two sibling components both use `useSingleton(CartViewModel)`, tearing it down when one unmounts will dispose the instance the other is still reading. Only tear down at the highest common owner — or don't tear down at all if the singleton should be app-wide.
+
+**Don't use `useTeardown` with `useLocal`.** `useLocal` creates and disposes its own instance — it doesn't use the singleton registry. `useTeardown` only affects singletons.
+
+**Prefer `teardownAll()` in tests over `useTeardown`.** Test cleanup should use `teardownAll()` in `beforeEach` for complete isolation. `useTeardown` is a runtime hook for production component lifecycles.
+
+---
+
+## Related
+
+- [Singleton Registry](../singleton.md) — `singleton()`, `teardown()`, `teardownAll()`, `hasSingleton()`
+- [ViewModel](../ViewModel.md) — most common class used with singleton teardown
+- [Collection](../Collection.md) — shared data caches often torn down with their owning ViewModel
+- [Channel](../Channel.md) — persistent connections that should be disposed when no longer needed
+- [EventBus](../EventBus.md) — app-level event buses that may need teardown on route exit

package/src/react/use-teardown.test.tsx

@@ -0,0 +1,86 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render } from '@testing-library/react';
+import { vi, beforeEach, afterEach } from 'vitest';
+import { ViewModel } from '../ViewModel';
+import { singleton, hasSingleton, teardownAll } from '../singleton';
+import { useTeardown } from './use-teardown';
+
+interface CountState {
+  count: number;
+}
+
+class CounterVM extends ViewModel<CountState> {
+  constructor() {
+    super({ count: 0 });
+  }
+}
+
+class AnotherVM extends ViewModel<CountState> {
+  constructor() {
+    super({ count: 0 });
+  }
+}
+
+describe('useTeardown', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.runAllTimers();
+    vi.useRealTimers();
+    teardownAll();
+  });
+
+  it('should teardown singleton on unmount', () => {
+    singleton(CounterVM);
+    expect(hasSingleton(CounterVM)).toBe(true);
+
+    function Component() {
+      useTeardown(CounterVM);
+      return null;
+    }
+
+    const { unmount } = render(<Component />);
+    expect(hasSingleton(CounterVM)).toBe(true);
+
+    unmount();
+    // Teardown is deferred
+    expect(hasSingleton(CounterVM)).toBe(true);
+
+    vi.runAllTimers();
+    expect(hasSingleton(CounterVM)).toBe(false);
+  });
+
+  it('should teardown multiple singletons', () => {
+    singleton(CounterVM);
+    singleton(AnotherVM);
+    expect(hasSingleton(CounterVM)).toBe(true);
+    expect(hasSingleton(AnotherVM)).toBe(true);
+
+    function Component() {
+      useTeardown(CounterVM, AnotherVM);
+      return null;
+    }
+
+    const { unmount } = render(<Component />);
+    unmount();
+
+    vi.runAllTimers();
+    expect(hasSingleton(CounterVM)).toBe(false);
+    expect(hasSingleton(AnotherVM)).toBe(false);
+  });
+
+  it('should not throw if singleton does not exist', () => {
+    function Component() {
+      useTeardown(CounterVM);
+      return null;
+    }
+
+    const { unmount } = render(<Component />);
+    unmount();
+    expect(() => vi.runAllTimers()).not.toThrow();
+  });
+});

package/src/react/use-teardown.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react';
+import type { Disposable } from '../types';
+import { teardown } from '../singleton';
+
+/**
+ * Teardown singleton class(es) on unmount.
+ * Uses deferred disposal to handle StrictMode's double-mount cycle.
+ */
+export function useTeardown(
+  ...Classes: Array<new (...args: unknown[]) => Disposable>
+): void {
+  const mountedRef = useRef(false);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      setTimeout(() => {
+        if (!mountedRef.current) {
+          for (const Class of Classes) {
+            teardown(Class);
+          }
+        }
+      }, 0);
+    };
+  }, []);  // eslint-disable-line react-hooks/exhaustive-deps
+}

package/src/react-native/NativeCollection.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { NativeCollection } from './NativeCollection';
+import { teardownAll } from '../singleton';
+
+interface Todo {
+  id: string;
+  title: string;
+  done: boolean;
+}
+
+// In-memory async storage mock
+function createMockStorage() {
+  const store = new Map<string, string>();
+  return {
+    store,
+    getItem: vi.fn((key: string) => Promise.resolve(store.get(key) ?? null)),
+    setItem: vi.fn((key: string, value: string) => {
+      store.set(key, value);
+      return Promise.resolve();
+    }),
+    removeItem: vi.fn((key: string) => {
+      store.delete(key);
+      return Promise.resolve();
+    }),
+  };
+}
+
+class TodosCollection extends NativeCollection<Todo> {
+  protected readonly storageKey = 'todos';
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 10));
+
+describe('NativeCollection', () => {
+  let mock: ReturnType<typeof createMockStorage>;
+
+  beforeEach(() => {
+    teardownAll();
+    NativeCollection.resetAdapter();
+    mock = createMockStorage();
+    NativeCollection.configure(mock);
+  });
+
+  afterEach(() => {
+    NativeCollection.resetAdapter();
+  });
+
+  describe('configure pattern', () => {
+    it('uses configured adapter for storage', async () => {
+      const c = new TodosCollection();
+      c.add({ id: '1', title: 'Test', done: false });
+      await tick();
+
+      expect(mock.setItem).toHaveBeenCalledWith('todos', expect.any(String));
+      const stored = JSON.parse(mock.store.get('todos')!);
+      expect(stored).toEqual([{ id: '1', title: 'Test', done: false }]);
+      c.dispose();
+    });
+
+    it('hydrates from configured adapter', async () => {
+      mock.store.set(
+        'todos',
+        JSON.stringify([
+          { id: '1', title: 'Existing', done: true },
+          { id: '2', title: 'Another', done: false },
+        ]),
+      );
+
+      const c = new TodosCollection();
+      await c.hydrate();
+
+      expect(c.hydrated).toBe(true);
+      expect(c.length).toBe(2);
+      expect(c.get('1')!.title).toBe('Existing');
+      expect(c.get('2')!.done).toBe(false);
+      c.dispose();
+    });
+
+    it('hydrate is idempotent', async () => {
+      mock.store.set('todos', JSON.stringify([{ id: '1', title: 'A', done: false }]));
+
+      const c = new TodosCollection();
+      await c.hydrate();
+      c.add({ id: '2', title: 'B', done: false });
+      const items = await c.hydrate();
+
+      expect(items).toHaveLength(2);
+      expect(mock.getItem).toHaveBeenCalledTimes(1);
+      c.dispose();
+    });
+  });
+
+  describe('per-class override', () => {
+    it('per-class methods take priority over configure()', async () => {
+      const customMock = createMockStorage();
+
+      class CustomCollection extends NativeCollection<Todo> {
+        protected readonly storageKey = 'custom';
+        protected override getItem(key: string) {
+          return customMock.getItem(key);
+        }
+        protected override setItem(key: string, value: string) {
+          return customMock.setItem(key, value);
+        }
+        protected override removeItem(key: string) {
+          return customMock.removeItem(key);
+        }
+      }
+
+      const c = new CustomCollection();
+      c.add({ id: '1', title: 'Custom', done: false });
+      await tick();
+
+      // Custom mock was used, not the global mock
+      expect(customMock.setItem).toHaveBeenCalled();
+      expect(mock.setItem).not.toHaveBeenCalled();
+
+      const stored = JSON.parse(customMock.store.get('custom')!);
+      expect(stored).toEqual([{ id: '1', title: 'Custom', done: false }]);
+      c.dispose();
+    });
+  });
+
+  describe('no adapter configured', () => {
+    it('errors when no adapter configured and no override', async () => {
+      NativeCollection.resetAdapter();
+      const errorSpy = vi.fn();
+
+      class UnconfiguredCollection extends NativeCollection<Todo> {
+        protected readonly storageKey = 'unconfigured';
+        protected onPersistError = errorSpy;
+      }
+
+      const c = new UnconfiguredCollection();
+      await c.hydrate();
+
+      // Error routed to onPersistError hook
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ message: expect.stringContaining('No storage adapter configured') }),
+      );
+      c.dispose();
+    });
+  });
+
+  describe('persistence (blob strategy)', () => {
+    it('mutations persist via setItem', async () => {
+      const c = new TodosCollection();
+      c.add({ id: '1', title: 'A', done: false });
+      await tick();
+
+      c.add({ id: '2', title: 'B', done: true });
+      await tick();
+
+      const stored = JSON.parse(mock.store.get('todos')!);
+      expect(stored).toHaveLength(2);
+      c.dispose();
+    });
+
+    it('remove persists correctly', async () => {
+      const c = new TodosCollection();
+      c.add(
+        { id: '1', title: 'A', done: false },
+        { id: '2', title: 'B', done: true },
+      );
+      await tick();
+
+      c.remove('1');
+      await tick();
+
+      const stored = JSON.parse(mock.store.get('todos')!);
+      expect(stored).toEqual([{ id: '2', title: 'B', done: true }]);
+      c.dispose();
+    });
+  });
+
+  describe('clearStorage', () => {
+    it('calls removeItem and clears in-memory', async () => {
+      const c = new TodosCollection();
+      c.add({ id: '1', title: 'Test', done: false });
+      await tick();
+
+      await c.clearStorage();
+
+      expect(c.length).toBe(0);
+      expect(mock.removeItem).toHaveBeenCalledWith('todos');
+      c.dispose();
+    });
+  });
+
+  describe('JSON round-trip', () => {
+    it('preserves data through serialize/deserialize cycle', async () => {
+      const c = new TodosCollection();
+      c.add({ id: '1', title: 'Round-trip', done: true });
+      await tick();
+      c.dispose();
+
+      const c2 = new TodosCollection();
+      await c2.hydrate();
+      expect(c2.get('1')).toEqual({ id: '1', title: 'Round-trip', done: true });
+      c2.dispose();
+    });
+  });
+
+  describe('custom serialize/deserialize', () => {
+    it('uses overridden serialize/deserialize', async () => {
+      class CustomSerializeCollection extends NativeCollection<Todo> {
+        protected readonly storageKey = 'custom-ser';
+        protected override serialize(items: Todo[]): string {
+          return JSON.stringify({ version: 1, data: items });
+        }
+        protected override deserialize(raw: string): Todo[] {
+          const parsed = JSON.parse(raw);
+          return parsed.data;
+        }
+      }
+
+      const c = new CustomSerializeCollection();
+      c.add({ id: '1', title: 'Custom', done: false });
+      await tick();
+
+      const raw = JSON.parse(mock.store.get('custom-ser')!);
+      expect(raw.version).toBe(1);
+      expect(raw.data).toEqual([{ id: '1', title: 'Custom', done: false }]);
+      c.dispose();
+
+      // Verify it can read back
+      const c2 = new CustomSerializeCollection();
+      await c2.hydrate();
+      expect(c2.get('1')!.title).toBe('Custom');
+      c2.dispose();
+    });
+  });
+
+  describe('corrupted data', () => {
+    it('handles corrupted JSON gracefully', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      mock.store.set('todos', 'not-valid-json{{{');
+
+      const c = new TodosCollection();
+      await c.hydrate();
+
+      expect(c.length).toBe(0);
+      expect(c.hydrated).toBe(true);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Corrupted data'));
+
+      warnSpy.mockRestore();
+      c.dispose();
+    });
+  });
+});