mvc-kit 2.12.0 → 2.12.2

package/src/Selection.ts

@@ -0,0 +1,117 @@
+import { Trackable } from './Trackable';
+
+/**
+ * Key-based selection set with toggle and select-all support.
+ * Tracks which items are selected by their key (id).
+ * Subscribable — auto-tracked when used as a ViewModel property.
+ */
+export class Selection<K extends string | number = string | number> extends Trackable {
+  private _selected: Set<K> = new Set();
+  private _readonlyView: ReadonlySet<K> = this._selected;
+
+  constructor() {
+    super();
+  }
+
+  // ── Readable state ──
+
+  /** Read-only view of currently selected keys. */
+  get selected(): ReadonlySet<K> {
+    return this._readonlyView;
+  }
+
+  /** Number of currently selected items. */
+  get count(): number {
+    return this._selected.size;
+  }
+
+  /** Whether any items are currently selected. */
+  get hasSelection(): boolean {
+    return this._selected.size > 0;
+  }
+
+  // ── Query ──
+
+  /** Check whether a specific key is selected. */
+  isSelected(key: K): boolean {
+    return this._selected.has(key);
+  }
+
+  // ── Actions ──
+
+  /** Toggle a key's selection state (select if unselected, deselect if selected). */
+  toggle(key: K): void {
+    if (this._selected.has(key)) {
+      this._selected.delete(key);
+    } else {
+      this._selected.add(key);
+    }
+    this._publish();
+  }
+
+  /** Add one or more keys to the selection. */
+  select(...keys: K[]): void {
+    let changed = false;
+    for (const key of keys) {
+      if (!this._selected.has(key)) {
+        this._selected.add(key);
+        changed = true;
+      }
+    }
+    if (changed) this._publish();
+  }
+
+  /** Remove one or more keys from the selection. */
+  deselect(...keys: K[]): void {
+    let changed = false;
+    for (const key of keys) {
+      if (this._selected.has(key)) {
+        this._selected.delete(key);
+        changed = true;
+      }
+    }
+    if (changed) this._publish();
+  }
+
+  /** If all selected → deselect all, else select all. */
+  toggleAll(allKeys: K[]): void {
+    const allSelected = allKeys.length > 0 && allKeys.every(k => this._selected.has(k));
+    if (allSelected) {
+      this._selected.clear();
+    } else {
+      for (const key of allKeys) this._selected.add(key);
+    }
+    this._publish();
+  }
+
+  /** Replace the entire selection atomically. Single notification. */
+  set(...keys: K[]): void {
+    // Check if anything actually changed
+    if (keys.length === this._selected.size && keys.every(k => this._selected.has(k))) return;
+    this._selected.clear();
+    for (const key of keys) this._selected.add(key);
+    this._publish();
+  }
+
+  /** Remove all items from the selection. */
+  clear(): void {
+    if (this._selected.size === 0) return;
+    this._selected.clear();
+    this._publish();
+  }
+
+  // ── Utility ──
+
+  /** Filter an array to only items whose key is in the selection. */
+  selectedFrom<T>(items: T[], keyOf: (item: T) => K): T[] {
+    return items.filter(item => this._selected.has(keyOf(item)));
+  }
+
+  // ── Internal ──
+
+  private _publish(): void {
+    // Replace readonlyView so reference equality changes (needed for React)
+    this._readonlyView = new Set(this._selected);
+    this.notify();
+  }
+}

package/src/Service.md

@@ -0,0 +1,440 @@
+# Service
+
+A base class for non-reactive infrastructure adapters. Services encapsulate external dependencies — APIs, storage, third-party SDKs — behind clean, stateless interfaces. They sit at the bottom of the dependency graph: ViewModels and Controllers depend on Services, but Services depend on nothing in mvc-kit.
+
+---
+
+## When to Use
+
+| Question | Use |
+|---|---|
+| Does it wrap raw `fetch()` with `HttpError` and response parsing? | **Service** |
+| Does it wrap a third-party SDK behind a clean interface? | **Service** |
+| Does it manage auth headers, retries, or compose multiple HTTP calls? | **Service** |
+| Does it hold UI state, computed properties, or actions for a component? | **ViewModel** |
+| Does it hold a list of entities with CRUD operations? | **Collection** |
+
+If the class needs reactive state, getters, or async tracking — it's a ViewModel, not a Service.
+
+**When NOT to use a Service:** If you already have a typed API client (RPC client, tRPC, GraphQL codegen, OpenAPI generated client) that handles error types, response parsing, and signal passing, don't wrap it in a Service. Call it directly from your Resource or ViewModel. A Service that only destructures and re-returns the client's response is a pass-through that adds lines without value.
+
+---
+
+## Subclass Contract
+
+Service is `abstract`. Extend it and add your methods:
+
+```typescript
+import { Service, HttpError } from 'mvc-kit';
+
+export class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<UserState[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async update(id: string, data: Partial<UserState>, signal?: AbortSignal): Promise<UserState> {
+    const res = await fetch(`/api/users/${id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      signal,
+    });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+---
+
+## What Service Provides
+
+Service is deliberately minimal. It provides lifecycle management and cancellation — nothing more.
+
+| Feature | Included |
+|---|---|
+| `init()` / `dispose()` lifecycle | Yes |
+| `onInit()` / `onDispose()` hooks | Yes |
+| `disposeSignal` (AbortSignal) | Yes |
+| `addCleanup(fn)` | Yes |
+| `initialized` / `disposed` flags | Yes |
+| Reactive state | No |
+| Computed getters | No |
+| Async tracking | No |
+| Events / emit | No |
+| `subscribeTo` | No |
+
+---
+
+## API
+
+### `init(): void | Promise<void>`
+
+Initializes the Service. Calls `onInit()` if defined. Idempotent — calling it multiple times only runs `onInit()` once. No-op if already disposed.
+
+```typescript
+const service = new UserService();
+service.init();
+service.init(); // no-op
+```
+
+Supports async initialization:
+
+```typescript
+class ConfigService extends Service {
+  private config: AppConfig | null = null;
+
+  protected async onInit() {
+    const res = await fetch('/api/config');
+    this.config = await res.json();
+  }
+
+  getConfig(): AppConfig {
+    return this.config!;
+  }
+}
+
+const service = new ConfigService();
+await service.init();
+```
+
+### `dispose(): void`
+
+Tears down the Service. In order:
+1. Sets `disposed` to `true`
+2. Aborts `disposeSignal`
+3. Runs all registered cleanups
+4. Calls `onDispose()`
+
+Idempotent — safe to call multiple times. `onDispose()` only runs once.
+
+```typescript
+service.dispose();
+service.dispose(); // no-op
+```
+
+### `disposeSignal: AbortSignal`
+
+A lazily-created AbortSignal that aborts when the Service is disposed. Pass it to `fetch()` or other cancellable APIs to cancel in-flight operations on teardown.
+
+```typescript
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<UserState[]> {
+    // Compose with disposeSignal for double protection
+    const res = await fetch('/api/users', {
+      signal: signal ?? this.disposeSignal,
+    });
+    return res.json();
+  }
+}
+```
+
+The signal is:
+- **Lazy** — zero cost if never accessed. No AbortController is allocated unless you read `disposeSignal`.
+- **Stable** — returns the same signal on every access.
+- **Aborted before `onDispose()` runs** — cleanup code can check `this.disposeSignal.aborted` and it will be `true`.
+
+### `addCleanup(fn: () => void): void` (protected)
+
+Registers a cleanup function that runs on dispose. Use this for teardown that the base class can't handle automatically.
+
+```typescript
+class PollingService extends Service {
+  private intervalId?: ReturnType<typeof setInterval>;
+
+  protected onInit() {
+    this.intervalId = setInterval(() => this.poll(), 5000);
+    this.addCleanup(() => clearInterval(this.intervalId));
+  }
+
+  private async poll() { /* ... */ }
+}
+```
+
+### `onInit?(): void | Promise<void>` (protected)
+
+Override to run setup logic when `init()` is called. This is where you open connections, start timers, or perform initial configuration.
+
+### `onDispose?(): void` (protected)
+
+Override to run teardown logic when `dispose()` is called. Runs after the signal is aborted and cleanups have fired.
+
+```typescript
+class StorageService extends Service {
+  private data = new Map<string, string>();
+
+  protected onDispose() {
+    this.data.clear();
+  }
+}
+```
+
+---
+
+## Lifecycle
+
+```
+new Service()           → disposed: false, initialized: false
+       │
+    init()              → initialized: true, onInit() called
+       │
+    dispose()           → disposed: true
+                          1. abort signal
+                          2. run cleanups
+                          3. onDispose() called
+```
+
+- `init()` after `dispose()` is a no-op — the Service stays uninitialized.
+- `dispose()` before `init()` works — the Service is disposed without ever initializing.
+
+---
+
+## Singleton Usage
+
+Services are almost always singletons. They're stateless infrastructure — there's no reason to have two instances of the same service.
+
+```typescript
+import { singleton, teardown, teardownAll } from 'mvc-kit';
+
+// Resolved inside ViewModels as property initializers
+class LocationsViewModel extends ViewModel<State> {
+  private service = singleton(LocationService);
+}
+
+// Same instance on repeated calls
+singleton(LocationService) === singleton(LocationService); // true
+
+// Teardown disposes and removes from registry
+teardown(LocationService);
+
+// Or tear down everything at once (common in test setup)
+teardownAll();
+```
+
+---
+
+## Error Handling
+
+### Throw HttpError for HTTP Failures
+
+`HttpError` is a typed error class that carries the HTTP status code. The ViewModel's async tracking and `classifyError()` use it to produce canonical error codes.
+
+```typescript
+import { HttpError } from 'mvc-kit';
+
+class UserService extends Service {
+  async getById(id: string, signal?: AbortSignal): Promise<UserState> {
+    const res = await fetch(`/api/users/${id}`, { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+When a ViewModel calls this method, async tracking automatically classifies the error:
+
+| Status | `errorCode` |
+|---|---|
+| 401 | `'unauthorized'` |
+| 403 | `'forbidden'` |
+| 404 | `'not_found'` |
+| 422 | `'validation'` |
+| 429 | `'rate_limited'` |
+| 500+ | `'server_error'` |
+| Fetch failure | `'network'` |
+| AbortError | Silently swallowed |
+
+### Accept AbortSignal Parameters
+
+Every async method should accept an optional `AbortSignal`. This lets ViewModels pass `this.disposeSignal` to cancel in-flight requests when components unmount.
+
+```typescript
+async getAll(signal?: AbortSignal): Promise<UserState[]> {
+  const res = await fetch('/api/users', { signal });
+  if (!res.ok) throw new HttpError(res.status, res.statusText);
+  return res.json();
+}
+```
+
+The ViewModel passes its signal:
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+---
+
+## Examples
+
+### Basic REST Service
+
+```typescript
+class LocationService extends Service {
+  async getAll(signal?: AbortSignal): Promise<LocationState[]> {
+    const res = await fetch('/api/locations', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async create(data: Omit<LocationState, 'id'>, signal?: AbortSignal): Promise<LocationState> {
+    const res = await fetch('/api/locations', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      signal,
+    });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  async delete(id: string, signal?: AbortSignal): Promise<void> {
+    const res = await fetch(`/api/locations/${id}`, { method: 'DELETE', signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+  }
+}
+```
+
+### Service with Initialization
+
+```typescript
+class AuthService extends Service {
+  private token: string | null = null;
+
+  protected async onInit() {
+    this.token = localStorage.getItem('auth_token');
+  }
+
+  private get headers(): HeadersInit {
+    return this.token
+      ? { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' }
+      : { 'Content-Type': 'application/json' };
+  }
+
+  async getCurrentUser(signal?: AbortSignal): Promise<UserState> {
+    const res = await fetch('/api/me', { headers: this.headers, signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+
+  setToken(token: string) {
+    this.token = token;
+    localStorage.setItem('auth_token', token);
+  }
+
+  protected onDispose() {
+    this.token = null;
+  }
+}
+```
+
+### Service with Cleanup
+
+```typescript
+class PollingService extends Service {
+  private intervalId?: ReturnType<typeof setInterval>;
+
+  protected onInit() {
+    this.intervalId = setInterval(() => this.healthCheck(), 30_000);
+    this.addCleanup(() => clearInterval(this.intervalId));
+  }
+
+  private async healthCheck() {
+    try {
+      await fetch('/api/health', { signal: this.disposeSignal });
+    } catch {
+      // swallow — health checks are best-effort
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Keep Services stateless.** Don't cache data between calls — that's a Collection's job. A Service transforms requests and responses; it doesn't own data.
+
+2. **Accept `AbortSignal` on every async method.** This lets ViewModels cancel in-flight requests via `disposeSignal` when components unmount.
+
+3. **Throw `HttpError` for HTTP failures.** It carries the status code, which `classifyError()` maps to canonical error codes for the ViewModel's async tracking.
+
+4. **Use `singleton()` resolution.** Services are stateless infrastructure — always resolve via `singleton(MyService)` inside ViewModel property initializers.
+
+5. **Don't import ViewModels or Collections.** Services sit at the bottom of the dependency graph. They don't know about the rest of mvc-kit. Data flows up: Service → ViewModel → Component.
+
+6. **Use `onInit()` for one-time setup.** Loading configuration, reading from localStorage, or establishing non-connection infrastructure.
+
+7. **Use `addCleanup()` for timers and external subscriptions.** Anything started in `onInit()` or service methods that needs teardown.
+
+## Anti-Patterns
+
+```typescript
+// Don't cache data in a Service — use a Collection
+class BadService extends Service {
+  private cache: UserState[] = [];       // belongs in UsersCollection
+  async getAll() {
+    if (this.cache.length) return this.cache;
+    this.cache = await fetch('/api/users').then(r => r.json());
+    return this.cache;
+  }
+}
+
+// Don't make Services reactive — use a ViewModel
+class BadReactiveService extends Service {
+  state = { loading: false };            // Services have no reactive state
+  listeners = new Set<() => void>();     // Services have no subscriptions
+}
+
+// Don't forget AbortSignal parameters
+class BadService extends Service {
+  async getAll(): Promise<UserState[]> {
+    const res = await fetch('/api/users'); // uncancellable — leaks on unmount
+    return res.json();
+  }
+}
+
+// Don't throw plain Errors for HTTP failures
+class BadService extends Service {
+  async getAll(signal?: AbortSignal) {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new Error('Request failed'); // loses status code
+    return res.json();
+  }
+}
+
+// Don't create a pass-through Service for a typed API client
+// BAD — Service just proxies an existing client
+class ArticleService extends Service {
+  async get(id: string, signal?: AbortSignal) {
+    const { result } = await rpcClient.articles.get({ id }, { abortSignal: signal });
+    return result;
+  }
+  async create(input: CreateInput, signal?: AbortSignal) {
+    const { result } = await rpcClient.articles.create(input, { abortSignal: signal });
+    return result;
+  }
+}
+// GOOD — Resource calls the API client directly
+class ArticleResource extends Resource<Article> {
+  async loadById(id: string) {
+    const { result } = await rpcClient.articles.get({ id }, { abortSignal: this.disposeSignal });
+    this.upsert(result);
+  }
+}
+```
+
+> See `BEST_PRACTICES.md` for prescribed usage patterns and dependency flow rules.
+
+## Method Binding
+
+All public methods are auto-bound in the constructor. You can pass them point-free as callbacks without losing `this` context:
+
+```tsx
+const { fetchData } = service;
+onMount(fetchData); // point-free works
+```