/** * vapor-chamber - fast lane. * * A minimal-allocation dispatch path for real-real-hot loops. NOT a * general-purpose command bus - it deliberately strips every feature that * costs per-call CPU or memory. * * Use when: * - Per-frame game tick * - Trading tick data (1k-100k+ msg/sec) * - Audio buffer sample handling * - Scroll / mousemove / pointer sampling * - Physics or simulation step * * Do NOT use for general app dispatch (cart, form, navigation, analytics). * Use `createCommandBus()` for those - its ergonomics are correct for * those use cases. The fast lane intentionally drops: * - Command envelope allocation (handler receives `data` directly) * - CommandResult allocation (handler returns whatever) * - Plugin chain, before/after hooks * - Wildcard listeners * - Schema validation, batch, request/response, AbortController * - meta / id / correlation / causation tracing * - Auto-cleanup hooks (no Vue scope integration) * * If you need any of the above on a per-call basis, use the regular bus. * * @example Single-handler hot dispatch * const lane = createFastLane(); * const onTick = lane.compile('tick', (dt: number) => physicsStep(dt)); * onTick(deltaSeconds); // pure function call, no envelope * * @example Multi-subscriber pub/sub * lane.on('frame', (dt) => animate(dt)); * lane.on('frame', (dt) => render(dt)); * lane.emit('frame', dt); */ export type FastDispatcher = (data: T) => R; export type FastListener = (data: T) => void; /** A live-mode subscription: `off` is set when it is unsubscribed. */ type LiveEntry = { fn: FastListener; off: boolean }; export type FastLane = { /** * Bind a handler to an action and return a pre-compiled dispatcher. * The returned callable invokes the handler with no envelope, no * result wrapping, no plugin chain. * * Calling `compile` twice for the same action overwrites the binding; * the previously-returned dispatcher will route to the new handler on * its next invocation (closures share the same lookup). */ compile(action: string, handler: (data: T) => R): FastDispatcher; /** Remove an action's handler and any subscribers. */ remove(action: string): void; /** * Subscribe to multi-listener fan-out for an action. Listeners run in * registration order via a tight indexed loop. */ on(action: string, listener: FastListener): () => void; /** * Fan out an event to all subscribers. No envelope allocation; listeners * receive `data` directly. */ emit(action: string, data: T): void; /** Diagnostic: list the actions with a `compile()`d handler (not those with only subscribers). */ registeredActions(): string[]; /** Reset all bindings. */ clear(): void; }; export type FastLaneOptions = { /** * What a mid-emit unsubscribe means for the CURRENT emit. Chosen once at * factory time - the emit/unsub closures are built per mode, so the hot * path carries zero mode-branching. * * - `'live'` (default) - matches the main bus: an emit calls the listeners * that existed when it started; one removed during it (by itself or a * peer) does NOT run in that emit, and one added during it runs from the * next. Costs one `off` read per listener call. * - `'snapshot'` - the emit fans out to the subscriber list as it was * when the emit started; a listener removed mid-emit still runs once. * Unsubscribe replaces the bucket array instead of splicing it (the * same copy-on-write nanoevents uses), so the emit loop is one call * per slot with no guards. Allocation moves to the cold unsub path; * the hot path stays allocation-free either way. * * Opt into `'snapshot'` only when a measured fan-out hot loop says so - * see docs/performance.md Tuning. */ removal?: 'live' | 'snapshot'; /** * Where a listener's throw goes, with the action it was emitted on. Given, * the throw is passed here and the emit goes on to the next listener, the * rule a bus listener follows. Without it a throw stops the fan-out and * reaches the caller of `emit`. Chosen once at factory time, like * `removal`. tests/store-one-watcher.test.ts. */ onError?: (error: unknown, action: string) => void; }; export function createFastLane(options: FastLaneOptions = {}): FastLane { const snapshot = options.removal === 'snapshot'; // Two parallel maps: one for compile()-style single dispatch, one for // emit()-style multi-listener fan-out. Kept separate so compile()'s // returned closure can reference a single function via Map lookup, not // an array iteration. const handlers = new Map any>(); // Snapshot mode keeps the listeners themselves; live mode keeps LiveEntry // records, whose `off` an emit already walking them reads. const listeners = new Map | LiveEntry>>(); // Snapshot mode: an unsubscribe reaches only the registration it came from. // It finds its listener by function, so one kept from before remove()/clear() // removed a later registration of the same function, and one call removed // every copy. `epochs` counts remove()s per action and `clears` the clear()s // since; an unsubscribe from an earlier one does nothing. const epochs = new Map(); let clears = 0; function compile(action: string, handler: (data: T) => R): FastDispatcher { handlers.set(action, handler as any); // The dispatcher closes over `handlers` and `action`, not over `handler` // directly - so re-compiling the same action re-routes the existing // dispatcher to the new handler without forcing callers to re-acquire // the dispatcher. Tiny indirection: one Map.get + one call per dispatch. return ((data: T): R => { const h = handlers.get(action); return h !== undefined ? (h(data) as R) : (undefined as unknown as R); }); } /** Live mode: mark a bucket's entries off, so an emit walking it stops calling them. */ function markOff(bucket: Array | LiveEntry> | undefined): void { if (!snapshot && bucket !== undefined) for (const e of bucket) (e as LiveEntry).off = true; } function remove(action: string): void { if (snapshot) epochs.set(action, (epochs.get(action) ?? 0) + 1); handlers.delete(action); markOff(listeners.get(action)); listeners.delete(action); } function on(action: string, listener: FastListener): () => void { let bucket = listeners.get(action); if (bucket === undefined) { bucket = []; listeners.set(action, bucket); } // Both modes unsubscribe copy-on-write: replace the array, never splice // it, so an emit that started earlier keeps walking the array it // captured, to the length it started with. Allocation here is fine: // unsubscribe is the cold path. Live mode also marks the entry off, so // that emit does not call it. if (snapshot) { bucket.push(listener); const epoch = epochs.get(action) ?? 0; const cleared = clears; let done = false; return () => { if (done) return; done = true; if (cleared !== clears || (epochs.get(action) ?? 0) !== epoch) return; // Present: in the same epoch every live unsubscribe still has its // registration in the bucket (each removes one), as in live mode. const b = listeners.get(action)!; if (b.length === 1) { listeners.delete(action); return; } const at = b.indexOf(listener); const next = b.slice(); next.splice(at, 1); listeners.set(action, next); }; } const entry: LiveEntry = { fn: listener, off: false }; bucket.push(entry); return () => { if (entry.off) return; entry.off = true; // Present: remove() and clear() mark their entries off before dropping a bucket. const next = listeners.get(action)!.filter((e) => e !== entry); if (next.length === 0) listeners.delete(action); else listeners.set(action, next); }; } // Two emit implementations, selected once at factory time - the hot path // never branches on mode. Both share the single-listener fast path: with // one listener there is no neighbour to skip or double-invoke, so the // guard question is moot and the loop machinery is pure overhead. // With `onError`, each call is in a try and a throw goes there; the loops // are otherwise the two below. Built only when asked, so the default paths // never carry the try. const onError = options.onError; const emit: (action: string, data: T) => void = onError !== undefined ? snapshot ? (action, data) => { const bucket = listeners.get(action) as FastListener[] | undefined; if (bucket === undefined) return; for (let i = 0, len = bucket.length; i < len; i++) { try { bucket[i](data); } catch (e) { onError(e, action); } } } : (action, data) => { const bucket = listeners.get(action) as LiveEntry[] | undefined; if (bucket === undefined) return; // One listener, as the default path: no neighbour, no loop. if (bucket.length === 1) { try { bucket[0].fn(data); } catch (err) { onError(err, action); } return; } for (let i = 0, len = bucket.length; i < len; i++) { const e = bucket[i]; if (!e.off) { try { e.fn(data); } catch (err) { onError(err, action); } } } } : snapshot ? (action, data) => { // SNAPSHOT mode: unsub replaces arrays (see on() above), so the ref // captured here is never mutated mid-flight - one call per slot, no // guards. Contract: a listener removed during this emit still runs // once; a listener added during it does not run until the next. const bucket = listeners.get(action) as FastListener[] | undefined; if (bucket === undefined) return; if (bucket.length === 1) { bucket[0](data); return; } for (let i = 0, len = bucket.length; i < len; i++) bucket[i](data); } : (action, data) => { const bucket = listeners.get(action) as LiveEntry[] | undefined; if (bucket === undefined) return; // One listener: nothing it does can affect another in this emit. if (bucket.length === 1) { bucket[0].fn(data); return; } // LIVE mode (default, bus parity, the rule fanOutListeners states): // the listeners that existed when the emit started; one removed // during it is marked off and skipped, one added during it is past // `len`. Nothing a listener does moves the cursor, so removing several // peers on both sides of itself never skips or re-runs one (log s35.67). for (let i = 0, len = bucket.length; i < len; i++) { const e = bucket[i]; if (!e.off) e.fn(data); } }; function registeredActions(): string[] { return Array.from(handlers.keys()); } function clear(): void { clears++; epochs.clear(); handlers.clear(); for (const b of listeners.values()) markOff(b); listeners.clear(); } return { compile, remove, on, emit, registeredActions, clear }; }