mvc-kit 2.12.0 → 2.12.1

package/src/Resource.md

@@ -0,0 +1,239 @@
+# Resource
+
+A **Collection + async tracking toolkit**. Resource extends Collection with lifecycle management (`init`/`dispose`) and automatic async method tracking (`resource.async.methodName.loading/error`). Use it when you need a data cache with built-in loading state for your API calls.
+
+## When to Use Resource vs Collection
+
+| Use Case | Class |
+|---|---|
+| Shared data cache, no async loading | `Collection` |
+| Shared data cache + API loading + loading/error state | `Resource` |
+| Multiple data sources feeding one cache (Resource + Channel) | `Resource` with external `Collection` |
+
+## Creating a Resource
+
+Define your own async methods. Use inherited Collection mutations (`reset`, `add`, `upsert`, etc.) to manage data. Resource automatically tracks loading/error state per method.
+
+If you already have a typed API client (RPC client, tRPC, GraphQL codegen, OpenAPI generated client), call it directly — no Service wrapper needed:
+
+```typescript
+import { Resource } from 'mvc-kit';
+import { apiClient } from '@/api';
+
+class UsersResource extends Resource<User> {
+  async loadAll() {
+    const users = await apiClient.users.list({ signal: this.disposeSignal });
+    this.reset(users);
+  }
+
+  async loadById(id: number) {
+    const user = await apiClient.users.get(id, { signal: this.disposeSignal });
+    this.upsert(user);
+  }
+
+  async create(data: CreateUserInput) {
+    const user = await apiClient.users.create(data, { signal: this.disposeSignal });
+    this.add(user);
+    return user;
+  }
+
+  async remove(id: number) {
+    await apiClient.users.delete(id, { signal: this.disposeSignal });
+    super.remove(id);
+  }
+}
+```
+
+When using raw `fetch()`, wrap it in a Service to handle `HttpError` and response parsing:
+
+```typescript
+import { Resource, singleton, Service, HttpError } from 'mvc-kit';
+
+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();
+  }
+}
+
+class UsersResource extends Resource<User> {
+  private api = singleton(UserService);
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data);
+  }
+}
+```
+
+> **When does a Service earn its place?** When it wraps raw `fetch()` with `HttpError`, transforms responses, composes multiple HTTP calls, handles retries, or manages authentication headers. If your API client already does this, the Service is a pass-through — skip it.
+
+## External Collection Injection
+
+When multiple sources feed the same data store (e.g., a Resource for REST + a Channel for WebSocket), inject a shared Collection:
+
+```typescript
+class SharedUsersCollection extends Collection<User> {}
+
+class UsersResource extends Resource<User> {
+  private api = singleton(UserService);
+
+  constructor() {
+    super(singleton(SharedUsersCollection)); // Inject external collection
+  }
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data); // Mutates the shared collection
+  }
+}
+
+class UsersChannel extends Channel<UserMessages> {
+  private users = singleton(SharedUsersCollection);
+
+  protected onMessage(type: string, data: any) {
+    if (type === 'user:updated') {
+      this.users.upsert(data); // Same shared collection
+    }
+  }
+}
+```
+
+All Collection methods transparently delegate to the external collection. `resource.items`, `resource.get(id)`, `resource.subscribe()` all operate on the shared data. Resource disposal does **not** dispose the shared collection.
+
+> **Note:** `MAX_SIZE` and `TTL` statics on a Resource with external injection are inert — configure these on the shared Collection instead.
+
+## Async Tracking
+
+After `init()`, all subclass methods are automatically tracked:
+
+```typescript
+const users = singleton(UsersResource);
+await users.init();
+
+users.loadAll();
+users.async.loadAll.loading;   // true while loading
+users.async.loadAll.error;     // error message string, or null
+users.async.loadAll.errorCode; // 'not_found', 'network', etc., or null
+```
+
+- **Concurrent calls**: `loading` stays `true` until all concurrent calls resolve
+- **AbortError**: silently swallowed (no error state)
+- **Sync methods**: auto-pruned on first call (zero overhead after)
+- **Pre-init calls**: methods work but have no tracking (DEV warning)
+
+## Lifecycle
+
+```typescript
+class UsersResource extends Resource<User> {
+  // Called after init() — load initial data
+  onInit() {
+    if (this.length === 0) this.loadAll();
+  }
+
+  // Called during dispose() — custom teardown
+  onDispose() {
+    // cleanup logic
+  }
+}
+```
+
+- `init()` → wraps methods for async tracking → calls `onInit()`
+- `dispose()` → inherited from Collection → aborts `disposeSignal`, runs cleanups, calls `onDispose()`
+- `initialized` — `false` before `init()`, `true` after
+- `disposeSignal` — AbortSignal that fires on dispose (pass to fetch calls)
+
+## React Integration
+
+Resource works with `useSingleton` (shared) or `useLocal` (component-scoped):
+
+```tsx
+import { useSingleton } from 'mvc-kit/react';
+
+function UserList() {
+  const [items, users] = useSingleton(UsersResource);
+  const { loading, error } = users.async.loadAll;
+
+  if (loading) return <Spinner />;
+  if (error) return <Error message={error} />;
+
+  return <ul>{items.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+- `useSingleton` auto-calls `init()` (via `isInitializable` duck-typing)
+- `subscribeAsync` duck-typing enables `useInstance` to re-render on async changes
+- ViewModel getters that read `resource.items` auto-track via `subscribe` delegation
+
+## ViewModel Integration
+
+ViewModels access Resources via `singleton()`. Getter auto-tracking handles reactivity:
+
+```typescript
+class UsersViewModel extends ViewModel<{ search: string }> {
+  private users = singleton(UsersResource);
+
+  // Auto-tracked: re-evaluates when users.items changes
+  get filtered() {
+    return this.users.filter(u =>
+      u.name.includes(this.state.search)
+    );
+  }
+
+  onInit() {
+    if (this.users.length === 0) this.users.loadAll();
+  }
+}
+```
+
+## Properties & Methods
+
+### Inherited from Collection
+
+| Member | Type | Description |
+|---|---|---|
+| `items` | `T[]` | The raw array |
+| `state` | `T[]` | Alias for `items` (Subscribable compatibility) |
+| `length` | `number` | Item count |
+| `disposed` | `boolean` | Whether disposed |
+| `disposeSignal` | `AbortSignal` | Fires on dispose |
+| `add(...items)` | `void` | Add items (skip duplicates) |
+| `upsert(...items)` | `void` | Add or replace by ID |
+| `update(id, changes)` | `void` | Partial update by ID |
+| `remove(...ids)` | `void` | Remove by ID(s) |
+| `reset(items)` | `void` | Replace all items |
+| `clear()` | `void` | Remove all items |
+| `optimistic(cb)` | `() => void` | Snapshot → mutate → rollback fn |
+| `get(id)` | `T \| undefined` | Lookup by ID |
+| `has(id)` | `boolean` | Check existence |
+| `find(pred)` | `T \| undefined` | First match |
+| `filter(pred)` | `T[]` | All matches |
+| `sorted(cmp)` | `T[]` | Sorted copy |
+| `map(fn)` | `U[]` | Mapped array |
+| `subscribe(listener)` | `() => void` | Subscribe to changes |
+| `dispose()` | `void` | Tear down |
+| `static MAX_SIZE` | `number` | Max items (FIFO eviction), 0 = unlimited |
+| `static TTL` | `number` | Time-to-live (ms), 0 = no expiry |
+
+### Resource-Specific
+
+| Member | Type | Description |
+|---|---|---|
+| `initialized` | `boolean` | Whether `init()` has been called |
+| `init()` | `void \| Promise<void>` | Initialize (wraps methods, calls `onInit`) |
+| `onInit()` | `void \| Promise<void>` | Lifecycle hook for initial data loading |
+| `onDispose()` | `void` | Lifecycle hook for custom teardown |
+| `async` | `{ [method]: TaskState }` | Async tracking proxy |
+| `subscribeAsync(cb)` | `() => void` | Subscribe to async state changes |
+| `addCleanup(fn)` | `void` | Register cleanup for dispose |
+| `static GHOST_TIMEOUT` | `number` | DEV-only ghost detection delay (ms) |
+
+## 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 { add, upsert } = resource;
+channel.on("update", upsert); // point-free works
+```