@ignex/nova 0.1.1 → 0.1.3

package/src/codegen/registry-gen.ts

@@ -0,0 +1,242 @@
+import { WIRE_HEADER_LEN, WIRE_VERSION } from "./constants";
+import { eventId } from "./hash";
+import type { EmitContext, FieldDef, Model } from "./schema-model";
+import { plainTsType, toSnake } from "./schema-model";
+
+/**
+ * Generated TS registry shared by BOTH sides:
+ *   - server: `eventNameToId` for `encodeEvent`
+ *   - client: `eventIdToDecoder` + `decodeFrame` for the standard `on(...)` API
+ *
+ * The `*ToPlain` adaptors convert flatc `unpack()` output (snake_case fields,
+ * numeric enums, bigint int64) into the exact `Events[K]` plain-object shape.
+ * Event-root adaptors are typed against `Events[K]` (compile-time check); nested
+ * adaptors infer their object shape.
+ *
+ * Event ids are STABLE FNV-1a 32-bit hashes of the event name (not insertion
+ * order), so schema reordering / field additions no longer renumber the wire
+ * format. The frame envelope is `[WIRE_VERSION:1][event_id:u32 LE][size-prefixed
+ * FlatBuffer]` — see `scripts/constants.ts`.
+ *
+ * `ctx.schemaImport === null` (user-mode generation) emits self-contained local
+ * `Events` / `ControlEvents` payload types instead of importing the app schema.
+ */
+export function emitRegistry(m: Model, fingerprint: number, ctx: EmitContext = {}): string {
+  const enumValues = new Map(m.enums.map((e) => [e.name, e.values]));
+
+  // tables reachable from an event root
+  const needed = new Set<string>();
+  const visit = (name: string) => {
+    if (needed.has(name)) return;
+    needed.add(name);
+    const t = m.tables.find((t) => t.name === name)!;
+    for (const f of t.fields) {
+      if (f.kind === "table" || f.kind === "vector-table") visit(f.tableName!);
+    }
+  };
+  for (const ev of m.events) visit(ev.tableName);
+  const neededTables = m.tables.filter((t) => needed.has(t.name));
+
+  const userMode = ctx.schemaImport === null;
+  const schemaImport = userMode ? "" : (ctx.schemaImport ?? "../schema");
+  const poolImport = userMode
+    ? (ctx.libraryImport ?? "@ignex/nova")
+    : "../transport/byte-buffer-pool";
+
+  const lines: string[] = [];
+  lines.push("// @ts-nocheck — generated file: not subject to hand-typed strictness gates");
+  lines.push("// @generated by src/codegen/registry-gen.ts — DO NOT EDIT");
+  lines.push('import * as flatbuffers from "flatbuffers";');
+  lines.push(`import { pooledByteBuffer } from ${JSON.stringify(poolImport)};`);
+  lines.push("");
+  lines.push("import {");
+  for (const t of neededTables) {
+    lines.push(`  ${t.name},`);
+  }
+  for (const t of neededTables) {
+    lines.push(`  type ${t.name}T,`);
+  }
+  lines.push('} from "./ts/backend";');
+  if (!userMode) {
+    lines.push(
+      `import type { AnyEventName, ControlEventName, ControlEvents, Events, EventName } from ${JSON.stringify(schemaImport)};`,
+    );
+  }
+  lines.push("");
+  lines.push(`export const WIRE_VERSION = ${WIRE_VERSION};`);
+  lines.push(`export const WIRE_HEADER_LEN = ${WIRE_HEADER_LEN}; // [version:1][event_id:u32 LE]`);
+  lines.push(`export const SCHEMA_FINGERPRINT = ${fingerprint}; // fnv1a32(canonical model)`);
+  lines.push("");
+  const appEvents = m.events.filter((e) => !e.control);
+  const controlEvents = m.events.filter((e) => e.control);
+  if (userMode) lines.push(...emitLocalTypes(m, neededTables, appEvents, controlEvents));
+  lines.push("export const eventNameToId: Record<EventName, number> = {");
+  for (const ev of appEvents)
+    lines.push(`  ${ev.name}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
+  lines.push("};");
+  lines.push("");
+  lines.push("export const controlEventNameToId: Record<ControlEventName, number> = {");
+  for (const ev of controlEvents)
+    lines.push(`  ${ev.name}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
+  lines.push("};");
+  lines.push("");
+  lines.push("/** merged app + control registry (used by encodeToScratch / JS encoder). */");
+  lines.push("export const anyEventNameToId: Record<string, number> = {");
+  for (const ev of m.events) lines.push(`  ${ev.name}: ${eventId(ev.name)},`);
+  lines.push("};");
+  lines.push("");
+  lines.push("export const idToEventName: Record<number, EventName> = {");
+  for (const ev of appEvents) lines.push(`  ${eventId(ev.name)}: ${JSON.stringify(ev.name)},`);
+  lines.push("};");
+  lines.push("");
+  lines.push("/** merged app + control id → name lookup (decode dispatch). */");
+  lines.push("export const idToAnyEventName: Record<number, AnyEventName> = {");
+  for (const ev of m.events) lines.push(`  ${eventId(ev.name)}: ${JSON.stringify(ev.name)},`);
+  lines.push("};");
+  lines.push("");
+  lines.push("export type DecodeFn = (bb: flatbuffers.ByteBuffer) => unknown;");
+  lines.push("");
+  lines.push("export const eventIdToDecoder: Record<number, DecodeFn> = {");
+  for (const ev of m.events) {
+    const plain = toSnake(ev.tableName);
+    lines.push(
+      `  ${eventId(ev.name)}: (bb) => ${plain}ToPlain(${ev.tableName}.getSizePrefixedRootAs${ev.tableName}(bb).unpack()),`,
+    );
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push("const controlIds = new Set<number>([");
+  for (const ev of controlEvents) lines.push(`  ${eventId(ev.name)},`);
+  lines.push("]);");
+  lines.push("export function isControlId(id: number): boolean { return controlIds.has(id); }");
+  lines.push("");
+  lines.push(
+    "export function readFrameHeader(bytes: Uint8Array): { name: AnyEventName; id: number } | null {",
+  );
+  lines.push("  if (bytes.byteLength < WIRE_HEADER_LEN) return null;");
+  lines.push("  if (bytes[0] !== WIRE_VERSION) return null; // version mismatch — reject");
+  lines.push(
+    "  const id = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1, true);",
+  );
+  lines.push("  const name = idToAnyEventName[id];");
+  lines.push("  if (name === undefined) return null;");
+  lines.push("  return { name, id };");
+  lines.push("}");
+  lines.push("");
+  lines.push("/** Decode a frame's payload given a validated id (no envelope re-parse). */");
+  lines.push("export function decodePayload(id: number, bytes: Uint8Array): unknown {");
+  lines.push("  const decoder = eventIdToDecoder[id];");
+  lines.push("  if (!decoder) return null;");
+  lines.push("  // Reuse the pooled ByteBuffer (no per-frame ByteBuffer + TextDecoder");
+  lines.push("  // allocation); position it at the payload start (relative to the view).");
+  lines.push("  return decoder(pooledByteBuffer(bytes, WIRE_HEADER_LEN));");
+  lines.push("}");
+  lines.push("");
+  lines.push(
+    "export function decodeFrame(bytes: Uint8Array): { name: AnyEventName; id: number; payload: unknown } | null {",
+  );
+  lines.push("  const h = readFrameHeader(bytes);");
+  lines.push("  if (!h) return null;");
+  lines.push("  return { name: h.name, id: h.id, payload: decodePayload(h.id, bytes) };");
+  lines.push("}");
+  lines.push("");
+  lines.push("// reused for every string decode (flatc object-API strings are Uint8Array)");
+  lines.push("const textDecoder = new TextDecoder();");
+  lines.push('function str(v: string | Uint8Array | null | undefined, dflt = ""): string {');
+  lines.push('  return v == null ? dflt : typeof v === "string" ? v : textDecoder.decode(v);');
+  lines.push("}");
+  lines.push("");
+
+  for (const t of neededTables) {
+    const event = m.events.find((e) => e.tableName === t.name);
+    const annot = event
+      ? `: ${event.control ? "ControlEvents" : "Events"}[${JSON.stringify(event.name)}]`
+      : "";
+    lines.push(`function ${toSnake(t.name)}ToPlain(o: ${t.name}T)${annot} {`);
+    lines.push("  return {");
+    for (const f of t.fields) {
+      lines.push(`    ${f.jsonName}: ${plainExpr(f, enumValues)},`);
+    }
+    lines.push("  };");
+    lines.push("}");
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/** Self-contained `Events` / `ControlEvents` payload types (user-mode codegen). */
+function emitLocalTypes(
+  m: Model,
+  tables: Model["tables"],
+  appEvents: Model["events"],
+  controlEvents: Model["events"],
+): string[] {
+  const lines: string[] = [];
+  for (const t of tables) {
+    lines.push(`export interface ${t.name}Payload {`);
+    for (const f of t.fields) {
+      lines.push(`  ${f.jsonName}${f.required ? "" : "?"}: ${plainTsType(m, f)};`);
+    }
+    lines.push("}");
+    lines.push("");
+  }
+  const appNames = appEvents.map((e) => `"${e.name}"`).join(" | ");
+  const ctlNames = controlEvents.map((e) => `"${e.name}"`).join(" | ");
+  lines.push(`export type EventName = ${appNames};`);
+  lines.push(`export type ControlEventName = ${ctlNames};`);
+  lines.push(`export type AnyEventName = EventName | ControlEventName;`);
+  lines.push("");
+  lines.push("export type Events = {");
+  for (const ev of appEvents) lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Payload;`);
+  lines.push("};");
+  lines.push("export type ControlEvents = {");
+  for (const ev of controlEvents)
+    lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Payload;`);
+  lines.push("};");
+  lines.push("");
+  return lines;
+}
+
+function plainExpr(f: FieldDef, enumValues: Map<string, string[]>): string {
+  // flatc TS accessors/.T fields are camelCase (it converts the snake_case .fbs
+  // names) — so read via jsonName, which equals the TypeBox/Events key.
+  const o = `o.${f.jsonName}`;
+  switch (f.kind) {
+    case "string":
+      return f.required ? `str(${o})` : `${o} == null ? undefined : str(${o})`;
+    case "double":
+    case "bool":
+      return o;
+    case "int64":
+      // bigint-annotated fields stay bigint (exact); plain int64 → number
+      return f.bigint ? o : `Number(${o})`;
+    case "enum":
+      return `${enumTuple(f.enumName!, enumValues)}[${o}] ?? ${JSON.stringify(enumValues.get(f.enumName!)?.[0] ?? "")}`;
+    case "table":
+      // Required nested tables are always written by the encoder, so the
+      // decoder may assert non-null (keeps the Events[K] type honest);
+      // optional tables keep the defensive undefined fallback.
+      return f.required
+        ? `${toSnake(f.tableName!)}ToPlain(${o}!)`
+        : `${o} === null || ${o} === undefined ? undefined : ${toSnake(f.tableName!)}ToPlain(${o})`;
+    case "vector-string":
+      return `${o}.map((s) => str(s))`;
+    case "vector-double":
+    case "vector-bool":
+      return `${o}.map((n) => n)`;
+    case "vector-int64":
+      return `${o}.map((n) => Number(n))`;
+    case "vector-enum":
+      return `${o}.map((n) => ${enumTuple(f.enumName!, enumValues)}[n] ?? ${JSON.stringify(enumValues.get(f.enumName!)?.[0] ?? "")})`;
+    case "vector-table":
+      return `${o}.map((c) => ${toSnake(f.tableName!)}ToPlain(c))`;
+    default:
+      return o;
+  }
+}
+
+function enumTuple(enumName: string, enumValues: Map<string, string[]>): string {
+  const values = enumValues.get(enumName) ?? [];
+  return `([${values.map((v) => JSON.stringify(v)).join(", ")}] as const)`;
+}