mvc-kit 2.12.0 → 2.12.1

package/src/Pagination.ts

@@ -0,0 +1,92 @@
+import { Trackable } from './Trackable';
+
+/**
+ * Page-based pagination state manager with array slicing pipeline.
+ * Tracks current page and page size, provides navigation helpers.
+ * Subscribable — auto-tracked when used as a ViewModel property.
+ */
+export class Pagination extends Trackable {
+  private _page: number = 1;
+  private _pageSize: number;
+
+  constructor(options?: { pageSize?: number }) {
+    super();
+    this._pageSize = options?.pageSize ?? 10;
+  }
+
+  // ── Readable state ──
+
+  /** Current page number (1-based). */
+  get page(): number {
+    return this._page;
+  }
+
+  /** Number of items per page. */
+  get pageSize(): number {
+    return this._pageSize;
+  }
+
+  // ── Derived (require total) ──
+
+  /** Total number of pages for the given item count. */
+  pageCount(total: number): number {
+    return Math.max(1, Math.ceil(total / this._pageSize));
+  }
+
+  /** Whether there is a next page available. */
+  hasNext(total: number): boolean {
+    return this._page < this.pageCount(total);
+  }
+
+  /** Whether there is a previous page available. */
+  hasPrev(): boolean {
+    return this._page > 1;
+  }
+
+  // ── Actions ──
+
+  /** Navigate to a specific page (clamped to >= 1). */
+  setPage(page: number): void {
+    const clamped = Math.max(1, Math.floor(page));
+    if (clamped === this._page) return;
+    this._page = clamped;
+    this.notify();
+  }
+
+  /** Change the page size and reset to page 1. */
+  setPageSize(size: number): void {
+    if (size < 1) return;
+    this._pageSize = size;
+    this._page = 1;
+    this.notify();
+  }
+
+  /** Advance to the next page. */
+  nextPage(): void {
+    this._page++;
+    this.notify();
+  }
+
+  /** Go back to the previous page. No-op if already on page 1. */
+  prevPage(): void {
+    if (this._page > 1) {
+      this._page--;
+      this.notify();
+    }
+  }
+
+  /** Reset to page 1. */
+  reset(): void {
+    if (this._page === 1) return;
+    this._page = 1;
+    this.notify();
+  }
+
+  // ── Pipeline ──
+
+  /** Slice an array to the current page window. Returns the page subset. */
+  apply<T>(items: T[]): T[] {
+    const start = (this._page - 1) * this._pageSize;
+    return items.slice(start, start + this._pageSize);
+  }
+}

package/src/Pending.md

@@ -0,0 +1,380 @@
+# Pending
+
+Per-item operation queue with retry and status tracking. Manages optimistic update lifecycle with exponential backoff on transient errors. Extends [`Trackable`](./Trackable.md) — subscribable, disposable, and auto-bound.
+
+---
+
+## When to Use
+
+Use Pending as a Resource property to track per-item server operations that may fail transiently. Pending provides:
+
+- **Per-item status indicators** — show users which items are saving, retrying, or failed
+- **Automatic retry with backoff** — network errors, timeouts, and 5xx errors retry automatically
+- **Error classification** — 4xx errors (auth, validation) fail immediately without retry
+- **Survive unmount** — lives on the singleton Resource, not the component-scoped ViewModel
+- **Typed metadata** — attach display context (names, previews) to operations for rich UIs
+
+For simple fire-and-forget operations where you don't need per-item status, use standard async tracking instead.
+
+---
+
+## Creating an Instance
+
+```typescript
+import { Pending } from 'mvc-kit';
+
+// String keys (default)
+readonly pending = new Pending<string>();
+
+// Numeric keys
+readonly pending = new Pending<number>();
+
+// With typed metadata for UI display
+interface SendMeta { recipientName: string; preview: string }
+readonly pending = new Pending<string, SendMeta>();
+```
+
+### Custom Configuration via Subclass
+
+Override static properties (Channel pattern):
+
+```typescript
+class AggressivePending extends Pending<string> {
+  static override MAX_RETRIES = 10;
+  static override RETRY_BASE = 500;
+  static override RETRY_MAX = 60000;
+  static override RETRY_FACTOR = 1.5;
+}
+```
+
+---
+
+## API
+
+### Readable State
+
+#### `getStatus(id: K): PendingOperation<Meta> | null`
+
+Frozen snapshot of the operation's current state. Returns `null` if no operation exists for the given ID.
+
+```typescript
+interface PendingOperation<Meta = unknown> {
+  readonly status: 'active' | 'retrying' | 'failed';
+  readonly operation: string;
+  readonly attempts: number;
+  readonly maxRetries: number;
+  readonly error: string | null;
+  readonly errorCode: AppError['code'] | null;
+  readonly nextRetryAt: number | null;
+  readonly createdAt: number;
+  readonly meta: Meta | null;
+}
+```
+
+The `meta` field contains the metadata passed to `enqueue()`, or `null` if none was provided.
+
+#### `has(id: K): boolean`
+
+Whether an operation exists for the given ID.
+
+#### `count: number`
+
+Total number of operations (all statuses).
+
+#### `hasPending: boolean`
+
+Whether any operations are in-flight (active or retrying). Does **not** include failed operations — use `hasFailed` for those.
+
+#### `hasFailed: boolean`
+
+Whether any operations are in `'failed'` status.
+
+#### `failedCount: number`
+
+Number of operations in `'failed'` status. Useful for rendering "N operations failed" banners.
+
+#### `entries: readonly PendingEntry<K, Meta>[]`
+
+All operations as a frozen array. Each entry extends `PendingOperation<Meta>` with an `id: K` field. Cached until the next mutation — reference-stable between reads.
+
+```typescript
+interface PendingEntry<K extends string | number, Meta = unknown>
+  extends PendingOperation<Meta> {
+  readonly id: K;
+}
+```
+
+Use for rendering lists of pending/failed operations (e.g., in modals or status panels):
+
+```typescript
+for (const entry of vm.pending.entries) {
+  entry.id;         // K
+  entry.status;     // 'active' | 'retrying' | 'failed'
+  entry.operation;  // string
+  entry.meta;       // Meta | null
+}
+```
+
+### Core API
+
+#### `enqueue(id: K, operation: string, execute: (signal: AbortSignal) => Promise<void>, meta?: Meta): void`
+
+Fire-and-forget. Enqueues an operation and starts processing via microtask. If the same ID already has a pending operation, it is superseded (previous signal aborted).
+
+```typescript
+// In a Resource method:
+async deleteItem(id: string) {
+  this.optimistic(() => this.remove(id));
+  this.pending.enqueue(id, 'delete', async (signal) => {
+    await api.deleteItem(id, signal);
+  });
+}
+
+// With metadata for UI display:
+enqueueSend(tempId: string, text: string, recipientName: string) {
+  this.pending.enqueue(tempId, 'send', async (signal) => {
+    await api.sendMessage(tempId, text, signal);
+  }, { recipientName, preview: text.slice(0, 50) });
+}
+```
+
+The `signal` parameter is owned by Pending — do **not** pass `this.disposeSignal` from a ViewModel.
+
+### Controls
+
+#### `retry(id: K): void`
+
+Re-process a failed operation. Resets attempts to 0. No-op if the operation is not in `'failed'` status.
+
+#### `retryAll(): void`
+
+Retry all failed operations.
+
+#### `cancel(id: K): void`
+
+Abort an in-flight operation's signal, clear its retry timer, and remove it. Works on any status.
+
+#### `cancelAll(): void`
+
+Cancel all operations.
+
+#### `dismiss(id: K): void`
+
+Remove a failed operation without retrying. No-op if the operation is not in `'failed'` status. Use for "dismiss" buttons in failure UIs.
+
+#### `dismissAll(): void`
+
+Remove all failed operations without retrying. Single notification. Does not affect active or retrying operations.
+
+### Hooks
+
+Override in a subclass for side effects:
+
+#### `protected isRetryable(error: unknown): boolean`
+
+Determines whether an error should trigger retry. Default: retries on `network`, `timeout`, and `server_error` codes.
+
+#### `protected onConfirmed?(id: K, operation: string): void`
+
+Called when an operation succeeds.
+
+#### `protected onFailed?(id: K, operation: string, error: unknown): void`
+
+Called when an operation fails permanently (non-retryable or max retries exceeded).
+
+### Subscribable Interface
+
+#### `subscribe(cb: () => void): () => void`
+
+Subscribe to state changes. Returns an unsubscribe function. Auto-tracked by ViewModel when assigned as a property.
+
+### Lifecycle
+
+#### `disposed: boolean`
+
+Whether this instance has been disposed.
+
+#### `dispose(): void`
+
+Cancels all operations, clears all listeners. Called automatically when the owning Resource is torn down.
+
+---
+
+## ViewModel Integration
+
+Pending lives on the **singleton Resource** so operations survive component unmount. The ViewModel holds a reference for auto-tracking:
+
+```typescript
+class ItemsResource extends Resource<Item> {
+  readonly pending = new Pending<string>();
+
+  async deleteItem(id: string) {
+    this.optimistic(() => this.remove(id));
+    this.pending.enqueue(id, 'delete', async (signal) => {
+      await api.deleteItem(id, signal);
+    });
+  }
+
+  protected override onDispose() {
+    this.pending.dispose();
+  }
+}
+
+class ItemsVM extends ViewModel<{ filter: string }> {
+  private resource = singleton(ItemsResource);
+
+  // Auto-tracked: getter recomputes when pending status changes
+  get pending() { return this.resource.pending; }
+  get hasFailed() { return this.resource.pending.hasFailed; }
+  get failedCount() { return this.resource.pending.failedCount; }
+
+  get items() {
+    return this.resource.items.filter(i =>
+      i.name.includes(this.state.filter),
+    );
+  }
+
+  deleteItem(id: string) {
+    this.resource.deleteItem(id);
+  }
+
+  retryFailed() {
+    this.resource.pending.retryAll();
+  }
+
+  dismissFailed() {
+    this.resource.pending.dismissAll();
+  }
+}
+```
+
+### Signal Ownership
+
+The `signal` passed to `enqueue`'s callback is owned by Pending. It is aborted when:
+- The operation is superseded (same ID enqueued again)
+- The operation is cancelled via `cancel()` / `cancelAll()`
+- The Pending instance is disposed
+
+Do **not** pass `vm.disposeSignal` — that would abort the operation when the component unmounts, defeating the purpose of singleton-scoped resilience.
+
+---
+
+## React Usage
+
+```tsx
+function ItemRow({ item, vm }: { item: Item; vm: ItemsVM }) {
+  const status = vm.pending.getStatus(item.id);
+
+  return (
+    <tr>
+      <td>{item.name}</td>
+      <td>
+        {status?.status === 'retrying' && <span>Retrying...</span>}
+        {status?.status === 'failed' && (
+          <>
+            <span>Failed: {status.error}</span>
+            <button onClick={() => vm.pending.retry(item.id)}>Retry</button>
+            <button onClick={() => vm.pending.dismiss(item.id)}>Dismiss</button>
+          </>
+        )}
+      </td>
+    </tr>
+  );
+}
+
+function FailedBanner({ vm }: { vm: ItemsVM }) {
+  if (!vm.hasFailed) return null;
+  return (
+    <div>
+      {vm.failedCount} operation(s) failed.
+      <button onClick={() => vm.retryFailed()}>Retry all</button>
+      <button onClick={() => vm.dismissFailed()}>Dismiss all</button>
+    </div>
+  );
+}
+```
+
+### Pending Operations Modal with Meta
+
+Use `entries` and typed metadata to render rich pending operations UIs:
+
+```typescript
+// Resource with typed metadata
+interface SendMeta { recipientName: string; preview: string }
+
+class MessagesResource extends Resource<MessageState> {
+  readonly pending = new Pending<string, SendMeta>();
+
+  enqueueSend(tempId: string, convId: string, text: string, recipientName: string) {
+    this.pending.enqueue(tempId, 'send', async (signal) => {
+      await api.sendMessage(convId, text, signal);
+    }, { recipientName, preview: text.slice(0, 50) });
+  }
+}
+```
+
+```tsx
+// Modal listing all pending/failed operations
+function PendingModal({ pending }: { pending: Pending<string, SendMeta> }) {
+  return (
+    <ul>
+      {pending.entries.map(entry => (
+        <li key={entry.id}>
+          <strong>To: {entry.meta?.recipientName}</strong>
+          <span>{entry.meta?.preview}</span>
+          <span>{entry.status} (attempt {entry.attempts}/{entry.maxRetries})</span>
+          {entry.status === 'failed' && (
+            <>
+              <button onClick={() => pending.retry(entry.id)}>Retry</button>
+              <button onClick={() => pending.dismiss(entry.id)}>Dismiss</button>
+            </>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Error Classification
+
+Pending uses `classifyError()` from `src/errors.ts` to determine retry behavior:
+
+| Error Code | Retries? | Examples |
+|---|---|---|
+| `network` | Yes | `TypeError: Failed to fetch` |
+| `timeout` | Yes | `TimeoutError` |
+| `server_error` | Yes | HTTP 500, 502, 503 |
+| `unauthorized` | No | HTTP 401 |
+| `forbidden` | No | HTTP 403 |
+| `not_found` | No | HTTP 404 |
+| `validation` | No | HTTP 422 |
+| `rate_limited` | No | HTTP 429 |
+| `unknown` | No | Unrecognized errors |
+| `abort` | Silent remove | `AbortError` |
+
+Override `isRetryable()` in a subclass to customize (e.g., to retry rate-limited requests).
+
+---
+
+## Configuration
+
+| Static Property | Default | Description |
+|---|---|---|
+| `MAX_RETRIES` | `5` | Maximum retry attempts before marking as failed |
+| `RETRY_BASE` | `1000` | Base delay (ms) for exponential backoff |
+| `RETRY_MAX` | `30000` | Maximum delay cap (ms) |
+| `RETRY_FACTOR` | `2` | Exponential multiplier |
+
+Backoff formula (same as Channel): `Math.random() * Math.min(BASE * FACTOR^attempt, MAX)`
+
+## 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 { retryAll, dismissAll } = pending;
+<button onClick={retryAll}>Retry All</button> // point-free works
+```