@ignex/nova 0.1.5 → 0.1.6

package/package.json

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

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(