@metaobjectsdev/codegen-ts 0.8.1-rc.1 → 0.9.0-rc.1

package/src/payload-codegen.ts

@@ -12,16 +12,20 @@
 
 import {
   type MetaData,
+  type MetaField,
   TYPE_OBJECT,
   TYPE_FIELD,
   TYPE_TEMPLATE,
   FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_REQUIRED,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
 } from "@metaobjectsdev/metadata";
+import { enumValues } from "./enum-meta.js";
+import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
 
 const SCALAR_TS: Record<string, string> = {
   string: "string",
@@ -44,7 +48,18 @@ function findObject(root: MetaData, name: string): MetaData | undefined {
   return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
 }
 
-function fieldTsType(field: MetaData): { type: string; refVo?: string } {
+/**
+ * Map a payload field to its strict TS type.
+ *  - `refVo`: the nested @objectRef VO to recurse into (object fields only).
+ *  - `enumAlias`: a `{ name, decl }` for a `field.enum` — `name` is the union-alias
+ *    type referenced inline; `decl` is the `export type <name> = "A" | "B";` line the
+ *    caller hoists above the interface (deduped). Reuses the SAME naming + union
+ *    logic as the entity inferred-types emitter (single source of truth).
+ */
+function fieldTsType(
+  field: MetaData,
+  ownerName: string,
+): { type: string; refVo?: string; enumAlias?: { name: string; decl: string } } {
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
     const refName = typeof ref === "string" ? ref : "unknown";
@@ -56,6 +71,21 @@ function fieldTsType(field: MetaData): { type: string; refVo?: string } {
     if (typeof ref === "string") result.refVo = ref;
     return result;
   }
+  // field.enum: a value-constrained string-literal union alias (NOT `unknown`).
+  // Field nodes are MetaField instances at runtime (MetaField extends MetaData),
+  // so the enum helpers (effective @values + super-resolving name) apply.
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const values = enumValues(field as MetaField);
+    if (values !== undefined) {
+      const aliasName = enumUnionAliasName(ownerName, field as MetaField);
+      return {
+        type: field.isArray ? `${aliasName}[]` : aliasName,
+        enumAlias: { name: aliasName, decl: `export type ${aliasName} = ${enumUnionString(values)};` },
+      };
+    }
+    // No @values → fall through to the raw-string representation.
+    return { type: field.isArray ? "string[]" : "string" };
+  }
   const scalar = SCALAR_TS[field.subType] ?? "unknown";
   return { type: field.isArray ? `${scalar}[]` : scalar };
 }
@@ -65,15 +95,28 @@ function isFieldRequired(field: MetaData): boolean {
   return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
 }
 
-function emitInterface(root: MetaData, voName: string, emitted: Set<string>, out: string[]): void {
+function emitInterface(
+  root: MetaData,
+  voName: string,
+  emitted: Set<string>,
+  out: string[],
+  enumAliases: Set<string>,
+): void {
   if (emitted.has(voName)) return;
   const vo = findObject(root, voName);
   if (!vo) return;
   emitted.add(voName);
+  const aliasLines: string[] = [];
   const lines: string[] = [`export interface ${voName} {`];
   const refs: string[] = [];
   for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
-    const { type, refVo } = fieldTsType(f);
+    const { type, refVo, enumAlias } = fieldTsType(f, voName);
+    // Hoist the enum union alias above the interface, deduped across the whole
+    // batch (multiple fields/objects can share one abstract enum's alias).
+    if (enumAlias && !enumAliases.has(enumAlias.name)) {
+      enumAliases.add(enumAlias.name);
+      aliasLines.push(enumAlias.decl);
+    }
     // Required fields: `name: T;`
     // Optional fields: `name?: T | null;` — the `| null` lets values from
     // Drizzle entity rows (which return `null` for nullable columns) flow
@@ -86,14 +129,15 @@ function emitInterface(root: MetaData, voName: string, emitted: Set<string>, out
     if (refVo) refs.push(refVo);
   }
   lines.push("}");
-  out.push(lines.join("\n"));
-  for (const r of refs) emitInterface(root, r, emitted, out);
+  const block = aliasLines.length > 0 ? `${aliasLines.join("\n")}\n${lines.join("\n")}` : lines.join("\n");
+  out.push(block);
+  for (const r of refs) emitInterface(root, r, emitted, out, enumAliases);
 }
 
 /** Emit the payload `interface` (+ nested element interfaces) for an object.value view-object. */
 export function generatePayloadInterfaces(root: MetaData, voName: string): string {
   const out: string[] = [];
-  emitInterface(root, voName, new Set<string>(), out);
+  emitInterface(root, voName, new Set<string>(), out, new Set<string>());
   return out.join("\n\n") + "\n";
 }
 
@@ -108,8 +152,9 @@ export function generatePayloadInterfacesBatch(root: MetaData, voNames: readonly
   if (voNames.length === 0) return "";
   const out: string[] = [];
   const emitted = new Set<string>();
+  const enumAliases = new Set<string>();
   for (const name of voNames) {
-    emitInterface(root, name, emitted, out);
+    emitInterface(root, name, emitted, out, enumAliases);
   }
   return out.length === 0 ? "" : out.join("\n\n") + "\n";
 }

package/src/projection/extract-view-spec.ts

@@ -46,12 +46,20 @@ function findRelationship(obj: MetaData, name: string): MetaData | undefined {
 }
 
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
-  // The read-only source carries the physical view name (@table).
+  // The read-only source carries the physical view name. FR-016: physicalName
+  // implements the four-step rule (kind-matching alias → legacy @table →
+  // source.name → entity-name fallback), so the call below correctly resolves
+  // @view / @materializedView / legacy @table for projection sources.
   const viewSource = projection.ownChildren().find(
     (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
   );
-  const explicit = viewSource?.tableName;
-  return explicit ?? viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
+  const explicit = viewSource?.physicalName;
+  // physicalName always returns a string; empty string means the source had
+  // neither alias nor a name and the owning entity name was empty (impossible
+  // for a real projection). Fall through to the helper anyway for safety.
+  return explicit !== undefined && explicit !== ""
+    ? explicit
+    : viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
 }
 
 /**

package/src/render-engine/framework-provider.ts

@@ -27,8 +27,13 @@ const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
  *  `templates/` directory contains our canonical shipped template (i.e., the
  *  codegen-ts package root). Works the same way from
  *  `src/render-engine/framework-provider.ts` (during dev) and
- *  `dist/render-engine/framework-provider.js` (after `npm install`). */
-function findFrameworkTemplatesDir(start: string): string {
+ *  `dist/render-engine/framework-provider.js` (after `npm install`).
+ *
+ *  Returns `undefined` when no on-disk templates dir can be found — e.g. inside
+ *  the `bun build --compile` standalone binary, whose `import.meta.url` is a
+ *  `/$bunfs/root` virtual path with no real `package.json` alongside it. The
+ *  embedded-template fallback (see `FileSystemProvider`) covers that case. */
+function findFrameworkTemplatesDir(start: string): string | undefined {
   let dir = start;
   while (true) {
     const pkgJson = join(dir, "package.json");
@@ -43,19 +48,25 @@ function findFrameworkTemplatesDir(start: string): string {
     if (parent === dir) break;
     dir = parent;
   }
-  throw new Error(
-    `framework templates dir unresolved: walked up from ${start} without finding a package.json ` +
-    `whose templates/${CANONICAL_TEMPLATE_REL} exists. This usually means codegen-ts was installed ` +
-    `via a hoisted layout (pnpm/bun workspaces) into an unexpected location, or the published ` +
-    `tarball is missing the templates/ directory.`,
-  );
+  return undefined;
 }
 
 // In ESM (CLAUDE.md: "ESM only. No CommonJS."), `import.meta.url` is
 // guaranteed to be a file: URL; no defensive try/catch needed.
 const SELF_DIR = dirname(fileURLToPath(import.meta.url));
 
-const FRAMEWORK_TEMPLATES_DIR = findFrameworkTemplatesDir(SELF_DIR);
+// Lazy + cached: resolving the on-disk templates dir walks the filesystem, and
+// in the standalone binary it never finds one (the embedded fallback handles
+// it). Deferring the walk keeps merely *importing* this module side-effect-free
+// — critical for the compiled `meta` binary, where eager resolution at import
+// time used to throw before any command (even `--help`) could run.
+let _frameworkTemplatesDir: string | null | undefined;
+function frameworkTemplatesDir(): string | undefined {
+  if (_frameworkTemplatesDir === undefined) {
+    _frameworkTemplatesDir = findFrameworkTemplatesDir(SELF_DIR) ?? null;
+  }
+  return _frameworkTemplatesDir ?? undefined;
+}
 
 /** Provider backed by an arbitrary on-disk template directory. References
  *  resolve as `<dir>/<ref>.mustache`. Used by both the framework default
@@ -70,10 +81,27 @@ export class FileSystemProvider implements Provider {
 }
 
 /** The framework defaults provider — resolves refs against codegen-ts's own
- *  `templates/` directory. */
-export const frameworkTemplatesProvider: Provider = new FileSystemProvider(
-  FRAMEWORK_TEMPLATES_DIR,
-);
+ *  on-disk `templates/` directory.
+ *
+ *  Resolution is lazy: the directory is located on first `resolve()`, not at
+ *  module import. This keeps merely importing this module side-effect-free,
+ *  which matters for the `bun build --compile` standalone `meta` binary — its
+ *  `import.meta.url` is a `/$bunfs/root` virtual path with no on-disk
+ *  `templates/` dir, so eager resolution at import time used to throw before
+ *  any command (even `--help` or the schema ops `migrate`/`verify --db`) could
+ *  run. Now non-codegen commands import cleanly; only the codegen doc path
+ *  (which the standalone binary doesn't target) needs the on-disk dir. */
+class FrameworkTemplatesProvider implements Provider {
+  resolve(ref: string): string | undefined {
+    const dir = frameworkTemplatesDir();
+    if (dir === undefined) return undefined;
+    const path = join(dir, `${ref}.mustache`);
+    if (!existsSync(path)) return undefined;
+    return readFileSync(path, "utf-8");
+  }
+}
+
+export const frameworkTemplatesProvider: Provider = new FrameworkTemplatesProvider();
 
 /** Compose providers: first match wins. Adopters typically chain
  *  `[projectProvider, frameworkTemplatesProvider]` so their own templates
@@ -102,6 +130,15 @@ export function projectProvider(projectRoot?: string): Provider {
   ]);
 }
 
-/** Exposed for tests that want to inspect / clear the resolved framework
- *  templates directory (don't use outside tests). */
-export const __frameworkTemplatesDirForTests = FRAMEWORK_TEMPLATES_DIR;
+/** Exposed for tests that want to inspect the resolved framework templates
+ *  directory (don't use outside tests). Resolved lazily so that merely
+ *  importing this module never walks the filesystem or throws — tests always
+ *  run from source where the on-disk dir exists; the standalone binary (where
+ *  no dir exists) never touches this export. */
+export function frameworkTemplatesDirForTests(): string {
+  const dir = frameworkTemplatesDir();
+  if (dir === undefined) {
+    throw new Error("framework templates dir unresolved (test ran outside a source/install layout)");
+  }
+  return dir;
+}

package/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));
+}
+`;
+}