@ignex/nova 0.1.1 → 0.1.3

package/src/core/server.ts

@@ -4,31 +4,37 @@
  * `IgnServer` API object (no class, no `this`). This is the ONLY place that
  * knows how the pieces fit together.
  *
+ * Generic over the wire stack: `createServer({ bindings })` with your own
+ * generated bindings types `publish` / `on` / ... against YOUR events. The
+ * default is the built-in registry, so existing code keeps working unchanged.
+ *
  * Public entry: `public/server.ts` re-exports `createServer` + the types.
  */
 import type { ServerWebSocket } from "bun";
-import { WIRE_VERSION } from "../generated/registry";
-import type { Events, EventName } from "../schema";
-import { getEncodeStats, encodeToScratch } from "../transport/transport";
-import { setInt64GuardMode } from "./int64-guard";
-import type { MetricsSnapshot } from "./metrics";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
+import { createNatsBridge } from "../bridge/nats";
+import { createEventsHub, type EventsHubInternal } from "../events/hub";
+import type { EventsHub } from "../events/types";
 import { checkUpgrade } from "./auth";
-import { drainSocket, sendControl, sendFrame } from "./outbound";
-import { handleMessage } from "./routing";
-import { joinRoom, leaveRoom, publishToRoom, roomTopics } from "./rooms";
 import {
   activeGroups,
-  groupMembers as groupMemberIds,
   joinGroup as addToGroup,
-  leaveGroup as removeFromGroup,
+  groupMembers as groupMemberIds,
   publishToGroup as publishToGroupState,
+  leaveGroup as removeFromGroup,
 } from "./groups";
+import { setInt64GuardMode } from "./int64-guard";
+import type { MetricsSnapshot } from "./metrics";
+import { drainSocket, sendControl, sendFrame } from "./outbound";
+import { joinRoom, leaveRoom, publishToRoom, roomTopics } from "./rooms";
+import { handleMessage } from "./routing";
 import { createServerState, type IgnServerOptions, type WsData } from "./state";
-import { createNatsBridge } from "../bridge/nats";
 
 /** A snapshot of an active client (from `getClient` / `getClients` / GET /clients). */
 export interface ClientInfo {
   id: string;
+  /** identity this connection acts on behalf of (undefined if none) */
+  userId?: string;
   /** arbitrary app metadata from `authenticate` (undefined if none) */
   meta?: Record<string, unknown>;
   /** server-side groups this client belongs to */
@@ -44,7 +50,8 @@ export interface ClientInfo {
 function toClientInfo(ws: ServerWebSocket<WsData>): ClientInfo {
   return {
     id: ws.data.id,
-    meta: ws.data.meta,
+    ...(ws.data.userId !== undefined ? { userId: ws.data.userId } : {}),
+    ...(ws.data.meta !== undefined ? { meta: ws.data.meta } : {}),
     groups: [...ws.data.groups],
     topics: [...ws.data.topics],
     connectedAt: ws.data.connectedAt,
@@ -53,18 +60,28 @@ function toClientInfo(ws: ServerWebSocket<WsData>): ClientInfo {
 }
 
 /** The public server API (returned by `createServer`). */
-export interface IgnServer {
+export interface IgnServer<B extends Bindings = DefaultBindings> {
   readonly port: number;
   readonly clientCount: number;
   getMetrics(): MetricsSnapshot;
   /** Broadcast a typed event to every connected client (zero-alloc on the happy path). */
-  publish<K extends EventName>(name: K, payload: Events[K]): void;
+  publish<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
   /** Send a typed event to a single socket (zero-alloc on the happy path). */
-  publishTo<K extends EventName>(ws: ServerWebSocket<WsData>, name: K, payload: Events[K]): void;
+  publishTo<K extends EventNameOf<B>>(
+    ws: ServerWebSocket<WsData>,
+    name: K,
+    payload: EventsOf<B>[K],
+  ): void;
   /** Publish a typed event to every socket subscribed to `topic`. */
-  publishToTopic<K extends EventName>(topic: string, name: K, payload: Events[K]): void;
+  publishToTopic<K extends EventNameOf<B>>(topic: string, name: K, payload: EventsOf<B>[K]): void;
   /** Send a typed event to a specific client by id. Returns false if that client is offline. */
-  publishToClient<K extends EventName>(id: string, name: K, payload: Events[K]): boolean;
+  publishToClient<K extends EventNameOf<B>>(id: string, name: K, payload: EventsOf<B>[K]): boolean;
+  /**
+   * Allow clients to send `name` (adds it to the inbound allowlist at runtime).
+   * The events layer calls this automatically when `server.events.on(name)` is
+   * first used.
+   */
+  allowInbound<K extends EventNameOf<B>>(name: K): IgnServer<B>;
   /** Programmatic room membership (clients can also join via subscribe frames). */
   join(topic: string, ws: ServerWebSocket<WsData>): void;
   leave(topic: string, ws: ServerWebSocket<WsData>): void;
@@ -74,7 +91,7 @@ export interface IgnServer {
   joinGroup(id: string, group: string): void;
   leaveGroup(id: string, group: string): void;
   /** Publish a typed event to every client in a server-side group. */
-  publishToGroup<K extends EventName>(group: string, name: K, payload: Events[K]): void;
+  publishToGroup<K extends EventNameOf<B>>(group: string, name: K, payload: EventsOf<B>[K]): void;
   /** Live server-side group names (with at least one member). */
   groups(): string[];
   /** Client ids currently in `group`. */
@@ -89,42 +106,59 @@ export interface IgnServer {
   /** Disconnect a client by id. Returns false if that client is offline. */
   disconnectClient(id: string): boolean;
   /** Register a handler for an inbound app event (must be in `options.inbound`). */
-  on<K extends EventName>(name: K, handler: (payload: Events[K], ws: ServerWebSocket<WsData>) => void): IgnServer;
-  off<K extends EventName>(name: K): IgnServer;
+  on<K extends EventNameOf<B>>(
+    name: K,
+    handler: (payload: EventsOf<B>[K], ws: ServerWebSocket<WsData>) => void,
+  ): IgnServer<B>;
+  off<K extends EventNameOf<B>>(name: K): IgnServer<B>;
+  /**
+   * The events hub — present when `createServer({ events: {...} })` is used:
+   * typed handlers (`server.events.on`), client records, groups, and the
+   * cluster-aware emit surface.
+   */
+  readonly events: EventsHub<B> | undefined;
   /** Graceful drain: stop accepting, wait up to `timeoutMs` for queues to flush. */
   drain(timeoutMs?: number): Promise<void>;
   stop(force?: boolean): void;
 }
 
-export function createServer(options: IgnServerOptions): IgnServer {
+export function createServer<B extends Bindings = DefaultBindings>(
+  options: IgnServerOptions<B>,
+): IgnServer<B> {
   const state = createServerState(options);
   setInt64GuardMode(options.int64Guard ?? "off");
+  const bindings = state.bindings;
 
   // NATS bridge (optional, best-effort — created eagerly, connects in the background)
   const natsOpt = options.nats;
-  if (natsOpt) state.bridge = "publish" in natsOpt ? natsOpt : createNatsBridge(natsOpt);
+  if (natsOpt)
+    state.bridge = "publish" in natsOpt ? natsOpt : createNatsBridge(natsOpt, undefined, bindings);
 
   // Encode once + broadcast to every connected client (NO bridge) — the shared
   // hot path for `publish` and NATS-inbound forwarding. Loop prevention: inbound
   // events reach clients but are never re-bridged to NATS.
-  function fanOutAll(name: Parameters<typeof encodeToScratch>[0], payload: unknown): Uint8Array {
-    const frame = encodeToScratch(name, payload);
+  function fanOutAll(name: string, payload: unknown): Uint8Array {
+    const frame = state.transport.encodeToScratch(name, payload);
     state.metrics.published++;
     for (const ws of state.sockets) sendFrame(state, ws, frame);
     return frame;
   }
 
+  let eventsHub: EventsHubInternal<B> | undefined;
+
   if (state.bridge) {
     state.bridge.setOnInbound((name, payload) => {
       fanOutAll(name, payload);
+      // server-side handling of externally-published events (the events layer)
+      eventsHub?.dispatchBridgeInbound(name, payload);
     });
   }
 
   const bun = Bun.serve<WsData>({
     port: options.port,
-    hostname: options.hostname,
+    ...(options.hostname !== undefined ? { hostname: options.hostname } : {}),
     idleTimeout: options.idleTimeout ?? 30,
-    tls: options.tls,
+    ...(options.tls !== undefined ? { tls: options.tls } : {}),
     fetch: (req, srv) => {
       const url = new URL(req.url);
       if (url.pathname === state.path) return checkUpgrade(state, req, srv);
@@ -150,13 +184,17 @@ export function createServer(options: IgnServerOptions): IgnServer {
         const existing = state.clients.get(ws.data.id);
         if (existing && existing !== ws) existing.close(1000, "replaced by newer session");
         state.clients.set(ws.data.id, ws);
+        // events-layer attach (client record + presence) BEFORE group seeding
+        state.onConnect?.(ws);
         for (const g of ws.data.groups) addToGroup(state, ws, g);
         // announce our wire version + capabilities so clients can negotiate
-        sendControl(state, ws, "hello", { version: WIRE_VERSION, caps: [], lastSeq: 0 });
+        sendControl(state, ws, "hello", { version: bindings.wireVersion, caps: [], lastSeq: 0 });
         // then assign identity so the client knows its id + server-side groups
         sendControl(state, ws, "welcome", { clientId: ws.data.id, groups: [...ws.data.groups] });
       },
       close: (ws) => {
+        // events-layer detach FIRST (client record still carries groups/topics)
+        state.onDisconnect?.(ws);
         state.sockets.delete(ws);
         state.clients.delete(ws.data.id);
         for (const g of ws.data.groups) removeFromGroup(state, ws, g);
@@ -170,7 +208,7 @@ export function createServer(options: IgnServerOptions): IgnServer {
     },
   });
 
-  const api: IgnServer = {
+  const api: IgnServer<B> = {
     get port(): number {
       return bun.port ?? 0;
     },
@@ -178,13 +216,16 @@ export function createServer(options: IgnServerOptions): IgnServer {
       return state.sockets.size;
     },
     getMetrics(): MetricsSnapshot {
-      const stats = getEncodeStats();
+      const stats = state.transport.getEncodeStats();
       for (const [name, n] of Object.entries(stats.direct)) {
         if (n > 0) state.metrics.countPath(name, "direct");
       }
       for (const [name, n] of Object.entries(stats.json)) {
         if (n > 0) state.metrics.countPath(name, "json");
       }
+      for (const [name, n] of Object.entries(stats.js)) {
+        if (n > 0) state.metrics.countPath(name, "js");
+      }
       const snapshot = state.metrics.snapshot(state.sockets.size);
       const b = state.bridge;
       if (b) {
@@ -195,6 +236,7 @@ export function createServer(options: IgnServerOptions): IgnServer {
         snapshot.bridgeInboundErrors = b.stats.bridgeInboundErrors;
         snapshot.natsStatus = b.status;
       }
+      if (eventsHub) snapshot.events = eventsHub.metrics();
       return snapshot;
     },
     publish(name, payload) {
@@ -203,10 +245,10 @@ export function createServer(options: IgnServerOptions): IgnServer {
     },
     publishTo(ws, name, payload) {
       state.metrics.published++;
-      sendFrame(state, ws, encodeToScratch(name, payload));
+      sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
     },
     publishToTopic(topic, name, payload) {
-      const frame = encodeToScratch(name, payload);
+      const frame = state.transport.encodeToScratch(name, payload);
       state.metrics.published++;
       publishToRoom(state, topic, frame);
       state.bridge?.publish(state.bridge.subjects.topic(topic, name), frame);
@@ -215,9 +257,13 @@ export function createServer(options: IgnServerOptions): IgnServer {
       const ws = state.clients.get(id);
       if (!ws) return false;
       state.metrics.published++;
-      sendFrame(state, ws, encodeToScratch(name, payload));
+      sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
       return true;
     },
+    allowInbound(name) {
+      state.inbound.add(name);
+      return api;
+    },
     join(topic, ws) {
       joinRoom(state, ws, topic);
     },
@@ -236,7 +282,7 @@ export function createServer(options: IgnServerOptions): IgnServer {
       if (ws) removeFromGroup(state, ws, group);
     },
     publishToGroup(group, name, payload) {
-      const frame = encodeToScratch(name, payload);
+      const frame = state.transport.encodeToScratch(name, payload);
       state.metrics.published++;
       publishToGroupState(state, group, frame);
       state.bridge?.publish(state.bridge.subjects.group(group, name), frame);
@@ -268,15 +314,22 @@ export function createServer(options: IgnServerOptions): IgnServer {
       return true;
     },
     on(name, handler) {
-      state.inboundHandlers.set(name, handler as (payload: unknown, ws: ServerWebSocket<WsData>) => void);
+      state.inboundHandlers.set(
+        name,
+        handler as (payload: unknown, ws: ServerWebSocket<WsData>) => void,
+      );
       return api;
     },
     off(name) {
       state.inboundHandlers.delete(name);
       return api;
     },
+    get events(): EventsHub<B> | undefined {
+      return eventsHub;
+    },
     async drain(timeoutMs = 2000): Promise<void> {
       bun.stop(false); // stop listening; keep active sockets draining
+      await eventsHub?.close();
       await state.bridge?.close();
       const deadline = Date.now() + timeoutMs;
       while (state.sockets.size > 0 && Date.now() < deadline) {
@@ -286,9 +339,30 @@ export function createServer(options: IgnServerOptions): IgnServer {
     },
     stop(force = true): void {
       bun.stop(force);
+      void eventsHub?.close();
       void state.bridge?.close();
     },
   };
 
+  // ── events layer (opt-in) ─────────────────────────────────────────────
+  if (options.events) {
+    eventsHub = createEventsHub({
+      state,
+      server: api,
+      bindings,
+      ...(state.bridge !== undefined ? { serverBridge: state.bridge } : {}),
+      options: options.events,
+    });
+    state.onConnect = (ws) => {
+      eventsHub!.attach(ws);
+    };
+    state.onDisconnect = (ws) => {
+      eventsHub!.detach(ws);
+    };
+    state.onGroupChange = (group, ws, joined) => {
+      eventsHub!.onGroupChange(group, ws, joined);
+    };
+  }
+
   return api;
 }

package/src/core/state.ts

@@ -7,11 +7,13 @@
  * PUBLIC surface and are re-exported by `public/server.ts`.
  */
 import type { ServerWebSocket } from "bun";
-import type { EventName } from "../schema";
+import { defaultBindings } from "../bindings/default";
+import type { Bindings, DefaultBindings, EventNameOf } from "../bindings/types";
+import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+import { createTransport, defaultTransport, type Transport } from "../transport/transport";
 import type { Int64GuardMode } from "./int64-guard";
 import { createMetrics, type Metrics } from "./metrics";
-import { RingBuffer } from "./ring";
-import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+import type { RingBuffer } from "./ring";
 
 /**
  * Optional identity metadata a client may carry for targeting / grouping.
@@ -20,6 +22,12 @@ import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
 export interface ClientMeta {
   /** explicit client id; omitted → auto-assigned `crypto.randomUUID()` */
   id?: string;
+  /**
+   * The identity this connection acts ON BEHALF OF (e.g. the logged-in user).
+   * Several connections may share a `userId` (multi-tab / multi-device) — the
+   * events layer groups them for user-targeted emits (`hub.emitToUser`).
+   */
+  userId?: string;
   /** server-side groups this client belongs to on connect */
   groups?: string[];
   /** arbitrary app metadata (exposed via `getClient` / `getClients`) */
@@ -41,6 +49,8 @@ export interface WsData {
   groups: Set<string>;
   /** stable client id (auth metadata or auto-generated UUID) */
   id: string;
+  /** identity this connection acts on behalf of (undefined = anonymous) */
+  userId?: string;
   /** arbitrary app metadata from `authenticate` (undefined if none) */
   meta?: Record<string, unknown>;
   /** epoch ms when the socket opened (for `getClients` ordering/uptime) */
@@ -61,15 +71,22 @@ export interface IgnBackpressureOptions {
   maxQueue?: number;
 }
 
-export interface IgnServerOptions {
+export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
   port: number;
   hostname?: string;
   /** seconds; 0 = no timeout */
   idleTimeout?: number;
   /** websocket path, default "/ws" */
   path?: string;
+  /**
+   * The wire stack (event ids, decoders, encoders). Defaults to the built-in
+   * registry; pass your own (from `generateBindings` + `assembleBindings`) to
+   * serve YOUR schema. When provided, the server API (`publish` / `on` / ...)
+   * is typed against your `Events`.
+   */
+  bindings?: B;
   /** app events clients are ALLOWED to send; control events are always allowed. default [] */
-  inbound?: EventName[];
+  inbound?: EventNameOf<B>[];
   /** slow-consumer protection. default: off (unbounded buffering) */
   backpressure?: IgnBackpressureOptions;
   /**
@@ -117,6 +134,13 @@ export interface IgnServerOptions {
    * NATS.
    */
   nats?: NatsBridgeOptions | NatsBridge;
+  /**
+   * Enable the events layer (typed event handlers + the global emit, client
+   * records with per-connection data, groups, optional cluster sync). Exposed
+   * as `server.events`; the module-global `emit`/`on` singleton
+   * (`ignex-nova/events`) is bound by default.
+   */
+  events?: import("../events/types").EventsOptions<B>;
   /** additional HTTP handler for non-ws routes (e.g. serving a static demo page) */
   fetch?: (req: Request) => Response | Promise<Response>;
 }
@@ -125,8 +149,12 @@ type InboundHandler = (payload: unknown, ws: ServerWebSocket<WsData>) => void;
 
 /** The full, explicit server state — created once per server, passed to actions. */
 export interface ServerState {
+  /** the wire stack this server speaks (ids / decoders / encoders). */
+  bindings: Bindings;
+  /** per-server encoder (scratch + FFI binding or pure-JS fallback). */
+  transport: Transport;
   path: string;
-  inbound: ReadonlySet<EventName>;
+  inbound: Set<string>;
   bp: Required<IgnBackpressureOptions> | null;
   metrics: Metrics;
   startedAt: number;
@@ -144,13 +172,23 @@ export interface ServerState {
   groups: Map<string, Set<ServerWebSocket<WsData>>>;
   /** optional NATS bridge (wired in createServer when `options.nats` is set) */
   bridge?: NatsBridge;
-  inboundHandlers: Map<EventName, InboundHandler>;
+  inboundHandlers: Map<string, InboundHandler>;
   topicHistory: Map<string, RingBuffer<{ seq: number; frame: Uint8Array }>>;
   replaySeq: number;
+  /** events-layer lifecycle hooks (wired by createServer when `events` is set) */
+  onConnect?: (ws: ServerWebSocket<WsData>) => void;
+  onDisconnect?: (ws: ServerWebSocket<WsData>) => void;
+  /** fired on ANY group membership change (auth seed, control frames, programmatic) */
+  onGroupChange?: (group: string, ws: ServerWebSocket<WsData>, joined: boolean) => void;
 }
 
-export function createServerState(options: IgnServerOptions): ServerState {
+export function createServerState<B extends Bindings = DefaultBindings>(
+  options: IgnServerOptions<B>,
+): ServerState {
+  const bindings = options.bindings ?? defaultBindings;
   return {
+    bindings,
+    transport: bindings === defaultBindings ? defaultTransport : createTransport(bindings),
     path: options.path ?? "/ws",
     inbound: new Set(options.inbound ?? []),
     bp: options.backpressure
@@ -162,11 +200,11 @@ export function createServerState(options: IgnServerOptions): ServerState {
       : null,
     metrics: createMetrics(),
     startedAt: Date.now(),
-    authenticate: options.authenticate,
-    allowedOrigins: options.allowedOrigins,
-    token: options.token,
-    maxConnections: options.maxConnections,
-    maxMessageSize: options.maxMessageSize,
+    ...(options.authenticate !== undefined ? { authenticate: options.authenticate } : {}),
+    ...(options.allowedOrigins !== undefined ? { allowedOrigins: options.allowedOrigins } : {}),
+    ...(options.token !== undefined ? { token: options.token } : {}),
+    ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
+    ...(options.maxMessageSize !== undefined ? { maxMessageSize: options.maxMessageSize } : {}),
     replay: options.replay ? { historySize: options.replay.historySize ?? 64 } : null,
     sockets: new Set(),
     clients: new Map(),

package/src/events/clients.ts

@@ -0,0 +1,156 @@
+/**
+ * Client store — the live registry of active connections, "who is connected,
+ * on whose behalf, and what the app remembers about them".
+ *
+ * - `byId: Map<clientId, EventClient>` — one record per socket.
+ * - `byUser: Map<userId, Set<clientId>>` — the reverse "on what behalf" index,
+ *   so a user with several tabs/devices is one logical target.
+ * - Each record carries a per-connection `data` store (created on attach,
+ *   dropped on detach) — `hub.setClientData` / `client.data` read/write it.
+ *
+ * Pure local state: cross-instance presence / state sync lives in `cluster.ts`
+ * and is driven FROM this store via the `onAttach` / `onDetach` hooks (which
+ * the hub wires to offloaded queue work, keeping connect/disconnect O(1)).
+ */
+import type { ServerWebSocket } from "bun";
+import type { WsData } from "../core/state";
+import { createClientData } from "./data";
+import type { ClientData, EventClient } from "./types";
+
+/** Factory for a client record bound to a live socket. */
+export function createEventClient(
+  ws: ServerWebSocket<WsData>,
+): EventClient {
+  const client: MutableEventClient = {
+    get id(): string {
+      return ws.data.id;
+    },
+    // `userId` is the identity this connection acts on behalf of — read live
+    // from the socket data (single source of truth; `setUserId` writes there).
+    get userId(): string | undefined {
+      return ws.data.userId;
+    },
+    get meta(): Record<string, unknown> | undefined {
+      return ws.data.meta;
+    },
+    data: createClientData(),
+    get groups(): ReadonlySet<string> {
+      return ws.data.groups;
+    },
+    get topics(): ReadonlySet<string> {
+      return ws.data.topics;
+    },
+    get connectedAt(): number {
+      return ws.data.connectedAt;
+    },
+    get ip(): string {
+      return ws.remoteAddress;
+    },
+    // plain mutable property — the store flips it to true on detach
+    closed: false,
+    get ws(): ServerWebSocket<WsData> {
+      return ws;
+    },
+  };
+  return client;
+}
+
+/** The client record with readonly modifiers stripped (internal mutation). */
+export type MutableEventClient = {
+  -readonly [K in keyof EventClient]: EventClient[K];
+};
+
+export interface ClientStore {
+  readonly size: number;
+  attach(ws: ServerWebSocket<WsData>): EventClient;
+  detach(ws: ServerWebSocket<WsData>): EventClient | undefined;
+  get(id: string): EventClient | undefined;
+  all(): EventClient[];
+  byUser(userId: string): EventClient[];
+  setUserId(clientId: string, userId: string): boolean;
+  onAttach(cb: (client: EventClient) => void): void;
+  onDetach(cb: (client: EventClient) => void): void;
+}
+
+export function createClientStore(): ClientStore {
+  const byId = new Map<string, MutableEventClient>();
+  const byUser = new Map<string, Set<string>>();
+  const attachCbs: Array<(client: EventClient) => void> = [];
+  const detachCbs: Array<(client: EventClient) => void> = [];
+
+  const indexUser = (client: EventClient): void => {
+    const userId = client.userId;
+    if (!userId) return;
+    let set = byUser.get(userId);
+    if (!set) {
+      set = new Set();
+      byUser.set(userId, set);
+    }
+    set.add(client.id);
+  };
+
+  const unindexUser = (client: EventClient): void => {
+    const userId = client.userId;
+    if (!userId) return;
+    const set = byUser.get(userId);
+    if (!set) return;
+    set.delete(client.id);
+    if (set.size === 0) byUser.delete(userId);
+  };
+
+  return {
+    get size(): number {
+      return byId.size;
+    },
+    attach(ws) {
+      const existing = byId.get(ws.data.id);
+      if (existing) return existing;
+      const client = createEventClient(ws);
+      byId.set(client.id, client);
+      indexUser(client);
+      for (const cb of attachCbs) cb(client);
+      return client;
+    },
+    detach(ws) {
+      const client = byId.get(ws.data.id);
+      if (!client) return undefined;
+      byId.delete(client.id);
+      unindexUser(client);
+      client.closed = true;
+      for (const cb of detachCbs) cb(client);
+      return client;
+    },
+    get(id) {
+      return byId.get(id);
+    },
+    all() {
+      return [...byId.values()];
+    },
+    byUser(userId) {
+      const ids = byUser.get(userId);
+      if (!ids) return [];
+      const out: EventClient[] = [];
+      for (const id of ids) {
+        const c = byId.get(id);
+        if (c) out.push(c);
+      }
+      return out;
+    },
+    setUserId(clientId, userId) {
+      const client = byId.get(clientId);
+      if (!client) return false;
+      client.ws.data.userId = userId;
+      unindexUser(client);
+      indexUser(client);
+      return true;
+    },
+    onAttach(cb) {
+      attachCbs.push(cb as (client: EventClient) => void);
+    },
+    onDetach(cb) {
+      detachCbs.push(cb as (client: EventClient) => void);
+    },
+  };
+}
+
+export type { ClientData };