@metaobjectsdev/codegen-ts 0.5.0-rc.1

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

@@ -0,0 +1,372 @@
+import {
+  TYPE_FIELD,
+  TYPE_ORIGIN,
+  TYPE_RELATIONSHIP,
+  TYPE_SOURCE,
+  SOURCE_SUBTYPE_DB_VIEW,
+  SOURCE_DB_VIEW_ATTR_NAME,
+  ORIGIN_SUBTYPE_PASSTHROUGH,
+  ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA,
+  ORIGIN_AGGREGATE_ATTR_AGG,
+  ORIGIN_AGGREGATE_ATTR_OF,
+  ORIGIN_AGGREGATE_ATTR_VIA,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_CARDINALITY,
+  CARDINALITY_ONE,
+  FIELD_ATTR_DB_COLUMN,
+  findReferenceBetween,
+  type AggregateFunction,
+} from "@metaobjectsdev/metadata";
+import { type MetaData, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import {
+  columnNameFromField,
+  viewNameFromProjection,
+} from "../naming.js";
+import type { ColumnNamingStrategy } from "../metaobjects-config.js";
+import type {
+  JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec,
+} from "./view-spec.js";
+
+// ---------------------------------------------------------------------------
+// Public context type
+// ---------------------------------------------------------------------------
+
+export interface ExtractContext {
+  readonly columnNamingStrategy: ColumnNamingStrategy;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function findRelationship(obj: MetaData, name: string): MetaData | undefined {
+  return obj.ownChildren().find(
+    (c) => c.type === TYPE_RELATIONSHIP && c.name === name,
+  );
+}
+
+function viewName(projection: MetaObject, ctx: ExtractContext): string {
+  const dbView = projection.ownChildren().find(
+    (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_VIEW,
+  );
+  const explicit = dbView?.ownAttr(SOURCE_DB_VIEW_ATTR_NAME) as string | undefined;
+  return explicit ?? viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
+}
+
+function baseEntityFor(
+  projection: MetaObject,
+  root: MetaRoot,
+): MetaObject {
+  // v1: base entity is the resolved super (set via `extends:` in metadata).
+  const superModel = projection.superResolved;
+  const superName = superModel?.name ?? projection.superRef;
+  if (!superName) {
+    throw new Error(
+      `Projection ${projection.name}: missing extends — projections must extend a writable entity in v1.`,
+    );
+  }
+  const base =
+    superModel instanceof MetaObject ? superModel : root.findObject(superName);
+  if (!base) {
+    throw new Error(
+      `Projection ${projection.name}: extends "${superName}" does not resolve to any entity.`,
+    );
+  }
+  return base;
+}
+
+function sourceColumnNameFor(
+  entityField: MetaData,
+  ctx: ExtractContext,
+): string {
+  const explicit = entityField.ownAttr(FIELD_ATTR_DB_COLUMN) as string | undefined;
+  return explicit ?? columnNameFromField(entityField.name, ctx.columnNamingStrategy);
+}
+
+function shortAliasFor(entityName: string, used: Set<string>): string {
+  const base = (entityName[0] ?? "x").toLowerCase();
+  if (!used.has(base)) { used.add(base); return base; }
+  let i = 0;
+  let candidate: string;
+  do { candidate = `${base}${i}`; i++; } while (used.has(candidate));
+  used.add(candidate);
+  return candidate;
+}
+
+// ---------------------------------------------------------------------------
+// JoinTree builder — walks all `@via` paths from origin children, dedupes via
+// prefix into a trie, then converts to JoinNode tree.
+// ---------------------------------------------------------------------------
+
+interface PathStep {
+  entity: MetaData;
+  relationship: string;
+  cardinality: "one" | "many";
+  fkField: string;
+  pkField: string;
+  referenceHolder: "source" | "target";
+  targetEntity: string;
+}
+
+type Path = PathStep[];
+
+interface TrieNode {
+  children: Map<string, TrieNode>;
+  step?: PathStep;
+}
+
+function buildJoinTree(
+  projection: MetaObject,
+  base: MetaObject,
+  root: MetaRoot,
+  usedAliases: Set<string>,
+  baseAlias: string,
+): JoinTree {
+  const allPaths: Path[] = [];
+
+  for (const field of projection.ownChildren()) {
+    if (field.type !== TYPE_FIELD) continue;
+    for (const origin of field.ownChildren()) {
+      if (origin.type !== TYPE_ORIGIN) continue;
+      const viaAttr = origin.subType === ORIGIN_SUBTYPE_AGGREGATE
+        ? (origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA) as string | undefined)
+        : (origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA) as string | undefined);
+      if (!viaAttr) continue;
+
+      const segments = viaAttr.split(".");
+      const entityName = segments[0];
+      const relSegments = segments.slice(1);
+      if (!entityName) continue;
+      let currentObj = root.findObject(entityName);
+      if (!currentObj) continue;
+
+      const path: Path = [];
+      for (const relName of relSegments) {
+        const rel = findRelationship(currentObj, relName);
+        if (!rel) break;
+        const targetName = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+        const target = targetName ? root.findObject(targetName) : undefined;
+        if (!target || !targetName) break;
+
+        const cardAttr = rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+        const cardinality: "one" | "many" = cardAttr === CARDINALITY_ONE ? "one" : "many";
+
+        const ref = findReferenceBetween(currentObj as MetaObject, target);
+        if (!ref) break;
+
+        const fkField = ref.referenceIdentity.fields[0];
+        if (!fkField) break;
+
+        const resolvedPkField = ref.referenceIdentity.resolvedTargetPkField(root) ?? "id";
+
+        const referenceHolder: "source" | "target" =
+          ref.holder.name === currentObj.name ? "source" : "target";
+
+        path.push({
+          entity: currentObj,
+          relationship: relName,
+          cardinality,
+          fkField,
+          pkField: resolvedPkField,
+          referenceHolder,
+          targetEntity: targetName,
+        });
+        currentObj = target;
+      }
+      if (path.length > 0) allPaths.push(path);
+    }
+  }
+
+  // Dedupe by prefix: paths sharing a prefix collapse into one join branch.
+  const trieRoot: TrieNode = { children: new Map() };
+  for (const path of allPaths) {
+    let node = trieRoot;
+    for (const step of path) {
+      let child = node.children.get(step.relationship);
+      if (!child) {
+        child = { children: new Map(), step };
+        node.children.set(step.relationship, child);
+      }
+      node = child;
+    }
+  }
+
+  function toJoinNode(node: TrieNode): JoinNode {
+    const step = node.step!;
+    return {
+      relationship: step.relationship,
+      targetEntity: step.targetEntity,
+      alias: shortAliasFor(step.targetEntity, usedAliases),
+      cardinality: step.cardinality,
+      fkField: step.fkField,
+      pkField: step.pkField,
+      referenceHolder: step.referenceHolder,
+      children: Array.from(node.children.values()).map(toJoinNode),
+    };
+  }
+
+  return {
+    baseEntity: base.name,
+    baseAlias,
+    joins: Array.from(trieRoot.children.values()).map(toJoinNode),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers for SelectSpec building
+// ---------------------------------------------------------------------------
+
+function findAliasInTree(
+  joinTree: JoinTree,
+  entityName: string,
+): string | undefined {
+  if (joinTree.baseEntity === entityName) return joinTree.baseAlias;
+
+  function recurse(nodes: readonly JoinNode[]): string | undefined {
+    for (const n of nodes) {
+      if (n.targetEntity === entityName) return n.alias;
+      const found = recurse(n.children);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+
+  return recurse(joinTree.joins);
+}
+
+function buildSelectSpec(
+  projection: MetaObject,
+  base: MetaObject,
+  joinTree: JoinTree,
+  root: MetaRoot,
+  ctx: ExtractContext,
+): SelectSpec {
+  const columns: SelectColumn[] = [];
+
+  // Inherited fields from extends parent — emit as passthrough on baseAlias.
+  // Skip fields that the projection has overridden with an explicit origin.
+  // fields() is effective-by-default, so multi-level inheritance (base → BaseEntity) works.
+  for (const baseField of base.fields()) {
+    const overridden = projection.ownChildren().find(
+      (c) => c.type === TYPE_FIELD && c.name === baseField.name,
+    );
+    if (overridden) continue;
+    columns.push({
+      kind: "passthrough",
+      fieldName: baseField.name,
+      dbColAlias: sourceColumnNameFor(baseField, ctx),
+      sourceAlias: joinTree.baseAlias,
+      sourceColumn: sourceColumnNameFor(baseField, ctx),
+    });
+  }
+
+  // Fields explicitly declared on the projection.
+  for (const field of projection.ownChildren()) {
+    if (field.type !== TYPE_FIELD) continue;
+    const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
+    const dbCol = sourceColumnNameFor(field, ctx);
+
+    if (!origin) {
+      // Declared on projection but no origin — passthrough from base table.
+      columns.push({
+        kind: "passthrough",
+        fieldName: field.name,
+        dbColAlias: dbCol,
+        sourceAlias: joinTree.baseAlias,
+        sourceColumn: dbCol,
+      });
+      continue;
+    }
+
+    if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
+      const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM) as string;
+      const dotIdx = from.indexOf(".");
+      if (dotIdx < 1) continue;
+      const entityName = from.slice(0, dotIdx);
+      const fieldName = from.slice(dotIdx + 1);
+      const targetEntity = root.findObject(entityName);
+      const sourceAlias = findAliasInTree(joinTree, entityName);
+      if (!targetEntity || sourceAlias === undefined) continue;
+      const targetField = targetEntity.ownChildren().find(
+        (c) => c.type === TYPE_FIELD && c.name === fieldName,
+      );
+      if (!targetField) continue;
+      columns.push({
+        kind: "passthrough",
+        fieldName: field.name,
+        dbColAlias: dbCol,
+        sourceAlias,
+        sourceColumn: sourceColumnNameFor(targetField, ctx),
+      });
+    } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
+      const agg = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG) as AggregateFunction;
+      const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF) as string;
+      if (!agg || !of_) continue;
+      const dotIdx = of_.indexOf(".");
+      if (dotIdx < 1) continue;
+      const entityName = of_.slice(0, dotIdx);
+      const fieldName = of_.slice(dotIdx + 1);
+      const targetEntity = root.findObject(entityName);
+      const sourceAlias = findAliasInTree(joinTree, entityName);
+      if (!targetEntity || sourceAlias === undefined) continue;
+      const targetField = targetEntity.ownChildren().find(
+        (c) => c.type === TYPE_FIELD && c.name === fieldName,
+      );
+      if (!targetField) continue;
+      columns.push({
+        kind: "aggregate",
+        fieldName: field.name,
+        dbColAlias: dbCol,
+        agg,
+        sourceAlias,
+        sourceColumn: sourceColumnNameFor(targetField, ctx),
+      });
+    }
+  }
+
+  return { columns };
+}
+
+function buildGroupBy(spec: SelectSpec): string[] {
+  const hasAgg = spec.columns.some((c) => c.kind === "aggregate");
+  if (!hasAgg) return [];
+  return spec.columns
+    .filter((c) => c.kind === "passthrough")
+    .map((c) => `${c.sourceAlias}.${c.sourceColumn}`);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk a projection's origin children to produce a ViewSpec.
+ *
+ * @param projection  The projection entity (has a source[dbView] child
+ *                    and extends a writable entity).
+ * @param root        The loader's MetaRoot — all top-level objects are
+ *                    direct children of root (returned by `MetaDataLoader.load()`
+ *                    / `FileMetaDataLoader.loadFiles()` as `result.root`).
+ * @param ctx         Column naming strategy for SQL identifiers.
+ */
+export function extractViewSpec(
+  projection: MetaObject,
+  root: MetaRoot,
+  ctx: ExtractContext,
+): ViewSpec {
+  const base = baseEntityFor(projection, root);
+  const usedAliases = new Set<string>();
+  const baseAlias = shortAliasFor(base.name, usedAliases);
+  const joinTree = buildJoinTree(projection, base, root, usedAliases, baseAlias);
+  const selectSpec = buildSelectSpec(projection, base, joinTree, root, ctx);
+  const groupBy = buildGroupBy(selectSpec);
+
+  return {
+    viewName: viewName(projection, ctx),
+    joinTree,
+    selectSpec,
+    groupBy,
+  };
+}

package/src/projection/index.ts

@@ -0,0 +1,4 @@
+export * from "./view-spec.js";
+export * from "./extract-view-spec.js";
+export * from "./view-ddl-emit.js";
+export * from "./projection-detector.js";

package/src/projection/projection-detector.ts

@@ -0,0 +1,26 @@
+import {
+  TYPE_SOURCE,
+  SOURCE_SUBTYPE_DB_TABLE,
+  SOURCE_SUBTYPE_DB_VIEW,
+} from "@metaobjectsdev/metadata";
+import type { MetaData } from "@metaobjectsdev/metadata";
+
+function hasSource(entity: MetaData, subType: string): boolean {
+  return entity.ownChildren().some(
+    (c) => c.type === TYPE_SOURCE && c.subType === subType,
+  );
+}
+
+export function isProjection(entity: MetaData): boolean {
+  return (
+    hasSource(entity, SOURCE_SUBTYPE_DB_VIEW) &&
+    !hasSource(entity, SOURCE_SUBTYPE_DB_TABLE)
+  );
+}
+
+export function isWriteThrough(entity: MetaData): boolean {
+  return (
+    hasSource(entity, SOURCE_SUBTYPE_DB_VIEW) &&
+    hasSource(entity, SOURCE_SUBTYPE_DB_TABLE)
+  );
+}

package/src/projection/view-ddl-emit.ts

@@ -0,0 +1,66 @@
+import { toSnakeCase } from "../naming.js";
+import type { JoinNode, ViewSpec } from "./view-spec.js";
+
+export interface EmitOptions {
+  readonly dialect: "postgres" | "sqlite";
+  /** Resolved table name for the JoinTree's base entity. */
+  readonly baseTableName: string;
+  /** Map from entity name → table name for every entity referenced in joins. */
+  readonly joinTables: Readonly<Record<string, string>>;
+}
+
+function renderColumn(c: import("./view-spec.js").SelectColumn): string {
+  if (c.kind === "passthrough") {
+    return `${c.sourceAlias}.${c.sourceColumn} AS ${c.dbColAlias}`;
+  }
+  // aggregate — use DISTINCT for count() over joined PKs to avoid join inflation.
+  if (c.agg === "count") {
+    return `COUNT(DISTINCT ${c.sourceAlias}.${c.sourceColumn}) AS ${c.dbColAlias}`;
+  }
+  return `${c.agg.toUpperCase()}(${c.sourceAlias}.${c.sourceColumn}) AS ${c.dbColAlias}`;
+}
+
+function renderJoin(
+  node: JoinNode,
+  parentAlias: string,
+  options: EmitOptions,
+): string {
+  const table = options.joinTables[node.targetEntity];
+  if (!table) {
+    throw new Error(
+      `view-ddl-emit: no table name registered for joined entity "${node.targetEntity}".`,
+    );
+  }
+  // JoinNode stores raw camelCase field names from metadata (e.g. "programId").
+  // Emit always applies snake_case — view DDL is SQL-side and always snake_case.
+  const fkCol = toSnakeCase(node.fkField);
+  const pkCol = toSnakeCase(node.pkField);
+  const childAlias = node.alias;
+  // referenceHolder = "source" → FK on parent (source): child.pk = parent.fk  (belongs-to)
+  // referenceHolder = "target" → FK on child  (target): child.fk = parent.pk  (has-many)
+  const onClause = node.referenceHolder === "source"
+    ? `${childAlias}.${pkCol} = ${parentAlias}.${fkCol}`
+    : `${childAlias}.${fkCol} = ${parentAlias}.${pkCol}`;
+  let sql = `  LEFT OUTER JOIN ${table} ${childAlias} ON ${onClause}`;
+  for (const childJoin of node.children) {
+    sql += "\n" + renderJoin(childJoin, childAlias, options);
+  }
+  return sql;
+}
+
+export function emitViewDdl(spec: ViewSpec, options: EmitOptions): string {
+  const cols = spec.selectSpec.columns
+    .map((c) => "    " + renderColumn(c))
+    .join(",\n");
+  const fromClause = `  FROM ${options.baseTableName} ${spec.joinTree.baseAlias}`;
+  const joinsClause = spec.joinTree.joins
+    .map((j) => renderJoin(j, spec.joinTree.baseAlias, options))
+    .join("\n");
+  const groupByClause =
+    spec.groupBy.length > 0 ? `\n  GROUP BY ${spec.groupBy.join(", ")}` : "";
+
+  return `CREATE VIEW ${spec.viewName} AS
+  SELECT
+${cols}
+${fromClause}${joinsClause ? "\n" + joinsClause : ""}${groupByClause};`;
+}

package/src/projection/view-spec.ts

@@ -0,0 +1,62 @@
+import type { AggregateFunction } from "@metaobjectsdev/metadata";
+
+/** One node in the JOIN tree. `alias` is an auto-generated unique short alias. */
+export interface JoinNode {
+  /** Relationship name on the parent object (e.g., "weeks"). */
+  readonly relationship: string;
+  /** Entity name this join lands on (e.g., "Week"). */
+  readonly targetEntity: string;
+  /** Auto-assigned SQL alias for this join (e.g., "w", "w0"). */
+  readonly alias: string;
+  /** Cardinality of the relationship being traversed. */
+  readonly cardinality: "one" | "many";
+  /** FK field name (lives on whichever side `referenceHolder` indicates). */
+  readonly fkField: string;
+  /** PK field name on the side that does NOT hold the FK. */
+  readonly pkField: string;
+  /** Which side of this hop physically holds the FK: the parent (source) or the child (target). */
+  readonly referenceHolder: "source" | "target";
+  /** Child joins. */
+  readonly children: readonly JoinNode[];
+}
+
+/** Tree of JOINs rooted at the projection's base entity. */
+export interface JoinTree {
+  /** Base entity name (e.g., "Program"). */
+  readonly baseEntity: string;
+  /** SQL alias for the base entity (typically "p", "p0"). */
+  readonly baseAlias: string;
+  /** Joined entities (could be empty for a flat projection). */
+  readonly joins: readonly JoinNode[];
+}
+
+/** One column of the SELECT list. */
+export type SelectColumn =
+  | {
+      readonly kind: "passthrough";
+      readonly fieldName: string;        // projection field name
+      readonly dbColAlias: string;       // SQL output column name
+      readonly sourceAlias: string;      // join alias of the source
+      readonly sourceColumn: string;     // source table's column name (already strategy-applied)
+    }
+  | {
+      readonly kind: "aggregate";
+      readonly fieldName: string;
+      readonly dbColAlias: string;
+      readonly agg: AggregateFunction;
+      readonly sourceAlias: string;
+      readonly sourceColumn: string;
+    };
+
+export interface SelectSpec {
+  readonly columns: readonly SelectColumn[];
+}
+
+/** Top-level view specification consumed by view-ddl-emit + Drizzle declaration. */
+export interface ViewSpec {
+  readonly viewName: string;        // already strategy-applied (e.g., "v_program_summary")
+  readonly joinTree: JoinTree;
+  readonly selectSpec: SelectSpec;
+  /** non-aggregate column SQL fragments to put in GROUP BY (empty if no aggregates). */
+  readonly groupBy: readonly string[];
+}

package/src/relation-resolver.ts

@@ -0,0 +1,87 @@
+// Relation resolver — pre-pass that builds the inverse-side map for relations() emission.
+// For each entity, we need to know:
+//   - Which outgoing belongs-to relationships it declares (one-side, reference on this entity)
+//   - Which incoming relationships point to it (many-side, reference on the other entity)
+//
+// Reads identity.reference declarations to determine the physical reference side.
+
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  CARDINALITY_ONE,
+  stripPackage,
+} from "@metaobjectsdev/metadata";
+import { variableNameFromEntity } from "./naming.js";
+import { isProjection } from "./projection/projection-detector.js";
+
+export interface RelationEntry {
+  /** Name of the relationship (e.g., "author") */
+  name: string;
+  /** Cardinality: 'one' | 'many' */
+  cardinality: "one" | "many";
+  /** The other entity's name (e.g., "User") */
+  targetEntity: string;
+  /** For cardinality 'one': the field on THIS entity that holds the FK (e.g., "authorId") */
+  fkField?: string;
+  /** For cardinality 'one': the target entity's PK field (e.g., "id") */
+  targetPkField?: string;
+}
+
+/** Map from entity name → list of relations for that entity's relations() block */
+export type RelationMap = Map<string, RelationEntry[]>;
+
+/**
+ * Walk all entities, collect relationship children, and also register inverse
+ * many() sides on the target entity.
+ */
+export function buildRelationMap(root: MetaRoot): RelationMap {
+  const result: RelationMap = new Map();
+
+  const ensure = (name: string): RelationEntry[] => {
+    if (!result.has(name)) result.set(name, []);
+    return result.get(name)!;
+  };
+
+  for (const obj of root.objects()) {
+    // Projections (source.dbView) are view-backed; they never emit a relations()
+    // block, and their inherited belongs-to relationships would otherwise register
+    // a spurious inverse-many on the target entity.
+    if (isProjection(obj)) continue;
+
+    for (const child of obj.relationships()) {
+      const cardinality = child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+      if (cardinality !== CARDINALITY_ONE) continue;
+
+      const targetEntityRaw = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+      if (!targetEntityRaw) continue;
+      const targetEntity = stripPackage(targetEntityRaw);
+
+      // Find an identity.reference on `obj` whose @references targets this relationship's target.
+      // Compare against package-stripped names since both relationship @objectRef and
+      // identity.reference @references may carry package-qualified entity names.
+      const refs = obj.referenceIdentities();
+      const matching = refs.find((r) => stripPackage(r.targetEntity ?? "") === targetEntity);
+      if (!matching) continue;
+
+      const fkFields = matching.fields;
+      if (fkFields.length === 0) continue;
+      const fkField = fkFields[0]!;
+
+      ensure(obj.name).push({
+        name: child.name,
+        cardinality: "one",
+        targetEntity,
+        fkField,
+        targetPkField: "id",
+      });
+      ensure(targetEntity).push({
+        name: variableNameFromEntity(obj.name),
+        cardinality: "many",
+        targetEntity: obj.name,
+      });
+    }
+  }
+
+  return result;
+}