feat(codegen-ts): FR-015 callable wrapper generator (storedProc / tableFunction)

Emits a typed wrapper function per entity backed by a stored procedure or
table function. One file per callable entity at
<outDir>/<package>/<Entity>.callable.ts:

  import { sql } from "drizzle-orm";
  import type { NodePgDatabase } from "drizzle-orm/node-postgres";
  import type { PhaseSummaryArgs } from "./PhaseSummaryArgs.js";
  import { PhaseSummarySchema, type PhaseSummary } from "./PhaseSummary.js";

  export async function callPhaseSummary(
    db: NodePgDatabase, args: PhaseSummaryArgs,
  ): Promise<PhaseSummary[]> {
    const r = await db.execute(
      sql`SELECT * FROM fn_phase_summary(${args.caseId}, ${args.asOfDate})`,
    );
    return r.rows.map((row) => PhaseSummarySchema.parse(row as unknown));
  }

Args bind in the @parameterRef value-object's field declaration order. Zero-
arg procs (no @parameterRef) emit a no-args wrapper with the same shape.
Drizzle's sql tag handles parameter binding so injection is impossible.

Files:
- templates/callable-file.ts — renderCallableFile + isCallableEntity helper.
- generators/callable-file.ts — factory registered via `callableFile()` in a
  user's metaobjects.config.ts. Filter skips non-callable entities so vanilla
  tables/views never emit a noisy empty file.
- generators/index.ts — re-exports the factory.

Tests: 3 new tests in test/templates/callable-file.test.ts covering stored
proc + table function + zero-arg cases. Full codegen-ts: 414 pass / 4
pre-existing extract-codegen fails unrelated to this change.

Deferred (per the metadata-codegen plan): @exposeAsRoute opt-in REST route
emission + matching TanStack hook. The wrapper is the foundation; REST
exposure can be added as an additive layer when an adopter actually needs
HTTP-exposed procs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts/src/generators/callable-file.ts

@@ -0,0 +1,44 @@
+// FR-015 callable-wrapper generator factory.
+//
+// One file per entity backed by a stored procedure or table function:
+//   <outDir>/<package>/<Entity>.callable.ts
+//
+// Non-callable entities are skipped (filter narrows the iteration set so
+// vanilla tables/views never emit a noisy empty file).
+
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderCallableFile, isCallableEntity } from "../templates/callable-file.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface CallableFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const callableFile = function callableFile(opts?: CallableFileOpts): Generator {
+  const userFilter = opts?.filter;
+  const filter: (e: MetaObject) => boolean = userFilter
+    ? (e) => isCallableEntity(e) && userFilter(e)
+    : isCallableEntity;
+
+  const generator: Generator = {
+    name: "callable-file",
+    filter,
+    generate: perEntity(async (entity, ctx) => {
+      return {
+        path: entityOutputPath(
+          ctx.config.outputLayout ?? "flat",
+          entity.package,
+          `${entity.name}.callable.ts`,
+        ),
+        content: await formatTs(renderCallableFile(entity)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<CallableFileOpts>;

server/typescript/packages/codegen-ts/src/generators/index.ts

@@ -1,5 +1,6 @@
 export { entityFile, type EntityFileOpts } from "./entity-file.js";
 export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
+export { callableFile, type CallableFileOpts } from "./callable-file.js";
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
 export { barrel, type BarrelOpts } from "./barrel.js";

server/typescript/packages/codegen-ts/src/templates/callable-file.ts

@@ -0,0 +1,122 @@
+// FR-015 — render a typed wrapper function for an entity backed by a stored
+// procedure or table function. One generated file per callable entity:
+//
+//   import { sql } from "drizzle-orm";
+//   import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+//   import type { PhaseSummaryArgs } from "./PhaseSummaryArgs.js";
+//   import { PhaseSummarySchema, type PhaseSummary } from "./PhaseSummary.js";
+//
+//   export async function callPhaseSummary(
+//     db: NodePgDatabase,
+//     args: PhaseSummaryArgs,
+//   ): Promise<PhaseSummary[]> {
+//     const r = await db.execute(
+//       sql`SELECT * FROM fn_phase_summary(${args.caseId}, ${args.asOfDate})`,
+//     );
+//     return r.rows.map((row) => PhaseSummarySchema.parse(row));
+//   }
+//
+// Zero-argument procs (no @parameterRef) emit a no-args version that drops the
+// `args` parameter and calls `fn_x()`.
+
+import {
+  type MetaObject,
+  MetaSource,
+  SOURCE_ATTR_PARAMETER_REF,
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+  TYPE_FIELD,
+  TYPE_SOURCE,
+  OBJECT_SUBTYPE_VALUE,
+} from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+
+const CALLABLE_KINDS: ReadonlySet<string> = new Set([
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+]);
+
+/** Return true when this entity is backed by a callable source (stored
+ *  procedure or table function). Used by the generator factory to filter. */
+export function isCallableEntity(entity: MetaObject): boolean {
+  const src = callableSource(entity);
+  return src !== undefined;
+}
+
+function callableSource(entity: MetaObject): MetaSource | undefined {
+  for (const child of entity.ownChildren()) {
+    if (child.type !== TYPE_SOURCE) continue;
+    if (!(child instanceof MetaSource)) continue;
+    if (CALLABLE_KINDS.has(child.effectiveKind)) return child;
+  }
+  return undefined;
+}
+
+/** Render the full file content for an entity's callable wrapper. Caller
+ *  is responsible for formatting (prettier / biome) and writing to disk. */
+export function renderCallableFile(entity: MetaObject): string {
+  const source = callableSource(entity);
+  if (source === undefined) {
+    throw new Error(
+      `renderCallableFile: entity "${entity.name}" has no source.rdb with @kind: "storedProc" or "tableFunction"`,
+    );
+  }
+
+  const procName = source.physicalName;
+  const argsRef = source.ownAttr(SOURCE_ATTR_PARAMETER_REF);
+  const argsObjectName = typeof argsRef === "string" && argsRef !== "" ? argsRef : undefined;
+
+  // Resolve the parameter value-object (when set) — same root as the entity.
+  const root = entity.root();
+  const argsObject =
+    argsObjectName !== undefined
+      ? (root.ownChildren().find(
+          (c) =>
+            c.subType === OBJECT_SUBTYPE_VALUE && c.name === argsObjectName,
+        ) as MetaObject | undefined)
+      : undefined;
+
+  // Build the parameter list for the SQL call site. Declaration order = arg
+  // order. Empty when argsObject is undefined (zero-arg proc).
+  const paramFieldNames: string[] = argsObject
+    ? argsObject.ownChildren()
+        .filter((c) => c.type === TYPE_FIELD)
+        .map((f) => f.name)
+    : [];
+
+  const sqlArgList = paramFieldNames.length === 0
+    ? ""
+    : paramFieldNames.map((n) => `\${args.${n}}`).join(", ");
+
+  const fnName = `call${entity.name}`;
+  const projectionType = entity.name;
+  const projectionSchemaName = `${entity.name}Schema`;
+
+  // Imports: entity (Zod schema + type) + drizzle sql + the args value-object
+  // when applicable.
+  const argsImport = argsObject
+    ? `import type { ${argsObjectName} } from "./${argsObjectName}.js";\n`
+    : "";
+
+  const signature = argsObject
+    ? `db: NodePgDatabase, args: ${argsObjectName}`
+    : `db: NodePgDatabase`;
+
+  return `// ${GENERATED_HEADER}
+import { sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+${argsImport}import { ${projectionSchemaName}, type ${projectionType} } from "./${entity.name}.js";
+
+/**
+ * FR-015: typed wrapper around the \`${procName}\` ${source.effectiveKind === SOURCE_KIND_STORED_PROC ? "stored procedure" : "table function"}.
+ * Drizzle passes a parameterised SELECT — args bind in declaration order from
+ * the @parameterRef value-object${argsObject ? `, here ${argsObjectName}` : ""}.
+ */
+export async function ${fnName}(${signature}): Promise<${projectionType}[]> {
+  const r = await db.execute(
+    sql\`SELECT * FROM ${procName}(${sqlArgList})\`,
+  );
+  return r.rows.map((row) => ${projectionSchemaName}.parse(row as unknown));
+}
+`;
+}

server/typescript/packages/codegen-ts/test/templates/callable-file.test.ts

@@ -0,0 +1,130 @@
+// FR-015 — codegen-ts callable-file emission test.
+// Generated wrapper for an entity backed by a stored procedure or table
+// function: typed args (from @parameterRef object.value) + projection return.
+
+import { describe, expect, test } from "bun:test";
+import {
+  MetaDataLoader,
+  InMemoryStringSource,
+} from "@metaobjectsdev/metadata";
+import { renderCallableFile } from "../../src/templates/callable-file.js";
+
+async function loadFirstEntity(doc: unknown) {
+  const loader = new MetaDataLoader();
+  const { root, errors } = await loader.load([
+    new InMemoryStringSource(JSON.stringify(doc), { id: "demo.json" }),
+  ]);
+  if (errors.length > 0) throw new Error(`load errors: ${errors.map((e) => e.message).join("; ")}`);
+  const procEntity = root.objects().find((o) => o.name === "PhaseSummary")!;
+  return { root, procEntity };
+}
+
+describe("renderCallableFile", () => {
+  test("storedProc with @parameterRef emits typed wrapper function", async () => {
+    const { procEntity } = await loadFirstEntity({
+      "metadata.root": {
+        package: "demo",
+        children: [
+          {
+            "object.value": {
+              name: "PhaseSummaryArgs",
+              children: [
+                { "field.int": { name: "caseId", "@required": true } },
+                { "field.timestamp": { name: "asOfDate" } },
+              ],
+            },
+          },
+          {
+            "object.entity": {
+              name: "PhaseSummary",
+              children: [
+                {
+                  "source.rdb": {
+                    "@kind": "storedProc",
+                    "@proc": "fn_phase_summary",
+                    "@parameterRef": "PhaseSummaryArgs",
+                  },
+                },
+                { "field.long": { name: "phaseId" } },
+                { "field.string": { name: "phaseName" } },
+                { "identity.primary": { "@fields": "phaseId" } },
+              ],
+            },
+          },
+        ],
+      },
+    });
+
+    const out = renderCallableFile(procEntity);
+    expect(out).toContain("export async function callPhaseSummary");
+    expect(out).toContain("args: PhaseSummaryArgs");
+    expect(out).toContain("fn_phase_summary");
+    expect(out).toContain("args.caseId");
+    expect(out).toContain("args.asOfDate");
+    expect(out).toContain("Promise<PhaseSummary[]>");
+  });
+
+  test("tableFunction with @parameterRef emits the same shape with the @function name", async () => {
+    const { procEntity } = await loadFirstEntity({
+      "metadata.root": {
+        package: "demo",
+        children: [
+          {
+            "object.value": {
+              name: "PhaseSummaryArgs",
+              children: [{ "field.int": { name: "id" } }],
+            },
+          },
+          {
+            "object.entity": {
+              name: "PhaseSummary",
+              children: [
+                {
+                  "source.rdb": {
+                    "@kind": "tableFunction",
+                    "@function": "fn_phase_listing",
+                    "@parameterRef": "PhaseSummaryArgs",
+                  },
+                },
+                { "field.long": { name: "id" } },
+                { "identity.primary": { "@fields": "id" } },
+              ],
+            },
+          },
+        ],
+      },
+    });
+    const out = renderCallableFile(procEntity);
+    expect(out).toContain("fn_phase_listing");
+    expect(out).toContain("args.id");
+  });
+
+  test("storedProc with NO @parameterRef emits a zero-arg wrapper", async () => {
+    const { procEntity } = await loadFirstEntity({
+      "metadata.root": {
+        package: "demo",
+        children: [
+          {
+            "object.entity": {
+              name: "PhaseSummary",
+              children: [
+                {
+                  "source.rdb": {
+                    "@kind": "storedProc",
+                    "@proc": "fn_ping",
+                  },
+                },
+                { "field.long": { name: "id" } },
+                { "identity.primary": { "@fields": "id" } },
+              ],
+            },
+          },
+        ],
+      },
+    });
+    const out = renderCallableFile(procEntity);
+    expect(out).toContain("callPhaseSummary(db");
+    expect(out).not.toContain("args:");
+    expect(out).toContain("fn_ping()");
+  });
+});