mvc-kit 2.0.0 → 2.1.0

package/agent-config/claude-code/skills/guide/anti-patterns.md

@@ -0,0 +1,321 @@
+# mvc-kit Anti-Patterns
+
+Reject these patterns. Each entry shows the bad pattern and the correct alternative.
+
+---
+
+## 1. Loading/Error Flags in State
+
+```typescript
+// BAD
+interface State {
+  items: Item[];
+  loading: boolean;
+  error: string | null;
+}
+
+// GOOD — async tracking handles it
+interface State {
+  items: Item[];
+}
+// Read: vm.async.load.loading, vm.async.load.error
+```
+
+---
+
+## 2. Stored Derived State
+
+```typescript
+// BAD — manually syncing derived state
+interface State {
+  items: Item[];
+  search: string;
+  filtered: Item[];  // derived value stored in state
+}
+setSearch(search: string) {
+  this.set({ search });
+  this.refilter(); // manual sync step
+}
+
+// GOOD — getter computes automatically
+get filtered(): Item[] {
+  return this.state.items.filter(i => i.name.includes(this.state.search));
+}
+setSearch(search: string) { this.set({ search }); }
+```
+
+---
+
+## 3. Manual Try/Catch for Standard Loads
+
+```typescript
+// BAD — unnecessary boilerplate
+async load() {
+  this.set({ loading: true, error: null });
+  try {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.set({ items: data, loading: false });
+  } catch (e) {
+    if (isAbortError(e)) return;
+    this.set({ loading: false, error: e.message });
+  }
+}
+
+// GOOD — async tracking handles everything
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+---
+
+## 4. Two-Step Setters
+
+```typescript
+// BAD — setter calls refilter
+setSearch(search: string) {
+  this.set({ search });
+  this.refilter(); // unnecessary — getters recompute on access
+}
+
+// GOOD — one-liner setter, getter handles derivation
+setSearch(search: string) { this.set({ search }); }
+```
+
+---
+
+## 5. Multiple useLocal in One Component
+
+```tsx
+// BAD — split into two components
+function Dashboard() {
+  const [usersState, usersVM] = useLocal(UsersViewModel, { ... });
+  const [ordersState, ordersVM] = useLocal(OrdersViewModel, { ... });
+  return <div>...</div>;
+}
+
+// GOOD — each component owns one ViewModel
+function Dashboard() {
+  return (
+    <div>
+      <UsersPanel />
+      <OrdersPanel />
+    </div>
+  );
+}
+```
+
+---
+
+## 6. Collections Accessed from Components
+
+```tsx
+// BAD — component imports infrastructure
+import { singleton } from 'mvc-kit';
+import { UsersCollection } from '../collections/UsersCollection';
+function UsersPage() {
+  const collection = singleton(UsersCollection);
+  // ...
+}
+
+// GOOD — component only knows its ViewModel
+import { useLocal } from 'mvc-kit/react';
+import { UsersViewModel } from '../viewmodels/UsersViewModel';
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  // ...
+}
+```
+
+---
+
+## 7. Services Holding State
+
+```typescript
+// BAD — service caches data
+class UserService extends Service {
+  private cache: User[] = [];
+  async getAll() {
+    if (this.cache.length) return this.cache;
+    this.cache = await fetch(...).then(r => r.json());
+    return this.cache;
+  }
+}
+
+// GOOD — Collection is the cache, Service is stateless
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<User[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+---
+
+## 8. Swallowing Errors Without Re-Throwing
+
+```typescript
+// BAD — breaks async tracking
+async save() {
+  try {
+    await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: this.state.draft.id });
+  } catch (e) {
+    this.emit('error', { message: e.message });
+    // Error swallowed! vm.async.save.error will be null
+  }
+}
+
+// GOOD — re-throw for async tracking
+async save() {
+  try {
+    await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: this.state.draft.id });
+  } catch (e) {
+    if (!isAbortError(e)) {
+      this.emit('error', { message: classifyError(e).message });
+    }
+    throw e; // async tracking captures the error
+  }
+}
+```
+
+---
+
+## 9. useEffect for Data Loading
+
+```tsx
+// BAD — component orchestrates loading
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  useEffect(() => { vm.load(); }, []);
+  return <div>...</div>;
+}
+
+// GOOD — ViewModel handles its own initialization
+// (onInit() is called automatically by useLocal)
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  return <div>...</div>;
+}
+```
+
+---
+
+## 10. useState/useMemo/useCallback in Connected Components
+
+```tsx
+// BAD — React hooks alongside ViewModel
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  const [showModal, setShowModal] = useState(false);
+  const filtered = useMemo(() => state.items.filter(...), [state.items]);
+
+  // GOOD — put it all in the ViewModel
+  // state.showModal, vm.filtered, vm.toggleModal()
+}
+```
+
+---
+
+## 11. Manual Optimistic Snapshot/Restore
+
+```typescript
+// BAD — manual snapshot management
+async toggleStatus(id: string) {
+  const prev = [...this.collection.items];
+  this.collection.update(id, { status: 'done' });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch {
+    this.collection.reset(prev); // manual restore
+  }
+}
+
+// GOOD — use collection.optimistic()
+async toggleStatus(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { status: 'done' });
+  });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback();
+    throw e;
+  }
+}
+```
+
+---
+
+## 12. Separate EventBus for ViewModel Events
+
+```typescript
+// BAD — unnecessary EventBus when ViewModel events suffice
+class ItemViewModel extends ViewModel<State> {
+  private eventBus = new EventBus<{ saved: { id: string } }>();
+  get bus() { return this.eventBus; }
+}
+
+// GOOD — use the second generic parameter
+class ItemViewModel extends ViewModel<State, { saved: { id: string } }> {
+  // emit('saved', { id }) is built-in and protected
+}
+```
+
+---
+
+## 13. set() Inside a Getter
+
+```typescript
+// BAD — creates infinite loop
+get filtered(): Item[] {
+  const result = this.state.items.filter(...);
+  this.set({ filteredCount: result.length }); // INFINITE LOOP
+  return result;
+}
+
+// GOOD — use a separate getter for the count
+get filtered(): Item[] { return this.state.items.filter(...); }
+get filteredCount(): number { return this.filtered.length; }
+```
+
+---
+
+## 14. Logic/Filtering in Components
+
+```tsx
+// BAD — component does derivation
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  const active = state.items.filter(u => u.status === 'active');
+  return <UserList users={active} />;
+}
+
+// GOOD — getter on the ViewModel
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  return <UserList users={vm.active} />;
+}
+```
+
+---
+
+## 15. Missing disposeSignal on Async Calls
+
+```typescript
+// BAD — no cancellation on unmount
+async load() {
+  const data = await this.service.getAll();
+  this.set({ items: data });
+}
+
+// GOOD — cancels on unmount, AbortError auto-swallowed
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.set({ items: data });
+}
+```

package/agent-config/claude-code/skills/guide/api-reference.md

@@ -0,0 +1,310 @@
+# mvc-kit API Reference
+
+## Imports
+
+```typescript
+// Core classes and utilities
+import { ViewModel, Model, Collection, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { singleton, hasSingleton, teardown, teardownAll } from 'mvc-kit';
+import { HttpError, isAbortError, classifyError } from 'mvc-kit';
+import type { Subscribable, Disposable, Initializable, Listener, Updater, ValidationErrors, TaskState, AppError, AsyncMethodKeys, ChannelStatus } from 'mvc-kit';
+
+// React hooks
+import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+import type { StateOf, ItemOf, SingletonClass, ProviderRegistry, ModelHandle, FieldHandle, ProviderProps } from 'mvc-kit/react';
+```
+
+---
+
+## ViewModel<S, E = {}>
+
+Reactive state container with computed getters, automatic async tracking, and optional typed events.
+
+### Constructor
+```typescript
+new MyViewModel(initialState: S)
+```
+
+### State
+- `state: Readonly<S>` — Current frozen state. Read `state.x` for raw values.
+- `set(partial: Partial<S>)` — Merge partial state. Skips if no values change.
+- `set(updater: (prev: Readonly<S>) => Partial<S>)` — Functional update.
+- `reset(newState?: S)` — Tear down lifecycle, re-initialize. Clears async tracking, re-runs `onInit()`.
+
+### Computed Getters
+Define TypeScript `get` accessors on the subclass. Auto-memoized after `init()` with dependency tracking.
+```typescript
+get filtered(): Item[] { return this.state.items.filter(i => i.active); }
+```
+
+### Async Tracking
+After `init()`, every subclass method is wrapped. Async methods get automatic loading/error tracking.
+- `async: Record<string, TaskState>` — `vm.async.methodName` returns `{ loading: boolean, error: string | null, errorCode: string | null }`.
+- `subscribeAsync(listener: () => void): () => void` — Subscribe to async state changes.
+- Unknown keys return `{ loading: false, error: null, errorCode: null }`.
+
+### Typed Events (optional)
+Pass a second generic `E` to enable typed events.
+```typescript
+class MyVM extends ViewModel<State, { saved: { id: string }; error: void }> {
+  protected emit(event, payload) // type-safe, protected
+}
+```
+- `events: EventBus<E>` — Lazy getter; zero cost if unused.
+- `emit(event, payload)` — Protected. Only the ViewModel can emit.
+- Event bus auto-disposes with the ViewModel.
+
+### Lifecycle Hooks
+- `onInit(): void | Promise<void>` — Called once after `init()`. Data loading, subscriptions.
+- `onSet(prev: Readonly<S>, next: Readonly<S>): void` — Called after every state change.
+- `onDispose(): void` — Called during `dispose()`, after cleanup callbacks.
+
+### Cleanup
+- `disposeSignal: AbortSignal` — Lazily created, auto-aborted on `dispose()`.
+- `subscribeTo(source: Subscribable, listener): void` — Auto-unsubscribe on dispose.
+- `addCleanup(fn: () => void): void` — Register teardown callback.
+- `subscribe(listener: Listener<S>): () => void` — Subscribe to state changes.
+- `dispose(): void` — Idempotent. `set()` and `emit()` become no-ops after dispose.
+
+### Static
+- `static GHOST_TIMEOUT = 3000` — DEV-only. Timeout before ghost async warnings.
+
+---
+
+## Model<S>
+
+Entity with validation and dirty tracking.
+
+### Constructor
+```typescript
+new MyModel(initialState: S)
+```
+
+### State & Validation
+- `state: Readonly<S>` — Current state.
+- `set(partial: Partial<S>)` — Update state, re-validates.
+- `errors: ValidationErrors<S>` — `Partial<Record<keyof S, string>>`.
+- `valid: boolean` — True when `errors` is empty.
+- `dirty: boolean` — True when state differs from committed state.
+- `commit(): void` — Mark current state as baseline (resets dirty).
+- `rollback(): void` — Revert to committed state.
+
+### Override
+```typescript
+protected validate(state: S): ValidationErrors<S> {
+  const errors: Partial<Record<keyof S, string>> = {};
+  if (!state.name) errors.name = 'Required';
+  return errors;
+}
+```
+
+### Lifecycle & Cleanup
+Same as ViewModel: `onInit()`, `onSet()`, `onDispose()`, `disposeSignal`, `subscribeTo()`, `addCleanup()`, `subscribe()`, `dispose()`.
+
+---
+
+## Collection<T extends { id: string }>
+
+Reactive typed array with CRUD and query methods. Items must have an `id: string` field.
+
+### CRUD (triggers notifications)
+- `add(item: T): void`
+- `update(id: string, partial: Partial<T>): void`
+- `remove(id: string): void`
+- `reset(items: T[]): void` — Replace all items.
+- `clear(): void`
+
+### Query (pure, no notifications)
+- `items: readonly T[]` — Same as `state`.
+- `length: number`
+- `get(id: string): T | undefined` — O(1) via internal index.
+- `has(id: string): boolean`
+- `find(predicate: (item: T) => boolean): T | undefined`
+- `filter(predicate: (item: T) => boolean): T[]`
+- `sorted(comparator: (a: T, b: T) => number): T[]`
+- `map<U>(fn: (item: T) => U): U[]`
+
+### Optimistic Updates
+```typescript
+const rollback = collection.optimistic(() => {
+  collection.update(id, { status: 'done' });
+});
+// On failure: rollback()
+```
+
+### Lifecycle & Cleanup
+`subscribe()`, `dispose()`, `disposeSignal`, `addCleanup()`, `onDispose()`.
+
+---
+
+## Service
+
+Stateless infrastructure adapter. Singleton-scoped.
+
+### Lifecycle & Cleanup
+- `disposeSignal: AbortSignal`
+- `addCleanup(fn: () => void): void`
+- `onDispose(): void`
+- `dispose(): void`
+- `disposed: boolean`
+
+No state, no getters, no async tracking. Just a base class with lifecycle.
+
+---
+
+## EventBus<E>
+
+Typed pub/sub event bus.
+
+- `on(event: K, handler: (payload: E[K]) => void): () => void` — Subscribe. Returns unsubscribe.
+- `once(event: K, handler): () => void` — One-time subscription.
+- `emit(event: K, payload: E[K]): void` — Emit event.
+- `dispose(): void` — Remove all listeners.
+
+---
+
+## Channel<M>
+
+Persistent connection (WebSocket/SSE) with auto-reconnect. Extends EventBus for message routing.
+
+### Subclass Contract
+```typescript
+protected abstract connect(): void;    // Open the connection
+protected abstract disconnect(): void; // Close the connection
+```
+
+### Connection Control
+- `open(): void` — Start connection.
+- `close(): void` — Stop connection and auto-reconnect.
+- `state: ChannelStatus` — `'disconnected' | 'connecting' | 'connected' | 'reconnecting'`
+- `subscribe(listener): () => void` — Subscribe to status changes.
+
+### Auto-Reconnect
+- `static RECONNECT_DELAY = 1000`
+- `static MAX_RECONNECT_DELAY = 30000`
+- `static MAX_RECONNECT_ATTEMPTS = Infinity`
+
+---
+
+## Controller
+
+Stateless orchestrator. Component-scoped.
+
+- `onInit(): void | Promise<void>`
+- `onDispose(): void`
+- `disposeSignal: AbortSignal`
+- `subscribeTo(source, listener): void`
+- `addCleanup(fn): void`
+- `dispose(): void`
+
+No state, no getters, no async tracking.
+
+---
+
+## Singleton Registry
+
+```typescript
+singleton(Class, ...args)     // Get or create singleton
+hasSingleton(Class)           // Check existence
+teardown(Class)               // Dispose and remove
+teardownAll()                 // Dispose all (use in test beforeEach)
+```
+
+---
+
+## Error Utilities
+
+- `HttpError(status: number, statusText: string)` — Throw from services.
+- `isAbortError(error: unknown): boolean` — Guard for AbortError.
+- `classifyError(error: unknown): AppError` — Returns `{ code, message, status? }`.
+  - Codes: `'unauthorized'`, `'forbidden'`, `'not_found'`, `'network'`, `'timeout'`, `'abort'`, `'server_error'`, `'unknown'`
+
+---
+
+## React Hooks
+
+### useLocal(Class, ...args) / useLocal(factory)
+Component-scoped. Auto-init/dispose. Returns `[state, instance]` for Subscribables, `instance` for Disposable-only.
+
+Optional `deps` array as final argument — recreates instance when deps change.
+```tsx
+const [state, vm] = useLocal(MyViewModel, { items: [] });
+const [state, vm] = useLocal(MyViewModel, { userId, data: null }, [userId]);
+const controller = useLocal(() => new MyController(dep1, dep2));
+```
+
+### useSingleton(Class, ...args)
+Singleton-scoped. Auto-init. Returns same as `useLocal`.
+```tsx
+const [state, vm] = useSingleton(CartViewModel, { items: [] });
+```
+
+### useInstance(subscribable)
+Subscribe to existing instance. No lifecycle management.
+```tsx
+const state = useInstance(existingVM);
+```
+
+### useModel(factory)
+Returns `ModelHandle: { state, errors, valid, dirty, model }`.
+```tsx
+const { state, errors, valid, dirty, model } = useModel(() => new UserModel({ name: '' }));
+```
+
+### useField(model, key)
+Returns `FieldHandle: { value, error, set }`. Surgical re-renders.
+```tsx
+const { value, error, set } = useField(model, 'name');
+```
+
+### useEvent(source, event, handler)
+Subscribe to EventBus or ViewModel event. Auto-unsubscribes.
+```tsx
+useEvent(vm, 'saved', ({ id }) => toast.success(`Saved ${id}`));
+```
+
+### useEmit(bus)
+Stable emit function.
+```tsx
+const emit = useEmit(bus);
+emit('user:login', { userId: '123' });
+```
+
+### Provider & useResolve
+DI for testing/Storybook.
+```tsx
+<Provider provide={[[ApiService, mockApi]]}>
+  <MyComponent />
+</Provider>
+
+const api = useResolve(ApiService); // falls back to singleton()
+```
+
+### useTeardown(...Classes)
+Teardown singletons on unmount.
+```tsx
+useTeardown(UserViewModel, CartViewModel);
+```
+
+---
+
+## Interfaces
+
+```typescript
+interface Subscribable<S> { state: Readonly<S>; subscribe(listener: Listener<S>): () => void; dispose(): void; disposeSignal: AbortSignal; }
+interface Disposable { disposed: boolean; disposeSignal: AbortSignal; dispose(): void; }
+interface Initializable { initialized: boolean; init(): void; }
+type Listener<S> = (state: Readonly<S>, prev: Readonly<S>) => void;
+type Updater<S> = (state: Readonly<S>) => Partial<S>;
+type ValidationErrors<S> = Partial<Record<keyof S, string>>;
+interface TaskState { readonly loading: boolean; readonly error: string | null; readonly errorCode: string | null; }
+```
+
+## Dev Mode (`__MVC_KIT_DEV__`)
+
+Enable in Vite:
+```typescript
+define: { __MVC_KIT_DEV__: process.env.NODE_ENV !== 'production' }
+```
+
+Checks: `set()` inside getter, ghost async ops, method call after dispose, method call before init, reserved key override.