@metaobjectsdev/codegen-ts 1.0.4 → 1.0.5-rc.2

package/src/templates/enum-int-codec.ts

@@ -0,0 +1,67 @@
+/**
+ * The int-backed `field.enum` codec emitter, shared by the two artifacts that can
+ * reference one: the entity's Drizzle table (`drizzle-schema.ts`) and any view-backed
+ * read model (`view-decl.ts` — a projection or an entity read-view).
+ *
+ * It lives in its own module because the codec is a MODULE-LOCAL const in whatever file
+ * declares the column, so every emitter that can produce such a column must be able to
+ * declare it too. While only the table template owned it, the view template emitted the
+ * call site and let the const name fall through to `imp(fnName@drizzle-orm/*-core)` —
+ * importing a member that package does not export, which `meta gen` reported as success
+ * and only `tsc` caught.
+ *
+ * The invariant this module exists to protect: the codec is declared ONCE PER MODULE, and
+ * it must precede every use. A write-through entity puts its table and its replica view in
+ * one file and both reference the same consts, so `entity-file.ts` renders the table first,
+ * collects the names it declared, and hands them to the view — which then references them
+ * instead of re-declaring. Two module-scope `const`s of one name is a JS parse error, and a
+ * declaration emitted after its use is a TDZ ReferenceError at import: both are worse than
+ * the missing-codec bug, because neither lets the module load at all.
+ */
+import { code, imp, type Code } from "ts-poet";
+import type { EnumIntCustomType } from "../column-mapper.js";
+
+/**
+ * Render an int-backed `field.enum`'s Drizzle `customType` helper plus its two
+ * lookup maps.
+ *
+ * The codec lives HERE, in the column definition, so nothing downstream needs to
+ * know about it: `db.insert().values()` encodes on bind, a selected row decodes on
+ * read, and a filter comparison encodes because Drizzle binds through the column
+ * type. That is why this shape was chosen over a Zod write-transform plus a
+ * generated read-decode — TS's generated queries return raw Drizzle rows and have
+ * no decode seam, so the query-layer approach meant inventing one and wrapping
+ * every generated read. It is also the direct analogue of what the other four
+ * ports already do (EF Core `HasConversion`, OMDB `JdbcFieldCodec`, Exposed
+ * `customEnumeration`, Python `ObjectManager` coercion).
+ *
+ * `fromDriver` throws on an unmapped integer rather than returning undefined: a
+ * value outside the map means the DB holds data the model says is impossible
+ * (a hand-written INSERT, or a member removed without a migration), and silently
+ * yielding `undefined` for a non-nullable field would surface far from the cause.
+ */
+export function renderEnumIntCustomType(t: EnumIntCustomType, importModule: string): Code {
+  const customTypeSym = imp(`customType@${importModule}`);
+  const union = t.members.map((m) => JSON.stringify(m)).join(" | ");
+  const toEntries = t.members
+    .map((m) => `${JSON.stringify(m)}: ${t.intByMember[m]}`)
+    .join(", ");
+  const fromEntries = t.members
+    .map((m) => `${t.intByMember[m]}: ${JSON.stringify(m)}`)
+    .join(", ");
+  return code`
+const ${t.toIntConstName} = { ${toEntries} } as const satisfies Record<${union}, number>;
+const ${t.fromIntConstName}: Record<number, ${union}> = { ${fromEntries} };
+const ${t.fnConstName} = ${customTypeSym}<{ data: ${union}; driverData: number }>({
+  dataType: () => ${JSON.stringify(t.dataType)},
+  toDriver: (value) => ${t.toIntConstName}[value],
+  fromDriver: (value) => {
+    const member = ${t.fromIntConstName}[value];
+    if (member === undefined) {
+      throw new Error(\`unmapped ${t.fnConstName} value: \${value}\`);
+    }
+    return member;
+  },
+});
+`;
+}

package/src/templates/inferred-types.ts

@@ -39,6 +39,7 @@ import { stripPackage } from "@metaobjectsdev/metadata";
 import { enumValues } from "../enum-meta.js";
 import { sharedEnumZodConstName } from "./enums-file.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { isTphReadNullTolerant } from "./zod-validators.js";
 import { sharedEnumForField } from "../enum-shared.js";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "../enum-import.js";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
@@ -387,7 +388,12 @@ export function renderValueObjectInterface(entity: MetaObject, ctx?: RenderConte
     const required = field.attr(FIELD_ATTR_REQUIRED) === true;
     const optional = required ? "" : "?";
     const tsType = valueObjectFieldType(entity, field, ctx);
-    lines.push(code`  ${field.name}${optional}: ${tsType};`);
+    // A TPH subtype's read schema accepts `null` for a column that is NULL on a
+    // sibling subtype's row; the declared type has to admit the same values, or
+    // `parse<Base>()` returns something this interface rejects. One predicate
+    // answers it for both emitters (ADR-style single source, see its docblock).
+    const nullable = isTphReadNullTolerant(entity, field) ? " | null" : "";
+    lines.push(code`  ${field.name}${optional}: ${tsType}${nullable};`);
   }
 
   // joinCode with "\n" interpolates each Code segment on its own line and

package/src/templates/relations-block.ts

@@ -8,6 +8,7 @@ import { type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier } from "../import-path.js";
 import type { RelationEntry } from "../relation-resolver.js";
 import { effectivePackage } from "../docs-paths.js";
+import { tphStorageName } from "./zod-validators.js";
 
 /**
  * Render the relations() block for one entity.
@@ -31,7 +32,7 @@ export function renderRelationsBlock(entity: MetaObject, ctx: RenderContext): Co
 
   const thisEntityPackage = effectivePackage(entity);
   const lines: Code[] = entries.map((entry) =>
-    renderRelationEntry(entry, ctx, varName, thisEntityPackage),
+    renderRelationEntry(entry, ctx, entity.name, varName, thisEntityPackage),
   );
 
   return code`export const ${relationsVarName} = ${relationsFn}(${varName}, (${params}) => ({
@@ -43,6 +44,7 @@ ${joinCode(lines, { on: ",\n", trim: false })}
 function renderRelationEntry(
   entry: RelationEntry,
   ctx: RenderContext,
+  thisEntityName: string,
   thisVarName: string,
   thisEntityPackage: string | undefined,
 ): Code {
@@ -63,18 +65,24 @@ function renderRelationEntry(
     return code`  ${entry.name}: many(${junctionVarSym})`;
   }
 
-  // Use imp() for cross-entity references so ts-poet tracks and emits the import.
-  const targetSpec = crossEntitySpecifier(
-    ctx.outputLayout,
-    thisEntityPackage,
-    ctx.packageOf.get(entry.targetEntity),
-    entry.targetEntity,
-    ctx.extStyle,
-  );
-  const targetVarSym = imp(`${ctx.collectionName(entry.targetEntity)}@${targetSpec}`);
+  // Bind to the table that stores the target's rows: a TPH subtype's module has no
+  // table const, so a navigation onto `Carrier` binds `parties` from `Party`.
+  const targetTableEntity = tphStorageName(entry.targetEntity, ctx.loadedRoot);
+  // A navigation onto this entity's OWN table (`Order.parent`, or a TPH base onto one of
+  // its subtypes) names the local const: importing it from this very module clashes with
+  // its declaration (TS2440). Otherwise imp() tracks and emits the cross-entity import.
+  const targetVarSym = targetTableEntity === thisEntityName
+    ? thisVarName
+    : imp(`${ctx.collectionName(targetTableEntity)}@${crossEntitySpecifier(
+      ctx.outputLayout,
+      thisEntityPackage,
+      ctx.packageOf.get(targetTableEntity),
+      targetTableEntity,
+      ctx.extStyle,
+    )}`);
 
   if (entry.cardinality === CARDINALITY_ONE) {
-    const pkInfo = ctx.pkMap.get(entry.targetEntity);
+    const pkInfo = ctx.pkMap.get(targetTableEntity);
     const targetPkField = pkInfo?.fieldName ?? "id";
     return code`  ${entry.name}: one(${targetVarSym}, { fields: [${thisVarName}.${entry.fkField ?? "id"}], references: [${targetVarSym}.${targetPkField}] })`;
   }

package/src/templates/routes-file.ts

@@ -31,6 +31,7 @@ import type { RelationEntry } from "../relation-resolver.js";
 import { isTphDiscriminatorBase, tphPlan } from "./tph-discriminator.js";
 import { authSeamJsDoc, type CrudVerb, exposeLine, intersectExpose, TPH_POLYMORPHIC_VERBS } from "../routes-expose.js";
 import { effectivePackage } from "../docs-paths.js";
+import { tphDiscriminatorPin, tphStorageObject } from "./zod-validators.js";
 
 export function renderRoutesFile(
   entity: MetaObject,
@@ -288,18 +289,30 @@ function renderM2mMount(
       ctx.extStyle,
     )}`,
   );
-  const targetVarSym = imp(
-    `${ctx.collectionName(entry.targetEntity)}@${crossEntitySpecifier(
-      ctx.outputLayout,
-      sourcePkg,
-      ctx.packageOf.get(entry.targetEntity),
-      entry.targetEntity,
-      ctx.extStyle,
-    )}`,
-  );
+  // An M:N onto a TPH subtype traverses into its discriminator BASE's table — the
+  // subtype has no table const, and the junction FK can only point at the base table —
+  // and filters the rows to the subtype, because a Broker id in that FK column is not a
+  // Carrier. Every other target binds to itself, and emits no filter.
+  const declaredTarget = ctx.loadedRoot.findObject(entry.targetEntity);
+  const target = declaredTarget === undefined ? undefined : tphStorageObject(declaredTarget);
+  const targetTableEntity = target?.name ?? entry.targetEntity;
+  const pin = declaredTarget === undefined ? undefined : tphDiscriminatorPin(declaredTarget);
+  // A self-join's target table IS the source table, which this file already imports from
+  // the entity module; a second import of the same binding is TS2300, and a SyntaxError
+  // when Node loads the module.
+  const targetVarSym = targetTableEntity === source.name
+    ? ctx.collectionName(source.name)
+    : imp(
+      `${ctx.collectionName(targetTableEntity)}@${crossEntitySpecifier(
+        ctx.outputLayout,
+        sourcePkg,
+        ctx.packageOf.get(targetTableEntity),
+        targetTableEntity,
+        ctx.extStyle,
+      )}`,
+    );
   const mountM2mRouteSym = imp("mountM2mRoute@@metaobjectsdev/runtime-ts/drizzle-fastify");
   const junction = ctx.loadedRoot.findObject(entry.junctionEntity);
-  const target = ctx.loadedRoot.findObject(entry.targetEntity);
   // fromPackage = source.package: this routes file is SOURCE's own module, never the
   // junction's or the target's — see resolveJunctionColumn's doc comment (B1).
   const sourceColumn: Code = junction
@@ -309,8 +322,12 @@ function renderM2mMount(
     ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx, sourcePkg)
     : code`${JSON.stringify(entry.targetJoinField!)}`;
   const targetPkColumn: Code = target
-    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx, sourcePkg)
+    ? resolveJunctionColumn(target, ctx.pkMap.get(targetTableEntity)?.fieldName ?? "id", ctx, sourcePkg)
     : code`${JSON.stringify("id")}`;
+  const discriminatorLine: Code | string = pin !== undefined && target !== undefined
+    ? code`
+    targetDiscriminator: { column: ${resolveJunctionColumn(target, pin.fieldName, ctx, sourcePkg)}, value: ${JSON.stringify(pin.value)} },`
+    : "";
 
   return code`  ${mountM2mRouteSym}({
     fastify: ${fastifyVar},
@@ -322,7 +339,7 @@ function renderM2mMount(
     sourceColumn: ${sourceColumn},
     targetColumn: ${targetColumn},
     targetPkColumn: ${targetPkColumn},
-    symmetric: ${entry.symmetric ? "true" : "false"},
+    symmetric: ${entry.symmetric ? "true" : "false"},${discriminatorLine}
   });`;
 }
 

package/src/templates/view-decl.ts

@@ -12,7 +12,8 @@ import {
   type MetaField, FIELD_SUBTYPE_OBJECT, FIELD_ATTR_OBJECT_REF,
 } from "@metaobjectsdev/metadata";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
-import { mapColumnType } from "../column-mapper.js";
+import { mapColumnType, type EnumIntCustomType } from "../column-mapper.js";
+import { renderEnumIntCustomType } from "./enum-int-codec.js";
 import { zodTypeFor } from "./field-meta.js";
 import { columnExpr, type ObjectNames } from "../names.js";
 
@@ -21,6 +22,14 @@ export interface ViewDeclOpts {
   readonly columnNamingStrategy: ColumnNamingStrategy;
   /** Drives the timestamp column TS type (Date vs string) in the view declaration. */
   readonly timestampMode: "date" | "string";
+  /**
+   * Int-backed-enum codec const names ALREADY declared in the module this view lands in.
+   * A write-through entity's table and its replica view share one file, and both reference
+   * the same codecs — so the view references these by name and declares only what the table
+   * did not (a derived field's codec, which the write table omits). Absent = the view owns
+   * every codec it needs, which is the projection case.
+   */
+  readonly declaredEnumIntCodecs?: ReadonlySet<string>;
   /**
    * ADR-0044/#228 — resolve a `field.object` / `field.map`'s `@objectRef` to the
    * value object's EMITTED name (bare when unique in the run, package-qualified on
@@ -72,10 +81,26 @@ export interface ViewDeclOpts {
  * so `db.select().from(<view>)` is typed. Honors `@dbColumnType`; `.existing()`
  * views carry type + physical name only (no PK/default/notNull DDL modifiers).
  */
-function viewColumnLine(f: MetaField, opts: ViewDeclOpts): Code {
+function viewColumnLine(
+  f: MetaField,
+  opts: ViewDeclOpts,
+  /** Codecs this view needs, collected for the caller to DECLARE — see below. */
+  enumIntTypes: Map<string, EnumIntCustomType>,
+): Code {
   const { dialect, columnNamingStrategy, timestampMode } = opts;
   const spec = mapColumnType(f, dialect, columnNamingStrategy, timestampMode);
-  const colSym = imp(`${spec.fnName}@${spec.importModule}`);
+  // An int-backed field.enum's column function is a LOCAL generated const (the
+  // customType helper the caller emits into this same file), so it must not be
+  // imported from drizzle-orm/*-core like a built-in column type would be. Same
+  // rule the table template applies in `renderColumn`; a view reads the very same
+  // integer column and needs the very same decode on the way out.
+  if (spec.enumIntCustomType !== undefined) {
+    enumIntTypes.set(spec.enumIntCustomType.fnConstName, spec.enumIntCustomType);
+  }
+  const colSym =
+    spec.enumIntCustomType !== undefined
+      ? spec.enumIntCustomType.fnConstName
+      : imp(`${spec.fnName}@${spec.importModule}`);
   const optsArg =
     spec.fnOptions && Object.keys(spec.fnOptions).length > 0
       ? `, ${JSON.stringify(spec.fnOptions)}`
@@ -137,7 +162,8 @@ export function renderExistingViewDecl(
   const viewFn = opts.dialect === "postgres" ? "pgView" : "sqliteView";
   const viewModule = opts.dialect === "postgres" ? "drizzle-orm/pg-core" : "drizzle-orm/sqlite-core";
   const viewSym = imp(`${viewFn}@${viewModule}`);
-  const viewColumnLines = fields.map((f) => viewColumnLine(f, opts));
+  const enumIntTypes = new Map<string, EnumIntCustomType>();
+  const viewColumnLines = fields.map((f) => viewColumnLine(f, opts, enumIntTypes));
   const viewNameExpr = typeof viewName === "string" ? code`${JSON.stringify(viewName)}` : viewName;
 
   // @schema — a view lands in a schema exactly as a table does, and migrate qualifies the
@@ -153,7 +179,16 @@ export function renderExistingViewDecl(
   const viewCall: Code = viewSchemaExpr === undefined
     ? code`${viewSym}`
     : code`${imp(`pgSchema@${viewModule}`)}(${viewSchemaExpr}).view`;
-  return code`
+  // Int-backed enum codecs are declared BEFORE the view that references them, sorted
+  // by const name so output is deterministic regardless of field order — the same
+  // contract the table template holds.
+  const alreadyDeclared = opts.declaredEnumIntCodecs;
+  const enumIntBlocks = [...enumIntTypes.values()]
+    .filter((t) => alreadyDeclared === undefined || !alreadyDeclared.has(t.fnConstName))
+    .sort((a, b) => a.fnConstName.localeCompare(b.fnConstName))
+    .map((t) => renderEnumIntCustomType(t, viewModule));
+
+  const viewBlock = code`
 // View declaration — Drizzle uses this for typed SELECT queries.
 // The SQL view is created/managed by migrate-ts; .existing() tells Drizzle
 // not to attempt DDL for this declaration.
@@ -161,6 +196,9 @@ export const ${viewVar} = ${viewCall}(${viewNameExpr}, {
 ${joinCode(viewColumnLines, { on: ",\n" })}
 }).existing();
 `;
+  return enumIntBlocks.length === 0
+    ? viewBlock
+    : joinCode([...enumIntBlocks, viewBlock], { on: "\n" });
 }
 
 /**

package/src/templates/zod-validators.ts

@@ -10,7 +10,7 @@
 // downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
 import { code, joinCode, imp, type Code } from "ts-poet";
-import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, type MetaRoot, stripPackage } from "@metaobjectsdev/metadata";
 import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
@@ -75,6 +75,28 @@ export function tphDiscriminatorBase(obj: MetaObject): MetaObject | undefined {
   return tphDiscriminatorLevel(obj)?.base;
 }
 
+/**
+ * The object whose TABLE stores `obj`'s rows: the discriminator base for anything beneath
+ * a TPH base — a concrete subtype or an abstract level in between — otherwise `obj`.
+ *
+ * Neither a subtype's module nor an abstract level's emits a table const, so anything
+ * that binds to "the other side" of a reference or relationship — an FK's `.references()`,
+ * a `relations()` entry, an M:N traversal's target table — must bind here and never to the
+ * target's own name. Binding to the subtype imported `carriers` from a `Carrier.ts` that
+ * does not export it.
+ */
+export function tphStorageObject(obj: MetaObject): MetaObject {
+  if (declaresTphDiscriminator(obj)) return obj;
+  return tphDiscriminatorBase(obj) ?? obj;
+}
+
+/** {@link tphStorageObject} by entity name, for the name-keyed relation map. A name the
+ *  root does not resolve is returned unchanged. */
+export function tphStorageName(entityName: string, root: MetaRoot): string {
+  const obj = root.findObject(entityName);
+  return obj === undefined ? entityName : tphStorageObject(obj).name;
+}
+
 /**
  * True when this object itself DECLARES `@discriminator` — the level of a TPH hierarchy
  * that owns the discriminator, whether or not any concrete subtype extends it yet.
@@ -126,6 +148,28 @@ export function hasAutoSetFields(obj: MetaObject): boolean {
   return false;
 }
 
+/**
+ * Is this field NULL-tolerant in a TPH subtype's READ shape?
+ *
+ * A TPH subtype shares one physical table with its siblings, so a column only one
+ * subtype declares is NULL on every other subtype's row, and a non-`@required` column
+ * of this subtype's own is NULL when unset. Either way the value read back is `null`,
+ * not `undefined`. The PRIMARY KEY is the exception — it is the shared base table's
+ * key and is present on every row.
+ *
+ * ONE predicate, because TWO emitters answer this question about the same field: the
+ * Zod read schema (`renderTphSubtypeReadSchema`) and the declared TS type
+ * (`renderValueObjectInterface`). They answered it differently, so the value
+ * `parse<Base>()` returns was not assignable to the base union and the generated
+ * module did not compile (TS2322). A second answer to one question is the defect;
+ * keeping the two call sites pointed here is the fix.
+ */
+export function isTphReadNullTolerant(obj: MetaObject, field: MetaField): boolean {
+  if (!isTphSubtype(obj)) return false;
+  if (!fieldWillBeOptional(field)) return false;
+  return !primaryIdentityFieldNames(obj).includes(field.name);
+}
+
 /**
  * FR-017 Tier 2 — the per-subtype FULL read schema `<Sub>Schema`. Unlike the
  * insert schema, this includes every effective field (PK included) so a raw DB
@@ -149,10 +193,12 @@ export function renderTphSubtypeReadSchema(obj: MetaObject, ctx?: RenderContext)
     }
     const expr = zodFieldExpr(child, obj, ctx);
     // zodFieldExpr already appends `.optional()` for non-required fields; add
-    // `.nullable()` on top so a NULL column value (the TPH default for any
-    // subtype-only column) parses cleanly.
+    // `.nullable()` on top so a NULL column value parses cleanly. The declared
+    // interface widens the SAME fields — see isTphReadNullTolerant.
     fieldLines.push(
-      fieldWillBeOptional(child) ? code`  ${child.name}: ${expr}.nullable()` : code`  ${child.name}: ${expr}`,
+      isTphReadNullTolerant(obj, child)
+        ? code`  ${child.name}: ${expr}.nullable()`
+        : code`  ${child.name}: ${expr}`,
     );
   }