mvc-kit 2.12.0 → 2.12.1

package/src/Channel.md

@@ -0,0 +1,408 @@
+# Channel
+
+A Channel manages a persistent external connection (WebSocket, SSE, or any transport) with built-in auto-reconnect, typed message routing, and subscribable connection status. It implements `Subscribable<ChannelStatus>`, `Initializable`, and `Disposable`.
+
+---
+
+## Subclass Contract
+
+Extend `Channel<MessageMap>` and implement two abstract methods:
+
+```typescript
+interface ChatMessages {
+  message: { userId: string; text: string };
+  typing: { userId: string };
+  presence: { online: string[] };
+}
+
+class ChatChannel extends Channel<ChatMessages> {
+  private ws: WebSocket | null = null;
+
+  protected open(signal: AbortSignal): void {
+    this.ws = new WebSocket('wss://chat.example.com');
+
+    this.ws.onopen = () => {
+      // Connection established — framework handles status transition
+    };
+
+    this.ws.onmessage = (e) => {
+      const { type, payload } = JSON.parse(e.data);
+      this.receive(type, payload); // dispatch to on() handlers
+    };
+
+    this.ws.onclose = () => {
+      if (!signal.aborted) {
+        this.disconnected(); // triggers auto-reconnect
+      }
+    };
+
+    this.ws.onerror = () => this.ws?.close();
+
+    signal.addEventListener('abort', () => this.ws?.close());
+  }
+
+  protected close(): void {
+    this.ws?.close();
+    this.ws = null;
+  }
+}
+```
+
+| Method | Purpose |
+|---|---|
+| `open(signal)` | Establish the connection. The `signal` aborts on disconnect or dispose. Can return `void` or `Promise<void>`. |
+| `close()` | Tear down the transport. Must not throw (errors are swallowed during dispose). |
+
+### Synchronous vs Async Open
+
+`open()` can be synchronous (returns `void`) or asynchronous (returns `Promise<void>`). When synchronous, the channel transitions to `connected` immediately. When async, it transitions after the promise resolves. If it rejects, reconnect is scheduled.
+
+---
+
+## Connection Status
+
+The `state` property exposes a frozen `ChannelStatus` object:
+
+```typescript
+interface ChannelStatus {
+  readonly connected: boolean;    // true when open() succeeded
+  readonly reconnecting: boolean; // true during backoff/retry
+  readonly attempt: number;       // current reconnect attempt (0 when connected or idle)
+  readonly error: string | null;  // last error message, or null
+}
+```
+
+Initial status is `{ connected: false, reconnecting: false, attempt: 0, error: null }`.
+
+### Status Transitions
+
+```
+Idle ──connect()──→ Connecting ──open() succeeds──→ Connected
+                        │                               │
+                   open() fails                   disconnected()
+                        │                               │
+                        ▼                               ▼
+                   Reconnecting ◄───────────────── Reconnecting
+                        │                               │
+                   timer fires → Connecting         timer fires → Connecting
+                        │
+                   MAX_ATTEMPTS exceeded → Idle (with error)
+```
+
+### Subscribing to Status Changes
+
+Channel implements `Subscribable<ChannelStatus>`. Listeners receive `(next, prev)`:
+
+```typescript
+channel.subscribe((next, prev) => {
+  console.log(`${prev.connected} → ${next.connected}`);
+});
+```
+
+Status notifications are **deduplicated** — if the status object hasn't changed (all four fields match), no notification fires. This means calling `disconnect()` on an already-idle channel triggers no listeners.
+
+---
+
+## Connection Control
+
+```typescript
+channel.connect();    // initiate connection (idempotent while connected/connecting)
+channel.disconnect(); // manual disconnect, cancels pending reconnect, resets status
+```
+
+**`connect()` behavior:**
+- Idempotent when already connected or connecting — calling it again is a no-op.
+- If called during reconnecting, it cancels the backoff timer and immediately attempts a fresh connection (attempt resets to 0).
+- Ignored after dispose (DEV mode logs a warning).
+- DEV mode warns if called before `init()`.
+
+**`disconnect()` behavior:**
+- Cancels any pending reconnect timer.
+- Aborts the in-flight `open()` signal.
+- Calls `close()` if connected or connecting.
+- Resets status to idle (`connected: false, reconnecting: false, attempt: 0, error: null`).
+- No-op if idle or disposed.
+
+**Reconnect cycle:**
+After `disconnect()` + `connect()`, the channel reconnects cleanly — each cycle creates a fresh `AbortController` for the open signal.
+
+---
+
+## Message Routing
+
+Subclasses dispatch incoming data via `this.receive(type, payload)`. Consumers subscribe via `on()` and `once()`:
+
+```typescript
+// Subscribe to all messages of a type
+const unsub = channel.on('message', ({ userId, text }) => {
+  console.log(`${userId}: ${text}`);
+});
+
+// Subscribe to only the first message
+channel.once('presence', ({ online }) => {
+  console.log('Initial presence:', online);
+});
+
+// Unsubscribe
+unsub();
+```
+
+**Key details:**
+- `receive()` is **protected** — only the subclass can dispatch messages.
+- Multiple handlers for the same type all fire in registration order.
+- Handlers for different types are independent.
+- `once()` auto-unsubscribes after the first delivery. Its unsubscribe function can cancel it before it fires.
+- `on()` on a disposed channel returns a no-op unsubscribe.
+- `receive()` after dispose is silently ignored (DEV mode logs a warning).
+
+---
+
+## Auto-Reconnect
+
+When `disconnected()` is called from a connected or connecting state, the Channel schedules reconnection with exponential backoff and jitter.
+
+### Tuning via Static Properties
+
+Override these on your subclass to control reconnect behavior:
+
+```typescript
+class ChatChannel extends Channel<ChatMessages> {
+  static RECONNECT_BASE = 1000;        // initial backoff (ms), default 1000
+  static RECONNECT_MAX = 30000;        // max backoff cap (ms), default 30000
+  static RECONNECT_FACTOR = 2;         // exponential multiplier, default 2
+  static MAX_ATTEMPTS = Infinity;      // give up after N attempts, default Infinity
+}
+```
+
+### Backoff Formula
+
+```
+delay = random() * min(RECONNECT_BASE * RECONNECT_FACTOR^attempt, RECONNECT_MAX)
+```
+
+The `random()` jitter prevents thundering-herd reconnect storms when many clients drop simultaneously.
+
+### MAX_ATTEMPTS
+
+When `attempt > MAX_ATTEMPTS`, the channel stops reconnecting and transitions to idle with an error. The `error` field contains the last error message or `'Max reconnection attempts reached'`.
+
+### Interrupting Reconnect
+
+- **`disconnect()`** — cancels the backoff timer, resets status to idle. No further attempts.
+- **`connect()`** during reconnect — cancels the timer, starts a fresh attempt from attempt 0.
+- **`dispose()`** — cancels everything. Timer is cleared, signals are aborted, transport is closed.
+
+### disconnected() Guards
+
+`disconnected()` is only meaningful from connected or connecting states. If called while idle or already reconnecting, it's a no-op. This prevents double-reconnect from redundant close events.
+
+---
+
+## Lifecycle
+
+### init / dispose
+
+```typescript
+const channel = new ChatChannel();
+channel.init();      // sets initialized flag, calls onInit()
+// ...use the channel...
+channel.dispose();   // tears down everything
+```
+
+- `init()` is **idempotent** — calling it twice only runs `onInit()` once.
+- `init()` after `dispose()` is a no-op.
+- `dispose()` is **idempotent** — safe to call multiple times.
+
+### onInit / onDispose
+
+Optional lifecycle hooks:
+
+```typescript
+class ChatChannel extends Channel<ChatMessages> {
+  protected onInit() {
+    // Set up external subscriptions, start timers, etc.
+  }
+
+  protected onDispose() {
+    // Final cleanup after everything else is torn down
+  }
+}
+```
+
+### Dispose Sequence
+
+When `dispose()` is called:
+
+1. Sets `disposed = true`
+2. Cancels pending reconnect timer
+3. Aborts the per-connection signal (`connectAbort`)
+4. Aborts the `disposeSignal`
+5. Calls `close()` (errors swallowed)
+6. Runs all registered `addCleanup()` callbacks
+7. Calls `onDispose()`
+8. Clears all status listeners and message handlers
+
+### disposeSignal
+
+Lazy `AbortSignal` that aborts when the channel is disposed. The signal passed to `open()` is composed from both the dispose signal and a per-connection signal, so it aborts on either dispose **or** disconnect.
+
+```typescript
+// In a ViewModel using a channel
+protected onInit() {
+  this.channel.on('message', (msg) => {
+    this.set({ messages: [...this.state.messages, msg] });
+  });
+  this.channel.connect();
+}
+```
+
+---
+
+## Infrastructure Helpers
+
+### addCleanup(fn)
+
+Register a cleanup function that runs on dispose:
+
+```typescript
+protected onInit() {
+  const unsub = externalService.on('event', this.handleEvent);
+  this.addCleanup(unsub);
+}
+```
+
+### subscribeTo(source, listener)
+
+Subscribe to another `Subscribable` with automatic cleanup on dispose:
+
+```typescript
+protected onInit() {
+  this.subscribeTo(someOtherChannel, (status) => {
+    // React to another channel's status changes
+  });
+}
+```
+
+### listenTo(source, event, handler)
+
+Subscribe to a typed event on another Channel or EventBus with automatic cleanup on dispose:
+
+```typescript
+protected onInit() {
+  this.listenTo(this.appBus, 'auth:logout', () => {
+    this.disconnect();
+  });
+}
+```
+
+---
+
+## ViewModel Integration
+
+Channels are typically singletons. ViewModels subscribe to them for status changes and message handling:
+
+```typescript
+class ChatViewModel extends ViewModel<State> {
+  private channel = singleton(ChatChannel);
+
+  protected onInit() {
+    // Auto-tracked: channel status changes invalidate getters
+    this.subscribeTo(this.channel, () => {
+      this.set({ connectionStatus: this.channel.state });
+    });
+
+    // Message handling
+    const unsub = this.channel.on('message', (msg) => {
+      this.set({ messages: [...this.state.messages, msg] });
+    });
+    this.addCleanup(unsub);
+
+    this.channel.connect();
+  }
+
+  get isConnected() {
+    return this.channel.state.connected; // auto-tracked via subscribable detection
+  }
+}
+```
+
+### pipeChannel — Channel-to-Collection Bridge
+
+For the common pattern of piping Channel messages into a Collection, use `pipeChannel`:
+
+```typescript
+class DashboardCardViewModel extends ViewModel {
+  private channel = singleton(DashboardChannel);
+  private collection = singleton(DashboardCollection);
+
+  protected onInit() {
+    this.pipeChannel(this.channel, 'data', this.collection);
+    this.channel.connect();
+  }
+}
+```
+
+This calls `channel.init()` (idempotent), subscribes to the event, and upserts each payload into the collection. Auto-cleanup on dispose and reset. Use `listenTo` directly if you need to transform or filter messages.
+
+### Auto-Tracking
+
+Because Channel implements `Subscribable` (has a `subscribe` method), the ViewModel's getter memoization system auto-detects it. When the channel's status changes:
+
+1. The ViewModel's `_revision` counter increments
+2. Memoized getter caches invalidate
+3. Getters that read `channel.state` recompute on next access
+4. React re-renders via `useSyncExternalStore`
+
+### Singleton Pattern
+
+```typescript
+const ch1 = singleton(ChatChannel);
+const ch2 = singleton(ChatChannel);
+ch1 === ch2; // true — same instance
+
+teardownAll(); // disposes the channel along with all other singletons
+```
+
+---
+
+## Best Practices
+
+**Always listen for abort in `open()`.** The signal passed to `open()` aborts on both disconnect and dispose. Attach a listener to clean up the transport:
+
+```typescript
+signal.addEventListener('abort', () => this.ws?.close());
+```
+
+**Call `disconnected()` from transport close events, not error events.** Let the transport's close handler trigger reconnect. Error events typically precede close — handling both causes double reconnect (which is safely guarded, but unnecessary).
+
+**Don't call `disconnected()` if the signal is aborted.** When the abort signal fires, the framework is intentionally closing the connection (disconnect or dispose). Only call `disconnected()` for unexpected drops:
+
+```typescript
+this.ws.onclose = () => {
+  if (!signal.aborted) this.disconnected();
+};
+```
+
+**Keep `close()` side-effect-free and safe.** It's called during dispose with errors swallowed, and can be called multiple times. Don't throw, and nullify references to prevent double-close issues.
+
+**Use singleton resolution.** Channels represent persistent connections shared across ViewModels. Always resolve via `singleton(MyChannel)` — never `new MyChannel()` in multiple places.
+
+**Override static config instead of overriding `_calculateDelay`.** The static properties (`RECONNECT_BASE`, `RECONNECT_MAX`, `RECONNECT_FACTOR`, `MAX_ATTEMPTS`) cover all tuning needs. Override `_calculateDelay` only if you need a completely custom backoff strategy (e.g., server-sent retry hints).
+
+**Use `listenTo` for `on()` subscriptions in ViewModels.** While `subscribeTo` auto-registers cleanup for state subscriptions, message subscriptions via `channel.on()` need `listenTo` for automatic cleanup:
+
+```typescript
+// Prescribed — auto-cleanup on dispose and reset
+this.listenTo(this.channel, 'message', handler);
+```
+
+> See `BEST_PRACTICES.md` for ViewModel integration patterns and prescribed usage.
+
+## 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 { connect, disconnect } = channel;
+<button onClick={connect}>Connect</button> // point-free works
+```