@metaobjectsdev/codegen-ts 0.7.0-rc.1 → 0.7.0-rc.11

package/src/templates/inferred-types.ts

@@ -1,9 +1,34 @@
 // Inferred types template — emits Drizzle's InferSelectModel / InferInsertModel type aliases,
 // plus named union types for field.enum fields.
+//
+// Also emits the structural TS interface for value-only objects (metaobjects
+// with no writable source.rdb). That path side-steps Drizzle entirely: the
+// interface is computed directly from the field tree, with `name?: T` for
+// optional fields (matching Zod's `.optional()` inference — `T | undefined` —
+// without the superfluous `| null` that Drizzle nullable columns introduce).
 
-import { code, imp, type Code } from "ts-poet";
-import type { MetaObject } from "@metaobjectsdev/metadata";
-import { FIELD_SUBTYPE_ENUM } from "@metaobjectsdev/metadata";
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_CLASS,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_OBJECT_REF,
+} from "@metaobjectsdev/metadata";
 import { variableNameFromEntity, toPascalCase } from "../naming.js";
 import { enumValues } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
@@ -53,3 +78,92 @@ export function renderEnumTypeAliases(entity: MetaObject): Code | null {
 
   return lines.length > 0 ? code`${lines.join("\n")}` : null;
 }
+
+// ---------------------------------------------------------------------------
+// Value-object interface emitter
+// ---------------------------------------------------------------------------
+
+const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
+  [FIELD_SUBTYPE_STRING]: "string",
+  [FIELD_SUBTYPE_CLASS]: "string",
+  [FIELD_SUBTYPE_INT]: "number",
+  [FIELD_SUBTYPE_SHORT]: "number",
+  [FIELD_SUBTYPE_BYTE]: "number",
+  [FIELD_SUBTYPE_LONG]: "number",
+  [FIELD_SUBTYPE_DOUBLE]: "number",
+  [FIELD_SUBTYPE_FLOAT]: "number",
+  [FIELD_SUBTYPE_DECIMAL]: "number",
+  [FIELD_SUBTYPE_CURRENCY]: "number",
+  [FIELD_SUBTYPE_BOOLEAN]: "boolean",
+  [FIELD_SUBTYPE_DATE]: "string",
+  [FIELD_SUBTYPE_TIME]: "string",
+  [FIELD_SUBTYPE_TIMESTAMP]: "string",
+};
+
+/** Type-alias name for a field.enum, mirroring renderEnumTypeAliases. */
+function enumTypeAliasName(entity: MetaObject, field: MetaField): string {
+  const superField = field.resolveSuper();
+  return superField !== undefined
+    ? toPascalCase(superField.name)
+    : `${entity.name}${toPascalCase(field.name)}`;
+}
+
+/**
+ * One-line TS type expression for a field on a value-only object.
+ * Returns a `Code` so cross-module `field.object` refs can be hoisted via
+ * ts-poet `imp(...)` — matching how the Zod emitter hoists `<Ref>InsertSchema`.
+ */
+function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
+  // field.object: import the referenced TS interface from its sibling module
+  // so ts-poet hoists the import. Mirrors zod-validators.ts's `<Ref>InsertSchema`
+  // import strategy, just for the type alias instead of the schema constant.
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof ref === "string" && ref.length > 0) {
+      const refImp = imp(`${ref}@./${ref}.js`);
+      return field.isArray ? code`${refImp}[]` : code`${refImp}`;
+    }
+    return field.isArray ? code`unknown[]` : code`unknown`;
+  }
+
+  // field.enum: use the same type-alias name as renderEnumTypeAliases emits.
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const values = enumValues(field);
+    if (values !== undefined) {
+      const alias = enumTypeAliasName(entity, field);
+      return field.isArray ? code`${alias}[]` : code`${alias}`;
+    }
+    return field.isArray ? code`string[]` : code`string`;
+  }
+
+  const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
+  return field.isArray ? code`${scalar}[]` : code`${scalar}`;
+}
+
+/**
+ * Emit a structural `interface <Name> { ... }` for a value-only object.
+ *
+ * Optional fields use `name?: T` (matching the Zod `.optional()` inference
+ * `T | undefined`) instead of `name?: T | null`. Value objects never round-
+ * trip through Drizzle nullable columns, so the null-bridge is unnecessary
+ * here — and forces consumers into a residual cast at the call site.
+ */
+export function renderValueObjectInterface(entity: MetaObject): Code {
+  const docs = renderDocsFor(entity);
+  const docsPrefix = docs ? `${docs}\n` : "";
+
+  const lines: Code[] = [];
+  for (const field of entity.fields()) {
+    const required = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+    const optional = required ? "" : "?";
+    const tsType = valueObjectFieldType(entity, field);
+    lines.push(code`  ${field.name}${optional}: ${tsType};`);
+  }
+
+  // joinCode with "\n" interpolates each Code segment on its own line and
+  // keeps the imp() registrations intact so ts-poet hoists the imports.
+  return code`${docsPrefix}export interface ${entity.name} {
+${joinCode(lines, { on: "\n" })}
+}
+`;
+}

package/src/templates/routes-file-hono.ts

@@ -0,0 +1,142 @@
+// Hono route template — emits a per-entity routes file that delegates
+// CRUD verbs to helpers from @metaobjectsdev/runtime-ts/hono.
+//
+// Hono parallel of templates/routes-file.ts. Two emit-shape differences
+// vs the Fastify flavor, both reflecting Hono idioms rather than contract
+// drift:
+//
+//   1) Exported function shape — `registerXxxRoutes(app, deps)` instead of
+//      `xxxRoutes(fastify)`. Workers/Bun consumers typically pass `db`
+//      through a per-request deps object (so a Worker can attach the
+//      D1 client pulled off bindings) rather than reaching for a
+//      module-level singleton. The Fastify flavor uses `import { db }`
+//      because Fastify apps are long-lived Node processes where a
+//      singleton is the norm. Both flavors talk to mountCrudRoutes /
+//      mountReadOnlyCrudRoutes with identical wire behavior.
+//
+//   2) apiPrefix is composed into the resource path (`${apiPrefix}${path}`)
+//      rather than wrapping the registration. Hono has no fastify.register
+//      / prefix-wrapping primitive; sub-apps via `app.route(prefix, sub)`
+//      exist but bloat the generated code. String concat is simpler and
+//      produces identical URL grammar.
+//
+// Dispatch logic mirrors Fastify:
+//   isProjection(entity)              → mountReadOnlyCrudRoutes (GET list + GET :id)
+//   vanilla / write-through entity    → mountCrudRoutes (all 5 CRUD verbs)
+
+import { code, imp } from "ts-poet";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { type RenderContext } from "../render-context.js";
+import { entityModuleSpecifier } from "../import-path.js";
+import { GENERATED_HEADER } from "../constants.js";
+import { variableNameFromEntity } from "../naming.js";
+import { isProjection } from "../projection/projection-detector.js";
+
+export function renderRoutesFileHono(entity: MetaObject, ctx: RenderContext): string {
+  const entityName = entity.name;
+  const handlerName = `register${entityName}Routes`;
+
+  const entityFileSpec = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    entity.package,
+    entityName,
+    ctx.extStyle,
+  );
+
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${entity.fqn()})\n` +
+    `// Customize via ${entityName}.extra.ts in this directory (e.g., auth, additional handlers).\n`;
+
+  // Path composition: apiPrefix is a literal string in the URL.
+  const pathExpr = ctx.apiPrefix
+    ? `\`${ctx.apiPrefix}\${${entityName}.$path}\``
+    : `${entityName}.$path`;
+
+  // --- Projection path: read-only routes (GET list + GET :id) ---
+  if (isProjection(entity)) {
+    const camelName = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+    const HonoSym = imp("t:Hono@hono");
+    const mountReadOnlyCrudRoutesSym = imp(
+      "mountReadOnlyCrudRoutes@@metaobjectsdev/runtime-ts/hono",
+    );
+
+    const literalImports = code`
+import {
+  ${entityName},
+  ${camelName}View,
+  ${entityName}FilterAllowlist,
+  ${entityName}SortAllowlist,
+} from ${JSON.stringify(entityFileSpec)};
+`;
+
+    const body = code`
+/**
+ * Mount read-only REST endpoints for ${entityName} (projection — view-backed, no writes).
+ *
+ * Exposes GET list + GET :id only. POST/PATCH/DELETE return 405.
+ * Customize: register this as-is, or import individual route helpers from
+ * @metaobjectsdev/runtime-ts/hono.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: consumer-defined Hono bindings/variables
+export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unknown }): void {
+  ${mountReadOnlyCrudRoutesSym}({
+    app,
+    path: ${pathExpr},
+    db: deps.db,
+    view: ${camelName}View,
+    filterAllowlist: ${entityName}FilterAllowlist,
+    sortAllowlist: ${entityName}SortAllowlist,
+    dialect: ${JSON.stringify(ctx.dialect)},
+  });
+}
+`;
+
+    return header + literalImports.toString() + body.toString();
+  }
+
+  // --- Vanilla / write-through entity path: full CRUD routes ---
+  const tableVar = variableNameFromEntity(entityName);
+
+  const HonoSym = imp("t:Hono@hono");
+  const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/hono");
+
+  const literalImports = code`
+import {
+  ${entityName},
+  ${tableVar},
+  ${entityName}InsertSchema,
+  ${entityName}UpdateSchema,
+  ${entityName}FilterAllowlist,
+  ${entityName}SortAllowlist,
+} from ${JSON.stringify(entityFileSpec)};
+`;
+
+  const body = code`
+/**
+ * Mount the 5 standard REST endpoints for ${entityName} using Drizzle directly.
+ *
+ * Customize: register this as-is for stock CRUD, OR import the per-verb
+ * helpers (mountListRoute, mountGetRoute, ...) from
+ * @metaobjectsdev/runtime-ts/hono and mix with your own handlers
+ * (auth, side effects, etc.).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: consumer-defined Hono bindings/variables
+export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unknown }): void {
+  ${mountCrudRoutesSym}({
+    app,
+    path: ${pathExpr},
+    db: deps.db,
+    table: ${tableVar},
+    insertSchema: ${entityName}InsertSchema,
+    updateSchema: ${entityName}UpdateSchema,
+    filterAllowlist: ${entityName}FilterAllowlist,
+    sortAllowlist: ${entityName}SortAllowlist,
+    dialect: ${JSON.stringify(ctx.dialect)},
+  });
+}
+`;
+
+  return header + literalImports.toString() + body.toString();
+}

package/src/templates/value-object-file.ts

@@ -0,0 +1,30 @@
+// Value-object file composer — emits a streamlined "value-only" module for
+// metaobjects with no writable source.rdb child. Output is just the TS
+// interface + the Zod schema (and enum type aliases when applicable); no
+// Drizzle table, no Infer*Model aliases, no filter allowlists, no constants
+// object.
+//
+// Dispatch: entity-file.ts routes here when hasWritableRdbSource(entity) is
+// false. The entity may still have read-only source.* children (those are
+// handled by the projection path before this one is reached).
+
+import { joinCode, type Code } from "ts-poet";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { renderValueObjectInterface, renderEnumTypeAliases } from "./inferred-types.js";
+import { renderInsertSchemaOnly } from "./zod-validators.js";
+import { GENERATED_HEADER } from "../constants.js";
+
+export function renderValueObjectFile(obj: MetaObject): string {
+  const enumAliases = renderEnumTypeAliases(obj);
+  const sections: Code[] = [
+    renderValueObjectInterface(obj),
+    ...(enumAliases !== null ? [enumAliases] : []),
+    renderInsertSchemaOnly(obj),
+  ];
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${obj.name} (${obj.fqn()})\n` +
+    `// Customize via ${obj.name}.extra.ts in this directory.\n`;
+  return header + body;
+}

package/src/templates/zod-validators.ts

@@ -2,53 +2,102 @@
 // Auto-generated PKs are EXCLUDED from InsertSchema (caller doesn't provide them).
 // @autoSet fields: INSERT → .optional().transform(() => new Date().toISOString())
 //                 UPDATE → onCreate fields omitted entirely; onUpdate gets same transform
+//
+// field.object isArray:true objectRef:<Ref> — emits z.array(<Ref>InsertSchema)
+// with a cross-module imp() so consumers passing the schema to
+// zod-to-json-schema get a properly element-typed array. Without this, every
+// object-array field collapsed to z.array(z.string()) and the JSON Schema sent
+// downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
-import { code, imp, type Code } from "ts-poet";
+import { code, joinCode, imp, type Code } from "ts-poet";
 import { MetaObject, MetaField } 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,
   FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP,
-  FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT,
   VALIDATOR_SUBTYPE_REQUIRED, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   FIELD_ATTR_REQUIRED, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT,
-  FIELD_ATTR_AUTO_SET, AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
+  FIELD_ATTR_AUTO_SET, FIELD_ATTR_OBJECT_REF, AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
 } from "@metaobjectsdev/metadata";
 import { enumValues, zodEnumExpr } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
 
-export function renderZodValidators(obj: MetaObject): Code {
-  const z = imp("z@zod");
+/** Auto-generated PK field names that should be omitted from InsertSchema. */
+function autoGenPkFieldNames(obj: MetaObject): Set<string> {
+  const out = new Set<string>();
   const primary = obj.primaryIdentity();
-  const autoGenPkFields = new Set<string>();
   if (primary) {
     const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
     if (generation === GENERATION_INCREMENT || generation === GENERATION_UUID) {
       const fields = primary.ownAttr(IDENTITY_ATTR_FIELDS);
       const fieldsList = Array.isArray(fields) ? fields : (typeof fields === "string" ? [fields] : []);
-      for (const f of fieldsList) autoGenPkFields.add(String(f));
+      for (const f of fieldsList) out.add(String(f));
     }
   }
+  return out;
+}
 
-  const insertFieldLines: string[] = [];
-  const updateFieldLines: string[] = [];
+/**
+ * Emit ONLY the `<Name>InsertSchema`. Used by the value-object file emitter
+ * for metaobjects with no writable source.rdb — those have no PATCH/update
+ * semantics, so emitting an UpdateSchema would be misleading.
+ *
+ * The schema name is kept as `<Name>InsertSchema` even for pure value objects
+ * so consumer imports don't churn. A future polish PR could add a `<Name>Schema`
+ * alias for clarity.
+ */
+export function renderInsertSchemaOnly(obj: MetaObject): Code {
+  const z = imp("z@zod");
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+
+  const insertFieldLines: Code[] = [];
+  for (const child of obj.fields()) {
+    if (autoGenPkFields.has(child.name)) continue;
+
+    const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
+
+    if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
+      );
+    } else {
+      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child)}`);
+    }
+  }
+
+  const insertSchemaName = `${obj.name}InsertSchema`;
+  const docs = renderDocsFor(obj);
+  const docsPrefix = docs ? `${docs}\n` : "";
+
+  return code`
+${docsPrefix}export const ${insertSchemaName} = ${z}.object({
+${joinCode(insertFieldLines, { on: ",\n" })}
+});
+`;
+}
+
+export function renderZodValidators(obj: MetaObject): Code {
+  const z = imp("z@zod");
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+
+  const insertFieldLines: Code[] = [];
+  const updateFieldLines: Code[] = [];
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
 
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
     // Insert schema: @autoSet fields use transform (always override client input).
-    // NOTE: use "z" as a literal string here — these lines are embedded in the
-    // `code` template tag below which resolves the imp("z@zod") import.
     if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
       insertFieldLines.push(
-        `  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
+        code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
     } else {
-      insertFieldLines.push(`  ${child.name}: ${zodFieldExpr(child)}`);
+      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child)}`);
     }
 
     // Update schema: @autoSet onCreate → omit entirely; onUpdate → transform
@@ -56,13 +105,16 @@ export function renderZodValidators(obj: MetaObject): Code {
       // Omit: creation timestamps cannot be changed after creation
     } else if (autoSet === AUTO_SET_ON_UPDATE) {
       updateFieldLines.push(
-        `  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
+        code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
     } else {
-      // All non-autoSet fields are optional in the update schema (PATCH semantics)
-      const expr = zodFieldExpr(child);
-      const optionalExpr = expr.endsWith(".optional()") ? expr : `${expr}.optional()`;
-      updateFieldLines.push(`  ${child.name}: ${optionalExpr}`);
+      // All non-autoSet fields are optional in the update schema (PATCH semantics).
+      // zodFieldExpr already appends .optional() when the field is non-required
+      // OR has a default; only append once more when it didn't.
+      const baseExpr = zodFieldExpr(child);
+      updateFieldLines.push(
+        fieldWillBeOptional(child) ? code`  ${child.name}: ${baseExpr}` : code`  ${child.name}: ${baseExpr}.optional()`,
+      );
     }
   }
 
@@ -74,48 +126,82 @@ export function renderZodValidators(obj: MetaObject): Code {
 
   return code`
 ${docsPrefix}export const ${insertSchemaName} = ${z}.object({
-${insertFieldLines.join(",\n")}
+${joinCode(insertFieldLines, { on: ",\n" })}
 });
 
 ${docsPrefix}export const ${updateSchemaName} = ${z}.object({
-${updateFieldLines.join(",\n")}
+${joinCode(updateFieldLines, { on: ",\n" })}
 });
 `;
 }
 
-function zodFieldExpr(field: MetaField): string {
-  let base: string;
+function zodFieldExpr(field: MetaField): Code {
+  // FIELD_SUBTYPE_OBJECT: emit z.array(<Ref>InsertSchema) / <Ref>InsertSchema
+  // via an imp() so ts-poet hoists the cross-module import. Without this the
+  // field used to collapse to z.string() / z.array(z.string()) and downstream
+  // JSON Schema (e.g. LLM tool_use input_schema) lost the nested object shape.
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof ref === "string" && ref.length > 0) {
+      const refImp = imp(`${ref}InsertSchema@./${ref}.js`);
+      let base: Code = code`${refImp}`;
+      if (field.isArray) base = code`z.array(${base})`;
+      return appendValidatorChain(base, field);
+    }
+    // No resolvable @objectRef — fall through to z.unknown(); downstream code
+    // can still pass a value through but loses validation.
+    let base: Code = code`z.unknown()`;
+    if (field.isArray) base = code`z.array(${base})`;
+    return appendValidatorChain(base, field);
+  }
+
+  let baseStr: string;
   switch (field.subType) {
     case FIELD_SUBTYPE_INT:
     case FIELD_SUBTYPE_CURRENCY:
     case FIELD_SUBTYPE_LONG:
-      base = "z.number().int()";
+      baseStr = "z.number().int()";
       break;
     case FIELD_SUBTYPE_DOUBLE:
     case FIELD_SUBTYPE_FLOAT:
-      base = "z.number()";
+      baseStr = "z.number()";
       break;
     case FIELD_SUBTYPE_BOOLEAN:
-      base = "z.boolean()";
+      baseStr = "z.boolean()";
       break;
     case FIELD_SUBTYPE_DATE:
     case FIELD_SUBTYPE_TIME:
     case FIELD_SUBTYPE_TIMESTAMP:
-      base = "z.string()";
+      baseStr = "z.string()";
       break;
     case FIELD_SUBTYPE_ENUM: {
       const values = enumValues(field);
-      base = values !== undefined ? zodEnumExpr(values) : "z.string()";
+      baseStr = values !== undefined ? zodEnumExpr(values) : "z.string()";
       break;
     }
     case FIELD_SUBTYPE_STRING:
     default:
-      base = "z.string()";
+      baseStr = "z.string()";
       break;
   }
 
-  if (field.isArray) base = `z.array(${base})`;
+  if (field.isArray) baseStr = `z.array(${baseStr})`;
+  return appendValidatorChain(code`${baseStr}`, field);
+}
+
+/** Mirrors the optional-or-not decision inside appendValidatorChain so the update-schema
+ *  caller can avoid stacking a second `.optional()` onto an already-optional expression. */
+function fieldWillBeOptional(field: MetaField): boolean {
+  let isRequired = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+  for (const child of field.validators()) {
+    if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) isRequired = true;
+  }
+  const hasDefault = field.ownAttr(FIELD_ATTR_DEFAULT) !== undefined;
+  return !isRequired || hasDefault;
+}
 
+/** Append .min/.max/.regex/.optional() based on field-level validators + required state. */
+function appendValidatorChain(base: Code, field: MetaField): Code {
   let isRequired = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
   let maxLen: number | undefined = field.ownAttr(FIELD_ATTR_MAX_LENGTH) as number | undefined;
   let minLen: number | undefined;
@@ -134,18 +220,18 @@ function zodFieldExpr(field: MetaField): string {
     }
   }
 
-  let chain = base;
+  let chain: Code = base;
   if (field.subType === FIELD_SUBTYPE_STRING && !field.isArray) {
-    if (minLen !== undefined) chain += `.min(${minLen})`;
-    else if (isRequired) chain += `.min(1)`;
-    if (maxLen !== undefined) chain += `.max(${maxLen})`;
-    if (pattern !== undefined) chain += `.regex(new RegExp(${JSON.stringify(pattern)}))`;
+    if (minLen !== undefined) chain = code`${chain}.min(${minLen})`;
+    else if (isRequired) chain = code`${chain}.min(1)`;
+    if (maxLen !== undefined) chain = code`${chain}.max(${maxLen})`;
+    if (pattern !== undefined) chain = code`${chain}.regex(new RegExp(${JSON.stringify(pattern)}))`;
   }
 
   // Fields with DB-level defaults are optional in the InsertSchema: the caller
   // can omit them and the DB will fill in. Otherwise required-with-default
   // would force callers to repeat the default at every call site.
   const hasDefault = field.ownAttr(FIELD_ATTR_DEFAULT) !== undefined;
-  if (!isRequired || hasDefault) chain += `.optional()`;
+  if (!isRequired || hasDefault) chain = code`${chain}.optional()`;
   return chain;
 }