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

package/src/templates/extract-delegate-emitter.ts

@@ -0,0 +1,370 @@
+// server/typescript/packages/codegen-ts/src/templates/extract-delegate-emitter.ts
+//
+// FR-010 Plan 2.1 (nested codegen gap) — the runtime-DELEGATING extract emitter.
+//
+// The self-contained extract<Name>(text) path (extract-schema-emitter + the baked
+// ExtractSchema) covers scalars / enums / scalar-arrays but leaves nested-object and
+// array-of-object components NULL — the historical FR-010 codegen gap. This module emits
+// the additive delegating overload that CLOSES that gap by wrapping the runtime extract:
+//
+//   extract<Name>(root: MetaRoot, text, opts?) -> ExtractionResult<<Name>Extracted>
+//
+// It resolves this payload's MetaObject by its baked simple name from the supplied MetaRoot,
+// delegates to extractObject() in @metaobjectsdev/runtime-ts (which assembles the FULL nested
+// object graph reflection-free via the Phase A object model — MetaObject.newInstance() + the
+// MetaField SPI), then maps the assembled ValueObject graph into the typed nullable mirror
+// graph via generated from<VO>(...) mapper functions (payload + every nested VO, deduped).
+//
+// This is the codegen-wrapping-runtime pattern (a generated DAO calling the dynamic-metadata
+// runtime), mirroring the Java SpringOutputParserGenerator + Kotlin pilots. The generated
+// mappers read the assembled graph through a tiny readProp() helper that mirrors the MetaField
+// getValue SPI (ValueObject.get(name) else plain-property access), so the emitted code stays
+// self-sufficient and reflection-free.
+
+import {
+  type MetaData,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_OBJECT_REF,
+  PACKAGE_SEPARATOR,
+} from "@metaobjectsdev/metadata";
+import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.js";
+
+function findObject(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+}
+
+/** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
+function refVo(field: MetaData, root: MetaData): MetaData | undefined {
+  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref !== "string") return undefined;
+  const direct = findObject(root, ref);
+  if (direct !== undefined) return direct;
+  const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  if (sep >= 0) return findObject(root, ref.slice(sep + PACKAGE_SEPARATOR.length));
+  return undefined;
+}
+
+/** True iff the field is a nested object reference (field.object — distinct from the
+ *  string-backed field.enum, which is treated as a scalar). */
+function isObjectField(field: MetaData): boolean {
+  return field.subType === FIELD_SUBTYPE_OBJECT;
+}
+
+/** The extracted-mirror interface name for a value-object (`<Name>Extracted`). */
+export function mirrorName(vo: MetaData): string {
+  return `${vo.name}Extracted`;
+}
+
+/** The mapper function name for a value-object (`from<Name>Extracted`). */
+function mapperName(vo: MetaData): string {
+  return `from${vo.name}Extracted`;
+}
+
+// =============================================================================
+// Nested-aware mirror interfaces (payload + every reachable nested VO)
+// =============================================================================
+
+/** The nullable mirror TS type for one field — nested-aware (recurses into nested mirror names). */
+function nestedMirrorType(field: MetaData, root: MetaData): string {
+  if (isObjectField(field)) {
+    const target = refVo(field, root);
+    const base = target !== undefined ? mirrorName(target) : "unknown";
+    const elem = `${base} | null`;
+    return isArray(field) ? `(${elem})[] | null` : elem;
+  }
+  if (isArray(field)) return "(string | null)[] | null";
+  if (field.subType === FIELD_SUBTYPE_ENUM) return "string | null";
+  switch (scalarKind(field.subType)) {
+    case "INT":
+    case "LONG":
+    case "DOUBLE":
+      return "number | null";
+    case "BOOLEAN":
+      return "boolean | null";
+    default:
+      return "string | null";
+  }
+}
+
+/**
+ * Emit the nested-aware mirror interface for `vo` and every value-object reachable from it
+ * (deduped by simple name; cycle-safe). The payload mirror keeps the canonical `<Payload>Extracted`
+ * name (passed in) so the existing self-contained extract<Name>() and the delegating overload
+ * share one mirror type. Returns the joined interface declarations in stable (BFS) order.
+ */
+export function nestedMirrorInterfaces(vo: MetaData, root: MetaData, payloadMirror: string): string {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  emitMirror(vo, root, payloadMirror, seen, out);
+  return out.join("\n\n");
+}
+
+function emitMirror(
+  vo: MetaData,
+  root: MetaData,
+  interfaceName: string,
+  seen: Set<string>,
+  out: string[],
+): void {
+  if (seen.has(vo.name)) return;
+  seen.add(vo.name);
+
+  const base = interfaceName.endsWith("Extracted")
+    ? interfaceName.slice(0, -"Extracted".length)
+    : interfaceName;
+  const lines: string[] = [];
+  lines.push(
+    `/** Best-effort extracted twin of \`${base}\` — every field nullable (null where lost/malformed). */`,
+  );
+  lines.push(`export interface ${interfaceName} {`);
+  for (const f of fields(vo)) {
+    lines.push(`  ${f.name}: ${nestedMirrorType(f, root)};`);
+  }
+  lines.push("}");
+  out.push(lines.join("\n"));
+
+  // Recurse into nested VOs (post-order via the shared seen set → dedupe + cycle guard).
+  for (const f of fields(vo)) {
+    if (isObjectField(f)) {
+      const target = refVo(f, root);
+      if (target !== undefined) emitMirror(target, root, mirrorName(target), seen, out);
+    }
+  }
+}
+
+// =============================================================================
+// Mapper functions (assembled ValueObject graph -> typed nullable mirror graph)
+// =============================================================================
+
+/**
+ * Emit one `from<VO>Extracted(o)` mapper per value-object reachable from `vo` (payload + nested,
+ * deduped). Each mapper reads the assembled object via readProp() and recurses into nested
+ * mappers for object/array-of-object components. Nested mappers use `from<NestedName>Extracted`
+ * returning `<NestedName>Extracted`. The ROOT mapper is overridden to the template-derived names
+ * (`rootMapperFn` / `rootMirror`) so it matches the canonically-named root mirror interface — the
+ * payload VO's own name may differ from the template name.
+ */
+export function nestedMappers(
+  vo: MetaData,
+  root: MetaData,
+  rootMapperFn: string,
+  rootMirror: string,
+): string {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  emitMapper(vo, root, seen, out, { fn: rootMapperFn, mirror: rootMirror });
+  return out.join("\n\n");
+}
+
+/** The root mapper's name + mirror — derived from the template, not the payload VO. */
+export function rootMapperName(template: string): string {
+  return `from${template}Extracted`;
+}
+
+function emitMapper(
+  vo: MetaData,
+  root: MetaData,
+  seen: Set<string>,
+  out: string[],
+  override?: { fn: string; mirror: string },
+): void {
+  if (seen.has(vo.name)) return;
+  seen.add(vo.name);
+
+  const fn = override?.fn ?? mapperName(vo);
+  const mir = override?.mirror ?? mirrorName(vo);
+  const assigns = fields(vo).map((f) => `    ${f.name}: ${mapperArg(f, root)},`);
+  const body = [
+    `/** Map an assembled ValueObject graph into a typed \`${mir}\` mirror. Generated; null-tolerant. */`,
+    `function ${fn}(o: unknown): ${mir} | null {`,
+    `  if (o == null) return null;`,
+    `  return {`,
+    ...assigns,
+    `  };`,
+    `}`,
+  ].join("\n");
+  out.push(body);
+
+  for (const f of fields(vo)) {
+    if (isObjectField(f)) {
+      const target = refVo(f, root);
+      if (target !== undefined) emitMapper(target, root, seen, out);
+    }
+  }
+}
+
+/** The mirror-field initializer expression that reads `field` from the assembled object `o`. */
+function mapperArg(field: MetaData, root: MetaData): string {
+  const key = jsonStringLiteral(field.name);
+
+  if (isObjectField(field)) {
+    const target = refVo(field, root);
+    if (target === undefined) return "null /* unresolved @objectRef */";
+    const fn = mapperName(target);
+    if (isArray(field)) {
+      return `mapObjectList(readProp(o, ${key}), ${fn})`;
+    }
+    return `${fn}(readProp(o, ${key}))`;
+  }
+
+  // Enum / scalar / scalar-array: the runtime already coerced; read + light-coerce to the
+  // mirror's nullable shape via the locally-defined dlg* readers. (These are distinct from the
+  // render ExtractMap helpers `asString(d, key)` etc., which the self-contained path imports — a
+  // local helper must NOT shadow those, so the delegate readers carry the `dlg` prefix.)
+  // An enum ARRAY is string-backed PER ELEMENT — it must use the list reader, NOT dlgString
+  // (which would String()-collapse the whole array into "A,B"). Check isArray before the enum
+  // scalar case. The mirror TYPE for an enum array is already `(string | null)[] | null` (see
+  // mirrorFieldType), so the list reader matches.
+  if (field.subType === FIELD_SUBTYPE_ENUM && isArray(field)) return `dlgStringList(readProp(o, ${key}))`;
+  if (field.subType === FIELD_SUBTYPE_ENUM) return `dlgString(readProp(o, ${key}))`;
+  if (isArray(field)) return `dlgStringList(readProp(o, ${key}))`;
+  switch (scalarKind(field.subType)) {
+    case "INT":
+    case "LONG":
+      return `dlgInt(readProp(o, ${key}))`;
+    case "DOUBLE":
+      return `dlgNumber(readProp(o, ${key}))`;
+    case "BOOLEAN":
+      return `dlgBool(readProp(o, ${key}))`;
+    default:
+      return `dlgString(readProp(o, ${key}))`;
+  }
+}
+
+/**
+ * The set of generated-helper names the mappers for `vo` (+ reachable nested VOs) actually
+ * reference. Used to emit only the needed helpers (consumer projects may run noUnusedLocals).
+ * `readProp` + at least one dlg* reader are always present once any mapper is emitted.
+ */
+export function usedHelpers(vo: MetaData, root: MetaData): Set<string> {
+  const used = new Set<string>(["readProp"]);
+  const seen = new Set<string>();
+  const stack = [vo];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    if (seen.has(cur.name)) continue;
+    seen.add(cur.name);
+    for (const f of fields(cur)) {
+      if (isObjectField(f)) {
+        const target = refVo(f, root);
+        if (target === undefined) continue;
+        stack.push(target);
+        if (isArray(f)) used.add("mapObjectList");
+        continue;
+      }
+      if (f.subType === FIELD_SUBTYPE_ENUM && isArray(f)) {
+        used.add("dlgStringList");
+      } else if (f.subType === FIELD_SUBTYPE_ENUM) {
+        used.add("dlgString");
+      } else if (isArray(f)) {
+        used.add("dlgStringList");
+      } else {
+        switch (scalarKind(f.subType)) {
+          case "INT":
+          case "LONG":
+            used.add("dlgInt");
+            break;
+          case "DOUBLE":
+            used.add("dlgNumber");
+            break;
+          case "BOOLEAN":
+            used.add("dlgBool");
+            break;
+          default:
+            used.add("dlgString");
+        }
+      }
+    }
+  }
+  return used;
+}
+
+/** True iff the payload (or any reachable nested VO) has a nested-object / array-of-object field. */
+export function hasNested(vo: MetaData, root: MetaData): boolean {
+  const seen = new Set<string>();
+  const stack = [vo];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    if (seen.has(cur.name)) continue;
+    seen.add(cur.name);
+    for (const f of cur.children().filter((c) => c.type === TYPE_FIELD)) {
+      if (isObjectField(f)) {
+        const target = refVo(f, root);
+        if (target !== undefined) {
+          stack.push(target);
+        }
+        // a nested object field exists regardless of resolvability → still "has nested"
+        if (f.subType === FIELD_SUBTYPE_OBJECT) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * The shared runtime-side helper block the generated mappers rely on:
+ *   • readProp  — null-tolerant read mirroring the MetaField getValue SPI (ValueObject.get(name)
+ *                 else plain-property access); keeps the mappers reflection-free + backing-agnostic.
+ *   • mapObjectList — map each element of an assembled array via a per-element mapper.
+ *   • dlg* readers — light null-tolerant coercion to the mirror's nullable scalar shapes. The
+ *     `dlg` prefix avoids shadowing the render ExtractMap helpers (`asString(d, key)` etc.) that
+ *     the self-contained extract path imports into the SAME file — a collision would silently
+ *     rebind those two-arg map readers to these one-arg readers.
+ * Emitted once per parser file.
+ */
+export function delegateHelpers(used: Set<string>): string {
+  const blocks: string[] = ["// ---- runtime-delegating extract helpers (generated) ----"];
+
+  // readProp is always needed once a mapper exists.
+  blocks.push(`/** Read a property from an assembled backing object, mirroring the MetaField getValue SPI. */
+function readProp(o: unknown, name: string): unknown {
+  if (o == null) return undefined;
+  const vo = o as { get?: (n: string) => unknown };
+  if (typeof vo.get === "function") return vo.get(name);
+  return (o as Record<string, unknown>)[name];
+}`);
+
+  if (used.has("mapObjectList")) {
+    blocks.push(`/** Map each element of an assembled array via \`fn\`; null/absent -> null; non-mappable -> filtered. */
+function mapObjectList<T>(v: unknown, fn: (o: unknown) => T | null): (T | null)[] | null {
+  if (!Array.isArray(v)) return null;
+  return v.map((e) => fn(e));
+}`);
+  }
+  if (used.has("dlgString")) {
+    blocks.push(`function dlgString(v: unknown): string | null {
+  return v == null ? null : String(v);
+}`);
+  }
+  if (used.has("dlgInt")) {
+    blocks.push(`function dlgInt(v: unknown): number | null {
+  if (v == null) return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? Math.trunc(n) : null;
+}`);
+  }
+  if (used.has("dlgNumber")) {
+    blocks.push(`function dlgNumber(v: unknown): number | null {
+  if (v == null) return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}`);
+  }
+  if (used.has("dlgBool")) {
+    blocks.push(`function dlgBool(v: unknown): boolean | null {
+  if (v == null) return null;
+  if (typeof v === "boolean") return v;
+  return String(v).toLowerCase() === "true";
+}`);
+  }
+  if (used.has("dlgStringList")) {
+    blocks.push(`function dlgStringList(v: unknown): (string | null)[] | null {
+  if (!Array.isArray(v)) return null;
+  return v.map((e) => (e == null ? null : String(e)));
+}`);
+  }
+  return blocks.join("\n\n");
+}

package/src/templates/{recover-schema-emitter.ts → extract-schema-emitter.ts}

@@ -1,15 +1,15 @@
-// server/typescript/packages/codegen-ts/src/templates/recover-schema-emitter.ts
+// server/typescript/packages/codegen-ts/src/templates/extract-schema-emitter.ts
 //
-// Turns a payload value-object into TS source fragments for the FR-010 recover codegen:
-//   • schemaLiteral     — a `recoverSchema(Format.JSON, "root", [ … ])` baked descriptor
+// Turns a payload value-object into TS source fragments for the FR-010 extract codegen:
+//   • schemaLiteral     — a `extractSchema(Format.JSON, "root", [ … ])` baked descriptor
 //                         built from FieldSpec factories (scalar / enumField).
-//   • mirrorInterface   — an all-nullable mirror interface `<Payload>Recovered` (each
-//                         component `T | null`); recover returns this nullable twin rather
+//   • mirrorInterface   — an all-nullable mirror interface `<Payload>Extracted` (each
+//                         component `T | null`); extract returns this nullable twin rather
 //                         than the strict payload (same reasoning as the Java/C#/Kotlin ports).
 //   • mirrorInitializer — `{ prop: asString(d, "prop"), … }` building the mirror from the
 //                         forgiving outcome map `d`.
 //
-// Mirrors the C# RecoverSchemaEmitter (adapted to TS syntax + the `| null` nullable mirror).
+// Mirrors the C# ExtractSchemaEmitter (adapted to TS syntax + the `| null` nullable mirror).
 // Bounded scope: scalar / enum / scalar-array. Nested object + array-of-enum deferred.
 
 import {
@@ -24,40 +24,60 @@ import {
   isArray,
   scalarKind,
   mirrorType,
-  recoverMapCall,
+  extractMapCall,
   enumValues,
+  coerceDefault,
+  defaultValue,
+  resolveNormalize,
   jsonStringLiteral,
   stringArrayLiteral,
   propertiesMapLiteral,
 } from "./fr010-field-mapping.js";
+import { NORMALIZE_DEFAULT } from "@metaobjectsdev/metadata";
 
-/** Emit `recoverSchema(Format.X, "rootName", [ … ])`. */
+/** Emit `extractSchema(Format.X, "rootName", [ … ])`. */
 export function schemaLiteral(vo: MetaData, format: string, rootName: string): string {
   const formatEnum = format.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
-  const specs = fields(vo).map(fieldSpecLiteral);
-  return `recoverSchema(${formatEnum}, ${jsonStringLiteral(rootName)}, [${specs.join(", ")}])`;
+  const specs = fields(vo).map((f) => fieldSpecLiteral(f, vo));
+  return `extractSchema(${formatEnum}, ${jsonStringLiteral(rootName)}, [${specs.join(", ")}])`;
 }
 
-function fieldSpecLiteral(field: MetaData): string {
+function fieldSpecLiteral(field: MetaData, owner: MetaData): string {
   const name = jsonStringLiteral(field.name);
   const required = isRequired(field);
 
   if (field.subType === FIELD_SUBTYPE_ENUM) {
     const valuesLit = stringArrayLiteral(enumValues(field));
     const aliasLit = propertiesMapLiteral(field.ownAttr(FIELD_ATTR_ENUM_ALIAS));
+    // FR-011: extended enumField signature is (name, required, values, aliases,
+    // coerceDefault?, normalize="strip", defaultValue?). Resolve the three new args
+    // (field → object → "strip" for normalize) and emit only what's needed: keep the
+    // back-compat 4-arg form when nothing is set, else emit the positional tail up to
+    // the last meaningful arg.
+    const cd = coerceDefault(field);
+    const dv = defaultValue(field);
+    const normalize = resolveNormalize(field, owner);
     // enumField() sets array:false; enum-array is a bounded deferral (parity with Java/C#).
-    return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit})`;
+    if (cd == null && dv == null && normalize === NORMALIZE_DEFAULT) {
+      return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit})`;
+    }
+    const cdLit = cd == null ? "null" : jsonStringLiteral(cd);
+    const normLit = jsonStringLiteral(normalize);
+    if (dv == null) {
+      return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit}, ${cdLit}, ${normLit})`;
+    }
+    return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit}, ${cdLit}, ${normLit}, ${jsonStringLiteral(dv)})`;
   }
 
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    // FR-010: nested recover deferred — treat as an opaque required/optional string slot.
-    return `scalar(${name}, FieldKind.STRING, ${required}) /* FR-010: nested recover deferred */`;
+    // FR-010: nested extract deferred — treat as an opaque required/optional string slot.
+    return `scalar(${name}, FieldKind.STRING, ${required}) /* FR-010: nested extract deferred */`;
   }
 
   const kind = scalarKind(field.subType) ?? "STRING";
   // Scalar-array: the scalar() factory only builds singular specs (array:false), so emit a
   // FieldSpec object literal with array:true. Tier-2 win over the Roslyn proof: the emitted
-  // recover() actually populates the array at runtime (RecoverMap.asStringList).
+  // extract() actually populates the array at runtime (ExtractMap.asStringList).
   if (isArray(field)) {
     return (
       `{ name: ${name}, kind: FieldKind.${kind}, required: ${required}, array: true, ` +
@@ -69,12 +89,12 @@ function fieldSpecLiteral(field: MetaData): string {
 
 /** Emit the all-nullable mirror interface declaration. */
 export function mirrorInterface(vo: MetaData, interfaceName: string): string {
-  const base = interfaceName.endsWith("Recovered")
-    ? interfaceName.slice(0, -"Recovered".length)
+  const base = interfaceName.endsWith("Extracted")
+    ? interfaceName.slice(0, -"Extracted".length)
     : interfaceName;
   const lines: string[] = [];
   lines.push(
-    `/** Best-effort recovered twin of \`${base}\` — every field nullable (null where lost/malformed). */`,
+    `/** Best-effort extracted twin of \`${base}\` — every field nullable (null where lost/malformed). */`,
   );
   lines.push(`export interface ${interfaceName} {`);
   for (const f of fields(vo)) {
@@ -86,6 +106,6 @@ export function mirrorInterface(vo: MetaData, interfaceName: string): string {
 
 /** Emit `{ prop: asString(d, "prop"), … }` building the mirror from the forgiving map `d`. */
 export function mirrorInitializer(vo: MetaData): string {
-  const assigns = fields(vo).map((f) => `${f.name}: ${recoverMapCall(f)}`);
+  const assigns = fields(vo).map((f) => `${f.name}: ${extractMapCall(f)}`);
   return `{ ${assigns.join(", ")} }`;
 }