@ignex/nova 0.1.1 → 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/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Events layer — internal barrel. Public entry: `public/events.ts`
+ * (`ignex-nova/events`).
+ */
+
+export { createClientStore, createEventClient } from "./clients";
+export {
+  createClusterSubjects,
+  createClusterSync,
+  createMemoryStateStore,
+  createNatsClusterTransport,
+  createRedisClusterTransport,
+  createRedisStateStore,
+  decodeClusterMessage,
+  encodeClusterMessage,
+} from "./cluster";
+export { createClientData } from "./data";
+export { createEmitter, deliverLocal } from "./emit";
+export {
+  bindEvents,
+  emit,
+  emitToClient,
+  emitToGroup,
+  emitToTopic,
+  emitToUser,
+  getEventsHub,
+  isEventsBound,
+  off,
+  offAny,
+  offServerEvent,
+  on,
+  onAny,
+  once,
+  onServerEvent,
+  unbindEvents,
+} from "./global";
+export { createGroupManager } from "./groups";
+export type { EventsHubInternal } from "./hub";
+export { createEventsHub } from "./hub";
+export { createTaskQueue } from "./queue";
+export { createHandlerRegistry } from "./registry";
+export type {
+  ClientData,
+  ClientGroup,
+  ClusterStateStore,
+  ClusterTransport,
+  EmitTarget,
+  EmitTargetKind,
+  EventClient,
+  EventContext,
+  EventHandler,
+  EventSource,
+  EventsClusterOptions,
+  EventsHub,
+  EventsMetricsSnapshot,
+  EventsOptions,
+  RedisConnectionOptions,
+  RemoteClient,
+  ServerEventHandler,
+  UserGroup,
+} from "./types";

package/src/events/queue.ts

@@ -0,0 +1,123 @@
+/**
+ * Offload task queue — a small bounded worker pool that keeps ALL non-essential
+ * work (cluster publishes, Redis/state-store writes, presence maintenance) off
+ * the WebSocket hot path.
+ *
+ * Contract:
+ *   - `enqueue` is O(1) and never throws; when the queue is full (over
+ *     `maxPending`) the NEWEST task is dropped and counted (`drop-newest` —
+ *     fresher state is more valuable than stale queued work).
+ *   - Tasks may be async; workers await them with bounded concurrency
+ *     (`workers`), so one slow Redis call can't stall the loop.
+ *   - Errors are caught per task, counted, and forwarded to `onError`
+ *     (default: nothing) — a failing task never takes the process down and
+ *     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;
+  drain(): Promise<void>;
+  close(): void;
+  stats(): { queued: number; processed: number; dropped: number; errors: number };
+}
+
+export interface TaskQueueOptions {
+  /** concurrent workers, default 2 */
+  workers?: number;
+  /** max queued tasks before drop-newest, default 4096 */
+  maxPending?: number;
+  onError?: (err: Error) => void;
+}
+
+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 = new RingBuffer<() => void | Promise<void>>(Math.min(maxPending, 64));
+  let queued = 0;
+  let processed = 0;
+  let dropped = 0;
+  let errors = 0;
+  let inflight = 0;
+  let stopping = false;
+
+  // 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 (;;) {
+      const task = tasks.shift();
+      if (task === undefined) {
+        if (stopping) return;
+        await park(); // parked — no CPU while idle
+        continue;
+      }
+      inflight++;
+      try {
+        await task();
+        processed++;
+      } catch (err) {
+        errors++;
+        onError?.(err instanceof Error ? err : new Error(String(err)));
+      } finally {
+        inflight--;
+      }
+      notifyIdle();
+    }
+  };
+
+  for (let i = 0; i < workersN; i++) void worker();
+
+  return {
+    get pending(): number {
+      return tasks.length + inflight;
+    },
+    enqueue(task) {
+      if (stopping) return;
+      if (tasks.length >= maxPending) {
+        dropped++;
+        return;
+      }
+      tasks.push(task);
+      queued++;
+      wakeOne();
+    },
+    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

@@ -0,0 +1,214 @@
+/**
+ * Handler registry — the "events file receives events" core. An ordered,
+ * multi-handler-per-event registry with per-handler error isolation:
+ * one throwing handler never prevents the others, and every failure is
+ * counted (surfaced via `hub.metrics().handlerErrors`).
+ *
+ * Supports `on` / `off` / `once` / `onAny` / `removeAllListeners` and a
+ * separate server-event registry (`onServerEvent`) for events that arrive
+ * from other instances or the NATS bridge.
+ *
+ * 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. */
+export type DispatchContext = unknown;
+
+type AnyHandler = (payload: unknown, ctx: DispatchContext) => void | Promise<void>;
+
+export interface HandlerRegistry {
+  on(name: string, handler: AnyHandler): void;
+  off(name: string, handler?: AnyHandler): void;
+  once(name: string, handler: AnyHandler): void;
+  onAny(cb: AnyHandler): void;
+  offAny(cb: AnyHandler): void;
+  has(name: string): boolean;
+  names(): string[];
+  count(name: string): number;
+  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;
+  /** true when a server-event handler exists for `name` (avoids payload decode). */
+  wantsServerEvent(name: string): boolean;
+  dispatchServerEvent(name: string, payload: unknown, ctx: DispatchContext): void;
+  onError(cb: (err: Error, name: string) => void): void;
+  /** total handler exceptions since creation */
+  readonly errorCount: number;
+}
+
+function invoke(handler: AnyHandler, payload: unknown, ctx: DispatchContext, onError: (err: Error) => void): void {
+  try {
+    const r = handler(payload, ctx);
+    if (r && typeof (r as Promise<void>).then === "function") {
+      void (r as Promise<void>).catch((err: unknown) => onError(err instanceof Error ? err : new Error(String(err))));
+    }
+  } catch (err) {
+    onError(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+
+// ── 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, AnyHandler[]>();
+  let anyHandlers: AnyHandler[] = [];
+  const serverHandlers = new Map<string, AnyHandler[]>();
+  const errorCbs: Array<(err: Error, name: string) => void> = [];
+  let errorCount = 0;
+
+  const report = (err: Error, name: string): void => {
+    errorCount++;
+    for (const cb of errorCbs) {
+      try {
+        cb(err, name);
+      } catch {
+        // error reporters must never break dispatch
+      }
+    }
+  };
+
+  return {
+    on(name, handler) {
+      handlers.set(name, cowAdd(handlers.get(name), handler));
+    },
+    off(name, handler) {
+      if (!handler) {
+        handlers.delete(name);
+        return;
+      }
+      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) => {
+        // 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);
+      };
+      handlers.set(name, cowAdd(handlers.get(name), wrap));
+    },
+    onAny(cb) {
+      anyHandlers = [...anyHandlers, cb];
+    },
+    offAny(cb) {
+      const next = anyHandlers.filter((x) => x !== cb);
+      anyHandlers = next;
+    },
+    has(name) {
+      return handlers.has(name) || anyHandlers.length > 0;
+    },
+    names() {
+      return [...handlers.keys()];
+    },
+    count(name) {
+      return handlers.get(name)?.length ?? 0;
+    },
+    removeAll(name) {
+      if (name) handlers.delete(name);
+      else handlers.clear();
+    },
+    dispatch(name, payload, ctx) {
+      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));
+        }
+      }
+      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)?.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) {
+      serverHandlers.set(name, cowAdd(serverHandlers.get(name), handler));
+    },
+    offServerEvent(name, handler) {
+      if (!handler) {
+        serverHandlers.delete(name);
+        return;
+      }
+      const next = cowRemove(serverHandlers.get(name), handler);
+      if (next === undefined) serverHandlers.delete(name);
+      else serverHandlers.set(name, next);
+    },
+    dispatchServerEvent(name, payload, ctx) {
+      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) {
+      errorCbs.push(cb);
+    },
+    get errorCount(): number {
+      return errorCount;
+    },
+  };
+}

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();
+    },
+  };
+}