@ignex/nova 0.1.1 → 0.1.3

package/src/core/client-state.ts

@@ -3,7 +3,9 @@
  * explicit state object the client action functions read/mutate. The option /
  * status types are the PUBLIC surface and are re-exported by `public/client.ts`.
  */
-import type { EventName, Events } from "../schema";
+
+import { defaultBindings } from "../bindings/default";
+import type { Bindings, DefaultBindings } from "../bindings/types";
 
 export type ClientStatus = "connecting" | "connected" | "disconnected" | "reconnecting" | "closed";
 
@@ -16,7 +18,14 @@ export interface IgnReconnectOptions {
   jitter?: boolean;
 }
 
-export interface IgnClientOptions {
+export interface IgnClientOptions<B extends Bindings = DefaultBindings> {
+  /**
+   * The wire stack (event ids, decoders, encoders). Defaults to the built-in
+   * registry; pass your own (from `generateBindings` + `assembleBindings`) to
+   * speak YOUR schema. When provided, the client API (`on` / `send` / ...) is
+   * typed against your `Events`.
+   */
+  bindings?: B;
   /** auto-reconnect on unexpected close, default false (boolean or options) */
   reconnect?: boolean | IgnReconnectOptions;
   /** app-level ping interval in ms (0 disables), default 15000 */
@@ -25,14 +34,14 @@ export interface IgnClientOptions {
   heartbeatMisses?: number;
 }
 
-type Handler<K extends EventName> = (payload: Events[K]) => void;
-
 export interface ClientState {
   url: string;
-  opts: IgnClientOptions;
+  opts: IgnClientOptions<Bindings>;
+  /** the wire stack this client speaks (ids / decoders / encoders). */
+  bindings: Bindings;
   ws: WebSocket | null;
-  handlers: Map<EventName, Set<Handler<never>>>;
-  anyHandlers: Set<(name: EventName, payload: unknown) => void>;
+  handlers: Map<string, Set<(payload: unknown) => void>>;
+  anyHandlers: Set<(name: string, payload: unknown) => void>;
   errorCbs: Set<(err: Error) => void>;
   statusCbs: Set<(status: ClientStatus) => void>;
   closed: boolean;
@@ -48,10 +57,14 @@ export interface ClientState {
   groups: string[];
 }
 
-export function createClientState(url: string, opts: IgnClientOptions = {}): ClientState {
+export function createClientState<B extends Bindings = DefaultBindings>(
+  url: string,
+  opts: IgnClientOptions<B> = {},
+): ClientState {
   return {
     url,
     opts,
+    bindings: opts.bindings ?? defaultBindings,
     ws: null,
     handlers: new Map(),
     anyHandlers: new Set(),

package/src/core/client-wire.ts

@@ -1,11 +1,10 @@
 /**
  * Client wire handling — outbound frame sends + inbound decode/dispatch.
  * `handleMessage` decodes the envelope, filters control frames, and fans app
- * events out to the registered handlers.
+ * events out to the registered handlers. All decode/encode goes through
+ * `state.bindings`, so a client speaks whatever wire stack it was given.
  */
-import { decodeFrame, isControlId, WIRE_VERSION } from "../generated/registry";
-import { encodeEventFrame } from "../generated/ts-ser";
-import type { ControlEventName, ControlEvents, EventName } from "../schema";
+import type { ControlEventName, ControlEvents } from "../schema";
 import type { ClientState } from "./client-state";
 
 /** Send an encoded frame, if the socket is open. */
@@ -21,7 +20,7 @@ export function sendControl<K extends ControlEventName>(
   name: K,
   payload: ControlEvents[K],
 ): void {
-  sendFrame(state, encodeEventFrame(name, payload));
+  sendFrame(state, state.bindings.encodeFrame(name, payload));
 }
 
 export function emitError(state: ClientState, err: Error): void {
@@ -32,10 +31,10 @@ export function handleControl(state: ClientState, name: ControlEventName, payloa
   switch (name) {
     case "hello": {
       const p = payload as ControlEvents["hello"];
-      if (p.version !== WIRE_VERSION) {
+      if (p.version !== state.bindings.wireVersion) {
         // server speaks a different wire version — refuse + surface
         state.ws?.close(1002, "wire version mismatch");
-        emitError(state, new Error(`ignex: server wire version ${p.version} does not match ${WIRE_VERSION}`));
+        emitError(state, new Error(`ignex: server wire version ${p.version} does not match ${state.bindings.wireVersion}`));
       }
       break;
     }
@@ -56,17 +55,17 @@ export function handleControl(state: ClientState, name: ControlEventName, payloa
 export function handleMessage(state: ClientState, data: ArrayBuffer | string): void {
   if (typeof data === "string") return; // ignore text frames
   const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : (data as Uint8Array);
-  const frame = decodeFrame(bytes);
+  const frame = state.bindings.decodeFrame(bytes);
   if (!frame) {
     emitError(state, new Error("ignex: undecodable / version-mismatched frame dropped"));
     return;
   }
-  if (isControlId(frame.id)) {
+  if (state.bindings.isControlId(frame.id)) {
     handleControl(state, frame.name as ControlEventName, frame.payload);
     return;
   }
-  const name = frame.name as EventName;
+  const name = frame.name;
   const set = state.handlers.get(name);
-  if (set) for (const cb of set) cb(frame.payload as never);
+  if (set) for (const cb of set) cb(frame.payload);
   for (const cb of state.anyHandlers) cb(name, frame.payload);
 }

package/src/core/client.ts

@@ -4,40 +4,42 @@
  * ONLY place that knows how the pieces fit together; `connect` lives here
  * because it owns the socket lifecycle.
  *
+ * Generic over the wire stack: `createClient(url, { bindings })` with your own
+ * generated bindings types `on` / `send` / ... against YOUR events. The default
+ * is the built-in registry, so existing code keeps working unchanged.
+ *
  * Public entry: `public/client.ts` re-exports `createClient` + the types.
  */
-import { WIRE_VERSION } from "../generated/registry";
-import { encodeEventFrame } from "../generated/ts-ser";
-import type { Events, EventName } from "../schema";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
 import { createClientState, setStatus, type ClientState, type ClientStatus, type IgnClientOptions } from "./client-state";
 import { handleMessage, sendControl, sendFrame } from "./client-wire";
 import { startHeartbeat, stopHeartbeat } from "./client-heartbeat";
 import { scheduleReconnect } from "./client-reconnect";
 
 /** The public client API (returned by `createClient`). */
-export interface IgnClient {
-  on<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
-  off<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+export interface IgnClient<B extends Bindings = DefaultBindings> {
+  on<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
+  off<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
   /** Register a handler that fires once for the event, then removes itself. */
-  once<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+  once<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
   /** Register a handler for EVERY incoming app event (name + payload). */
-  onAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
-  offAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
+  onAny(cb: (name: EventNameOf<B>, payload: unknown) => void): IgnClient<B>;
+  offAny(cb: (name: EventNameOf<B>, payload: unknown) => void): IgnClient<B>;
   /** Names that currently have at least one handler. */
-  events(): EventName[];
+  events(): EventNameOf<B>[];
   /** Remove all handlers (optionally just for one event). */
-  removeAllListeners(name?: EventName): IgnClient;
+  removeAllListeners(name?: EventNameOf<B>): IgnClient<B>;
   /** Register an error callback (decode failures, wire-version mismatch). */
-  onError(cb: (err: Error) => void): IgnClient;
-  offError(cb: (err: Error) => void): IgnClient;
+  onError(cb: (err: Error) => void): IgnClient<B>;
+  offError(cb: (err: Error) => void): IgnClient<B>;
   /** Watch connection lifecycle: "connecting" | "connected" | "disconnected" | "reconnecting" | "closed". */
-  onStatus(cb: (status: ClientStatus) => void): IgnClient;
-  offStatus(cb: (status: ClientStatus) => void): IgnClient;
+  onStatus(cb: (status: ClientStatus) => void): IgnClient<B>;
+  offStatus(cb: (status: ClientStatus) => void): IgnClient<B>;
   readonly currentStatus: ClientStatus;
-  connect(): IgnClient;
+  connect(): IgnClient<B>;
   close(): void;
   /** Send a typed app event to the server (server must allow it via `inbound`). */
-  send<K extends EventName>(name: K, payload: Events[K]): void;
+  send<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
   /** Ask the server to subscribe this socket to a topic (room membership + replay). */
   subscribe(topic: string): void;
   unsubscribe(topic: string): void;
@@ -50,10 +52,13 @@ export interface IgnClient {
   readonly groups: string[];
 }
 
-export function createClient(url: string, opts: IgnClientOptions = {}): IgnClient {
+export function createClient<B extends Bindings = DefaultBindings>(
+  url: string,
+  opts: IgnClientOptions<B> = {},
+): IgnClient<B> {
   const state: ClientState = createClientState(url, opts);
 
-  function connect(): IgnClient {
+  function connect(): IgnClient<B> {
     state.closed = false;
     setStatus(state, state.attempts === 0 ? "connecting" : "reconnecting");
     const ws = new WebSocket(url);
@@ -61,7 +66,7 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
     ws.onopen = () => {
       state.attempts = 0;
       setStatus(state, "connected");
-      sendControl(state, "hello", { version: WIRE_VERSION, caps: [], lastSeq: 0 });
+      sendControl(state, "hello", { version: state.bindings.wireVersion, caps: [], lastSeq: 0 });
       // re-subscribe topics from before the disconnect (server cleared them)
       for (const t of state.subscribedTopics) sendControl(state, "subscribe", { topic: t });
       startHeartbeat(state);
@@ -80,38 +85,38 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
     return api;
   }
 
-  const api: IgnClient = {
+  const api: IgnClient<B> = {
     on(name, handler) {
       let set = state.handlers.get(name);
       if (!set) {
         set = new Set();
         state.handlers.set(name, set);
       }
-      set.add(handler as never);
+      set.add(handler as (payload: unknown) => void);
       return api;
     },
     off(name, handler) {
-      state.handlers.get(name)?.delete(handler as never);
+      state.handlers.get(name)?.delete(handler as (payload: unknown) => void);
       return api;
     },
     once(name, handler) {
-      const wrap = (payload: never): void => {
+      const wrap = (payload: unknown): void => {
         api.off(name, wrap as never);
-        handler(payload);
+        (handler as (payload: unknown) => void)(payload);
       };
       api.on(name, wrap as never);
       return api;
     },
     onAny(cb) {
-      state.anyHandlers.add(cb);
+      state.anyHandlers.add(cb as (name: string, payload: unknown) => void);
       return api;
     },
     offAny(cb) {
-      state.anyHandlers.delete(cb);
+      state.anyHandlers.delete(cb as (name: string, payload: unknown) => void);
       return api;
     },
     events() {
-      return [...state.handlers.keys()];
+      return [...state.handlers.keys()] as EventNameOf<B>[];
     },
     removeAllListeners(name) {
       if (name) state.handlers.delete(name);
@@ -148,7 +153,7 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
       setStatus(state, "closed");
     },
     send(name, payload) {
-      sendFrame(state, encodeEventFrame(name, payload));
+      sendFrame(state, state.bindings.encodeFrame(name, payload));
     },
     subscribe(topic) {
       state.subscribedTopics.add(topic);

package/src/core/groups.ts

@@ -21,6 +21,8 @@ export function joinGroup(state: ServerState, ws: ServerWebSocket<WsData>, group
     state.groups.set(group, set);
   }
   set.add(ws);
+  // events-layer hook (auth seed, control frames, programmatic joins all pass here)
+  state.onGroupChange?.(group, ws, true);
 }
 
 /** Remove `ws` from `group`; prune the group when it becomes empty. */
@@ -30,6 +32,7 @@ export function leaveGroup(state: ServerState, ws: ServerWebSocket<WsData>, grou
   if (!set) return;
   set.delete(ws);
   if (set.size === 0) state.groups.delete(group);
+  state.onGroupChange?.(group, ws, false);
 }
 
 /** Fan `frame` out to every member of `group` (no replay). */

package/src/core/metrics.ts

@@ -9,6 +9,8 @@ export interface PathCounts {
   direct: number;
   /** encodes that fell back to the JSON path (nested/unions or disabled symbol) */
   json: number;
+  /** encodes via the pure-JS encoder (user schema without a native addon) */
+  js: number;
 }
 
 export interface MetricsSnapshot {
@@ -29,7 +31,7 @@ export interface MetricsSnapshot {
   /** undecodable / version-mismatched / unknown-id frames received */
   protocolErrors: number;
   bytesSent: number;
-  /** per-event encode path counts (direct vs json) */
+  /** per-event encode path counts (direct vs json vs js) */
   pathCounts: Record<string, PathCounts>;
   connectedClients: number;
   uptimeMs: number;
@@ -41,6 +43,8 @@ export interface MetricsSnapshot {
   bridgeInboundErrors?: number;
   /** "connected" | "connecting" | "closed" (undefined when no bridge) */
   natsStatus?: string;
+  /** events-layer counters (present only when `createServer({ events })` is used) */
+  events?: import("../events/types").EventsMetricsSnapshot;
 }
 
 export interface Metrics {
@@ -55,7 +59,7 @@ export interface Metrics {
   bytesSent: number;
   readonly pathCounts: Map<string, PathCounts>;
   /** Count an encode on a given path for an event (direct = zero-alloc FFI). */
-  countPath(name: string, path: "direct" | "json"): void;
+  countPath(name: string, path: "direct" | "json" | "js"): void;
   snapshot(connectedClients: number): MetricsSnapshot;
 }
 
@@ -76,7 +80,7 @@ export function createMetrics(startedAt = Date.now()): Metrics {
     countPath(name, path) {
       let pc = pathCounts.get(name);
       if (!pc) {
-        pc = { direct: 0, json: 0 };
+        pc = { direct: 0, json: 0, js: 0 };
         pathCounts.set(name, pc);
       }
       pc[path]++;

package/src/core/outbound.ts

@@ -4,11 +4,10 @@
  * `decide()` result; `doSend` is the single accounting point.
  */
 import type { ServerWebSocket } from "bun";
-import { encodeToScratch } from "../transport/transport";
+import type { ControlEventName, ControlEvents } from "../schema";
 import { decide } from "./backpressure";
 import { RingBuffer } from "./ring";
 import type { ServerState, WsData } from "./state";
-import type { ControlEventName, ControlEvents } from "../schema";
 
 /** Actual socket write + counters (single accounting point). */
 export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
@@ -24,7 +23,11 @@ export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: U
  * replaced by a bounded queue (drop-oldest) / skip (drop-newest) / close
  * (disconnect).
  */
-export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
+export function sendFrame(
+  state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  frame: Uint8Array,
+): void {
   const bp = state.bp;
   if (!bp) {
     doSend(state, ws, frame);
@@ -44,7 +47,11 @@ export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame
       return;
     case "enqueue": {
       // RingBuffer: O(1) push + drop-from-head (no array shift() memmove).
-      const q = (ws.data.queue ??= new RingBuffer<Uint8Array>());
+      let q = ws.data.queue;
+      if (q === undefined) {
+        q = new RingBuffer<Uint8Array>();
+        ws.data.queue = q;
+      }
       q.push(frame.slice()); // owned copy for the queue
       for (let i = 0; i < d.dropHead; i++) {
         q.shift();
@@ -72,5 +79,5 @@ export function sendControl<K extends ControlEventName>(
   name: K,
   payload: ControlEvents[K],
 ): void {
-  sendFrame(state, ws, encodeToScratch(name, payload));
+  sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
 }

package/src/core/routing.ts

@@ -10,8 +10,7 @@
  * going to discard.
  */
 import type { ServerWebSocket } from "bun";
-import { decodePayload, isControlId, readFrameHeader, WIRE_VERSION } from "../generated/registry";
-import type { ControlEventName, ControlEvents, EventName } from "../schema";
+import type { ControlEventName, ControlEvents } from "../schema";
 import { sendControl } from "./outbound";
 import { joinRoom, leaveRoom } from "./rooms";
 import { joinGroup, leaveGroup } from "./groups";
@@ -31,20 +30,30 @@ export function handleMessage(
     ws.close(1009, "message too big");
     return;
   }
-  const header = readFrameHeader(bytes);
+  const header = state.bindings.readFrameHeader(bytes);
   if (!header) {
     state.metrics.protocolErrors++;
     return; // undecodable / wrong version / unknown id — drop
   }
-  if (isControlId(header.id)) {
+  if (state.bindings.isControlId(header.id)) {
     state.metrics.inboundControl++;
-    handleControl(state, ws, header.name as ControlEventName, decodePayload(header.id, bytes) as never);
+    handleControl(state, ws, header.name as ControlEventName, state.bindings.decodePayload(header.id, bytes) as never);
     return;
   }
-  const name = header.name as EventName;
+  const name = header.name;
   if (!state.inbound.has(name)) return; // not an allowed inbound event — no payload decode
   state.metrics.inbound++;
-  state.inboundHandlers.get(name)?.(decodePayload(header.id, bytes), ws);
+  state.inboundHandlers.get(name)?.(state.bindings.decodePayload(header.id, bytes), ws);
+  // Horizontal scaling: when the bridge is configured with `bridgeClientEvents`,
+  // every accepted client event is re-published to `{prefix}.inbound.<event>` so
+  // OTHER server instances (and BE consumers) receive it. NATS-inbound frames
+  // arrive via `onInbound` → `fanOutAll` (never through this path), so there is
+  // no loop; this server's own clients are re-delivered exactly once through its
+  // own inbound subscription (the app handler should therefore not ALSO
+  // broadcast, or the event would be delivered twice locally).
+  if (state.bridge?.clientEvents) {
+    state.bridge.publish(state.bridge.subjects.inboundEvent(name), bytes);
+  }
 }
 
 export function handleControl(
@@ -58,7 +67,7 @@ export function handleControl(
       const p = payload as ControlEvents["hello"];
       ws.data.version = p.version;
       ws.data.lastSeq = p.lastSeq;
-      if (p.version !== WIRE_VERSION) {
+      if (p.version !== state.bindings.wireVersion) {
         // protocol version mismatch — refuse this client
         ws.close(1002, "wire version mismatch");
       }