@ignex/nova 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignex/nova",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "TypeBox-driven FlatBuffer transport: Rust FFI serializer + Bun WebSocket + typed pub/sub API for server and FE.",
   "license": "MIT",

package/public/events.ts

@@ -38,6 +38,7 @@ export {
   emitToGroup,
   emitToTopic,
   emitToUser,
+  emitToUserAnywhere,
   getEventsHub,
   isEventsBound,
   off,

package/src/core/client-state.ts

@@ -32,6 +32,14 @@ export interface IgnClientOptions<B extends Bindings = DefaultBindings> {
   heartbeatMs?: number;
   /** miss this many heartbeats before assuming the connection is dead, default 2 */
   heartbeatMisses?: number;
+  /**
+   * Buffer app-event `send()` calls made before the socket is open and flush
+   * them automatically on connect (default true). This lets new users write
+   * `client.send(...)` right after `createClient(...)` — even before
+   * `connect()` — without waiting for the `connected` status. Set `false` to
+   * keep the strict behaviour of throwing `"ignex: client is not connected"`.
+   */
+  queueSends?: boolean;
   /**
    * Gap-free delivery (requires the server started with `resume`): track the
    * server's per-connection delivery seqs, detect gaps, and automatically
@@ -77,6 +85,8 @@ export interface ClientState {
   pendingFrom: number;
   /** in-flight resume request flag (throttles re-asks) */
   resumeInFlight: boolean;
+  /** app frames queued while the socket was not open (flushed on open) */
+  pendingSends: Uint8Array[];
   /** force-flush timer for an unfillable gap */
   gapTimer: ReturnType<typeof setTimeout> | null;
   /** request/response: correlation id → pending call */
@@ -118,6 +128,7 @@ export function createClientState<B extends Bindings = DefaultBindings>(
     pending: new Map(),
     pendingFrom: 0,
     resumeInFlight: false,
+    pendingSends: [],
     gapTimer: null,
     rpcPending: new Map(),
     requestTimeoutMs: opts.requestTimeoutMs ?? 10_000,

package/src/core/client-wire.ts

@@ -29,6 +29,47 @@ export function sendControl<K extends ControlEventName>(
   sendFrame(state, state.bindings.encodeFrame(name, payload));
 }
 
+/**
+ * Send an encoded APP frame, queueing it until the socket is open.
+ *
+ * New-user friendly: `client.send(...)` immediately after `createClient(...)`
+ * (even before `connect()`) buffers the frame and flushes it once the socket
+ * opens — callers don't have to wait for the `connected` status. When
+ * `opts.queueSends` is `false` this throws `"ignex: client is not connected"`
+ * (the previous strict behaviour); a closed client always throws.
+ */
+export function sendFrameQueued(state: ClientState, frame: Uint8Array): void {
+  const ws = state.ws;
+  if (ws !== null && ws.readyState === WebSocket.OPEN) {
+    ws.send(frame as Uint8Array<ArrayBuffer>);
+    return;
+  }
+  if (state.closed) throw new Error("ignex: client is closed");
+  if (state.opts.queueSends === false) throw new Error("ignex: client is not connected");
+  state.pendingSends.push(frame);
+}
+
+/**
+ * Send every queued app frame in order. Called once the socket is open (after
+ * the `hello` + reconnect-subscribe control frames, which must precede app
+ * traffic). If the socket drops mid-flush the remainder stays queued.
+ */
+export function flushPendingSends(state: ClientState): void {
+  if (state.pendingSends.length === 0) return;
+  const ws = state.ws;
+  if (ws === null || ws.readyState !== WebSocket.OPEN) return;
+  const q = state.pendingSends;
+  state.pendingSends = [];
+  for (let i = 0; i < q.length; i++) {
+    const w = state.ws;
+    if (w !== ws || w.readyState !== WebSocket.OPEN) {
+      state.pendingSends = q.slice(i); // connection changed — put the rest back
+      return;
+    }
+    w.send(q[i]! as Uint8Array<ArrayBuffer>);
+  }
+}
+
 export function emitError(state: ClientState, err: Error): void {
   for (const cb of state.errorCbs) cb(err);
 }

package/src/core/client.ts

@@ -12,7 +12,14 @@
  */
 import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
 import { createClientState, setStatus, type ClientState, type ClientStatus, type IgnClientOptions } from "./client-state";
-import { handleMessage, emitError, sendControl, sendFrame, flushPending } from "./client-wire";
+import {
+  handleMessage,
+  emitError,
+  sendControl,
+  sendFrameQueued,
+  flushPendingSends,
+  flushPending,
+} from "./client-wire";
 import { startHeartbeat, stopHeartbeat } from "./client-heartbeat";
 import { scheduleReconnect } from "./client-reconnect";
 import { failAllPending, createRpcRequest } from "./client-rpc";
@@ -107,6 +114,9 @@ export function createClient<B extends Bindings = DefaultBindings>(
       });
       // re-subscribe topics from before the disconnect (server cleared them)
       for (const t of state.subscribedTopics) sendControl(state, "subscribe", { topic: t });
+      // deliver app events that were sent before the socket was open (send()
+      // queues by default — no need to wait for the connected status)
+      flushPendingSends(state);
       startHeartbeat(state);
     };
     ws.onmessage = (ev) => {
@@ -204,13 +214,14 @@ export function createClient<B extends Bindings = DefaultBindings>(
       }
       state.pending.clear();
       state.pendingFrom = 0;
+      state.pendingSends = []; // never delivered — drop the queued app frames
       failAllPending(state, new Error("ignex: client closed"));
       state.ws?.close();
       state.ws = null;
       setStatus(state, "closed");
     },
     send(name, payload) {
-      sendFrame(state, state.bindings.encodeFrame(name, payload));
+      sendFrameQueued(state, state.bindings.encodeFrame(name, payload));
     },
     request(name, payload, opts) {
       return createRpcRequest(

package/src/events/emit.ts

@@ -146,7 +146,13 @@ export function createEmitter(opts: EmitterOptions): EmitEngine {
       if (cluster) {
         const msgId = crypto.randomUUID();
         const traceId = parentTraceId ?? "";
-        if (opts.routeInstances !== undefined && (target.type === "client" || target.type === "user")) {
+        // `user … anywhere: true` forces the full-mesh wildcard publish instead
+        // of presence routing — the user is reached on EVERY instance/service in
+        // the mesh, regardless of where presence thinks they are.
+        const routeable =
+          target.type === "client" ||
+          (target.type === "user" && target.anywhere !== true);
+        if (opts.routeInstances !== undefined && routeable) {
           // ROUTED targeted delivery: only the owning instances receive it
           const instances = opts.routeInstances(target);
           if (instances !== null) {

package/src/events/global.ts

@@ -68,6 +68,18 @@ export function emitToUser<K extends EventName>(userId: string, name: K, payload
   requireHub().emitToUser(userId, name as never, payload as never);
 }
 
+/**
+ * Deliver to the user on EVERY instance/service in the cluster mesh (full
+ * mesh, no presence routing) — reaches the user wherever they are connected.
+ */
+export function emitToUserAnywhere<K extends EventName>(
+  userId: string,
+  name: K,
+  payload: Events[K],
+): void {
+  requireHub().emitToUserAnywhere(userId, name as never, payload as never);
+}
+
 export function emitToClient<K extends EventName>(
   clientId: string,
   name: K,

package/src/events/hub/context-factory.ts

@@ -38,6 +38,8 @@ export function createContextFactory<B extends Bindings>(deps: {
       emit: (name, payload, target) => hub.emit(name as never, payload as never, target),
       emitToGroup: (group, name, payload) => hub.emitToGroup(group, name as never, payload as never),
       emitToUser: (userId, name, payload) => hub.emitToUser(userId, name as never, payload as never),
+      emitToUserAnywhere: (userId, name, payload) =>
+        hub.emitToUserAnywhere(userId, name as never, payload as never),
       emitToClient: (clientId, name, payload) =>
         hub.emitToClient(clientId, name as never, payload as never),
       emitToTopic: (topic, name, payload) => hub.emitToTopic(topic, name as never, payload as never),

package/src/events/hub/index.ts

@@ -364,6 +364,14 @@ export function createEventsHub<B extends Bindings = DefaultBindings>(
     emitToUser(userId, name, payload) {
       api.emit(name, payload, { type: "user", userId });
     },
+    /**
+     * Deliver to the user on EVERY instance/service in the cluster mesh — an
+     * explicit full-mesh emit (no presence routing). Use when the user may be
+     * connected to any service sharing the cluster transport.
+     */
+    emitToUserAnywhere(userId, name, payload) {
+      api.emit(name, payload, { type: "user", userId, anywhere: true });
+    },
     emitToClient(clientId, name, payload) {
       api.emit(name, payload, { type: "client", clientId });
     },

package/src/events/index.ts

@@ -23,6 +23,7 @@ export {
   emitToGroup,
   emitToTopic,
   emitToUser,
+  emitToUserAnywhere,
   getEventsHub,
   isEventsBound,
   off,

package/src/events/types/context.ts

@@ -33,6 +33,8 @@ export interface EventContext<B extends Bindings = DefaultBindings> {
   emit<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K], target?: EmitTarget): void;
   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;
+  /** Deliver to the user on every instance/service in the cluster mesh. */
+  emitToUserAnywhere<K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]): void;
   emitToClient<K extends EventNameOf<B>>(clientId: string, name: K, payload: EventsOf<B>[K]): void;
   emitToTopic<K extends EventNameOf<B>>(topic: string, name: K, payload: EventsOf<B>[K]): void;
 }

package/src/events/types/emit-target.ts

@@ -13,6 +13,9 @@
  *   - `{ type: "topic", topic }` — subscribers of a topic (rooms + replay).
  *   - `{ type: "group", group }` — members of a server-side group.
  *   - `{ type: "user", userId }` — every socket acting on behalf of `userId`.
+ *   - `{ type: "user", userId, anywhere: true }` — same, but ALWAYS fanned out
+ *     to every instance/service in the cluster mesh (ignores presence routing), so
+ *     the user is reached no matter which instance holds their socket.
  *   - `{ type: "client", clientId }` — one specific connection.
  *
  * Local delivery is synchronous and allocation-free (the transport scratch +
@@ -23,7 +26,7 @@ export type EmitTarget =
   | { type: "broadcast" }
   | { type: "topic"; topic: string }
   | { type: "group"; group: string }
-  | { type: "user"; userId: string }
+  | { type: "user"; userId: string; anywhere?: true }
   | { type: "client"; clientId: string };
 
 export type EmitTargetKind = EmitTarget["type"];

package/src/events/types/hub.ts

@@ -45,6 +45,11 @@ export interface EventsHub<B extends Bindings = DefaultBindings> {
   emitToTopic<K extends EventNameOf<B>>(topic: string, name: K, payload: EventsOf<B>[K]): void;
   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;
+  /**
+   * Deliver to the user on EVERY instance/service in the cluster mesh (full
+   * mesh, no presence routing) — reaches the user wherever they are.
+   */
+  emitToUserAnywhere<K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]): void;
   emitToClient<K extends EventNameOf<B>>(clientId: string, name: K, payload: EventsOf<B>[K]): void;
 
   // ── client records ("who is connected, on whose behalf") ──────────────