@ignex/nova 0.1.3 → 0.1.5

package/public/generate.ts

@@ -95,6 +95,32 @@ export interface GenerateOptions {
   wireVersion?: number;
   /** overwrite `outDir` if it exists, default true. */
   force?: boolean;
+  /**
+   * Emit a typed FRONTEND client (`<outDir>/client.gen.ts`): the assembled
+   * app bindings + a `createRealtimeClient(url, options?)` factory typed
+   * against YOUR events (the realtime analog of the generated OpenAPI SDK).
+   *
+   * ```ts
+   * // generated client.gen.ts
+   * import { createRealtimeClient } from "./generated/client.gen";
+   * const client = createRealtimeClient("ws://host/ws", { reconnect: true });
+   * client.on("chat.message", (m) => /* m: ChatMessagePayload *\/);
+   * client.send("chat.send", { orderId, body, clientTs });
+   * ```
+   *
+   * `schemaImport` is required: the emitted client assembles bindings from
+   * YOUR TypeBox registry (`makeBindings(schema)`), so it must point at the
+   * same `{ schemas, events, controlEvents }` object passed here (relative
+   * to the emitted file's location in `outDir`).
+   */
+  client?: {
+    /** specifier for the generated wire stack (`makeBindings`), default "./index". */
+    wireImport?: string;
+    /** specifier for YOUR TypeBox registry, relative to the emitted file. Required. */
+    schemaImport: string;
+    /** emitted filename inside `outDir`, default "client.gen.ts". */
+    outFile?: string;
+  };
 }
 
 export interface GeneratedBindings {
@@ -159,12 +185,62 @@ codegen-units = 1
   return { lib, ffi, cargo };
 }
 
+/**
+ * Emit the typed FRONTEND client module (see `GenerateOptions.client`).
+ * The client assembles the app bindings from YOUR schema and exposes a
+ * typed `createRealtimeClient` factory — `on`/`send` are statically checked
+ * against the app's event names, so no `as never` casts are needed on the FE.
+ */
+function emitClientModel(
+  model: Model,
+  wireImport: string,
+  schemaImport: string,
+  libraryImport: string,
+): string {
+  const eventNames = model.events
+    .filter((e) => !e.control)
+    .map((e) => `"${e.name}"`)
+    .join(" | ");
+  const lines: string[] = [];
+  lines.push("// @generated by ignex-nova generate — DO NOT EDIT");
+  lines.push("// Typed frontend realtime client (the realtime analog of the generated OpenAPI SDK).");
+  lines.push(`import { createClient } from ${JSON.stringify(libraryImport.replace(/\/bindings$/, "/client"))};`);
+  lines.push(`import type { IgnClient, IgnClientOptions } from ${JSON.stringify(libraryImport.replace(/\/bindings$/, "/client"))};`);
+  lines.push(`import { makeBindings } from ${JSON.stringify(wireImport)};`);
+  lines.push(`import * as schema from ${JSON.stringify(schemaImport)};`);
+  lines.push("");
+  lines.push("/** The app's assembled runtime bindings (typed against your events). */");
+  lines.push("export const bindings = makeBindings(schema);");
+  lines.push("export type RealtimeBindings = typeof bindings;");
+  lines.push("export type RealtimeClient = IgnClient<RealtimeBindings>;");
+  lines.push("");
+  lines.push("/** Event names your client can send/observe (derived from the schema). */");
+  lines.push(`export type RealtimeEventName = ${eventNames || "never"};`);
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Create a typed realtime client. `on`/`send` are checked against");
+  lines.push(" * RealtimeEventName — payload types flow from the generated registry.");
+  lines.push(" */");
+  lines.push("export const createRealtimeClient = (");
+  lines.push("  url: string,");
+  lines.push('  options?: Omit<IgnClientOptions<RealtimeBindings>, "bindings">,');
+  lines.push("): RealtimeClient => createClient(url, { ...options, bindings });");
+  lines.push("");
+  return lines.join("\n");
+}
+
 export function generateBindings(
   schema: SchemaRegistry,
   options: GenerateOptions = {},
 ): GeneratedBindings {
   const wireVersion = options.wireVersion ?? WIRE_VERSION;
-  const libraryImport = options.libraryImport ?? "@ignex/nova";
+  // Default: the FFI-free entry points. The package barrel ("@ignex/nova")
+  // pulls in bun:ffi at import time, which breaks vitest/node/browser module
+  // runners consuming generated bindings. Custom libraryImport values (e.g. a
+  // relative path to the repo in tests) keep the legacy single-import behavior.
+  const isDefaultLib = options.libraryImport === undefined || options.libraryImport === "@ignex/nova";
+  const libraryImport = options.libraryImport ?? "@ignex/nova/bindings";
+  const helperImport = isDefaultLib ? "@ignex/nova/internal" : libraryImport;
 
   // The standard transport control protocol is always present; users may add
   // custom control events but never override the standard ones.
@@ -246,8 +322,16 @@ export function generateBindings(
   }
 
   // Generated TS stack (user mode: self-contained local types + library imports)
-  files["registry.ts"] = emitRegistry(model, fingerprint, { schemaImport: null, libraryImport });
-  files["direct-ser.ts"] = emitDirectSer(model, { schemaImport: null, libraryImport });
+  // registry + direct-ser need the runtime HELPERS (@ignex/nova/internal in the
+  // default case); index.ts needs assembleBindings (@ignex/nova/bindings).
+  files["registry.ts"] = emitRegistry(model, fingerprint, {
+    schemaImport: null,
+    libraryImport: helperImport,
+  });
+  files["direct-ser.ts"] = emitDirectSer(model, {
+    schemaImport: null,
+    libraryImport: helperImport,
+  });
   files["ts-ser.ts"] = emitTsSer(model, { schemaImport: null });
 
   const subjectPrefix = options.subjectPrefix ?? "ignex";
@@ -261,6 +345,16 @@ export function generateBindings(
     fingerprint,
   );
 
+  if (options.client) {
+    const clientFile = options.client.outFile ?? "client.gen.ts";
+    files[clientFile] = emitClientModel(
+      model,
+      options.client.wireImport ?? "./index",
+      options.client.schemaImport,
+      libraryImport,
+    );
+  }
+
   files["README.md"] = emitReadme();
 
   const write = (): string[] => {

package/public/server.ts

@@ -30,6 +30,8 @@ export { createNatsBridge } from "../src/bridge/nats";
 export type { Int64GuardMode } from "../src/core/int64-guard";
 export type { MetricsSnapshot } from "../src/core/metrics";
 export { type ClientInfo, createServer, type IgnServer } from "../src/core/server";
+// Durable topic log (replay seam) — `createServer({ topicLog })` + adapters.
+export { createMemoryTopicLog, type LoggedFrame, type TopicLog } from "../src/core/topic-log";
 export type {
   AuthResult,
   BackpressurePolicy,
@@ -40,6 +42,7 @@ export type {
 } from "../src/core/state";
 // Events layer — re-exported so `createServer({ events })` is fully typed
 // without a separate import (the runtime API is `@ignex/nova/events`).
+export type { DeliveryPolicy } from "../src/events/delivery";
 export type {
   ClientData,
   ClientGroup,
@@ -59,3 +62,10 @@ export type {
   ServerEventHandler,
   UserGroup,
 } from "../src/events/types";
+// Event trace (debugger visibility) — `server.getEventTrace()` surface types.
+export type {
+  EventTraceOptions,
+  EventTraceRow,
+  EventTraceStats,
+  TraceDirection,
+} from "../src/events/trace";