mvc-kit 2.12.0 → 2.12.2

package/src/Controller.ts

@@ -0,0 +1,90 @@
+import type { Disposable, Subscribable, Listener, EventPayload } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+
+const PROTECTED_KEYS = new Set(['addCleanup', 'subscribeTo', 'listenTo']);
+
+/**
+ * Base class for stateless orchestrators.
+ * Controllers coordinate between ViewModels, Models, and Services.
+ */
+export abstract class Controller implements Disposable {
+  private _disposed = false;
+  private _initialized = false;
+  private _abortController: AbortController | null = null;
+  private _cleanups: (() => void)[] | null = null;
+
+  constructor() {
+    bindPublicMethods(this, Object.prototype, PROTECTED_KEYS);
+  }
+
+  /** Whether this instance has been disposed. */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** Whether init() has been called. */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /** Initializes the instance. Called automatically by React hooks after mount. */
+  init(): void | Promise<void> {
+    if (this._initialized || this._disposed) return;
+    this._initialized = true;
+    return this.onInit?.();
+  }
+
+  /** Tears down the instance, releasing all subscriptions and resources. */
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+
+    this._disposed = true;
+    this._abortController?.abort();
+    if (this._cleanups) {
+      for (const fn of this._cleanups) fn();
+      this._cleanups = null;
+    }
+    this.onDispose?.();
+  }
+
+  /** Registers a cleanup function to be called on dispose. @protected */
+  protected addCleanup(fn: () => void): void {
+    if (!this._cleanups) {
+      this._cleanups = [];
+    }
+    this._cleanups.push(fn);
+  }
+
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
+  protected subscribeTo<T>(source: Subscribable<T>, listener: Listener<T>): () => void {
+    const unsubscribe = source.subscribe(listener);
+    this.addCleanup(unsubscribe);
+    return unsubscribe;
+  }
+
+  /** Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose. @protected */
+  protected listenTo<K extends string, S extends { on(event: K, handler: (payload: any) => void): () => void }>(
+    source: S,
+    event: K,
+    handler: (payload: EventPayload<S, K>) => void,
+  ): () => void {
+    const unsubscribe = source.on(event, handler);
+    this.addCleanup(unsubscribe);
+    return unsubscribe;
+  }
+
+  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
+  protected onInit?(): void | Promise<void>;
+  /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+}

package/src/EventBus.md

@@ -0,0 +1,308 @@
+# EventBus
+
+Typed pub/sub event bus for broadcasting one-shot signals across decoupled parts of the application.
+
+---
+
+## When to Use
+
+Use EventBus for **intent-based communication** between parts of the app that have no direct reference to each other: toast notifications, logout broadcasts, cross-route coordination. If you need to react to **data changes**, subscribe to a Collection instead.
+
+| Scenario | Use |
+|---|---|
+| "Users were loaded on another route" | EventBus |
+| "The user list changed" | Collection subscription |
+| "User logged out globally" | EventBus |
+| "Show a toast after save" | ViewModel events (built-in) |
+
+---
+
+## Defining an Event Map
+
+Events are defined as a `Record<string, any>` where keys are event names and values are payload types. Use `undefined` for events with no payload.
+
+```typescript
+interface AppEvents {
+  'auth:logout': undefined;
+  'users:loaded': undefined;
+  'item:created': { id: string; name: string };
+}
+```
+
+## Creating an EventBus
+
+### App-Level (Singleton)
+
+Subclass for singleton identity, then resolve with `singleton()`:
+
+```typescript
+import { EventBus } from 'mvc-kit';
+
+export class AppEventBus extends EventBus<AppEvents> {}
+
+// In a ViewModel:
+private bus = singleton(AppEventBus);
+```
+
+### Standalone
+
+```typescript
+const bus = new EventBus<AppEvents>();
+```
+
+---
+
+## API
+
+### `on(event, handler): () => void`
+
+Subscribe to an event. Returns an unsubscribe function.
+
+```typescript
+const unsub = bus.on('item:created', ({ id, name }) => {
+  console.log(`Created ${name} (${id})`);
+});
+
+// Later:
+unsub();
+```
+
+Multiple handlers can subscribe to the same event. Each receives the payload independently. Handlers are called synchronously in registration order.
+
+Calling `on()` after dispose returns a no-op function (does not throw).
+
+### `once(event, handler): () => void`
+
+Subscribe to an event for a single invocation. The handler auto-unsubscribes after the first emit. Returns an unsubscribe function for early cancellation.
+
+```typescript
+bus.once('auth:logout', () => {
+  redirectToLogin();
+});
+```
+
+Can be manually unsubscribed before the event fires:
+
+```typescript
+const unsub = bus.once('auth:logout', handler);
+unsub(); // handler will never be called
+```
+
+### `emit(event, payload): void`
+
+Emit an event to all current subscribers. Pass `undefined` for events with no payload.
+
+```typescript
+bus.emit('item:created', { id: '42', name: 'Widget' });
+bus.emit('auth:logout', undefined);
+```
+
+Emitting with no subscribers is a safe no-op. Emitting after dispose throws:
+
+```
+Error: Cannot emit on disposed EventBus
+```
+
+### `dispose(): void`
+
+Tears down the bus: aborts `disposeSignal`, runs `addCleanup` callbacks, calls `onDispose()`, clears all handlers. Idempotent — subsequent calls are no-ops.
+
+### `disposed: boolean`
+
+Read-only flag. `true` after `dispose()` has been called.
+
+### `disposeSignal: AbortSignal`
+
+Lazily-created abort signal that fires on dispose. Use it to cancel async work tied to the bus lifecycle.
+
+```typescript
+class MyBus extends EventBus<AppEvents> {
+  startPolling() {
+    const signal = this.disposeSignal;
+    // signal aborts when bus is disposed
+  }
+}
+```
+
+The signal is created on first access — zero cost if never used.
+
+---
+
+## Lifecycle Hooks (Subclass Only)
+
+### `onDispose(): void` *(protected, optional)*
+
+Override to run custom teardown logic. Called once during dispose, after the abort signal fires but before handlers are cleared.
+
+```typescript
+class AppEventBus extends EventBus<AppEvents> {
+  protected onDispose() {
+    console.log('App event bus disposed');
+  }
+}
+```
+
+### `addCleanup(fn): void` *(protected)*
+
+Register a cleanup function that runs on dispose, before `onDispose()`. Useful for tearing down external subscriptions set up by the subclass.
+
+```typescript
+class AppEventBus extends EventBus<AppEvents> {
+  setup() {
+    const unsub = externalSource.subscribe(data => {
+      this.emit('item:created', data);
+    });
+    this.addCleanup(unsub);
+  }
+}
+```
+
+---
+
+## Dispose Order
+
+When `dispose()` is called:
+
+1. `_disposed` set to `true`
+2. `disposeSignal` aborted (if it was accessed)
+3. `addCleanup` callbacks run (in registration order)
+4. `onDispose()` called (if overridden)
+5. All handlers cleared
+
+---
+
+## Type Safety
+
+Event names and payloads are fully type-checked at compile time. Invalid event names are rejected by TypeScript:
+
+```typescript
+const bus = new EventBus<AppEvents>();
+
+bus.on('auth:logout', () => {});          // OK
+bus.emit('item:created', { id: '1', name: 'X' }); // OK
+
+bus.on('badEvent', () => {});             // TS error
+bus.emit('auth:logout', { extra: true }); // TS error
+```
+
+The `_types` phantom brand ensures correct generic inference when the bus is passed through helper functions like `useEvent()`.
+
+---
+
+## React Integration
+
+### `useEvent(source, event, handler)`
+
+Subscribe to an event with automatic cleanup on unmount. Accepts an `EventBus` directly or any object with an `events` property (e.g. a ViewModel).
+
+```tsx
+import { useEvent } from 'mvc-kit/react';
+
+// With a standalone EventBus
+function Notifications({ bus }: { bus: EventBus<AppEvents> }) {
+  useEvent(bus, 'item:created', ({ name }) => {
+    toast.success(`${name} created`);
+  });
+  return null;
+}
+
+// With a ViewModel (reads vm.events internally)
+function ItemPage() {
+  const [state, vm] = useLocal(ItemViewModel, { /* ... */ });
+
+  useEvent(vm, 'saved', ({ id }) => {
+    toast.success(`Saved ${id}`);
+    navigate(`/items/${id}`);
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+The handler ref is stable across re-renders — no stale closure issues, no need for `useCallback`.
+
+### `useEmit(bus)`
+
+Returns a stable `emit` function bound to the bus. Useful in components that only emit (no subscription).
+
+```tsx
+import { useEmit } from 'mvc-kit/react';
+
+function ActionBar({ bus }: { bus: EventBus<AppEvents> }) {
+  const emit = useEmit(bus);
+
+  return (
+    <button onClick={() => emit('auth:logout', undefined)}>
+      Log Out
+    </button>
+  );
+}
+```
+
+---
+
+## ViewModel Built-in Events
+
+ViewModels have an internal EventBus exposed via the `events` getter. Rather than creating a separate EventBus, use the second generic parameter:
+
+```typescript
+interface Events {
+  saved: { id: string };
+  validationFailed: undefined;
+}
+
+class ItemViewModel extends ViewModel<State, Events> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id }); // protected — only the VM can emit
+  }
+}
+```
+
+Key differences from a standalone EventBus:
+
+- The internal bus is **lazy** — created on first `emit()` or `events` access.
+- `emit()` is **protected** — components cannot emit, only subscribe.
+- The bus **auto-disposes** with the ViewModel.
+- `emit()` is silently skipped (not thrown) if the ViewModel or bus is disposed — safe during async cleanup callbacks.
+
+Components subscribe with `useEvent(vm, ...)`:
+
+```tsx
+useEvent(vm, 'saved', ({ id }) => navigate(`/items/${id}`));
+```
+
+---
+
+## Best Practices
+
+**Keep the event map small.** If it grows past 10-15 events, concerns are likely entangled and should be decoupled differently.
+
+**EventBus carries intent, Collections carry state.** Don't use EventBus as a proxy for data changes — subscribe to the Collection directly.
+
+**Prefer ViewModel events for component-scoped signals.** Only use a standalone singleton EventBus for cross-route or app-wide broadcasts.
+
+**Use `listenTo` in ViewModels and Controllers.** When subscribing to an EventBus from a lifecycle-managed class, use `this.listenTo(bus, 'event', handler)` instead of `bus.on('event', handler)` — it auto-cleans up on dispose (and reset, for ViewModels).
+
+**EventBus does NOT implement `Subscribable`.** It won't be auto-tracked by ViewModel's subscribable detection. This is by design — EventBus is for discrete events, not continuous state.
+
+**Use `undefined` (not `void`) for empty payloads.** The event map values are payload types passed to handlers.
+
+```typescript
+// In the type definition
+interface Events {
+  logout: undefined;  // not void
+}
+
+// When emitting
+bus.emit('logout', undefined);
+```
+
+## 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 { emit, on } = bus;
+on("userLoggedIn", handler); // point-free works
+```

package/src/EventBus.test.ts

@@ -0,0 +1,295 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EventBus } from './EventBus';
+import { singleton, teardownAll } from './singleton';
+import type { useEvent } from './react/use-event-bus';
+
+interface AppEvents {
+  userLoggedIn: { userId: string };
+  userLoggedOut: undefined;
+  itemAdded: { itemId: number; name: string };
+}
+
+describe('EventBus', () => {
+  describe('initialization', () => {
+    it('starts not disposed', () => {
+      const bus = new EventBus<AppEvents>();
+      expect(bus.disposed).toBe(false);
+    });
+  });
+
+  describe('on() and emit()', () => {
+    it('notifies handler when event is emitted', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      bus.on('userLoggedIn', handler);
+      bus.emit('userLoggedIn', { userId: '123' });
+
+      expect(handler).toHaveBeenCalledWith({ userId: '123' });
+    });
+
+    it('notifies multiple handlers', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      bus.on('userLoggedIn', handler1);
+      bus.on('userLoggedIn', handler2);
+      bus.emit('userLoggedIn', { userId: 'abc' });
+
+      expect(handler1).toHaveBeenCalledWith({ userId: 'abc' });
+      expect(handler2).toHaveBeenCalledWith({ userId: 'abc' });
+    });
+
+    it('does not notify handlers for other events', () => {
+      const bus = new EventBus<AppEvents>();
+      const loginHandler = vi.fn();
+      const logoutHandler = vi.fn();
+
+      bus.on('userLoggedIn', loginHandler);
+      bus.on('userLoggedOut', logoutHandler);
+      bus.emit('userLoggedIn', { userId: '123' });
+
+      expect(loginHandler).toHaveBeenCalled();
+      expect(logoutHandler).not.toHaveBeenCalled();
+    });
+
+    it('unsubscribe function works', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      const unsubscribe = bus.on('userLoggedIn', handler);
+      bus.emit('userLoggedIn', { userId: '1' });
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      bus.emit('userLoggedIn', { userId: '2' });
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it('handles emit with no subscribers', () => {
+      const bus = new EventBus<AppEvents>();
+      expect(() => bus.emit('userLoggedIn', { userId: '123' })).not.toThrow();
+    });
+  });
+
+  describe('once()', () => {
+    it('only notifies handler once', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      bus.once('userLoggedIn', handler);
+      bus.emit('userLoggedIn', { userId: '1' });
+      bus.emit('userLoggedIn', { userId: '2' });
+      bus.emit('userLoggedIn', { userId: '3' });
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith({ userId: '1' });
+    });
+
+    it('can be manually unsubscribed before event', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      const unsubscribe = bus.once('userLoggedIn', handler);
+      unsubscribe();
+      bus.emit('userLoggedIn', { userId: '1' });
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('dispose', () => {
+    it('sets disposed to true', () => {
+      const bus = new EventBus<AppEvents>();
+      bus.dispose();
+      expect(bus.disposed).toBe(true);
+    });
+
+    it('clears all handlers', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+      bus.on('userLoggedIn', handler);
+      bus.dispose();
+
+      // Can't emit after dispose, but handlers are cleared
+      expect(bus.disposed).toBe(true);
+    });
+
+    it('is idempotent', () => {
+      const bus = new EventBus<AppEvents>();
+      bus.dispose();
+      bus.dispose();
+      expect(bus.disposed).toBe(true);
+    });
+
+    it('throws on emit after dispose', () => {
+      const bus = new EventBus<AppEvents>();
+      bus.dispose();
+      expect(() => bus.emit('userLoggedIn', { userId: '123' })).toThrow(
+        'Cannot emit on disposed EventBus'
+      );
+    });
+
+    it('returns no-op on subscribe after dispose', () => {
+      const bus = new EventBus<AppEvents>();
+      bus.dispose();
+      const unsub = bus.on('userLoggedIn', () => {});
+      expect(typeof unsub).toBe('function');
+      expect(() => unsub()).not.toThrow();
+    });
+  });
+
+  describe('type safety', () => {
+    it('handles undefined payloads', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      bus.on('userLoggedOut', handler);
+      bus.emit('userLoggedOut', undefined);
+
+      expect(handler).toHaveBeenCalledWith(undefined);
+    });
+
+    it('handles complex payloads', () => {
+      const bus = new EventBus<AppEvents>();
+      const handler = vi.fn();
+
+      bus.on('itemAdded', handler);
+      bus.emit('itemAdded', { itemId: 42, name: 'Widget' });
+
+      expect(handler).toHaveBeenCalledWith({ itemId: 42, name: 'Widget' });
+    });
+  });
+
+  describe('singleton integration', () => {
+    beforeEach(() => {
+      teardownAll();
+    });
+
+    it('can be used with singleton registry', () => {
+      class AppEventBus extends EventBus<AppEvents> {}
+
+      const bus1 = singleton(AppEventBus);
+      const bus2 = singleton(AppEventBus);
+      expect(bus1).toBe(bus2);
+    });
+  });
+
+  describe('type-level: invalid event names are rejected', () => {
+    it('rejects invalid keys on direct bus.on()', () => {
+      const bus = new EventBus<AppEvents>();
+
+      // @ts-expect-error - 'badEvent' is not a key of AppEvents
+      bus.on('badEvent', () => {});
+    });
+
+    it('rejects invalid keys through useEvent with subclass', () => {
+      class MyBus extends EventBus<AppEvents> {}
+      const bus = new MyBus();
+
+      // Compile-time only — runtime call is a no-op
+      const _useEvent = (() => {}) as unknown as typeof useEvent;
+      // @ts-expect-error - 'badEvent' is not a key of AppEvents
+      _useEvent(bus, 'badEvent', () => {});
+    });
+  });
+
+  describe('signal and addCleanup', () => {
+    it('signal returns an AbortSignal', () => {
+      const bus = new EventBus<AppEvents>();
+      expect(bus.disposeSignal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('returns the same signal on multiple accesses', () => {
+      const bus = new EventBus<AppEvents>();
+      const s1 = bus.disposeSignal;
+      const s2 = bus.disposeSignal;
+      expect(s1).toBe(s2);
+    });
+
+    it('signal is not aborted before dispose', () => {
+      const bus = new EventBus<AppEvents>();
+      expect(bus.disposeSignal.aborted).toBe(false);
+    });
+
+    it('signal is aborted after dispose', () => {
+      const bus = new EventBus<AppEvents>();
+      const signal = bus.disposeSignal;
+      bus.dispose();
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('signal is aborted before onDispose runs', () => {
+      let wasAbortedDuringDispose = false;
+      class CheckBus extends EventBus<AppEvents> {
+        protected onDispose(): void {
+          wasAbortedDuringDispose = this.disposeSignal.aborted;
+        }
+      }
+      const bus = new CheckBus();
+      bus.disposeSignal; // force lazy creation
+      bus.dispose();
+      expect(wasAbortedDuringDispose).toBe(true);
+    });
+
+    it('addCleanup fires on dispose', () => {
+      let cleaned = false;
+      class CleanupBus extends EventBus<AppEvents> {
+        setup() {
+          this.addCleanup(() => { cleaned = true; });
+        }
+      }
+      const bus = new CleanupBus();
+      bus.setup();
+      expect(cleaned).toBe(false);
+      bus.dispose();
+      expect(cleaned).toBe(true);
+    });
+
+    it('dispose works without accessing signal (lazy, zero cost)', () => {
+      const bus = new EventBus<AppEvents>();
+      bus.dispose();
+      expect(bus.disposed).toBe(true);
+    });
+  });
+
+  describe('onDispose hook', () => {
+    it('calls onDispose on dispose (bug fix)', () => {
+      let called = false;
+      class DisposeBus extends EventBus<AppEvents> {
+        protected onDispose(): void {
+          called = true;
+        }
+      }
+      const bus = new DisposeBus();
+      bus.dispose();
+      expect(called).toBe(true);
+    });
+
+    it('onDispose called only once even with multiple dispose calls', () => {
+      let callCount = 0;
+      class CountingBus extends EventBus<AppEvents> {
+        protected onDispose(): void {
+          callCount++;
+        }
+      }
+      const bus = new CountingBus();
+      bus.dispose();
+      bus.dispose();
+      bus.dispose();
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const bus = new EventBus<AppEvents>();
+      const { on, emit } = bus;
+      const handler = vi.fn();
+      on('userLoggedIn', handler);
+      emit('userLoggedIn', { userId: '123' });
+      expect(handler).toHaveBeenCalledWith({ userId: '123' });
+    });
+  });
+});