@ignex/nova 0.1.1 → 0.1.3

package/src/events/data.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-connection app data store — the "what to store for each client" half of
+ * the client record. A tiny Map-backed key/value bag with JSON export, created
+ * on attach and discarded on detach (no leak across reconnects).
+ */
+import type { ClientData } from "./types";
+
+export function createClientData(): ClientData {
+  const map = new Map<string, unknown>();
+  return {
+    get(key) {
+      return map.get(key);
+    },
+    set(key, value) {
+      map.set(key, value);
+    },
+    has(key) {
+      return map.has(key);
+    },
+    delete(key) {
+      return map.delete(key);
+    },
+    clear() {
+      map.clear();
+    },
+    keys() {
+      return [...map.keys()];
+    },
+    entries() {
+      return [...map.entries()];
+    },
+    toJSON() {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of map) out[k] = v;
+      return out;
+    },
+  };
+}

package/src/events/emit.ts

@@ -0,0 +1,127 @@
+/**
+ * Emit engine — the "global emit" hot path. Encodes ONCE through the transport
+ * scratch (zero-alloc on the happy path), delivers to the target's local
+ * sockets synchronously, then hands the SAME frame to the external bridge
+ * (existing NATS broadcast/topic/group subjects) and the cluster sync
+ * (offloaded) so other instances deliver it too.
+ *
+ * Hot-path guarantees:
+ *   - encode + local delivery are synchronous and allocation-free (Bun copies
+ *     on `ws.send`);
+ *   - the bridge `publish` copies the scratch frame (never holds a stale view);
+ *   - cluster work is enqueued on the offload queue — a slow broker can never
+ *     stall the socket loop.
+ */
+import type { ServerWebSocket } from "bun";
+import type { NatsBridge } from "../bridge/nats";
+import type { ServerState, WsData } from "../core/state";
+import { sendFrame } from "../core/outbound";
+import { publishToGroup } from "../core/groups";
+import { publishToRoom } from "../core/rooms";
+import type { ClusterSync } from "./cluster";
+import type { EmitTarget, EmitTargetKind } from "./types";
+
+export interface EmitCounters {
+  emitted: number;
+  emittedByTarget: Record<EmitTargetKind, number>;
+  deliveredLocal: number;
+  clusterPublished: number;
+}
+
+export interface EmitEngine {
+  emit(name: string, payload: unknown, target: EmitTarget): void;
+}
+
+export interface EmitterOptions {
+  state: ServerState;
+  bridge?: NatsBridge;
+  cluster?: ClusterSync;
+  /** local sockets acting on behalf of a userId (user-target delivery) */
+  userSockets: (userId: string) => ServerWebSocket<WsData>[];
+  counters: EmitCounters;
+}
+
+/** Deliver `frame` to the target's LOCAL sockets; returns the number written. */
+export function deliverLocal(
+  state: ServerState,
+  target: EmitTarget,
+  frame: Uint8Array,
+  userSockets: (userId: string) => ServerWebSocket<WsData>[],
+): number {
+  switch (target.type) {
+    case "broadcast": {
+      for (const ws of state.sockets) sendFrame(state, ws, frame);
+      return state.sockets.size;
+    }
+    case "topic": {
+      const n = state.rooms.get(target.topic)?.size ?? 0;
+      publishToRoom(state, target.topic, frame);
+      return n;
+    }
+    case "group": {
+      const n = state.groups.get(target.group)?.size ?? 0;
+      publishToGroup(state, target.group, frame);
+      return n;
+    }
+    case "user": {
+      const list = userSockets(target.userId);
+      for (const ws of list) sendFrame(state, ws, frame);
+      return list.length;
+    }
+    case "client": {
+      const ws = state.clients.get(target.clientId);
+      if (!ws) return 0;
+      sendFrame(state, ws, frame);
+      return 1;
+    }
+  }
+}
+
+export function targetKey(target: EmitTarget): string | undefined {
+  switch (target.type) {
+    case "broadcast":
+      return undefined;
+    case "topic":
+      return target.topic;
+    case "group":
+      return target.group;
+    case "user":
+      return target.userId;
+    case "client":
+      return target.clientId;
+  }
+}
+
+export function createEmitter(opts: EmitterOptions): EmitEngine {
+  const { state, bridge, cluster } = opts;
+
+  const bridgeSubject = (target: EmitTarget, name: string): string | undefined => {
+    switch (target.type) {
+      case "broadcast":
+        return bridge?.subjects.broadcast(name);
+      case "topic":
+        return bridge?.subjects.topic(target.topic, name);
+      case "group":
+        return bridge?.subjects.group(target.group, name);
+      default:
+        return undefined; // user/client targets are not bridged externally
+    }
+  };
+
+  return {
+    emit(name, payload, target) {
+      const frame = state.transport.encodeToScratch(name, payload);
+      opts.counters.emitted++;
+      opts.counters.emittedByTarget[target.type]++;
+      opts.counters.deliveredLocal += deliverLocal(state, target, frame, opts.userSockets);
+      if (bridge) {
+        const subject = bridgeSubject(target, name);
+        if (subject) bridge.publish(subject, frame); // copies the scratch view
+      }
+      if (cluster) {
+        opts.counters.clusterPublished++;
+        cluster.publish(target.type, targetKey(target), name, frame);
+      }
+    },
+  };
+}

package/src/events/global.ts

@@ -0,0 +1,117 @@
+/**
+ * Global emit — the module-level singleton the events layer exposes so ANY
+ * module in the app can send events through websockets without holding a
+ * server reference (the "global emit" of the events file pattern):
+ *
+ *   import { on, emit } from "ignex-nova/events";
+ *   on("order.created", (ctx) => { ... });
+ *   emit("quote", { symbol: "AAPL", ... });                       // broadcast
+ *   emit("order", payload, { type: "group", group: "traders" });  // to a group
+ *   emit("alert", payload, { type: "user", userId: "u-1" });      // to a user
+ *
+ * Bound automatically when `createServer({ events: {...} })` runs (last hub
+ * wins — one active hub per process is the supported topology; use
+ * `server.events` directly for per-server control). Calls before binding
+ * throw a descriptive error; calls after `close()` are dropped silently.
+ *
+ * Typed against the BUILT-IN event registry. Custom-schema apps should use
+ * `server.events.emit` / `server.events.on` (fully typed against YOUR events).
+ */
+
+import type { DefaultBindings } from "../bindings/types";
+import type { EventName, Events } from "../schema";
+import type { EmitTarget, EventContext, EventHandler, EventsHub } from "./types";
+
+let bound: EventsHub | null = null;
+
+/** Bind the singleton to a hub (called by the hub on creation). */
+export function bindEvents(hub: EventsHub): void {
+  bound = hub;
+}
+
+/** Unbind the singleton (called by the hub on close). */
+export function unbindEvents(): void {
+  bound = null;
+}
+
+export function isEventsBound(): boolean {
+  return bound !== null;
+}
+
+/** The currently bound hub (null when none). */
+export function getEventsHub(): EventsHub | null {
+  return bound;
+}
+
+function requireHub(): EventsHub {
+  if (!bound) {
+    throw new Error(
+      "ignex events: no events hub bound — pass `events: {}` to createServer() (or call bindEvents(hub) once)",
+    );
+  }
+  return bound;
+}
+
+export function emit<K extends EventName>(name: K, payload: Events[K], target?: EmitTarget): void {
+  requireHub().emit(name as never, payload as never, target);
+}
+
+export function emitToTopic<K extends EventName>(topic: string, name: K, payload: Events[K]): void {
+  requireHub().emitToTopic(topic, name as never, payload as never);
+}
+
+export function emitToGroup<K extends EventName>(group: string, name: K, payload: Events[K]): void {
+  requireHub().emitToGroup(group, name as never, payload as never);
+}
+
+export function emitToUser<K extends EventName>(userId: string, name: K, payload: Events[K]): void {
+  requireHub().emitToUser(userId, name as never, payload as never);
+}
+
+export function emitToClient<K extends EventName>(
+  clientId: string,
+  name: K,
+  payload: Events[K],
+): void {
+  requireHub().emitToClient(clientId, name as never, payload as never);
+}
+
+export function on<K extends EventName>(name: K, handler: EventHandler<DefaultBindings, K>): void {
+  requireHub().on(name as never, handler as never);
+}
+
+export function off<K extends EventName>(
+  name: K,
+  handler?: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().off(name as never, handler as never);
+}
+
+export function once<K extends EventName>(
+  name: K,
+  handler: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().once(name as never, handler as never);
+}
+
+export function onAny(cb: (name: string, payload: unknown, ctx: EventContext) => void): void {
+  requireHub().onAny(cb as never);
+}
+
+export function offAny(cb: (name: string, payload: unknown, ctx: EventContext) => void): void {
+  requireHub().offAny(cb as never);
+}
+
+export function onServerEvent<K extends EventName>(
+  name: K,
+  handler: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().onServerEvent(name as never, handler as never);
+}
+
+export function offServerEvent<K extends EventName>(
+  name: K,
+  handler?: EventHandler<DefaultBindings, K>,
+): void {
+  requireHub().offServerEvent(name as never, handler as never);
+}

package/src/events/groups.ts

@@ -0,0 +1,118 @@
+/**
+ * Groups — named fan-out dimensions with explicit differentiation:
+ *
+ *   - CLIENT groups (`hub.group(name)`): membership by connection id. These
+ *     reuse the transport's group registry (`state.groups`), so auth-seeded
+ *     groups, control frames (`client.joinGroup`), `server.joinGroup` and the
+ *     events layer all see the SAME membership.
+ *   - USER groups (`hub.userGroup(name)`): membership by `userId`. Emitting to
+ *     a user group fans out to every socket acting on behalf of each member
+ *     user — the "broadcast to a group of people" case, independent of how
+ *     many devices each person has open.
+ *
+ * Both are cluster-aware at the hub level: emit → `emitToGroup` / `emitToUser`
+ * (which publish to the cluster subjects), and membership syncs to the shared
+ * state store when one is configured.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
+import { activeGroups, groupMembers as stateGroupMembers, joinGroup, leaveGroup } from "../core/groups";
+import type { ServerState, WsData } from "../core/state";
+import type { ClientGroup, UserGroup } from "./types";
+
+export interface GroupManager<B extends Bindings = DefaultBindings> {
+  clientGroup(name: string): ClientGroup<B>;
+  clientGroups(): string[];
+  userGroup(name: string): UserGroup<B>;
+  userGroups(): string[];
+}
+
+export interface GroupManagerOptions<B extends Bindings = DefaultBindings> {
+  state: ServerState;
+  emitToGroup: <K extends EventNameOf<B>>(group: string, name: K, payload: EventsOf<B>[K]) => void;
+  emitToUser: <K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]) => void;
+  /** fired on user-group membership change (hub wires cluster sync here) */
+  onUserGroupChange?: (name: string, members: ReadonlySet<string>) => void;
+}
+
+export function createGroupManager<B extends Bindings = DefaultBindings>(opts: GroupManagerOptions<B>): GroupManager<B> {
+  const userGroupsMap = new Map<string, Set<string>>();
+
+  const touchUserGroup = (name: string): void => {
+    opts.onUserGroupChange?.(name, userGroupsMap.get(name) ?? new Set());
+  };
+
+  const userGroupHandle = (name: string): UserGroup<B> => {
+    let set = userGroupsMap.get(name);
+    if (!set) {
+      set = new Set();
+      userGroupsMap.set(name, set);
+    }
+    return {
+      get name(): string {
+        return name;
+      },
+      add(userId) {
+        set!.add(userId);
+        touchUserGroup(name);
+      },
+      remove(userId) {
+        const existed = set!.delete(userId);
+        if (existed) {
+          if (set!.size === 0) userGroupsMap.delete(name);
+          touchUserGroup(name);
+        }
+      },
+      has(userId) {
+        return set!.has(userId);
+      },
+      members() {
+        return [...set!];
+      },
+      get size(): number {
+        return set!.size;
+      },
+      emit(event, payload) {
+        const snapshot = [...set!];
+        for (const userId of snapshot) opts.emitToUser(userId, event, payload);
+      },
+    };
+  };
+
+  const clientGroupHandle = (name: string): ClientGroup<B> => {
+    const socket = (clientId: string): ServerWebSocket<WsData> | undefined => opts.state.clients.get(clientId);
+    return {
+      get name(): string {
+        return name;
+      },
+      add(clientId) {
+        const ws = socket(clientId);
+        if (ws) joinGroup(opts.state, ws, name);
+      },
+      remove(clientId) {
+        const ws = socket(clientId);
+        if (ws) leaveGroup(opts.state, ws, name);
+      },
+      has(clientId) {
+        const ws = socket(clientId);
+        return ws !== undefined && ws.data.groups.has(name);
+      },
+      members() {
+        return stateGroupMembers(opts.state, name);
+      },
+      get size(): number {
+        return stateGroupMembers(opts.state, name).length;
+      },
+      emit(event, payload) {
+        opts.emitToGroup(name, event, payload);
+      },
+    };
+  };
+
+  return {
+    clientGroup: clientGroupHandle,
+    clientGroups: () => activeGroups(opts.state),
+    userGroup: userGroupHandle,
+    userGroups: () => [...userGroupsMap.keys()],
+  };
+}