mvc-kit 2.12.0 → 2.12.2

package/src/Controller.md

@@ -0,0 +1,306 @@
+# Controller
+
+A minimal base class for stateless orchestrators. Controllers coordinate between ViewModels, Models, and Services when a single ViewModel can't do the job alone.
+
+---
+
+## When to Use
+
+Most orchestration fits in a single ViewModel. Use a Controller only when coordinating multiple ViewModels in a single workflow — multi-step checkout, drag-and-drop between lists, complex form wizards.
+
+| Question | Use |
+|---|---|
+| Does the coordination involve UI state, getters, or async tracking? | **ViewModel** |
+| Is there pure cross-cutting coordination with no state of its own? | **Controller** |
+
+If you're reaching for a Controller, first ask whether one ViewModel can own the whole workflow. Usually it can.
+
+---
+
+## What Controller Provides
+
+Controller is deliberately minimal. It provides lifecycle management and subscription utilities — nothing more.
+
+| Feature | Included |
+|---|---|
+| `init()` / `dispose()` lifecycle | Yes |
+| `onInit()` / `onDispose()` hooks | Yes |
+| `disposeSignal` (AbortSignal) | Yes |
+| `subscribeTo(source, listener)` | Yes |
+| `addCleanup(fn)` | Yes |
+| `initialized` / `disposed` flags | Yes |
+| State management | No |
+| Computed getters | No |
+| Async tracking | No |
+| Events / emit | No |
+
+---
+
+## API
+
+### `init(): void | Promise<void>`
+
+Initializes the Controller. Calls `onInit()` if defined. Idempotent — calling it multiple times has no effect. No-op if already disposed.
+
+```typescript
+const controller = new CheckoutController();
+controller.init();
+controller.init(); // no-op
+```
+
+Supports async initialization:
+
+```typescript
+class SetupController extends Controller {
+  protected async onInit() {
+    await someAsyncSetup();
+  }
+}
+
+const controller = new SetupController();
+await controller.init();
+```
+
+### `dispose(): void`
+
+Tears down the Controller. 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
+controller.dispose();
+controller.dispose(); // no-op
+```
+
+### `disposeSignal: AbortSignal`
+
+A lazily-created AbortSignal that aborts when the Controller is disposed. Pass it to `fetch()` or `AbortSignal.any()` to cancel in-flight operations on teardown.
+
+```typescript
+class FetchController extends Controller {
+  async fetchData() {
+    const res = await fetch('/api/data', { 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`.
+
+### `subscribeTo<T>(source: Subscribable<T>, listener): () => void`
+
+Subscribes to any `Subscribable` source (Collection, ViewModel, Channel) and auto-unsubscribes on dispose. Returns an unsubscribe function for manual early cleanup.
+
+```typescript
+class SyncController extends Controller {
+  protected onInit() {
+    this.subscribeTo(this.collection, (items) => {
+      // react to collection changes
+    });
+
+    this.subscribeTo(this.viewModel, (newState, oldState) => {
+      // react to ViewModel state changes
+    });
+  }
+}
+```
+
+### `listenTo(source, event, handler): () => void`
+
+Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose. The event counterpart to `subscribeTo`.
+
+```typescript
+class ChatController extends Controller {
+  protected onInit() {
+    this.listenTo(this.channel, 'message', (msg) => {
+      // coordinate between ViewModels
+    });
+  }
+}
+```
+
+### `addCleanup(fn: () => void): void`
+
+Registers a cleanup function that runs on dispose. Use this for teardown that isn't covered by `subscribeTo` or `listenTo`.
+
+```typescript
+class TimerController extends Controller {
+  protected onInit() {
+    const id = setInterval(() => this.tick(), 1000);
+    this.addCleanup(() => clearInterval(id));
+  }
+}
+```
+
+### `onInit?(): void | Promise<void>` (protected)
+
+Override to run setup logic when `init()` is called. This is where you wire up subscriptions, start timers, or kick off initial coordination.
+
+### `onDispose?(): void` (protected)
+
+Override to run teardown logic when `dispose()` is called. Runs after the signal is aborted and cleanups have fired.
+
+---
+
+## Lifecycle
+
+```
+new Controller()        → 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 Controller stays uninitialized.
+- `dispose()` before `init()` works — the Controller is disposed without ever initializing.
+
+---
+
+## Abstract Class
+
+Controller is `abstract`. You must subclass it:
+
+```typescript
+// Minimal subclass
+class MyController extends Controller {
+  doSomething(): string {
+    return 'done';
+  }
+}
+```
+
+---
+
+## Singleton Usage
+
+Controllers can be registered as singletons when they coordinate app-wide concerns:
+
+```typescript
+import { singleton, teardown, teardownAll } from 'mvc-kit';
+
+const controller = singleton(MyController);
+
+// Same instance on repeated calls
+singleton(MyController) === controller; // true
+
+// Teardown disposes and removes from registry
+teardown(MyController);
+controller.disposed; // true
+```
+
+---
+
+## Example: Coordinating Two ViewModels
+
+A drag-and-drop controller that moves items between two list ViewModels:
+
+```typescript
+class DragDropController extends Controller {
+  private sourceVM: TaskListViewModel;
+  private targetVM: TaskListViewModel;
+
+  constructor(source: TaskListViewModel, target: TaskListViewModel) {
+    super();
+    this.sourceVM = source;
+    this.targetVM = target;
+  }
+
+  moveItem(itemId: string) {
+    const item = this.sourceVM.state.items.find(i => i.id === itemId);
+    if (!item) return;
+    this.sourceVM.removeItem(itemId);
+    this.targetVM.addItem(item);
+  }
+}
+```
+
+## Example: Subscribing to Multiple Sources
+
+```typescript
+class SyncController extends Controller {
+  private usersCollection = singleton(UsersCollection);
+  private locationsCollection = singleton(LocationsCollection);
+
+  protected onInit() {
+    this.subscribeTo(this.usersCollection, () => {
+      this.reconcile();
+    });
+
+    this.subscribeTo(this.locationsCollection, () => {
+      this.reconcile();
+    });
+  }
+
+  private reconcile() {
+    // Cross-cutting logic when either collection changes
+  }
+}
+```
+
+## Example: Async Initialization with Cancellation
+
+```typescript
+class BootstrapController extends Controller {
+  private authService = singleton(AuthService);
+  private configService = singleton(ConfigService);
+
+  protected async onInit() {
+    const [user, config] = await Promise.all([
+      this.authService.getCurrentUser(this.disposeSignal),
+      this.configService.load(this.disposeSignal),
+    ]);
+    // coordinate initial app state
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Reach for ViewModel first.** Controller is a last resort for coordination that doesn't fit a single ViewModel.
+2. **Keep it stateless.** Controllers don't have `set()` or state. If you need reactive state, use a ViewModel.
+3. **Use `subscribeTo` for subscriptions.** It auto-cleans up on dispose — no manual bookkeeping.
+4. **Pass `disposeSignal` to async calls.** Ensures in-flight operations cancel on teardown.
+5. **Keep Controllers small.** If a Controller grows large, the workflow it manages should probably be restructured into better-scoped ViewModels.
+
+## Anti-Patterns
+
+```typescript
+// Don't store reactive state on a Controller
+class BadController extends Controller {
+  items: Item[] = []; // not reactive — use a ViewModel or Collection
+}
+
+// Don't use Controller when a ViewModel works
+class OverEngineered extends Controller {
+  // If this needs state, getters, or async tracking — it's a ViewModel
+}
+
+// Don't forget to clean up non-subscription resources
+class LeakyController extends Controller {
+  protected onInit() {
+    setInterval(() => this.tick(), 1000); // leaked — use addCleanup
+  }
+}
+```
+
+## 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 { doAction } = controller;
+<button onClick={doAction}>Run</button> // point-free works
+```

package/src/Controller.test.ts

@@ -0,0 +1,380 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Controller } from './Controller';
+import { ViewModel } from './ViewModel';
+import { Collection } from './Collection';
+import { EventBus } from './EventBus';
+import { singleton, teardown, teardownAll } from './singleton';
+
+class TestController extends Controller {
+  onDisposeCalled = false;
+  actionCalled = false;
+
+  protected onDispose(): void {
+    this.onDisposeCalled = true;
+  }
+
+  doAction(): void {
+    this.actionCalled = true;
+  }
+}
+
+class SimpleController extends Controller {
+  doSomething(): string {
+    return 'done';
+  }
+}
+
+describe('Controller', () => {
+  describe('initialization', () => {
+    it('starts not disposed', () => {
+      const controller = new TestController();
+      expect(controller.disposed).toBe(false);
+    });
+  });
+
+  describe('dispose', () => {
+    it('sets disposed to true', () => {
+      const controller = new TestController();
+      controller.dispose();
+      expect(controller.disposed).toBe(true);
+    });
+
+    it('calls onDispose hook', () => {
+      const controller = new TestController();
+      expect(controller.onDisposeCalled).toBe(false);
+      controller.dispose();
+      expect(controller.onDisposeCalled).toBe(true);
+    });
+
+    it('is idempotent', () => {
+      let callCount = 0;
+      class CountingController extends Controller {
+        protected onDispose(): void {
+          callCount++;
+        }
+      }
+      const controller = new CountingController();
+      controller.dispose();
+      controller.dispose();
+      controller.dispose();
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('init', () => {
+    it('starts not initialized', () => {
+      const controller = new TestController();
+      expect(controller.initialized).toBe(false);
+    });
+
+    it('sets initialized to true after init()', () => {
+      const controller = new TestController();
+      controller.init();
+      expect(controller.initialized).toBe(true);
+    });
+
+    it('calls onInit hook', () => {
+      let called = false;
+      class InitController extends Controller {
+        protected onInit() {
+          called = true;
+        }
+      }
+      const controller = new InitController();
+      controller.init();
+      expect(called).toBe(true);
+    });
+
+    it('is idempotent — onInit called only once', () => {
+      let callCount = 0;
+      class CountingController extends Controller {
+        protected onInit() {
+          callCount++;
+        }
+      }
+      const controller = new CountingController();
+      controller.init();
+      controller.init();
+      controller.init();
+      expect(callCount).toBe(1);
+    });
+
+    it('supports async onInit', async () => {
+      let resolved = false;
+      class AsyncController extends Controller {
+        protected async onInit() {
+          await Promise.resolve();
+          resolved = true;
+        }
+      }
+      const controller = new AsyncController();
+      await controller.init();
+      expect(resolved).toBe(true);
+    });
+
+    it('is a no-op after dispose', () => {
+      let called = false;
+      class InitController extends Controller {
+        protected onInit() {
+          called = true;
+        }
+      }
+      const controller = new InitController();
+      controller.dispose();
+      controller.init();
+      expect(called).toBe(false);
+      expect(controller.initialized).toBe(false);
+    });
+  });
+
+  describe('methods', () => {
+    it('can execute actions', () => {
+      const controller = new TestController();
+      controller.doAction();
+      expect(controller.actionCalled).toBe(true);
+    });
+  });
+
+  describe('singleton integration', () => {
+    beforeEach(() => {
+      teardownAll();
+    });
+
+    it('can be used with singleton registry', () => {
+      const c1 = singleton(SimpleController);
+      const c2 = singleton(SimpleController);
+      expect(c1).toBe(c2);
+    });
+
+    it('can be torn down', () => {
+      const controller = singleton(SimpleController);
+      teardown(SimpleController);
+      expect(controller.disposed).toBe(true);
+    });
+  });
+
+  describe('signal and addCleanup', () => {
+    it('signal returns an AbortSignal', () => {
+      const controller = new TestController();
+      expect(controller.disposeSignal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('returns the same signal on multiple accesses', () => {
+      const controller = new TestController();
+      const s1 = controller.disposeSignal;
+      const s2 = controller.disposeSignal;
+      expect(s1).toBe(s2);
+    });
+
+    it('signal is not aborted before dispose', () => {
+      const controller = new TestController();
+      expect(controller.disposeSignal.aborted).toBe(false);
+    });
+
+    it('signal is aborted after dispose', () => {
+      const controller = new TestController();
+      const signal = controller.disposeSignal;
+      controller.dispose();
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('signal is aborted before onDispose runs', () => {
+      let wasAbortedDuringDispose = false;
+      class CheckController extends Controller {
+        protected onDispose(): void {
+          wasAbortedDuringDispose = this.disposeSignal.aborted;
+        }
+      }
+      const controller = new CheckController();
+      controller.disposeSignal; // force lazy creation
+      controller.dispose();
+      expect(wasAbortedDuringDispose).toBe(true);
+    });
+
+    it('addCleanup fires on dispose', () => {
+      let cleaned = false;
+      class CleanupController extends Controller {
+        setup() {
+          this.addCleanup(() => { cleaned = true; });
+        }
+      }
+      const controller = new CleanupController();
+      controller.setup();
+      expect(cleaned).toBe(false);
+      controller.dispose();
+      expect(cleaned).toBe(true);
+    });
+
+    it('dispose works without accessing signal (lazy, zero cost)', () => {
+      const controller = new TestController();
+      controller.dispose();
+      expect(controller.disposed).toBe(true);
+    });
+  });
+
+  describe('subscribeTo', () => {
+    interface Item { id: string; value: number }
+
+    it('listener is called when source changes', () => {
+      const collection = new Collection<Item>();
+
+      class SubController extends Controller {
+        values: number[] = [];
+        setup(col: Collection<Item>) {
+          this.subscribeTo(col, (items) => {
+            this.values = items.map(i => i.value);
+          });
+        }
+      }
+
+      const ctrl = new SubController();
+      ctrl.setup(collection);
+
+      collection.add({ id: '1', value: 42 });
+      expect(ctrl.values).toEqual([42]);
+    });
+
+    it('auto-unsubscribes on dispose', () => {
+      const collection = new Collection<Item>();
+      const listener = vi.fn();
+
+      class SubController extends Controller {
+        setup(col: Collection<Item>) {
+          this.subscribeTo(col, listener);
+        }
+      }
+
+      const ctrl = new SubController();
+      ctrl.setup(collection);
+
+      collection.add({ id: '1', value: 1 });
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      ctrl.dispose();
+
+      collection.add({ id: '2', value: 2 });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns unsubscribe function for manual cleanup', () => {
+      const collection = new Collection<Item>();
+      const listener = vi.fn();
+
+      class SubController extends Controller {
+        setup(col: Collection<Item>): () => void {
+          return this.subscribeTo(col, listener);
+        }
+      }
+
+      const ctrl = new SubController();
+      const unsub = ctrl.setup(collection);
+
+      collection.add({ id: '1', value: 1 });
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      unsub();
+
+      collection.add({ id: '2', value: 2 });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('works with a ViewModel as source', () => {
+      interface CountState { count: number }
+      class CountVM extends ViewModel<CountState> {
+        increment() { this.set({ count: this.state.count + 1 }); }
+      }
+
+      const vm = new CountVM({ count: 0 });
+      const listener = vi.fn();
+
+      class SubController extends Controller {
+        setup(src: CountVM) {
+          this.subscribeTo(src, listener);
+        }
+      }
+
+      const ctrl = new SubController();
+      ctrl.setup(vm);
+
+      vm.increment();
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(listener).toHaveBeenCalledWith({ count: 1 }, { count: 0 });
+    });
+  });
+
+  describe('listenTo', () => {
+    interface TestEvents {
+      alert: { message: string };
+    }
+
+    it('handler is called when event is emitted', () => {
+      const bus = new EventBus<TestEvents>();
+      const alerts: TestEvents['alert'][] = [];
+
+      class ListenCtrl extends Controller {
+        setup(b: EventBus<TestEvents>) {
+          this.listenTo(b, 'alert', (a) => alerts.push(a));
+        }
+      }
+
+      const ctrl = new ListenCtrl();
+      ctrl.setup(bus);
+
+      bus.emit('alert', { message: 'fire' });
+      expect(alerts).toEqual([{ message: 'fire' }]);
+    });
+
+    it('auto-unsubscribes on dispose', () => {
+      const bus = new EventBus<TestEvents>();
+      const handler = vi.fn();
+
+      class ListenCtrl extends Controller {
+        setup(b: EventBus<TestEvents>) {
+          this.listenTo(b, 'alert', handler);
+        }
+      }
+
+      const ctrl = new ListenCtrl();
+      ctrl.setup(bus);
+
+      bus.emit('alert', { message: 'one' });
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      ctrl.dispose();
+
+      bus.emit('alert', { message: 'two' });
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns unsubscribe function for manual cleanup', () => {
+      const bus = new EventBus<TestEvents>();
+      const handler = vi.fn();
+
+      class ListenCtrl extends Controller {
+        setup(b: EventBus<TestEvents>): () => void {
+          return this.listenTo(b, 'alert', handler);
+        }
+      }
+
+      const ctrl = new ListenCtrl();
+      const unsub = ctrl.setup(bus);
+
+      bus.emit('alert', { message: 'one' });
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsub();
+
+      bus.emit('alert', { message: 'two' });
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('method binding', () => {
+    it('subclass methods work point-free', () => {
+      const ctrl = new TestController();
+      const { doAction } = ctrl;
+      doAction();
+      expect(ctrl.actionCalled).toBe(true);
+    });
+  });
+});