@metaobjectsdev/codegen-ts 0.5.0-rc.1

package/src/column-mapper.ts

@@ -0,0 +1,266 @@
+// Field-type → Drizzle column type mapping. Per design §6.
+// Uses the typed MetaField.validators() accessor (effective — includes inherited) for all validator checks.
+
+import type { MetaField } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_CLASS,
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_DB_COLUMN,
+  FIELD_ATTR_UNIQUE,
+  FIELD_ATTR_DEFAULT,
+  VALIDATOR_ATTR_MAX,
+} from "@metaobjectsdev/metadata";
+import { columnNameFromField } from "./naming.js";
+import type { Dialect, ColumnNamingStrategy } from "./metaobjects-config.js";
+
+export type { Dialect };
+
+/**
+ * Discriminated union describing how a column default should be emitted.
+ * - { kind: "now" }            — dialect-aware: sql`CURRENT_TIMESTAMP` (sqlite) or .defaultNow() (postgres)
+ * - { kind: "sqlExpr"; raw }   — raw SQL expression wrapped in sql`...` (CURRENT_DATE, CURRENT_TIME, function calls)
+ * - { kind: "literal"; value } — .default(JSON.stringify(value))
+ */
+export type DefaultExpr =
+  | { kind: "now" }
+  | { kind: "sqlExpr"; raw: string }
+  | { kind: "literal"; value: unknown };
+
+/**
+ * Patterns recognized as SQL expressions in a default value. Anything matching
+ * these is treated as a SQL expression, not a string literal. Mirrors
+ * migrate-ts/src/expected-schema.ts's EXPR_DEFAULT_PATTERNS so both sides
+ * agree on what's an expression.
+ */
+const SQL_EXPR_PATTERNS: RegExp[] = [
+  /^now$/i,
+  /^now\(\)$/i,
+  /^current_timestamp$/i,
+  /^current_date$/i,
+  /^current_time$/i,
+  /\(\)$/,                // anything function-like
+];
+
+/** True iff the value should be emitted as a SQL expression. */
+function isSqlExprDefault(value: string): boolean {
+  return SQL_EXPR_PATTERNS.some((re) => re.test(value));
+}
+
+/** Map a recognized SQL expression to its canonical raw form (uppercase keywords). */
+function canonicalizeSqlExpr(value: string): string {
+  const lower = value.toLowerCase();
+  if (lower === "now" || lower === "now()" || lower === "current_timestamp") {
+    return "CURRENT_TIMESTAMP";
+  }
+  if (lower === "current_date") return "CURRENT_DATE";
+  if (lower === "current_time") return "CURRENT_TIME";
+  return value; // unrecognized — pass through (function calls etc.)
+}
+
+export interface ColumnSpec {
+  /** Drizzle function name, e.g., "text", "integer", "varchar". */
+  fnName: string;
+  /** DB column name (snake_case from field name, or @dbColumn override). */
+  dbName: string;
+  /** Positional args after dbName (currently always empty; reserved). */
+  fnArgs: unknown[];
+  /** Object passed as second arg if non-empty (e.g., { length: 200 }, { mode: 'boolean' }). */
+  fnOptions?: Record<string, unknown>;
+  /** Method chain modifiers, e.g., [".notNull()", ".unique()"]. */
+  modifiers: string[];
+  /** Default expression for the column — dialect-specific emission handled by the template. */
+  defaultExpr?: DefaultExpr;
+  /** Drizzle import module: "drizzle-orm/sqlite-core" or "drizzle-orm/pg-core". */
+  importModule: string;
+  /** Optional leading line-comment for the generated column (e.g., type-fallback notice). */
+  leadingComment?: string;
+}
+
+/** Resolve max length from validator.length child or @maxLength attr.
+ *  Uses field.validators() (effective) so inherited validators are seen. */
+function getMaxLength(field: MetaField): number | undefined {
+  const lenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  if (typeof lenAttr === "number") return lenAttr;
+  for (const child of field.validators()) {
+    if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
+      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      if (typeof max === "number") return max;
+    }
+  }
+  return undefined;
+}
+
+/** Check for validator.required child OR @required attr.
+ *  Uses field.validators() (effective) so inherited validators are seen. */
+function isRequired(field: MetaField): boolean {
+  if (field.ownAttr(FIELD_ATTR_REQUIRED) === true) return true;
+  return field.validators().some((child) => child.subType === VALIDATOR_SUBTYPE_REQUIRED);
+}
+
+export function mapColumnType(
+  field: MetaField,
+  dialect: Dialect,
+  strategy: ColumnNamingStrategy = "snake_case",
+): ColumnSpec {
+  const dbName = (field.ownAttr(FIELD_ATTR_DB_COLUMN) as string | undefined) ?? columnNameFromField(field.name, strategy);
+  const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
+  const subType = field.subType;
+  const isArray = field.isArray;
+
+  let fnName: string;
+  let fnOptions: Record<string, unknown> | undefined;
+
+  let leadingComment: string | undefined;
+  if (dialect === "sqlite") {
+    if (isArray) {
+      // SQLite has no native array type; serialize as JSON in a text column.
+      fnName = "text";
+      fnOptions = { mode: "json" };
+    } else {
+      switch (subType) {
+        case FIELD_SUBTYPE_BOOLEAN:
+          fnName = "integer";
+          fnOptions = { mode: "boolean" };
+          break;
+        case FIELD_SUBTYPE_INT:
+        case FIELD_SUBTYPE_CURRENCY:
+        case FIELD_SUBTYPE_LONG:
+          fnName = "integer";
+          break;
+        case FIELD_SUBTYPE_DOUBLE:
+        case FIELD_SUBTYPE_FLOAT:
+          fnName = "real";
+          break;
+        case FIELD_SUBTYPE_DECIMAL:
+          fnName = "text";
+          // SQLite has no decimal type; the user must do precision math at the app
+          // layer or migrate to Postgres. Surface this in the generated file so it
+          // isn't a silent rounding hazard.
+          leadingComment = "TODO: SQLite has no decimal type; stored as text. Convert at the application boundary or migrate to Postgres for native numeric.";
+          break;
+        case FIELD_SUBTYPE_DATE:
+        case FIELD_SUBTYPE_TIME:
+        case FIELD_SUBTYPE_TIMESTAMP:
+        case FIELD_SUBTYPE_STRING:
+        case FIELD_SUBTYPE_CLASS:
+        case FIELD_SUBTYPE_OBJECT:
+        default:
+          fnName = "text";
+          break;
+      }
+    }
+  } else {
+    switch (subType) {
+      case FIELD_SUBTYPE_BOOLEAN:
+        fnName = "boolean";
+        break;
+      case FIELD_SUBTYPE_INT:
+        fnName = "integer";
+        break;
+      case FIELD_SUBTYPE_CURRENCY:
+      case FIELD_SUBTYPE_LONG:
+        fnName = "bigint";
+        fnOptions = { mode: "number" };
+        break;
+      case FIELD_SUBTYPE_DOUBLE:
+        fnName = "doublePrecision";
+        break;
+      case FIELD_SUBTYPE_FLOAT:
+        fnName = "real";
+        break;
+      case FIELD_SUBTYPE_DATE:
+        fnName = "date";
+        break;
+      case FIELD_SUBTYPE_TIME:
+        fnName = "time";
+        break;
+      case FIELD_SUBTYPE_TIMESTAMP:
+        fnName = "timestamp";
+        break;
+      case FIELD_SUBTYPE_DECIMAL:
+        fnName = "numeric";
+        fnOptions = { precision: 19, scale: 4 }; // sane default; @precision/@scale attrs override
+        break;
+      case FIELD_SUBTYPE_STRING: {
+        const maxLen = getMaxLength(field);
+        if (maxLen !== undefined) {
+          fnName = "varchar";
+          fnOptions = { length: maxLen };
+        } else {
+          fnName = "text";
+        }
+        break;
+      }
+      case FIELD_SUBTYPE_CLASS:
+      case FIELD_SUBTYPE_OBJECT:
+      default:
+        fnName = "text";
+        break;
+    }
+  }
+
+  const modifiers: string[] = [];
+
+  if (dialect === "postgres" && isArray) {
+    modifiers.push(".array()");
+  }
+
+  if (isRequired(field)) {
+    modifiers.push(".notNull()");
+  }
+
+  if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) {
+    modifiers.push(".unique()");
+  }
+
+  let defaultExpr: DefaultExpr | undefined;
+  const defaultAttr = field.ownAttr(FIELD_ATTR_DEFAULT);
+  if (defaultAttr !== undefined) {
+    // SQL-expression detection runs on the raw string value — a string like
+    // "CURRENT_TIMESTAMP" or "now" must be emitted as sql`...`, not a literal.
+    if (typeof defaultAttr === "string" && isSqlExprDefault(defaultAttr)) {
+      const canonical = canonicalizeSqlExpr(defaultAttr);
+      // "now"/"CURRENT_TIMESTAMP" gets the dialect-aware emit path (defaultNow for postgres);
+      // other SQL keywords go through the generic sqlExpr emit.
+      if (canonical === "CURRENT_TIMESTAMP") {
+        defaultExpr = { kind: "now" };
+      } else {
+        defaultExpr = { kind: "sqlExpr", raw: canonical };
+      }
+    } else {
+      // Literal branch: use the field-type-converted value so booleans/numbers
+      // are real JS booleans/numbers (not strings). field.defaultValue() applies
+      // convertToDataType(field.dataType, raw) — Java parity with getDefaultValue().
+      // JSON.stringify(false) → "false", JSON.stringify(0) → "0" (unquoted) in templates.
+      const typedValue = field.defaultValue() ?? defaultAttr;
+      defaultExpr = { kind: "literal", value: typedValue };
+    }
+  }
+
+  const result: ColumnSpec = {
+    fnName,
+    dbName,
+    fnArgs: [],
+    modifiers,
+    importModule,
+  };
+  if (fnOptions !== undefined) result.fnOptions = fnOptions;
+  if (defaultExpr !== undefined) result.defaultExpr = defaultExpr;
+  if (leadingComment !== undefined) result.leadingComment = leadingComment;
+  return result;
+}

package/src/constants.ts

@@ -0,0 +1,10 @@
+// Local constants for codegen-ts.
+
+/** The marker that says "codegen owns this file" — drives the overwrite policy. */
+export const GENERATED_HEADER = "@generated by @metaobjectsdev/codegen-ts";
+
+/** Suffix for sibling user extension files (codegen never touches these). */
+export const EXTRA_SUFFIX = ".extra";
+
+/** Default outDir used by tests + as a sane default for generate(). */
+export const DEFAULT_OUT_DIR = "./src/db/entities";

package/src/errors.ts

@@ -0,0 +1,10 @@
+// Typed errors for codegen-ts.
+
+export class CodegenError extends Error {
+  readonly file?: string;
+  constructor(message: string, opts?: { file?: string }) {
+    super(message);
+    this.name = "CodegenError";
+    if (opts?.file !== undefined) this.file = opts.file;
+  }
+}

package/src/format.ts

@@ -0,0 +1,50 @@
+// Biome formatter integration. Used by generate() to format rendered TS before write.
+// Per design §11: format errors are warnings, not throws.
+
+import { Biome, Distribution } from "@biomejs/js-api";
+
+// Cache the Promise (not the resolved instance) so concurrent first calls
+// share the same in-flight Biome.create() rather than racing to spawn two.
+let _biomePromise: Promise<Biome> | undefined;
+
+function getBiome(): Promise<Biome> {
+  if (!_biomePromise) {
+    _biomePromise = Biome.create({ distribution: Distribution.NODE }).then((biome) => {
+      biome.applyConfiguration({
+        formatter: { enabled: true, indentStyle: "space", indentWidth: 2 },
+        javascript: { formatter: { quoteStyle: "double", semicolons: "always" } },
+      });
+      return biome;
+    });
+  }
+  return _biomePromise;
+}
+
+/**
+ * Summarize Biome diagnostics into a single human-readable line, without
+ * dumping the raw diagnostic objects (which produce "[Object ...]" /
+ * "source: null" noise when stringified by console).
+ */
+function summarizeDiagnostics(diagnostics: ReadonlyArray<unknown>): string {
+  const count = diagnostics.length;
+  const first = diagnostics[0] as { description?: string; message?: string } | undefined;
+  const firstMsg = first?.description ?? first?.message ?? "(no description)";
+  return count === 1
+    ? `1 diagnostic: ${firstMsg}`
+    : `${count} diagnostics; first: ${firstMsg}`;
+}
+
+export async function formatTs(content: string): Promise<string> {
+  try {
+    const biome = await getBiome();
+    const result = biome.formatContent(content, { filePath: "in-memory.ts" });
+    if (result.diagnostics.length > 0) {
+      console.warn(`[codegen-ts] Biome formatter: ${summarizeDiagnostics(result.diagnostics)}`);
+      return content;
+    }
+    return result.content;
+  } catch (err) {
+    console.warn(`[codegen-ts] Biome formatter error: ${(err as Error).message}`);
+    return content;
+  }
+}

package/src/generator.ts

@@ -0,0 +1,73 @@
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import type { RenderContext } from "./render-context.js";
+import type { ResolvedGenConfig } from "./metaobjects-config.js";
+
+export interface EmittedFile {
+  /** Path relative to ResolvedGenConfig.outDir. */
+  path: string;
+  /** Final TypeScript source (formatted by the generator itself). */
+  content: string;
+  /** Set by the runner from generator.name — generators should not set this. */
+  generatedBy?: string;
+}
+
+export interface GenContext {
+  entities: MetaObject[];
+  loadedRoot: MetaRoot;
+  /** Pre-composed by the runner from generator.filter (returns true when no
+   *  filter is set). Always call this from helpers; do not call generator.filter
+   *  directly. */
+  matches: (entity: MetaObject) => boolean;
+  config: ResolvedGenConfig;
+  /** Pre-built by the runner for built-in generators that wrap existing
+   *  templates. Third-party generators typically don't need this. Always
+   *  present at run time when invoked via runGen(); optional in the type
+   *  so tests and custom callers don't need a placeholder. */
+  renderContext?: RenderContext;
+  warn: (msg: string) => void;
+}
+
+export interface Generator {
+  /** kebab-case identifier; surfaces in diagnostics + drift logs. */
+  name: string;
+  /** Optional per-entity filter applied via ctx.matches inside generate(). */
+  filter?: (entity: MetaObject) => boolean;
+  generate: (ctx: GenContext) => EmittedFile[] | Promise<EmittedFile[]>;
+  /** Named output target (registry key). Defaults to "default". */
+  target?: string;
+  /** Marks the generator that produces entity modules — the runner uses its
+   *  target as the entity-module target for cross-target import resolution. */
+  emitsEntityModule?: boolean;
+}
+
+export type GeneratorFactory<TOpts = void> = TOpts extends void
+  ? () => Generator
+  : (opts?: TOpts) => Generator;
+
+/** One-file-per-entity convenience. Async-safe. */
+export function perEntity(
+  fn: (entity: MetaObject, ctx: GenContext) =>
+    | EmittedFile
+    | EmittedFile[]
+    | Promise<EmittedFile | EmittedFile[]>,
+): (ctx: GenContext) => Promise<EmittedFile[]> {
+  return async (ctx) => {
+    const matched = ctx.entities.filter(ctx.matches);
+    const results = await Promise.all(matched.map((e) => fn(e, ctx)));
+    return results.flatMap((r) => (Array.isArray(r) ? r : [r]));
+  };
+}
+
+/** Called once with all matching entities. Use for barrels and cross-entity files. */
+export function oncePerRun(
+  fn: (entities: MetaObject[], ctx: GenContext) =>
+    | EmittedFile
+    | EmittedFile[]
+    | Promise<EmittedFile | EmittedFile[]>,
+): (ctx: GenContext) => Promise<EmittedFile[]> {
+  return async (ctx) => {
+    const matched = ctx.entities.filter(ctx.matches);
+    const result = await fn(matched, ctx);
+    return Array.isArray(result) ? result : [result];
+  };
+}

package/src/generators/barrel.ts

@@ -0,0 +1,28 @@
+import { oncePerRun, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderBarrel } from "../templates/barrel.js";
+import { formatTs } from "../format.js";
+
+export interface BarrelOpts {
+  target?: string;
+}
+
+export const barrel = function barrel(opts?: BarrelOpts): Generator {
+  const generator: Generator = {
+    name: "barrel",
+    generate: oncePerRun(async (entities, ctx) => ({
+      path: "index.ts",
+      content: await formatTs(
+        renderBarrel(
+          entities.map((e) => ({ name: e.name, package: e.package })),
+          ctx.renderContext!.extStyle,
+          ctx.renderContext!.selfTarget,
+          ctx.renderContext!.entityModuleTarget,
+        ),
+      ),
+    })),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<BarrelOpts>;

package/src/generators/entity-file.ts

@@ -0,0 +1,33 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderEntityFile } from "../templates/entity-file.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface EntityFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const entityFile = function entityFile(opts?: EntityFileOpts): Generator {
+  const generator: Generator = {
+    name: "entity-file",
+    emitsEntityModule: true,
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("entity-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
+        content: await formatTs(renderEntityFile(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.filter) {
+    generator.filter = opts.filter;
+  }
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<EntityFileOpts>;

package/src/generators/index.ts

@@ -0,0 +1,4 @@
+export { entityFile, type EntityFileOpts } from "./entity-file.js";
+export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
+export { routesFile, type RoutesFileOpts } from "./routes-file.js";
+export { barrel, type BarrelOpts } from "./barrel.js";

package/src/generators/queries-file.ts

@@ -0,0 +1,32 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderQueriesFile } from "../templates/queries-file.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface QueriesFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
+  const generator: Generator = {
+    name: "queries-file",
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("queries-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.queries.ts`),
+        content: await formatTs(renderQueriesFile(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.filter) {
+    generator.filter = opts.filter;
+  }
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<QueriesFileOpts>;

package/src/generators/routes-file.ts

@@ -0,0 +1,36 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderRoutesFile } from "../templates/routes-file.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface RoutesFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Per-entity opt-out via `@emitRoutes: false` is honored. If the user supplies
+ * their own filter, both must pass (AND).
+ */
+export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "routes-file",
+    // Always set: AND-composes metadata opt-out with optional user filter.
+    filter: (e: MetaObject) => e.ownAttr("emitRoutes") !== false && userFilter(e),
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("routes-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.routes.ts`),
+        content: await formatTs(renderRoutesFile(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileOpts>;