@ignex/nova 0.1.3 → 0.1.5

package/src/events/hub/resolve-cluster.ts

@@ -0,0 +1,49 @@
+/**
+ * Cluster transport resolution — maps `events.cluster` options onto a
+ * concrete {@link ClusterTransport} (plus an owned bridge when the hub had to
+ * create one and therefore must close it again).
+ *
+ * Pure resolver: no side effects beyond constructing the adapters it returns.
+ */
+import { createNatsBridge, type NatsBridge, type NatsBridgeOptions } from "../../bridge/nats";
+import type { Bindings } from "../../bindings/types";
+import type { ClusterTransport, EventsClusterOptions } from "../types";
+import { createNatsClusterTransport } from "../cluster/transport-nats";
+import { createRedisClusterTransport } from "../cluster/transport-redis";
+
+export interface ResolvedClusterTransport {
+  transport?: ClusterTransport;
+  /** set when this resolver created the bridge — the hub closes it on shutdown */
+  ownBridge?: NatsBridge;
+}
+
+export function resolveClusterTransport(
+  opts: EventsClusterOptions,
+  serverBridge: NatsBridge | undefined,
+  bindings: Bindings,
+  onError: (err: Error) => void,
+): ResolvedClusterTransport {
+  // explicit adapter always wins
+  if (opts.transport) return { transport: opts.transport };
+
+  if (opts.nats) {
+    const nats = opts.nats;
+    // `true` → reuse the server's bridge when present, else dial localhost
+    if (typeof nats === "boolean") {
+      if (serverBridge) return { transport: createNatsClusterTransport(serverBridge) };
+      const own = createNatsBridge(
+        { servers: ["nats://localhost:4222"], inbound: false },
+        undefined,
+        bindings,
+      );
+      return { transport: createNatsClusterTransport(own), ownBridge: own };
+    }
+    // a pre-built bridge (`status` is bridge-only surface) vs raw options
+    if ("status" in nats) return { transport: createNatsClusterTransport(nats) };
+    const own = createNatsBridge(nats as NatsBridgeOptions, undefined, bindings);
+    return { transport: createNatsClusterTransport(own), ownBridge: own };
+  }
+
+  if (opts.redis) return { transport: createRedisClusterTransport(opts.redis, onError) };
+  return {};
+}

package/src/events/queue.ts

@@ -14,7 +14,15 @@
  *     never breaks the caller's hot path.
  *   - `close()` stops accepting; `drain()` resolves once queued + in-flight
  *     work has completed (used by graceful shutdown).
+ *
+ * Efficiency: storage is a pre-allocated {@link RingBuffer} (O(1) push/shift,
+ * no `Array.shift` memmove while saturated) and IDLE WORKERS PARK on a
+ * promise — zero timers, zero `setImmediate` spins, zero CPU while idle.
+ * `enqueue` wakes exactly one parked worker; completion notifications drive
+ * `drain()`.
  */
+import { RingBuffer } from "../core/ring";
+
 export interface TaskQueue {
   readonly pending: number;
   enqueue(task: () => void | Promise<void>): void;
@@ -35,7 +43,7 @@ export function createTaskQueue(opts: TaskQueueOptions = {}): TaskQueue {
   const workersN = Math.max(1, opts.workers ?? 2);
   const maxPending = Math.max(1, opts.maxPending ?? 4096);
   const onError = opts.onError;
-  const tasks: Array<() => void | Promise<void>> = [];
+  const tasks = new RingBuffer<() => void | Promise<void>>(Math.min(maxPending, 64));
   let queued = 0;
   let processed = 0;
   let dropped = 0;
@@ -43,14 +51,31 @@ export function createTaskQueue(opts: TaskQueueOptions = {}): TaskQueue {
   let inflight = 0;
   let stopping = false;
 
-  const yieldToLoop = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+  // parked-worker wakeups: enqueue resolves one sleeper; close resolves all
+  const sleepers: Array<() => void> = [];
+  const park = (): Promise<void> => new Promise((resolve) => sleepers.push(resolve));
+  const wakeOne = (): void => {
+    const w = sleepers.shift();
+    if (w !== undefined) w();
+  };
+  const wakeAll = (): void => {
+    while (sleepers.length > 0) sleepers.shift()!();
+  };
+
+  // drain notification: resolved once the queue AND in-flight work hit zero
+  const drainWaiters: Array<() => void> = [];
+  const notifyIdle = (): void => {
+    if (drainWaiters.length === 0 || tasks.length > 0 || inflight > 0) return;
+    const waiters = drainWaiters.splice(0, drainWaiters.length);
+    for (const w of waiters) w();
+  };
 
   const worker = async (): Promise<void> => {
     for (;;) {
-      if (stopping && tasks.length === 0) return;
       const task = tasks.shift();
-      if (!task) {
-        await yieldToLoop();
+      if (task === undefined) {
+        if (stopping) return;
+        await park(); // parked — no CPU while idle
         continue;
       }
       inflight++;
@@ -63,6 +88,7 @@ export function createTaskQueue(opts: TaskQueueOptions = {}): TaskQueue {
       } finally {
         inflight--;
       }
+      notifyIdle();
     }
   };
 
@@ -80,14 +106,15 @@ export function createTaskQueue(opts: TaskQueueOptions = {}): TaskQueue {
       }
       tasks.push(task);
       queued++;
+      wakeOne();
     },
-    async drain() {
-      while (tasks.length > 0 || inflight > 0) {
-        await yieldToLoop();
-      }
+    drain() {
+      if (tasks.length === 0 && inflight === 0) return Promise.resolve();
+      return new Promise<void>((resolve) => drainWaiters.push(resolve));
     },
     close() {
       stopping = true;
+      wakeAll(); // let parked workers see `stopping` and exit
     },
     stats() {
       return { queued, processed, dropped, errors };

package/src/events/registry.ts

@@ -11,6 +11,12 @@
  * The registry is BINDINGS-AGNOSTIC: names and payloads are `unknown` here,
  * and the `ctx` is passed through opaquely (the hub types it as
  * `EventContext<B>` at the boundary).
+ *
+ * Dispatch is ALLOCATION-FREE by construction (copy-on-write): handler lists
+ * are plain arrays that are REPLACED on every mutation (`on`/`off`/`once`),
+ * so `dispatch` iterates its snapshot directly — no `[...set]` copies on the
+ * per-event hot path, and a handler that subscribes/unsubscribes mid-dispatch
+ * can never corrupt the in-flight iteration.
  */
 
 /** Opaque context — the hub hands a typed `EventContext<B>` through. */
@@ -30,6 +36,14 @@ export interface HandlerRegistry {
   removeAll(name?: string): void;
   /** dispatch to every handler for `name` + every onAny handler. Isolated. */
   dispatch(name: string, payload: unknown, ctx: DispatchContext): void;
+  /**
+   * Like `dispatch` / `dispatchServerEvent`, but resolves AFTER every matched
+   * handler settled (sync throw caught, async rejection awaited), collecting
+   * the errors. Allocation-per-call — used by the reliability layer
+   * (`delivery.ts`) for retry/DLQ decisions; the hot path keeps using
+   * `dispatch`.
+   */
+  settleDispatch(name: string, payload: unknown, ctx: DispatchContext, mode?: "client" | "server"): Promise<Error[]>;
   /** register a server-side handler (remote / bridge events only) */
   onServerEvent(name: string, handler: AnyHandler): void;
   offServerEvent(name: string, handler?: AnyHandler): void;
@@ -52,10 +66,23 @@ function invoke(handler: AnyHandler, payload: unknown, ctx: DispatchContext, onE
   }
 }
 
+// ── copy-on-write list helpers ──────────────────────────────────────────────
+// Mutations allocate (the write path); dispatch only reads.
+
+const cowAdd = (arr: AnyHandler[] | undefined, h: AnyHandler): AnyHandler[] =>
+  arr === undefined ? [h] : [...arr, h];
+
+const cowRemove = (arr: AnyHandler[] | undefined, h?: AnyHandler): AnyHandler[] | undefined => {
+  if (arr === undefined) return undefined;
+  if (h === undefined) return undefined; // remove whole list
+  const next = arr.filter((x) => x !== h);
+  return next.length === 0 ? undefined : next;
+};
+
 export function createHandlerRegistry(): HandlerRegistry {
-  const handlers = new Map<string, Set<AnyHandler>>();
-  const anyHandlers = new Set<AnyHandler>();
-  const serverHandlers = new Map<string, Set<AnyHandler>>();
+  const handlers = new Map<string, AnyHandler[]>();
+  let anyHandlers: AnyHandler[] = [];
+  const serverHandlers = new Map<string, AnyHandler[]>();
   const errorCbs: Array<(err: Error, name: string) => void> = [];
   let errorCount = 0;
 
@@ -70,102 +97,111 @@ export function createHandlerRegistry(): HandlerRegistry {
     }
   };
 
-  const add = (name: string, handler: AnyHandler): void => {
-    let set = handlers.get(name);
-    if (!set) {
-      set = new Set();
-      handlers.set(name, set);
-    }
-    set.add(handler);
-  };
-
-  const addServer = (name: string, handler: AnyHandler): void => {
-    let set = serverHandlers.get(name);
-    if (!set) {
-      set = new Set();
-      serverHandlers.set(name, set);
-    }
-    set.add(handler);
-  };
-
   return {
     on(name, handler) {
-      add(name, handler);
+      handlers.set(name, cowAdd(handlers.get(name), handler));
     },
     off(name, handler) {
       if (!handler) {
         handlers.delete(name);
         return;
       }
-      handlers.get(name)?.delete(handler);
+      const next = cowRemove(handlers.get(name), handler);
+      if (next === undefined) handlers.delete(name);
+      else handlers.set(name, next);
     },
     once(name, handler) {
       const wrap: AnyHandler = (payload, ctx) => {
-        handlers.get(name)?.delete(wrap);
+        // remove FIRST so a re-entrant fire cannot invoke it twice
+        const cur = handlers.get(name);
+        if (cur !== undefined) {
+          const next = cowRemove(cur, wrap);
+          if (next === undefined) handlers.delete(name);
+          else handlers.set(name, next);
+        }
         return handler(payload, ctx);
       };
-      add(name, wrap);
+      handlers.set(name, cowAdd(handlers.get(name), wrap));
     },
     onAny(cb) {
-      anyHandlers.add(cb);
+      anyHandlers = [...anyHandlers, cb];
     },
     offAny(cb) {
-      anyHandlers.delete(cb);
+      const next = anyHandlers.filter((x) => x !== cb);
+      anyHandlers = next;
     },
     has(name) {
-      return handlers.has(name) || anyHandlers.size > 0;
+      return handlers.has(name) || anyHandlers.length > 0;
     },
     names() {
       return [...handlers.keys()];
     },
     count(name) {
-      return handlers.get(name)?.size ?? 0;
+      return handlers.get(name)?.length ?? 0;
     },
     removeAll(name) {
       if (name) handlers.delete(name);
       else handlers.clear();
     },
     dispatch(name, payload, ctx) {
-      const set = handlers.get(name);
-      if (set) {
-        const snapshot = [...set];
-        for (const h of snapshot) {
-          invoke(h, payload, ctx, (err) => report(err, name));
+      const list = handlers.get(name);
+      if (list !== undefined) {
+        for (let i = 0; i < list.length; i++) {
+          const h = list[i];
+          if (h !== undefined) invoke(h, payload, ctx, (err) => report(err, name));
         }
       }
-      if (anyHandlers.size > 0) {
-        const snapshot = [...anyHandlers];
-        for (const h of snapshot) {
-          invoke(
-            (p) => {
-              (h as (n: string, p: unknown, c: DispatchContext) => unknown)(name, p, ctx);
-            },
-            payload,
-            ctx,
-            (err) => report(err, name),
-          );
-        }
+      const anys = anyHandlers;
+      for (let i = 0; i < anys.length; i++) {
+        const h = anys[i];
+        if (h === undefined) continue;
+        invoke(
+          (p) => {
+            (h as (n: string, p: unknown, c: DispatchContext) => unknown)(name, p, ctx);
+          },
+          payload,
+          ctx,
+          (err) => report(err, name),
+        );
       }
     },
     wantsServerEvent(name) {
-      return (serverHandlers.get(name)?.size ?? 0) > 0;
+      return (serverHandlers.get(name)?.length ?? 0) > 0;
+    },
+    async settleDispatch(name, payload, ctx, mode = "client") {
+      const errors: Error[] = [];
+      const run = async (h: AnyHandler): Promise<void> => {
+        try {
+          await h(payload, ctx);
+        } catch (err) {
+          errors.push(err instanceof Error ? err : new Error(String(err)));
+          report(errors[errors.length - 1]!, name);
+        }
+      };
+      const jobs: Promise<void>[] = [];
+      const source = mode === "server" ? serverHandlers.get(name) : handlers.get(name);
+      if (source !== undefined) for (const h of source) jobs.push(run(h));
+      await Promise.all(jobs);
+      return errors;
     },
     onServerEvent(name, handler) {
-      addServer(name, handler);
+      serverHandlers.set(name, cowAdd(serverHandlers.get(name), handler));
     },
     offServerEvent(name, handler) {
       if (!handler) {
         serverHandlers.delete(name);
         return;
       }
-      serverHandlers.get(name)?.delete(handler);
+      const next = cowRemove(serverHandlers.get(name), handler);
+      if (next === undefined) serverHandlers.delete(name);
+      else serverHandlers.set(name, next);
     },
     dispatchServerEvent(name, payload, ctx) {
-      const set = serverHandlers.get(name);
-      if (!set) return;
-      const snapshot = [...set];
-      for (const h of snapshot) {
-        invoke(h, payload, ctx, (err) => report(err, name));
+      const list = serverHandlers.get(name);
+      if (list === undefined) return;
+      for (let i = 0; i < list.length; i++) {
+        const h = list[i];
+        if (h !== undefined) invoke(h, payload, ctx, (err) => report(err, name));
       }
     },
     onError(cb) {

package/src/events/schedule.ts

@@ -0,0 +1,73 @@
+/**
+ * Scheduled emits — delayed/deferred event delivery with cancellation.
+ * Backs `hub.schedule(name, payload, target?, delayMs)` (time-based events:
+ * reminder pushes, cooldowns, TTL'd notices).
+ *
+ * Implementation is a plain per-entry `setTimeout` wheel: scheduling volume in
+ * an events hub is human-scale (thousands), where timer accuracy and O(1)
+ * cancel beat a heap's memory compactness. Entries are tracked in a Map so
+ * `cancel(id)` is exact; `clear()` drops everything (used on close). Timers
+ * never reference sockets directly — they call the hub's emit at fire time,
+ * so cluster routing / bridge semantics stay identical to a normal emit.
+ */
+
+export type EmitFn = (name: string, payload: unknown, target?: unknown) => void;
+
+export interface Scheduler {
+  /** schedule one emit; returns its id (cancel with it) */
+  schedule(name: string, payload: unknown, target: unknown, delayMs: number): string;
+  /** cancel a scheduled emit — true when it had not fired yet */
+  cancel(id: string): boolean;
+  /** ids currently pending */
+  pending(): string[];
+  readonly size: number;
+  clear(): void;
+}
+
+interface Entry {
+  timer: ReturnType<typeof setTimeout>;
+  name: string;
+  payload: unknown;
+  target: unknown;
+}
+
+export function createScheduler(emit: EmitFn): Scheduler {
+  const entries = new Map<string, Entry>();
+
+  const fire = (id: string): void => {
+    const e = entries.get(id);
+    if (!e) return;
+    entries.delete(id);
+    try {
+      emit(e.name, e.payload, e.target);
+    } catch {
+      // emit must not throw (hub guards this too)
+    }
+  };
+
+  return {
+    schedule(name, payload, target, delayMs) {
+      const id = crypto.randomUUID();
+      const ms = Math.max(0, delayMs);
+      entries.set(id, { name, payload, target, timer: setTimeout(() => fire(id), ms) });
+      return id;
+    },
+    cancel(id) {
+      const e = entries.get(id);
+      if (!e) return false;
+      clearTimeout(e.timer);
+      entries.delete(id);
+      return true;
+    },
+    pending() {
+      return [...entries.keys()];
+    },
+    get size(): number {
+      return entries.size;
+    },
+    clear() {
+      for (const e of entries.values()) clearTimeout(e.timer);
+      entries.clear();
+    },
+  };
+}