@metaobjectsdev/runtime-ts 0.9.0-rc.1 → 0.10.0

package/src/drizzle-fastify/mount-m2m.ts

@@ -0,0 +1,126 @@
+// M:N traversal route — mounts `GET {path}/:id/{relationName}` returning the
+// related target rows reached through a junction table.
+//
+// This is the Drizzle-direct executor for a many-to-many relationship. Codegen
+// derives the static descriptor at BUILD time (the source/target junction FK
+// columns come from the junction entity's two `identity.reference` children via
+// the shared `deriveM2MFields` SSOT — see relation-resolver.ts in codegen-ts),
+// then emits a `mountM2mRoute({...})` call carrying those resolved column names.
+// At runtime this helper performs the same two-stage join the ObjectManager
+// `n2m-resolver` performs, but expressed in Drizzle so it stays self-evident
+// Drizzle code in the user's app (no ObjectManager dependency, no metadata at
+// runtime — ADR-0001 build-time binding).
+//
+// Three modes, identical to the runtime resolver:
+//   1. Hetero (sourceCol != targetCol entity): junction WHERE sourceCol = :id,
+//      collect targetCol, target WHERE pk IN (...).
+//   2. Directed self-join: same traversal; codegen picked which junction FK is
+//      the source side (via @sourceRefField) → sourceColumn/targetColumn.
+//   3. Symmetric self-join: junction WHERE sourceCol = :id OR targetCol = :id;
+//      per row the related id is whichever column is NOT the source id.
+
+import type { FastifyInstance, RouteShorthandOptions } from "fastify";
+import { eq, or, inArray } from "drizzle-orm";
+import { parseId } from "./util.js";
+
+// Loose Drizzle types — the helper works across libsql / better-sqlite3 / pg.
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle instance
+type AnyDrizzle = any;
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle table
+type AnyTable = any;
+
+export interface M2mRouteOptions {
+  fastify: FastifyInstance;
+  /** Source resource path, e.g. "/posts". The route mounts at `{path}/:id/{relationName}`. */
+  path: string;
+  /** Navigation member name, e.g. "tags" → GET /posts/:id/tags. */
+  relationName: string;
+  /** User's Drizzle instance. */
+  db: AnyDrizzle;
+  /** The junction Drizzle table const (e.g. postTags). */
+  junctionTable: AnyTable;
+  /** The target Drizzle table const (e.g. tags). */
+  targetTable: AnyTable;
+  /** Junction FK column holding the SOURCE key (physical column name, e.g. "post_id"). */
+  sourceColumn: string;
+  /** Junction FK column holding the TARGET key (physical column name, e.g. "tag_id"). */
+  targetColumn: string;
+  /** Target entity PK column (physical column name, e.g. "id"). Defaults to "id". */
+  targetPkColumn?: string;
+  /** Undirected self-join: union both junction FK columns on read. */
+  symmetric: boolean;
+  /** Fastify route-level hooks (auth, etc.). */
+  routeOptions?: RouteShorthandOptions;
+}
+
+export function mountM2mRoute(opts: M2mRouteOptions): void {
+  const targetPk = opts.targetPkColumn ?? "id";
+  const route = `${opts.path}/:id/${opts.relationName}`;
+  const ro = opts.routeOptions ?? {};
+
+  opts.fastify.get(route, ro, async (req) => {
+    const { id } = req.params as { id: string };
+    const sourceId = parseId(id);
+
+    const srcCol = columnRef(opts.junctionTable, opts.sourceColumn);
+    const tgtCol = columnRef(opts.junctionTable, opts.targetColumn);
+
+    // Stage 1 — junction rows for this source id.
+    const joinWhere = opts.symmetric
+      ? or(eq(srcCol, sourceId), eq(tgtCol, sourceId))
+      : eq(srcCol, sourceId);
+    const joinRows = (await opts.db
+      .select({ src: srcCol, tgt: tgtCol })
+      .from(opts.junctionTable)
+      .where(joinWhere)) as Array<{ src: unknown; tgt: unknown }>;
+
+    // Collect the related target ids. Symmetric: the related endpoint is the
+    // column that is NOT the source id (compared by string key to bridge
+    // number/bigint-as-string driver skew). Otherwise: always the target column.
+    const sourceKey = String(sourceId);
+    const relatedIds = new Set<string | number>();
+    for (const r of joinRows) {
+      if (!opts.symmetric) {
+        addId(relatedIds, r.tgt);
+        continue;
+      }
+      const srcIsSource = r.src != null && String(r.src) === sourceKey;
+      // Self-loop (a,a): src matches → relate to a itself (single occurrence).
+      if (srcIsSource) addId(relatedIds, r.tgt);
+      else addId(relatedIds, r.src);
+    }
+
+    if (relatedIds.size === 0) return [];
+
+    // Stage 2 — load the target rows.
+    const pkCol = columnRef(opts.targetTable, targetPk);
+    return await opts.db
+      .select()
+      .from(opts.targetTable)
+      .where(inArray(pkCol, [...relatedIds]));
+  });
+}
+
+function addId(set: Set<string | number>, v: unknown): void {
+  if (v === null || v === undefined) return;
+  if (typeof v === "number" || typeof v === "string") set.add(v);
+  else if (typeof v === "bigint") set.add(Number(v));
+}
+
+/**
+ * Resolve a physical column name to its Drizzle column object. Drizzle exposes
+ * columns on the table object keyed by the TS property name, but the underlying
+ * `.name` is the physical column. The descriptor carries physical names (what
+ * the junction/target SQL uses), so match on `.name` and fall back to the key.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: returns a Drizzle column ref for the loose query builder
+function columnRef(table: AnyTable, physicalName: string): any {
+  for (const key of Object.keys(table)) {
+    const col = table[key];
+    if (col && typeof col === "object" && col.name === physicalName) return col;
+  }
+  // Fall back to the property-name lookup (covers tables whose TS key == column).
+  const direct = table[physicalName];
+  if (direct !== undefined) return direct;
+  throw new Error(`mountM2mRoute: column '${physicalName}' not found on table`);
+}

package/src/drizzle-fastify/util.ts

@@ -2,6 +2,12 @@
  * Shared utilities for drizzle-fastify route helpers.
  */
 
+/** Coerce a path-param id to number when numeric, else keep the string key. */
+export function parseId(raw: string): number | string {
+  const n = Number(raw);
+  return Number.isFinite(n) && raw.trim() !== "" ? n : raw;
+}
+
 // Accepts "1" or boolean true (the qs serialization of withCount: 1 from buildFilterQs).
 export function isTruthyFlag(v: unknown): boolean {
   if (v === undefined || v === null) return false;

package/src/extract-object.ts

@@ -33,14 +33,11 @@ import {
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_STRING,
-  FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_UUID,
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_DOUBLE,
@@ -54,6 +51,8 @@ import {
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_NORMALIZE,
   FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_XML_TEXT,
+  VALIDATOR_SUBTYPE_NUMERIC,
   NORMALIZE_DEFAULT,
   type NormalizeMode,
 } from "@metaobjectsdev/metadata";
@@ -62,6 +61,8 @@ import {
   Format,
   FieldKind,
   scalar,
+  range,
+  textContentField,
   enumField,
   enumArray,
   object,
@@ -175,6 +176,18 @@ function fieldSpecFor(
     // Scalar array: the engine coerces each element; no per-element default fill.
     return scalarArray(name, kind, required);
   }
+  // @xmlText: a (non-array) scalar field marked to receive its element's XML text content.
+  if (ownAttrString(field, FIELD_ATTR_XML_TEXT) === "true") {
+    return textContentField(name, kind, required);
+  }
+  // Numeric range: source the bound from the field's numeric validator (@min/@max) — the single
+  // source of truth — so the engine clamps (lenient) / rejects (strict) out-of-range values.
+  if (kind === FieldKind.INT || kind === FieldKind.LONG || kind === FieldKind.DOUBLE) {
+    const numeric = field.validators().find((v) => v.subType === VALIDATOR_SUBTYPE_NUMERIC);
+    if (numeric !== undefined && (numeric.min !== undefined || numeric.max !== undefined)) {
+      return range(name, kind, required, numeric.min ?? null, numeric.max ?? null);
+    }
+  }
   return scalar(name, kind, required, dv);
 }
 
@@ -267,7 +280,6 @@ function scalarArray(name: string, kind: FieldKind, required: boolean): FieldSpe
 function scalarKind(subType: string): FieldKind {
   switch (subType) {
     case FIELD_SUBTYPE_STRING:
-    case FIELD_SUBTYPE_CLASS:
     case FIELD_SUBTYPE_UUID:
     case FIELD_SUBTYPE_DATE:
     case FIELD_SUBTYPE_TIME:
@@ -277,8 +289,6 @@ function scalarKind(subType: string): FieldKind {
     case FIELD_SUBTYPE_DECIMAL:
       return FieldKind.STRING;
     case FIELD_SUBTYPE_INT:
-    case FIELD_SUBTYPE_SHORT:
-    case FIELD_SUBTYPE_BYTE:
       return FieldKind.INT;
     case FIELD_SUBTYPE_LONG:
     case FIELD_SUBTYPE_CURRENCY:

package/src/identity-strategy.ts

@@ -17,7 +17,8 @@ export type IdentityResolution =
   | { kind: "preset"; values: Record<string, unknown> };
 
 export function resolveIdentity(entity: MetaData, data: Record<string, unknown>): IdentityResolution {
-  const primary = entity.ownChildren().find(
+  // Effective children so a TPH subtype resolves the inherited primary identity.
+  const primary = entity.children().find(
     (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY,
   );
   if (!primary) {

package/src/index.ts

@@ -32,3 +32,10 @@ export {
   assemble,
   MAX_NEST_DEPTH,
 } from "./extract-object.js";
+
+// LLM call recorder seam + parse-then-persist helper.
+// Format is re-exported here so callers of recordLlmCall can import it from a
+// single location rather than reaching into @metaobjectsdev/render directly.
+export { Format } from "@metaobjectsdev/render";
+export { LlmCallDbRecorder, NullRecorder, recordLlmCall, buildLlmCallRow, persistLlmCallRow, truncateRow } from "./llm-recorder.js";
+export type { LlmRecorder, LlmCallRow, LlmCallInput, RecordLlmCallOptions, RecordLlmCallResult, LlmCallDbRecorderOpts } from "./llm-recorder.js";

package/src/llm-recorder.ts

@@ -0,0 +1,166 @@
+// LLM call recorder seam + base-row factory + shared persist helper.
+//
+// LlmRecorder is a thin write-side interface for persisting LLM call rows.
+// LlmCallDbRecorder writes via ObjectManager.create (using an entity declared
+// in the caller's own metadata).  NullRecorder is the no-op implementation
+// used in unit tests or when tracing is disabled.
+//
+// recordLlmCall is the GENERIC trace path: it builds the base trace row (the
+// envelope + the raw `llmRequest`/`llmResponse` columns declared on the shipped
+// `LlmCallBase`) and persists it.  It does NOT parse the response into a typed
+// VO — that extract step + the typed voRequest/voResponse columns live on the
+// generated typed helper (a later layer), so this generic path only ever writes
+// the base field set.
+
+import type { ObjectManager } from "./object-manager.js";
+
+// =============================================================================
+// Public types
+// =============================================================================
+
+export type LlmCallRow = Record<string, unknown>;
+
+export interface LlmRecorder {
+  record(call: LlmCallRow): Promise<void>;
+}
+
+// =============================================================================
+// NullRecorder — no-op (testing / disabled tracing)
+// =============================================================================
+
+export class NullRecorder implements LlmRecorder {
+  async record(_call: LlmCallRow): Promise<void> {
+    // deliberate no-op
+  }
+}
+
+// =============================================================================
+// LlmCallDbRecorder — persists via ObjectManager
+// =============================================================================
+
+export interface LlmCallDbRecorderOpts {
+  /** Called when om.create throws. Default: swallow. Telemetry never breaks the app. */
+  onError?: (error: unknown) => void;
+}
+
+export class LlmCallDbRecorder implements LlmRecorder {
+  private readonly om: ObjectManager;
+  private readonly entityName: string;
+  private readonly onError: (error: unknown) => void;
+
+  constructor(om: ObjectManager, entityName: string, opts?: LlmCallDbRecorderOpts) {
+    this.om = om;
+    this.entityName = entityName;
+    this.onError = opts?.onError ?? (() => {});
+  }
+
+  async record(call: LlmCallRow): Promise<void> {
+    try {
+      await this.om.create(this.entityName, call);
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+}
+
+// =============================================================================
+// recordLlmCall — generic base-row persist
+// =============================================================================
+
+export interface LlmCallInput {
+  spanId: string;
+  traceId: string;
+  /** Parent span id; null/absent → this is a root span. */
+  parentSpanId?: string;
+  /** Logical session/conversation id (gen_ai session grouping). */
+  sessionId?: string;
+  callType: string;
+  /** gen_ai.system — provider name, caller-supplied. */
+  system?: string;
+  /** ISO 8601 timestamp, supplied by the caller before the LLM call was made. */
+  startedAt: string;
+  llmRequest: unknown;
+  /** Raw response text/body — stored as the raw `llmResponse` column. */
+  llmResponseText: string;
+  requestModel?: string;
+  /** gen_ai.response.model — the model the provider actually used. */
+  responseModel?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  costMinor?: number;
+  latencyMs?: number;
+  finishReason?: string;
+  /** Call outcome, caller-supplied (provider/parse failure → "error"). */
+  status: "ok" | "error";
+  /** Failure detail (null on success). */
+  errorDetail: string | null;
+}
+
+export interface RecordLlmCallOptions {
+  recorder: LlmRecorder;
+  /** Optional scrub/cap applied immediately before persist (PII/secrets). */
+  redact?: (row: LlmCallRow) => LlmCallRow;
+}
+
+export interface RecordLlmCallResult {
+  status: "ok" | "error";
+  errorDetail: string | null;
+}
+
+/** Build the base trace row (envelope + raw llmRequest/llmResponse) — key set
+ *  is exactly LlmCallBase's fields. Typed voRequest/voResponse are added by the
+ *  generated typed helper, never here. */
+export function buildLlmCallRow(input: LlmCallInput): LlmCallRow {
+  return {
+    traceId: input.traceId,
+    spanId: input.spanId,
+    parentSpanId: input.parentSpanId ?? null,
+    sessionId: input.sessionId ?? null,
+    callType: input.callType,
+    system: input.system ?? null,
+    requestModel: input.requestModel ?? null,
+    responseModel: input.responseModel ?? null,
+    inputTokens: input.inputTokens ?? null,
+    outputTokens: input.outputTokens ?? null,
+    costMinor: input.costMinor ?? null,
+    latencyMs: input.latencyMs ?? null,
+    finishReason: input.finishReason ?? null,
+    status: input.status,
+    errorDetail: input.errorDetail,
+    startedAt: input.startedAt,
+    llmRequest: JSON.stringify(input.llmRequest),
+    llmResponse: JSON.stringify(input.llmResponseText),
+  };
+}
+
+/** Shared persist step: redact then record. Used by recordLlmCall AND (later) the
+ *  generated typed helper, so redaction applies on both paths. */
+export async function persistLlmCallRow(
+  recorder: LlmRecorder,
+  row: LlmCallRow,
+  opts?: { redact?: (row: LlmCallRow) => LlmCallRow },
+): Promise<void> {
+  await recorder.record(opts?.redact ? opts.redact(row) : row);
+}
+
+/** Cap the raw `llmRequest`/`llmResponse` string columns to `maxChars`.
+ *  Adopters compose this into a `redact` to bound trace-row size. Only the two
+ *  raw string columns are touched; all other fields pass through unchanged. */
+export function truncateRow(row: LlmCallRow, maxChars: number): LlmCallRow {
+  const cap = (v: unknown): unknown =>
+    typeof v === "string" && v.length > maxChars ? v.slice(0, maxChars) : v;
+  return { ...row, llmRequest: cap(row.llmRequest), llmResponse: cap(row.llmResponse) };
+}
+
+/** Persist one base trace row (envelope + raw I/O). Generic — does not extract. */
+export async function recordLlmCall(
+  input: LlmCallInput,
+  opts: RecordLlmCallOptions,
+): Promise<RecordLlmCallResult> {
+  await persistLlmCallRow(
+    opts.recorder,
+    buildLlmCallRow(input),
+    opts.redact ? { redact: opts.redact } : undefined,
+  );
+  return { status: input.status, errorDetail: input.errorDetail };
+}