@nanobpm/urban 0.25.0 → 0.26.0

package/src/toolkit/derivers/domain.ts

@@ -202,6 +202,12 @@ const PRIMITIVE_TS: Record<string, string> = {
   json: "unknown",
 };
 
+/** Whether a manifest field keyword resolves to a primitive (vs a nominal ref). Shared with the
+ * shape fuse (`shapes.ts`) so the primitive-keyword set has one definition (no drift). */
+export function isPrimitiveKeyword(type: string): boolean {
+  return Object.prototype.hasOwnProperty.call(PRIMITIVE_TS, type);
+}
+
 /**
  * The TS type for a registry field. A primitive keyword maps directly (and takes precedence over
  * an identically named type, per the schema); anything else is a nominal reference to another
@@ -252,6 +258,171 @@ export function emitDomainModel(
   return registry ? `${spine}\n${registry}` : spine;
 }
 
+// --- domain bindings: the typed data-object accessor (ADR 0029 §6) ---------------------------
+
+/** The generated bindings file's basename — the typed `openDomain()` accessor materialised next to
+ * `domain-rows.d.ts` under a project's `nano-generated/`. */
+export const DOMAIN_BINDINGS = "domain.ts";
+
+/** Members `openDomain()` reserves on the returned handle — the `DomainBase` escape hatch
+ * (`raw`/`close`). A table whose wire name is one of these would clobber the escape hatch (or the
+ * type intersection), so it is dropped from the typed table surface; it stays reachable via
+ * `db.raw.table("<name>", pk)`. */
+const RESERVED_DOMAIN_MEMBERS = new Set(["raw", "close"]);
+
+/** The primary-key column for a table's `Table` gateway: its first declared PK column, or `id`
+ * when the table declares none. */
+function primaryKeyOf(t: TableMeta): string {
+  return t.columns.find((c) => c.primaryKey)?.name ?? "id";
+}
+
+/**
+ * Emit `domain.ts`: a typed data-object accessor over the App's default datasource, so a worker
+ * writes `db.orders.insert({...})` / `db.orders.get(id)` instead of hand-writing SQL (ADR 0029 §6).
+ * The generic `Table<T>` runtime lives in `data-sdk.ts`; this generated module only binds each
+ * table name to its row type (from `domain-rows.d.ts`) and primary key, so it imports nothing but
+ * the sibling SDK (relative) and a type-only `domain-rows.d.ts` — staying dual-runtime and erased at
+ * `deno compile`. When the App declares multiple datasources this emits a *keyed*
+ * `openDomain<K>(source?)` whose returned accessor is typed against that source's tables; `db.raw`
+ * is the per-source escape hatch. Single-source apps keep the zero-arg `openDomain()` concrete form
+ * (byte-stable).
+ */
+export function emitDomainBindings(
+  sources: SourceSchema[],
+  defaultSource?: string,
+): string {
+  const header =
+    "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\n" +
+    "// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\n" +
+    "// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\n" +
+    "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n" +
+    "// eslint-disable\n";
+
+  const multi = sources.length > 1;
+  const def = defaultSource && sources.some((s) => s.source === defaultSource)
+    ? defaultSource
+    : sources[0]?.source;
+  const primary = sources.find((s) => s.source === def);
+  const tables = (primary?.tables ?? []).filter(
+    (t) => !RESERVED_DOMAIN_MEMBERS.has(t.name),
+  );
+
+  // Multi-source apps: emit a *keyed* accessor so `openDomain("analytics")` is typed against that
+  // source's tables, not the default's. The row-type spine (`DomainSources`, keyed by alias then
+  // wire table name) is already emitted in `domain-rows.d.ts`; here we bind a runtime
+  // table-descriptor map per source and a generic `openDomain<K>` that indexes it. Single-source
+  // apps keep the zero-arg concrete form below (byte-stable).
+  if (multi) {
+    return emitKeyedDomainBindings(header, sources, def!);
+  }
+
+  // Interface names must match `domain-rows.d.ts` exactly (prefixed when multi-source).
+  const typeName = (table: string) =>
+    multi ? prefixedInterfaceName(primary!.source, table) : interfaceName(table);
+  const propKey = (table: string) => (isIdent(table) ? table : JSON.stringify(table));
+
+  const typeImports = [...new Set(tables.map((t) => typeName(t.name)))].sort();
+  const importTypes = typeImports.length > 0
+    ? `import type { ${typeImports.join(", ")} } from "./${DOMAIN_DTS}";\n`
+    : "";
+
+  const fields = tables
+    .map((t) => `  readonly ${propKey(t.name)}: Table<${typeName(t.name)}>;`)
+    .join("\n");
+  const binds = tables
+    .map((t) =>
+      `    ${propKey(t.name)}: raw.table<${typeName(t.name)}>(` +
+      `${JSON.stringify(t.name)}, ${JSON.stringify(primaryKeyOf(t))}),`
+    )
+    .join("\n");
+
+  const domainIface = `export interface Domain {\n` +
+    `  /** The underlying datasource handle — the raw-SQL escape hatch. */\n` +
+    `  readonly raw: DataSource;\n` +
+    (fields ? `${fields}\n` : "") +
+    `  /** Close the underlying connection. */\n  close(): void;\n}`;
+
+  const openFn = `/**\n` +
+    ` * Open the App's ${multi ? `default (\`${def}\`) ` : ""}datasource as a typed domain: each table is\n` +
+    ` * a \`Table<T>\` gateway (\`db.orders.insert(...)\`, \`db.orders.get(id)\`), with the\n` +
+    ` * raw \`DataSource\` at \`db.raw\` for anything the gateway doesn't cover.\n` +
+    ` */\n` +
+    `export async function openDomain(source?: string): Promise<Domain> {\n` +
+    `  const raw = await openDataSource(source);\n` +
+    `  return {\n    raw,\n` +
+    (binds ? `${binds}\n` : "") +
+    `    close: () => raw.close(),\n  };\n}`;
+
+  return `${header}\n` +
+    `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+    importTypes +
+    `\n${domainIface}\n\n${openFn}\n\nexport type { Table };\n`;
+}
+
+/**
+ * Emit the *keyed* `domain.ts` for a multi-datasource App. `openDomain(source)` is
+ * runtime-polymorphic (it opens whichever source you name); here
+ * `openDomain<K extends DomainSource>(source?: K)` selects the row-type map for the requested
+ * source from `DomainSources` (emitted in `domain-rows.d.ts`), and a runtime per-source
+ * table-descriptor map binds the matching `Table<T>` gateways. Zero-arg / default-source calls keep
+ * resolving to the default source.
+ */
+function emitKeyedDomainBindings(
+  header: string,
+  sources: SourceSchema[],
+  def: string,
+): string {
+  const tableDescriptors = sources
+    .map((s) => {
+      const rows = s.tables
+        .filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name))
+        .map((t) =>
+          `{ name: ${JSON.stringify(t.name)}, pk: ${JSON.stringify(primaryKeyOf(t))} }`
+        )
+        .join(", ");
+      return `  ${JSON.stringify(s.source)}: [${rows}],`;
+    })
+    .join("\n");
+
+  const runtimeMap =
+    `const DOMAIN_TABLES: Record<string, { name: string; pk: string }[]> = {\n` +
+    `${tableDescriptors}\n};\n` +
+    `const DEFAULT_SOURCE = ${JSON.stringify(def)};`;
+
+  const types =
+    `/** The App's datasource aliases (ADR 0024). */\n` +
+    `export type DomainSource = keyof DomainSources;\n\n` +
+    `interface DomainBase {\n` +
+    `  /** The underlying datasource handle — the raw-SQL escape hatch. */\n` +
+    `  readonly raw: DataSource;\n` +
+    `  /** Close the underlying connection. */\n  close(): void;\n}\n\n` +
+    `type DomainTablesOf<M extends Record<string, object>> = { readonly [K in keyof M as K extends "raw" | "close" ? never : K]: Table<M[K]> };\n\n` +
+    `/** A datasource opened as a typed domain: one \`Table<T>\` per table, plus\n` +
+    ` * \`raw\`/\`close\`. Defaults to the default source (\`${def}\`) when unparameterised. */\n` +
+    `export type Domain<M extends Record<string, object> = DomainSources[${JSON.stringify(def)}]> =\n` +
+    `  DomainBase & DomainTablesOf<M>;`;
+
+  const openFn =
+    `/**\n` +
+    ` * Open one of the App's datasources as a typed domain. The \`source\` key\n` +
+    ` * selects that source's tables (\`openDomain("analytics").customers\`); omit it\n` +
+    ` * for the default source (\`${def}\`). \`db.raw\` is the raw-SQL escape hatch.\n` +
+    ` */\n` +
+    `export async function openDomain<K extends DomainSource = ${JSON.stringify(def)}>(\n` +
+    `  source?: K,\n` +
+    `): Promise<Domain<DomainSources[K]>> {\n` +
+    `  const key = (source ?? DEFAULT_SOURCE) as string;\n` +
+    `  const raw = await openDataSource(key);\n` +
+    `  const db: Record<string, unknown> = { raw, close: () => raw.close() };\n` +
+    `  for (const t of DOMAIN_TABLES[key] ?? []) db[t.name] = raw.table(t.name, t.pk);\n` +
+    `  return db as Domain<DomainSources[K]>;\n}`;
+
+  return `${header}\n` +
+    `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+    `import type { DomainSources } from "./${DOMAIN_DTS}";\n\n` +
+    `${runtimeMap}\n\n${types}\n\n${openFn}\n\nexport type { Table };\n`;
+}
+
 // --- manifest bridge (code-first, ADR 0054) --------------------------------------------------
 
 /** Project one manifest type's canonical schema into a `TableMeta` for the row-type spine. Reuses

package/src/toolkit/derivers/messages.ts

@@ -12,6 +12,9 @@ import { byModelPath, DOMAIN_DTS, typeRefFor, type ModelSource } from "./worker-
 
 /** Filename the console uses for the derived message-payload map; kept identical (drop-in). */
 export const MESSAGE_BINDINGS_DTS = "message-io.d.ts";
+/** The generated typed-`publishMessage` wrapper's basename — re-exports the worker SDK's
+ * `publishMessage` with a messageName-keyed typed signature. */
+export const MESSAGE_BINDINGS_TS = "messages.ts";
 
 const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
 const ENVELOPE_OUT = "io.nanobpm.dataEnvelope.out";
@@ -164,3 +167,38 @@ export const messagesDeriver: Deriver<{ models: ModelSource[]; declaredTypeIds:
   describe: "Derive message-io.d.ts (bpmn:message name + envelope payload) from BPMN models.",
   derive: ({ models, declaredTypeIds }) => deriveMessageBindings(models, declaredTypeIds),
 };
+
+/**
+ * The static typed-`publishMessage` wrapper (`messages.ts`). It re-exports the worker SDK's
+ * `publishMessage` (and its option/result types) and overrides `publishMessage` with a signature
+ * that keys off the `name` string literal: when a message is present in the generated
+ * `MessagePayloads` (ADR 0040 slice 2), the call's `variables` are typed from the declared domain
+ * type; otherwise they fall back to `MessageVars`. The body is a pass-through — the wire stays
+ * untyped JSON. This file never changes with the model, so it is written verbatim (unlike the
+ * regenerated `message-io.d.ts`). A byte-faithful port of the console's
+ * `emitMessageBindingsRuntime`.
+ */
+export function emitMessageBindingsRuntime(): string {
+  return "// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\n" +
+    "// Re-exports the worker SDK's `publishMessage` and overrides it with a\n" +
+    "// messageName-keyed typed signature (variables typed from the message's declared\n" +
+    "// envelope). Erased to a pass-through at runtime. Do not edit.\n" +
+    "// eslint-disable\n\n" +
+    `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n` +
+    `import type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n` +
+    `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n\n` +
+    `export type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n\n` +
+    `type PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\n\n` +
+    `/**\n` +
+    ` * Typed \`publishMessage\`: \`name\` is constrained to the model's declared message\n` +
+    ` * names (\`MessageName\`, ADR 0040 slice 2) so it autocompletes and rejects unknown\n` +
+    ` * messages, and \`variables\` are typed from the message's declared envelope. A\n` +
+    ` * declared message with no domain type falls back to MessageVars.\n` +
+    ` */\n` +
+    `export function publishMessage<K extends MessageName>(\n` +
+    `  name: K,\n` +
+    `  opts?: PublishMessageOptions<PayloadFor<K> & object>,\n` +
+    `): Promise<PublishMessageResult> {\n` +
+    `  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\n` +
+    `}\n`;
+}

package/src/toolkit/derivers/shapes.test.ts

@@ -0,0 +1,171 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  emitDomainModelJson,
+  resolveShapes,
+  type ShapeDecl,
+} from "./shapes.ts";
+import type { DomainTypeRegistry, SourceSchema } from "./domain.ts";
+
+// The fuse + its drift guards, ported byte-for-byte from the console's `resolveShapes` /
+// `emitDomainModelJson` tests (server domain_types_test.ts) — the toolkit is now the single source
+// of truth for the IDE's shape fuse (host dry-out nano-bpm#576), so these lock the same behaviour.
+
+test("emitDomainModelJson fuses tables, manifest types, shapes, and metadata", () => {
+  const json = emitDomainModelJson({
+    sources: [
+      {
+        source: "app",
+        tables: [
+          {
+            name: "orders",
+            columns: [{ name: "id", type: "INTEGER", notNull: true, primaryKey: true }],
+            indexes: [],
+            foreignKeys: [],
+          },
+        ],
+      },
+    ],
+    default: "app",
+    manifestTypes: { Order: { fields: { item: { type: "string" } } } },
+    shapes: [
+      {
+        decl: { id: "ApprovedOrder", process: "orders", ops: [] },
+        def: { fields: { item: { type: "string" }, approved: { type: "boolean" } } },
+      },
+    ],
+    meta: [{ process: "orders", key: "classification", value: "internal" }],
+    diagnostics: [],
+  });
+  const model = JSON.parse(json);
+  assert.equal(model.version, 1);
+  assert.equal(model.default, "app");
+  assert.equal(typeof model.inputsHash, "string");
+  assert.equal(model.inputsHash.length > 0, true);
+  const byId = new Map<string, { kind: string; provenance: string }>(
+    model.entities.map((e: { id: string; kind: string; provenance: string }) => [e.id, e]),
+  );
+  assert.equal(byId.get("app.orders")?.kind, "table");
+  assert.equal(byId.get("app.orders")?.provenance, "db:app.orders");
+  assert.equal(byId.get("Order")?.kind, "type");
+  assert.equal(byId.get("Order")?.provenance, "manifest:Order");
+  assert.equal(byId.get("ApprovedOrder")?.kind, "shape");
+  assert.equal(byId.get("ApprovedOrder")?.provenance, "model:orders");
+  assert.deepEqual(model.meta, [{ process: "orders", key: "classification", value: "internal" }]);
+});
+
+test("emitDomainModelJson inputsHash is stable across calls and shifts on any change", () => {
+  const base = {
+    sources: [],
+    manifestTypes: { Order: { fields: { item: { type: "string" } } } },
+    shapes: [],
+    meta: [{ key: "owner", value: "sre" }],
+    diagnostics: [],
+  };
+  const a = JSON.parse(emitDomainModelJson({ ...base }));
+  const b = JSON.parse(emitDomainModelJson({ ...base }));
+  assert.equal(a.inputsHash, b.inputsHash); // deterministic
+  const changed = JSON.parse(
+    emitDomainModelJson({ ...base, meta: [{ key: "owner", value: "ops" }] }),
+  );
+  assert.equal(changed.inputsHash !== a.inputsHash, true); // staleness detectable
+});
+
+test("resolveShapes reifies an all-extend shape into a flat domain type", () => {
+  const shapes: ShapeDecl[] = [
+    {
+      id: "PrReviewRoundIn",
+      name: "PR review round — input",
+      ops: [
+        { op: "extend", name: "prUrl", type: "string" },
+        { op: "extend", name: "prNumber", type: "integer" },
+        { op: "extend", name: "answer", type: "string", optional: true },
+        { op: "extend", name: "labels", type: "string", list: true },
+      ],
+    },
+  ];
+  const { types, diagnostics } = resolveShapes(shapes, {}, []);
+  assert.deepEqual(diagnostics, []);
+  assert.deepEqual(types.PrReviewRoundIn, {
+    name: "PR review round — input",
+    fields: {
+      prUrl: { type: "string" },
+      prNumber: { type: "integer" },
+      answer: { type: "string", optional: true },
+      labels: { type: "string", list: true },
+    },
+  });
+});
+
+test("resolveShapes drift-guards a shape id colliding with a manifest type", () => {
+  const shapes: ShapeDecl[] = [
+    { id: "Order", ops: [{ op: "extend", name: "item", type: "string" }] },
+  ];
+  const manifest: DomainTypeRegistry = { Order: { fields: { item: { type: "string" } } } };
+  const { types, diagnostics } = resolveShapes(shapes, manifest, []);
+  assert.deepEqual(Object.keys(types), []); // shape omitted — no silent shadow
+  assert.equal(diagnostics.length, 1);
+  assert.equal(diagnostics[0].kind, "same-id-collision");
+  assert.equal(diagnostics[0].severity, "error");
+  assert.equal(diagnostics[0].shape, "Order");
+});
+
+test("resolveShapes treats a qualified-alias carry of the colliding leaf as composed", () => {
+  // The shape id `orders` collides with the `app.orders` leaf, but it composes that same leaf via
+  // its unambiguous `app.orders` alias. Since both ids point at the one entity, this is a legitimate
+  // compose — not a same-id shadow — so no collision is raised.
+  const sources: SourceSchema[] = [
+    {
+      source: "app",
+      tables: [
+        {
+          name: "orders",
+          columns: [{ name: "id", type: "INTEGER", notNull: true, primaryKey: true }],
+          indexes: [],
+          foreignKeys: [],
+        },
+      ],
+    },
+  ];
+  const shapes: ShapeDecl[] = [{ id: "orders", ops: [{ op: "carry", ref: "app.orders" }] }];
+  const { types, diagnostics } = resolveShapes(shapes, {}, sources);
+  assert.equal(
+    diagnostics.some((d) => d.kind === "same-id-collision"),
+    false,
+  );
+  assert.ok(types.orders); // the shape resolves rather than being omitted
+  assert.deepEqual(Object.keys(types.orders.fields), ["id"]);
+});
+
+test("resolveShapes rejects a duplicate shape id as a fuse-identity collision", () => {
+  const shapes: ShapeDecl[] = [
+    { id: "Dup", ops: [{ op: "extend", name: "a", type: "string" }] },
+    { id: "Dup", ops: [{ op: "extend", name: "b", type: "string" }] },
+  ];
+  const { types, diagnostics } = resolveShapes(shapes, {}, []);
+  assert.deepEqual(Object.keys(types), []); // both omitted
+  assert.equal(diagnostics.length, 1);
+  assert.equal(diagnostics[0].kind, "duplicate-id");
+  assert.equal(diagnostics[0].severity, "error");
+});
+
+test("resolveShapes flags an extend whose type is neither scalar nor a fused entity", () => {
+  const shapes: ShapeDecl[] = [
+    { id: "Bad", ops: [{ op: "extend", name: "ref", type: "NoSuchType" }] },
+  ];
+  const { types, diagnostics } = resolveShapes(shapes, {}, []);
+  assert.deepEqual(Object.keys(types), []); // broken shape omitted
+  assert.equal(diagnostics.length, 1);
+  assert.equal(diagnostics[0].kind, "unresolved-reference");
+  assert.equal(diagnostics[0].severity, "error");
+});
+
+test("resolveShapes returns an empty resolution for no shapes", () => {
+  const { types, diagnostics } = resolveShapes(
+    [],
+    { Order: { fields: { item: { type: "string" } } } },
+    [],
+  );
+  assert.deepEqual(types, {});
+  assert.deepEqual(diagnostics, []);
+});