mvc-kit 2.12.0 → 2.12.2

package/src/react/use-singleton.md

@@ -0,0 +1,415 @@
+# useSingleton
+
+React hook for subscribing to a [singleton](../singleton.md) instance. Resolves the singleton from the global registry, auto-initializes it on mount, and subscribes to state changes. Multiple components sharing the same class see the same instance and the same state.
+
+---
+
+## Signatures
+
+### With DEFAULT_STATE (no args needed)
+
+If the class defines `static DEFAULT_STATE`, no constructor args are required:
+
+```typescript
+function useSingleton<T extends Subscribable & Disposable, S>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown },
+): [S, T]
+
+function useSingleton<T extends Disposable>(
+  Class: (new (...args: any[]) => T) & { DEFAULT_STATE: unknown },
+): T
+```
+
+### Subscribable (ViewModel, Collection, Channel)
+
+```typescript
+function useSingleton<T extends Subscribable & Disposable, S>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): [S, T]
+```
+
+Returns a `[state, instance]` tuple — identical shape to `useLocal`. The component re-renders when state changes.
+
+### Non-Subscribable (Service, Controller)
+
+```typescript
+function useSingleton<T extends Disposable>(
+  Class: new (...args: Args) => T,
+  ...args: Args
+): T
+```
+
+Returns the instance directly. No state subscription — the class has no reactive state to subscribe to.
+
+---
+
+## Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `Class` | `new (...args) => T` | The class to resolve as a singleton. Any `Disposable` works — [ViewModel](../ViewModel.md), [Service](../Service.md), [Collection](../Collection.md), [Channel](../Channel.md), [Controller](../Controller.md). |
+| `...args` | `Args` | Constructor arguments. Used **only on first creation**. Subsequent calls return the cached instance and ignore arguments. |
+
+---
+
+## Behavior
+
+### Singleton Resolution
+
+`useSingleton` calls `singleton(Class, ...args)` on every render. The singleton registry returns the existing instance if one exists and hasn't been disposed. If no instance exists (or the previous one was disposed), a new one is created with the provided arguments.
+
+```typescript
+// Both components get the exact same CounterVM instance
+function Counter() {
+  const [state, vm] = useSingleton(CounterVM, 0);
+  return <div>{state.count}</div>;
+}
+
+function App() {
+  return (
+    <>
+      <Counter />
+      <Counter />
+    </>
+  );
+}
+```
+
+### Auto-Initialization
+
+On mount, `useSingleton` calls `init()` on the instance if it implements `Initializable` (duck-typed check for an `init` method). Since `init()` is idempotent, multiple components mounting with the same singleton class only trigger `onInit()` once.
+
+```typescript
+class InitVM extends ViewModel<State> {
+  protected onInit() {
+    console.log('runs once, even with 5 components');
+  }
+}
+
+// All five components share one instance; onInit runs once
+function App() {
+  return (
+    <>
+      <Comp /> <Comp /> <Comp /> <Comp /> <Comp />
+    </>
+  );
+}
+```
+
+This applies to non-subscribable singletons too:
+
+```typescript
+class ConfigService extends Service {
+  protected onInit() {
+    // Runs once on first mount
+  }
+}
+
+function Comp() {
+  const service = useSingleton(ConfigService);
+  // service.init() called automatically
+}
+```
+
+### State Subscription (Subscribable Only)
+
+When the instance implements `Subscribable` (has `state` and `subscribe`), the hook uses `useInstance` internally to bind the instance's state to React via `useSyncExternalStore`. This includes:
+
+- **State changes** — re-renders when `set()` produces a new state reference
+- **Async status changes** — re-renders when any async method's `TaskState` changes (loading starts, completes, or fails)
+- **Subscribable member notifications** — re-renders when a Collection, Channel, or other subscribable member notifies
+
+### State Survives Unmount
+
+Because the instance lives in the singleton registry (not in component state), its state persists across mount/unmount cycles. Navigating away and back does not reset the ViewModel.
+
+```typescript
+// Mount, increment to 1, unmount
+const { unmount } = render(<Counter />);
+act(() => screen.getByRole('button').click());
+unmount();
+
+// Re-mount — state is still 1
+render(<Counter />);
+screen.getByTestId('count').textContent; // '1'
+```
+
+This is the key difference from `useLocal`, where state is tied to the component lifecycle.
+
+### No Auto-Dispose
+
+`useSingleton` does **not** dispose the instance on unmount. The singleton persists until explicitly torn down via `teardown(Class)` or `teardownAll()`. This is intentional — other components may still be subscribed to the same instance.
+
+---
+
+## Usage
+
+### Shared ViewModel (App-Wide State)
+
+Use `useSingleton` for state that must survive route changes and be accessible from anywhere — auth, theme, cart.
+
+```tsx
+import { ViewModel } from 'mvc-kit';
+import { useSingleton } from 'mvc-kit/react';
+
+interface CartState {
+  items: CartItem[];
+}
+
+class CartViewModel extends ViewModel<CartState> {
+  get itemCount(): number {
+    return this.state.items.length;
+  }
+
+  get total(): number {
+    return this.state.items.reduce((sum, item) => sum + item.price, 0);
+  }
+
+  addItem(item: CartItem) {
+    this.set({ items: [...this.state.items, item] });
+  }
+
+  removeItem(id: string) {
+    this.set({ items: this.state.items.filter(i => i.id !== id) });
+  }
+}
+
+class CartViewModel extends ViewModel<CartState> {
+  static DEFAULT_STATE: CartState = { items: [] };
+  // ...methods
+}
+
+// Header — shows item count badge (no args needed with DEFAULT_STATE)
+function CartIcon() {
+  const [state, vm] = useSingleton(CartViewModel);
+  return <span className="badge">{vm.itemCount}</span>;
+}
+
+// Drawer — shows full cart with remove buttons
+function CartDrawer() {
+  const [state, vm] = useSingleton(CartViewModel);
+  return (
+    <aside>
+      {state.items.map(item => (
+        <CartItem key={item.id} item={item} onRemove={() => vm.removeItem(item.id)} />
+      ))}
+      <p>Total: ${vm.total}</p>
+    </aside>
+  );
+}
+```
+
+Both `CartIcon` and `CartDrawer` subscribe to the same `CartViewModel`. When `CartDrawer` removes an item, `CartIcon`'s badge updates instantly.
+
+### Non-Subscribable Singleton (Service)
+
+For Services and other non-reactive singletons, the hook returns the instance directly.
+
+```tsx
+class ApiService extends Service {
+  async fetchUser(id: string, signal?: AbortSignal): Promise<User> {
+    const res = await fetch(`/api/users/${id}`, { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+
+function Dashboard() {
+  const api = useSingleton(ApiService);
+  // api is a stable reference — same instance on every render
+  // No reactive state — use a ViewModel for that
+  return <div>...</div>;
+}
+```
+
+Since Services have no reactive state, state changes won't trigger re-renders. If you need the component to react to data from a Service, wrap it in a ViewModel that calls the Service and holds the result in state.
+
+### Shared State Across Sibling Components
+
+```tsx
+function UsersPage() {
+  return (
+    <div className="layout">
+      <UsersTable />
+      <OnDutySidebar />
+    </div>
+  );
+}
+
+function UsersTable() {
+  const [state, vm] = useSingleton(UsersViewModel, { items: [], search: '' });
+  return <table>{/* renders vm.filtered */}</table>;
+}
+
+function OnDutySidebar() {
+  const [state, vm] = useSingleton(UsersViewModel, { items: [], search: '' });
+  return <aside>{/* renders vm.onDutyUsers */}</aside>;
+}
+```
+
+Both components read from and mutate the same ViewModel. A search typed in `UsersTable` is immediately visible in `OnDutySidebar`'s derived getters.
+
+---
+
+## Constructor Arguments
+
+Arguments are passed to `singleton()`, which forwards them to the constructor **only on first creation**. Once the instance exists in the registry, arguments are ignored on all subsequent calls.
+
+```typescript
+class CounterVM extends ViewModel<{ count: number }> {
+  constructor(initial = 0) {
+    super({ count: initial });
+  }
+}
+
+// First mount creates the instance with initial=0
+const [state1] = useSingleton(CounterVM, 0);
+
+// Second component — same instance, argument 100 is ignored
+const [state2] = useSingleton(CounterVM, 100);
+state2.count; // 0 (not 100)
+```
+
+This matches the `singleton()` registry semantics. If you need a fresh instance with different arguments, call `teardown(Class)` first.
+
+---
+
+## useSingleton vs useLocal
+
+| Behavior | `useSingleton` | `useLocal` |
+|---|---|---|
+| Instance lifetime | Global — survives unmount | Component-scoped — disposed on unmount |
+| Shared across components | Yes — same instance for all callers | No — each component gets its own |
+| Auto-dispose on unmount | No | Yes |
+| `deps` array for recreate | Not supported | Supported |
+| `init()` call count | Once globally (idempotent) | Once per component mount |
+| State persistence | Survives route changes | Lost on unmount |
+| Typical use | Auth, theme, cart, app-wide state | Page-level, form-level, card-level state |
+
+**Default to `useLocal`.** Promote to `useSingleton` only when state must be shared across unrelated components or survive route changes.
+
+---
+
+## Testing
+
+### Test Isolation
+
+Always call `teardownAll()` in test cleanup to prevent singleton leakage between tests:
+
+```typescript
+import { teardownAll } from 'mvc-kit';
+
+afterEach(() => {
+  teardownAll();
+});
+```
+
+### Asserting Shared State
+
+```tsx
+test('shared state across components', () => {
+  function App() {
+    return (
+      <>
+        <Counter />
+        <Counter />
+      </>
+    );
+  }
+
+  render(<App />);
+  const counts = screen.getAllByTestId('count');
+
+  // Both start at 0
+  expect(counts[0].textContent).toBe('0');
+  expect(counts[1].textContent).toBe('0');
+
+  // Click one — both update
+  act(() => screen.getAllByRole('button')[0].click());
+  expect(counts[0].textContent).toBe('1');
+  expect(counts[1].textContent).toBe('1');
+});
+```
+
+### Asserting State Persistence Across Remounts
+
+```tsx
+test('state survives unmount and remount', () => {
+  const { unmount } = render(<Counter />);
+
+  act(() => screen.getByRole('button').click());
+  expect(screen.getByTestId('count').textContent).toBe('1');
+
+  unmount();
+  render(<Counter />);
+
+  expect(screen.getByTestId('count').textContent).toBe('1');
+});
+```
+
+### Injecting Mocks via Provider
+
+Use `Provider` to inject mock instances in tests and Storybook:
+
+```tsx
+import { Provider } from 'mvc-kit/react';
+
+const mockService = new UserService();
+jest.spyOn(mockService, 'getAll').mockResolvedValue(mockUsers);
+
+render(
+  <Provider provide={[
+    [UserService, mockService],
+    [UsersCollection, testCollection],
+  ]}>
+    <UsersPage />
+  </Provider>
+);
+```
+
+---
+
+## Best Practices
+
+**Default to `useLocal`, promote to `useSingleton` when needed.** Most ViewModels are component-scoped. Only use `useSingleton` for app-wide concerns (auth, theme, cart) or when multiple unrelated components must share state.
+
+**Don't use `useSingleton` for Services inside components that also have a ViewModel.** The ViewModel should resolve its own Services via `singleton()` in property initializers. Components don't import infrastructure.
+
+```typescript
+// Bad: component resolves the service
+function UsersPage() {
+  const api = useSingleton(UserService);         // leaky
+  const [state, vm] = useLocal(UsersViewModel, { items: [] });
+}
+
+// Good: ViewModel resolves its own dependencies
+class UsersViewModel extends ViewModel<State> {
+  private service = singleton(UserService);       // encapsulated
+}
+```
+
+**Always `teardownAll()` in tests.** Singleton leakage is the most common cause of flaky tests.
+
+**Define `static DEFAULT_STATE` on singleton ViewModels.** This eliminates repeated initial state at every call site and prevents accidental divergence:
+
+```typescript
+class CartViewModel extends ViewModel<CartState> {
+  static DEFAULT_STATE: CartState = { items: [] };
+}
+
+// All consumers — no args needed:
+const [state, vm] = useSingleton(CartViewModel);
+```
+
+**Don't pass different constructor arguments from different components.** Arguments are first-call-only. If two components pass different args, the second one's args are silently ignored. Use `static DEFAULT_STATE` to declare the initial state once, or use a factory pattern with `teardown` for re-creation.
+
+---
+
+## Related
+
+- [singleton](../singleton.md) — the underlying registry that `useSingleton` delegates to
+- [ViewModel](../ViewModel.md) — the most common class used with `useSingleton`
+- [Service](../Service.md) — non-subscribable singletons returned as plain instances
+- [Collection](../Collection.md) — subscribable data cache (typically encapsulated by a ViewModel, not used directly with `useSingleton`)
+- [Channel](../Channel.md) — persistent connection singletons

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

@@ -0,0 +1,296 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { useState } from 'react';
+import { ViewModel } from '../ViewModel';
+import { Service } from '../Service';
+import { teardownAll } from '../singleton';
+import { useSingleton } from './use-singleton';
+
+interface CounterState {
+  count: number;
+}
+
+class CounterVM extends ViewModel<CounterState> {
+  constructor(initial = 0) {
+    super({ count: initial });
+  }
+
+  increment() {
+    this.set((prev) => ({ count: prev.count + 1 }));
+  }
+}
+
+function Counter() {
+  const [state, vm] = useSingleton(CounterVM, 0);
+  return (
+    <div>
+      <div data-testid="count">{state.count}</div>
+      <button onClick={() => vm.increment()}>Increment</button>
+    </div>
+  );
+}
+
+describe('useSingleton', () => {
+  afterEach(() => {
+    teardownAll();
+  });
+
+  describe('with Subscribable', () => {
+    it('should return state and vm tuple', () => {
+      render(<Counter />);
+      expect(screen.getByTestId('count').textContent).toBe('0');
+    });
+
+    it('should share state across multiple components', () => {
+      function App() {
+        return (
+          <>
+            <Counter />
+            <Counter />
+          </>
+        );
+      }
+
+      render(<App />);
+      const counts = screen.getAllByTestId('count');
+      expect(counts).toHaveLength(2);
+      expect(counts[0].textContent).toBe('0');
+      expect(counts[1].textContent).toBe('0');
+
+      act(() => {
+        screen.getAllByRole('button')[0].click();
+      });
+
+      expect(counts[0].textContent).toBe('1');
+      expect(counts[1].textContent).toBe('1');
+    });
+
+    it('should maintain singleton across remounts', () => {
+      const { unmount } = render(<Counter />);
+
+      act(() => {
+        screen.getByRole('button').click();
+      });
+      expect(screen.getByTestId('count').textContent).toBe('1');
+
+      unmount();
+
+      // Render fresh component - should still have the singleton state
+      render(<Counter />);
+
+      expect(screen.getByTestId('count').textContent).toBe('1');
+    });
+  });
+
+  describe('with Disposable-only (Service)', () => {
+    class ApiService extends Service {
+      private data: string[] = [];
+
+      addItem(item: string): void {
+        this.data.push(item);
+      }
+
+      getItems(): string[] {
+        return [...this.data];
+      }
+    }
+
+    function ServiceComponent() {
+      const api = useSingleton(ApiService);
+      const [items, setItems] = useState<string[]>([]);
+
+      return (
+        <div>
+          <div data-testid="svc-count">{items.length}</div>
+          <button onClick={() => {
+            api.addItem('item');
+            setItems(api.getItems());
+          }}>
+            Add
+          </button>
+        </div>
+      );
+    }
+
+    it('should return service instance directly', () => {
+      render(<ServiceComponent />);
+      expect(screen.getByTestId('svc-count').textContent).toBe('0');
+
+      act(() => {
+        screen.getByRole('button').click();
+      });
+
+      expect(screen.getByTestId('svc-count').textContent).toBe('1');
+    });
+
+    it('should share service across components', () => {
+      function App() {
+        return (
+          <>
+            <ServiceComponent />
+            <ServiceComponent />
+          </>
+        );
+      }
+
+      render(<App />);
+      const counts = screen.getAllByTestId('svc-count');
+
+      act(() => {
+        screen.getAllByRole('button')[0].click();
+      });
+
+      // Both should see the same data
+      act(() => {
+        screen.getAllByRole('button')[1].click();
+      });
+
+      // After the second click updates its local state
+      expect(counts[1].textContent).toBe('2');
+    });
+
+    it('should return same instance on re-render', () => {
+      let serviceRef: ApiService | null = null;
+
+      function Tracker() {
+        const service = useSingleton(ApiService);
+        if (serviceRef === null) {
+          serviceRef = service;
+        } else {
+          expect(service).toBe(serviceRef);
+        }
+        return null;
+      }
+
+      const { rerender } = render(<Tracker />);
+      rerender(<Tracker />);
+      rerender(<Tracker />);
+    });
+  });
+
+  describe('DEFAULT_STATE', () => {
+    class DefaultCounterVM extends ViewModel<CounterState> {
+      static DEFAULT_STATE: CounterState = { count: 7 };
+
+      increment() {
+        this.set((prev) => ({ count: prev.count + 1 }));
+      }
+    }
+
+    function DefaultCounter() {
+      const [state, vm] = useSingleton(DefaultCounterVM);
+      return (
+        <div>
+          <div data-testid="default-count">{state.count}</div>
+          <button onClick={() => vm.increment()}>Increment</button>
+        </div>
+      );
+    }
+
+    it('works without constructor args when DEFAULT_STATE is present', () => {
+      render(<DefaultCounter />);
+      expect(screen.getByTestId('default-count').textContent).toBe('7');
+    });
+
+    it('shares DEFAULT_STATE singleton across components', () => {
+      function App() {
+        return (
+          <>
+            <DefaultCounter />
+            <DefaultCounter />
+          </>
+        );
+      }
+
+      render(<App />);
+      const counts = screen.getAllByTestId('default-count');
+      expect(counts).toHaveLength(2);
+      expect(counts[0].textContent).toBe('7');
+      expect(counts[1].textContent).toBe('7');
+
+      act(() => {
+        screen.getAllByRole('button')[0].click();
+      });
+
+      expect(counts[0].textContent).toBe('8');
+      expect(counts[1].textContent).toBe('8');
+    });
+  });
+
+  describe('init lifecycle', () => {
+    it('should auto-call init on mount for Subscribable', () => {
+      let initCalled = false;
+      class InitVM extends ViewModel<CounterState> {
+        constructor(initial = 0) {
+          super({ count: initial });
+        }
+        protected onInit() {
+          initCalled = true;
+        }
+        increment() {
+          this.set((prev) => ({ count: prev.count + 1 }));
+        }
+      }
+
+      function Comp() {
+        const [state] = useSingleton(InitVM, 0);
+        return <div data-testid="count">{state.count}</div>;
+      }
+
+      render(<Comp />);
+      expect(initCalled).toBe(true);
+    });
+
+    it('should call init only once across multiple components sharing singleton', () => {
+      let initCount = 0;
+      class InitVM extends ViewModel<CounterState> {
+        constructor(initial = 0) {
+          super({ count: initial });
+        }
+        protected onInit() {
+          initCount++;
+        }
+        increment() {
+          this.set((prev) => ({ count: prev.count + 1 }));
+        }
+      }
+
+      function Comp() {
+        const [state] = useSingleton(InitVM, 0);
+        return <div data-testid="count">{state.count}</div>;
+      }
+
+      function App() {
+        return (
+          <>
+            <Comp />
+            <Comp />
+          </>
+        );
+      }
+
+      render(<App />);
+      // init() is idempotent — even though two components call it, onInit runs once
+      expect(initCount).toBe(1);
+    });
+
+    it('should auto-call init for Disposable-only singleton', () => {
+      let initCalled = false;
+      class InitService extends Service {
+        protected onInit() {
+          initCalled = true;
+        }
+      }
+
+      function Comp() {
+        useSingleton(InitService);
+        return null;
+      }
+
+      render(<Comp />);
+      expect(initCalled).toBe(true);
+    });
+  });
+});