@metaobjectsdev/codegen-ts 0.16.0 → 0.17.0-rc.1

package/src/templates/projection-decl.ts

@@ -10,18 +10,17 @@
 import { code, imp, joinCode, type Code } from "ts-poet";
 import {
   MetaField, MetaObject, type MetaRoot,
-  FIELD_SUBTYPE_OBJECT, FIELD_ATTR_OBJECT_REF, stripPackage,
 } from "@metaobjectsdev/metadata";
 import { projectionViewName } from "../projection/extract-view-spec.js";
 import { columnNameFromField, toSnakeCase, pluralize } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 import type { RenderContext } from "../render-context.js";
-import { mapColumnType } from "../column-mapper.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
-import { inferViewKind, zodTypeFor, currencyMetaFor, labelFor } from "./field-meta.js";
+import { inferViewKind, currencyMetaFor, labelFor } from "./field-meta.js";
+import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
 
 // ---------------------------------------------------------------------------
 // Public interface
@@ -100,16 +99,7 @@ export function renderProjectionDecl(
     ctx
       ? valueObjectModuleSpecifier(refBase, ctx.packageOf, projection.package, ctx.outputLayout, ctx.extStyle)
       : `./${refBase}.js`;
-  const objectRefOf = (f: MetaField): string | undefined => {
-    if (f.subType !== FIELD_SUBTYPE_OBJECT) return undefined;
-    const ref = f.attr(FIELD_ATTR_OBJECT_REF);
-    return typeof ref === "string" && ref.length > 0 ? stripPackage(ref) : undefined;
-  };
 
-  const viewFn = dialect === "postgres" ? "pgView" : "sqliteView";
-  const viewModule =
-    dialect === "postgres" ? "drizzle-orm/pg-core" : "drizzle-orm/sqlite-core";
-  const viewSym = imp(`${viewFn}@${viewModule}`);
   const z = imp("z@zod");
 
   // Read-model generation needs only the view name — NOT the join/DDL
@@ -136,57 +126,6 @@ export function renderProjectionDecl(
   // inherited fields are not duplicated.
   for (const f of projection.ownFields()) allFields.push(f);
 
-  // A field.object passthrough carries the value-object's Zod schema (so the
-  // view's read schema + inferred type expose the VO shape, not z.unknown()).
-  const zodLines: Code[] = allFields.map((f) => {
-    // The read schema's nullability MUST mirror the view column's: a column that
-    // is not `.notNull()` infers `T | null` in Drizzle's SELECT type, so the Zod
-    // read type (and thus the generated query's return type) must be `.nullable()`
-    // too — otherwise `db.select().from(view)` yields `T | null` into a non-null
-    // `<Name>` field and the generated query fails to compile under strict TS.
-    const nullable =
-      mapColumnType(f, dialect, columnNamingStrategy, timestampMode)
-        .modifiers.includes(".notNull()")
-        ? ""
-        : ".nullable()";
-    const refBase = objectRefOf(f);
-    if (refBase) {
-      const schemaSym = imp(`${refBase}InsertSchema@${voModule(refBase)}`);
-      const base = f.resolvedIsArray()
-        ? code`${z}.array(${schemaSym})`
-        : code`${schemaSym}`;
-      return code`  ${f.name}: ${base}${nullable}`;
-    }
-    return code`  ${f.name}: ${z}.${zodTypeFor(f).replace(/^z\./, "")}${nullable}`;
-  });
-
-  // Typed view column map for the Drizzle `.existing()` declaration — keyed by
-  // projection field name, valued by the column builder for the (renamed)
-  // physical view column, so `db.select().from(<view>)` is typed. Honors
-  // `@dbColumnType` (e.g. a passthrough of a jsonb column). `.existing()` views
-  // carry type + physical name only — no PK/default/notNull modifiers.
-  const viewColumnLines: Code[] = allFields.map((f) => {
-    const spec = mapColumnType(f, dialect, columnNamingStrategy, timestampMode);
-    const colSym = imp(`${spec.fnName}@${spec.importModule}`);
-    const optsArg =
-      spec.fnOptions && Object.keys(spec.fnOptions).length > 0
-        ? `, ${JSON.stringify(spec.fnOptions)}`
-        : "";
-    // Of the table modifiers, only `.notNull()` carries to an existing view (it
-    // shapes the SELECT type); `.primaryKey()`/`.default()`/`.references()` are
-    // table-DDL concerns and invalid on a `.existing()` view declaration.
-    const notNull = spec.modifiers.includes(".notNull()") ? ".notNull()" : "";
-    // Narrow a jsonb passthrough to its value-object type — `.$type<VO>()` —
-    // mirroring the entity column, so the read row is typed (not `unknown`).
-    let dollarType: Code | string = "";
-    const dtr = spec.dollarTypeRef;
-    if (dtr?.kind === "objectRef") {
-      const voTypeSym = imp(`${dtr.name}@${voModule(dtr.name)}`);
-      dollarType = dtr.array ? code`.$type<${voTypeSym}[]>()` : code`.$type<${voTypeSym}>()`;
-    }
-    return code`  ${f.name}: ${colSym}(${JSON.stringify(spec.dbName)}${optsArg})${dollarType}${notNull}`;
-  });
-
   const constFieldLines: string[] = allFields.map((f) => {
     const dbCol = columnNameFromField(f.name, columnNamingStrategy);
     const view = inferViewKind(f);
@@ -205,19 +144,14 @@ export function renderProjectionDecl(
 
   const sections: Code[] = [
     ...(includeViewDecl
-      ? [code`
-// View declaration — Drizzle uses this for typed SELECT queries.
-// The SQL view is created/managed by migrate-ts; .existing() tells Drizzle
-// not to attempt DDL for this declaration.
-export const ${camelName}View = ${viewSym}(${JSON.stringify(viewName)}, {
-${joinCode(viewColumnLines, { on: ",\n" })}
-}).existing();
-`]
+      ? [renderExistingViewDecl(allFields, viewName, `${camelName}View`, {
+          dialect, columnNamingStrategy, timestampMode, voModule,
+        })]
       : []),
     code`
-export const ${projName}Schema = ${z}.object({
-${joinCode(zodLines, { on: ",\n" })}
-});
+export const ${projName}Schema = ${renderViewReadZodObject(allFields, {
+  dialect, columnNamingStrategy, timestampMode, voModule,
+})};
 `,
     code`
 export type ${projName} = ${z}.infer<typeof ${projName}Schema>;

package/src/templates/queries-file.ts

@@ -13,16 +13,40 @@ import {
   renderFindByIdFn,
   renderListFn,
   renderCreateFn,
+  renderInsertPreservingFn,
   renderUpdateFn,
   renderDeleteByIdFn,
   renderReverseFinderFns,
   reverseFksFor,
   getPkInfo,
+  getPkFields,
 } from "./queries.js";
-import { pluralize, findByIdFnName, listFnName } from "../naming.js";
+import { pluralize, findByIdFnName, listFnName, createFnName, insertPreservingFnName, updateFnName } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isTphDiscriminatorBase, tphConcreteSubtypes } from "./tph-discriminator.js";
-import { isProjection } from "../projection/projection-detector.js";
+import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
+import { hasAutoSetFields } from "./zod-validators.js";
+
+/**
+ * The dialect-correct Drizzle `Db` type alias + its import — parameter-passed into every
+ * generated CRUD helper (ADR-0008), so the signatures `find…(db: Db, …)` typecheck without
+ * the consumer importing anything to construct one. Shared by every queries-file renderer.
+ *   - Postgres: `PgDatabase<…>` is the base every PG driver extends (node-postgres,
+ *     postgres.js, Neon, Vercel, pglite) — accepts whichever driver the consumer chose.
+ *   - SQLite: `BaseSQLiteDatabase<"sync" | "async", …>` accepts BOTH sync (better-sqlite3)
+ *     and async (libsql/Turso/D1) drivers; the generated queries `await` results, valid on either.
+ */
+function dbTypeBlock(dialect: "postgres" | "sqlite"): { import: string; alias: string } {
+  return dialect === "postgres"
+    ? {
+        import: `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`,
+        alias: `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`,
+      }
+    : {
+        import: `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`,
+        alias: `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`,
+      };
+}
 
 export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
   // FR-017 Tier 2 — a TPH discriminator base gets a polymorphic queries file:
@@ -42,6 +66,13 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
     return renderProjectionQueriesFile(obj, ctx);
   }
 
+  // #214 — a write-through entity read-view (FR-024 §7): READS route to the replica
+  // view (returning the derived fields), WRITES target the table. A hybrid of the
+  // projection read path + the vanilla write path.
+  if (isWriteThrough(obj)) {
+    return renderWriteThroughQueriesFile(obj, ctx);
+  }
+
   const entityName = obj.name;
   // Import the entity's own file. Same target → relative "./Entity"; cross
   // target → importBase-qualified package path.
@@ -58,21 +89,12 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
   // helper (ADR-0008). Emit the dialect-correct Drizzle type alias so the
   // signatures `findXxx(db: Db, ...)` typecheck without the consumer importing
   // anything to construct one. Consumers pass any compatible Drizzle instance.
-  const dbTypeImport =
-    ctx.dialect === "postgres"
-      ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
-      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
-  const dbTypeAlias =
-    ctx.dialect === "postgres"
-      // Postgres: the base class every PG driver extends (node-postgres,
-      // postgres.js, Neon, Vercel, pglite) — not just node-postgres, so any
-      // PG driver the consumer chose is accepted.
-      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
-      // SQLite: accept BOTH sync (better-sqlite3) and async (libsql/Turso/D1)
-      // drivers. Generated queries `await` their results, which is valid on
-      // either result-kind; pinning `<"async">` wrongly rejected better-sqlite3
-      // (the most common SQLite driver) with "is not assignable".
-      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+  const { import: dbTypeImport, alias: dbTypeAlias } = dbTypeBlock(ctx.dialect);
+
+  // #203 — an @autoSet entity additionally imports its preserving-shape schema
+  // and emits the `insertPreserving<Entity>` escape hatch after `create<Entity>`.
+  const autoSet = hasAutoSetFields(obj);
+  const preservingImport = autoSet ? `, ${entityName}InsertPreservingSchema` : "";
 
   // Literal imports (Db type + entity types) live in a code block so they sort
   // alongside ts-poet's hoisted imp() imports at the top of the body.
@@ -80,7 +102,7 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema${preservingImport}, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [
@@ -88,6 +110,7 @@ import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}I
     renderFindByIdFn(obj, ctx),
     renderListFn(obj, ctx),
     renderCreateFn(obj, ctx),
+    ...(autoSet ? [renderInsertPreservingFn(obj, ctx)] : []),
     renderUpdateFn(obj, ctx),
     renderDeleteByIdFn(obj, ctx),
   ];
@@ -130,21 +153,7 @@ function renderProjectionQueriesFile(obj: MetaObject, ctx: RenderContext): strin
   const { fieldName: pkField, tsType: pkType } = getPkInfo(obj, ctx);
   const eqSym = imp("eq@drizzle-orm");
 
-  const dbTypeImport =
-    ctx.dialect === "postgres"
-      ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
-      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
-  const dbTypeAlias =
-    ctx.dialect === "postgres"
-      // Postgres: the base class every PG driver extends (node-postgres,
-      // postgres.js, Neon, Vercel, pglite) — not just node-postgres, so any
-      // PG driver the consumer chose is accepted.
-      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
-      // SQLite: accept BOTH sync (better-sqlite3) and async (libsql/Turso/D1)
-      // drivers. Generated queries `await` their results, which is valid on
-      // either result-kind; pinning `<"async">` wrongly rejected better-sqlite3
-      // (the most common SQLite driver) with "is not assignable".
-      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+  const { import: dbTypeImport, alias: dbTypeAlias } = dbTypeBlock(ctx.dialect);
 
   const literalImports = code`
 ${dbTypeImport}
@@ -175,6 +184,96 @@ export async function ${listFnName(entityName)}(db: Db, opts?: { limit?: number;
   return header + body;
 }
 
+/**
+ * #214 — the queries file for a write-through entity read-view (FR-024 §7).
+ *
+ * Reads (`find<Name>ById`, `list<Plural>`, reverse finders) SELECT from the replica
+ * `<camel>View` so they return the derived fields; writes (`create`/`update`/`delete`)
+ * target the write TABLE (derived-free, #213). A create/update re-reads the row THROUGH
+ * the view by PK — a derived field is only computable via the view's join, so the
+ * returned `<Entity>` (view shape) is read-your-writes correct.
+ */
+function renderWriteThroughQueriesFile(obj: MetaObject, ctx: RenderContext): string {
+  const entityName = obj.name;
+  const camelName = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const viewVar = `${camelName}View`;
+  const tableVar = ctx.collectionName(entityName);
+  const singularVar = camelName;
+  const entityFileName = entityModuleSpecifier(
+    ctx.selfTarget, ctx.entityModuleTarget, obj.package, entityName, ctx.extStyle,
+  );
+  const { fieldName: pkField, tsType: pkType } = getPkInfo(obj, ctx);
+  const pkFields = getPkFields(obj);
+  const eqSym = imp("eq@drizzle-orm");
+  const andSym = imp("and@drizzle-orm");
+  const autoSet = hasAutoSetFields(obj);
+
+  const { import: dbTypeImport, alias: dbTypeAlias } = dbTypeBlock(ctx.dialect);
+
+  const preservingImport = autoSet ? `, ${entityName}InsertPreservingSchema` : "";
+  const literalImports = code`
+${dbTypeImport}
+${dbTypeAlias}
+
+import { ${viewVar}, ${tableVar}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema${preservingImport}, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
+`;
+
+  // The view re-read predicate keyed on ALL primary-key columns of `source` (the
+  // insert's returning() row), so a composite PK re-reads the EXACT written row rather
+  // than any view row sharing the first key component. `andSym`/`pkFields[i]` are only
+  // referenced when the PK is composite, so a single-PK entity emits a bare `eq(...)`.
+  const viewByAllPk = (source: string): Code =>
+    pkFields.length > 1
+      ? code`${andSym}(${joinCode(pkFields.map((f) => code`${eqSym}(${viewVar}.${f}, ${source}.${f})`), { on: ", " })})`
+      : code`${eqSym}(${viewVar}.${pkField}, ${source}.${pkField})`;
+
+  // A create/insertPreserving writes the table, then reads the persisted row back
+  // through the view so the returned <Entity> carries the derived fields.
+  const insertReturningView = (fnName: string, schemaName: string): Code => code`
+export async function ${fnName}(db: Db, data: unknown): Promise<${entityName}> {
+  const validated = ${schemaName}.parse(data);
+  const [${singularVar}] = await db.insert(${tableVar}).values(validated).returning();
+  const [row] = await db.select().from(${viewVar}).where(${viewByAllPk(`${singularVar}!`)}).limit(1);
+  return row!;
+}
+`;
+
+  const updateFn = code`
+export async function ${updateFnName(entityName)}(db: Db, ${pkField}: ${pkType}, patch: ${entityName}Patch): Promise<${entityName} | null> {
+  const validated = ${entityName}UpdateSchema.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current (view) row.
+  if (Object.keys(validated).length === 0) return ${findByIdFnName(entityName)}(db, ${pkField});
+  const updated = await db.update(${tableVar}).set(validated).where(${eqSym}(${tableVar}.${pkField}, ${pkField})).returning();
+  if (updated.length === 0) return null;
+  const [row] = await db.select().from(${viewVar}).where(${eqSym}(${viewVar}.${pkField}, ${pkField})).limit(1);
+  return row ?? null;
+}
+`;
+
+  const sections: Code[] = [
+    literalImports,
+    // Reads route to the replica view.
+    renderFindByIdFn(obj, ctx, viewVar),
+    renderListFn(obj, ctx, viewVar),
+    // Writes target the table (create/update re-read through the view; delete is boolean).
+    insertReturningView(createFnName(entityName), `${entityName}InsertSchema`),
+    ...(autoSet ? [insertReturningView(insertPreservingFnName(entityName), `${entityName}InsertPreservingSchema`)] : []),
+    updateFn,
+    renderDeleteByIdFn(obj, ctx),
+  ];
+  // Reverse finders are reads → route to the view.
+  for (const fk of reverseFksFor(obj)) {
+    sections.push(renderReverseFinderFns(obj, fk, ctx, viewVar));
+  }
+
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${obj.fqn()}) — write-through entity read-view (reads → view, writes → table)\n` +
+    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+  return header + body;
+}
+
 /**
  * FR-017 Tier 2 — the polymorphic + per-subtype queries file for a TPH base.
  *
@@ -203,21 +302,7 @@ function renderTphQueriesFile(base: MetaObject, ctx: RenderContext): string {
   const eqSym = imp("eq@drizzle-orm");
   const andSym = imp("and@drizzle-orm");
 
-  const dbTypeImport =
-    ctx.dialect === "postgres"
-      ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
-      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
-  const dbTypeAlias =
-    ctx.dialect === "postgres"
-      // Postgres: the base class every PG driver extends (node-postgres,
-      // postgres.js, Neon, Vercel, pglite) — not just node-postgres, so any
-      // PG driver the consumer chose is accepted.
-      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
-      // SQLite: accept BOTH sync (better-sqlite3) and async (libsql/Turso/D1)
-      // drivers. Generated queries `await` their results, which is valid on
-      // either result-kind; pinning `<"async">` wrongly rejected better-sqlite3
-      // (the most common SQLite driver) with "is not assignable".
-      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+  const { import: dbTypeImport, alias: dbTypeAlias } = dbTypeBlock(ctx.dialect);
 
   // --- Polymorphic base reads ---
   const polymorphic = code`

package/src/templates/queries.ts

@@ -9,6 +9,7 @@ import {
   findByIdFnName,
   listFnName,
   createFnName,
+  insertPreservingFnName,
   updateFnName,
   deleteByIdFnName,
   reverseFinderFnName,
@@ -27,17 +28,28 @@ function subTypeToTsType(subType: string): "number" | "boolean" | "string" {
 /** Get the PK field name and its TS type for a given entity. */
 export function getPkInfo(entity: MetaObject, ctx: RenderContext): { fieldName: string; tsType: string } {
   // Use primaryIdentity() to find the primary identity (may be inherited from extends:/super:).
-  const primary = entity.primaryIdentity();
-  const rawFields = primary?.attr(IDENTITY_ATTR_FIELDS);
-  const fields = Array.isArray(rawFields) ? rawFields : (typeof rawFields === "string" ? [rawFields] : undefined);
-  const pkFieldName = fields?.[0] ?? "id";
+  const pkFieldName = getPkFields(entity)[0] ?? "id";
   const pkInfo = ctx.pkMap.get(entity.name);
   const subType = pkInfo?.fieldSubType ?? "long";
   return { fieldName: pkFieldName, tsType: subTypeToTsType(subType) };
 }
 
-export function renderFindByIdFn(entity: MetaObject, ctx: RenderContext): Code {
-  const varName = ctx.collectionName(entity.name);
+/** All primary-key field names, in order. `getPkInfo` exposes only the first (the
+ *  query layer's single-PK finder/update signatures key on it); #214's write-through
+ *  create re-read keys on ALL of them so a composite PK re-reads the exact written row
+ *  (via the insert's returning() values), not any row sharing the first key component. */
+export function getPkFields(entity: MetaObject): string[] {
+  const rawFields = entity.primaryIdentity()?.attr(IDENTITY_ATTR_FIELDS);
+  if (Array.isArray(rawFields)) return rawFields.filter((f): f is string => typeof f === "string");
+  return typeof rawFields === "string" ? [rawFields] : [];
+}
+
+// #214 — a write-through entity read-view routes READS to its replica view; the read
+// renderers below accept an optional `readVar` (the collection to SELECT from). Absent,
+// they read the entity's own table (the vanilla path, byte-identical). Writes always
+// target the table, so create/update/delete take no such override.
+export function renderFindByIdFn(entity: MetaObject, ctx: RenderContext, readVar?: string): Code {
+  const varName = readVar ?? ctx.collectionName(entity.name);
   const entityName = entity.name;
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
@@ -52,8 +64,8 @@ export async function ${fnName}(db: Db, ${pkField}: ${pkType}): Promise<${entity
 `;
 }
 
-export function renderListFn(entity: MetaObject, ctx: RenderContext): Code {
-  const varName = ctx.collectionName(entity.name);
+export function renderListFn(entity: MetaObject, ctx: RenderContext, readVar?: string): Code {
+  const varName = readVar ?? ctx.collectionName(entity.name);
   const entityName = entity.name;
   // Pluralize the PascalCase entity name, preserving capitalization
   // (e.g., "Category" -> "Categories", not "Categorys").
@@ -85,6 +97,31 @@ export async function ${fnName}(db: Db, data: unknown): Promise<${entityName}> {
 `;
 }
 
+/**
+ * #203 — the `insertPreserving<Entity>` escape hatch. Cross-port with the Java /
+ * Kotlin / C# / Python ports: emitted ONLY for an entity that declares @autoSet
+ * fields, it persists the row WITHOUT the create-time now() stamp — the @autoSet
+ * columns are written verbatim from the caller's data — for import / restore /
+ * replication paths that must keep the original timestamps. It validates through
+ * `<Entity>InsertPreservingSchema` (the preserving-shape schema whose @autoSet
+ * columns carry no transform); the normal `create<Entity>` always stamps now().
+ */
+export function renderInsertPreservingFn(entity: MetaObject, ctx: RenderContext): Code {
+  const varName = ctx.collectionName(entity.name);
+  const entityName = entity.name;
+  const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const fnName = insertPreservingFnName(entityName);
+  const schemaName = `${entityName}InsertPreservingSchema`;
+
+  return code`
+export async function ${fnName}(db: Db, data: unknown): Promise<${entityName}> {
+  const validated = ${schemaName}.parse(data);
+  const [${singularVar}] = await db.insert(${varName}).values(validated).returning();
+  return ${singularVar}!;
+}
+`;
+}
+
 export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const varName = ctx.collectionName(entity.name);
   const entityName = entity.name;
@@ -157,9 +194,11 @@ export function reverseFksFor(entity: MetaObject): ReverseFk[] {
   return out;
 }
 
-/** Render the single + batched reverse finders for one FK on `entity`. */
-export function renderReverseFinderFns(entity: MetaObject, fk: ReverseFk, ctx: RenderContext): Code {
-  const varName = ctx.collectionName(entity.name);
+/** Render the single + batched reverse finders for one FK on `entity`. `readVar`
+ *  (#214) routes the SELECT to a write-through entity's replica view; absent, it
+ *  reads the entity's own table (vanilla, byte-identical). */
+export function renderReverseFinderFns(entity: MetaObject, fk: ReverseFk, ctx: RenderContext, readVar?: string): Code {
+  const varName = readVar ?? ctx.collectionName(entity.name);
   const entityName = entity.name;
   // The Drizzle table object is keyed by the LOGICAL field name (the DB column
   // name is the argument to integer()/text()), so column access uses fk.fkField.

package/src/templates/view-decl.ts

@@ -0,0 +1,128 @@
+// Shared Drizzle `.existing()` view declaration builder.
+//
+// A view-backed read model — a projection (read-only, view-only) OR the replica
+// view of a write-through entity (FR-024 §7, #214) — declares its physical SQL
+// view to Drizzle via `<viewVar> = pgView/sqliteView(<name>, { …cols }).existing()`
+// so `db.select().from(<viewVar>)` is typed and `.existing()` tells Drizzle not to
+// attempt DDL (the SQL view is created/owned by migrate-ts). Both hosts emit the
+// SAME declaration shape, so it lives here once (extracted from projection-decl).
+
+import { code, imp, joinCode, type Code } from "ts-poet";
+import {
+  type MetaField, FIELD_SUBTYPE_OBJECT, FIELD_ATTR_OBJECT_REF, stripPackage,
+} from "@metaobjectsdev/metadata";
+import type { ColumnNamingStrategy } from "../metaobjects-config.js";
+import { mapColumnType } from "../column-mapper.js";
+import { zodTypeFor } from "./field-meta.js";
+
+export interface ViewDeclOpts {
+  readonly dialect: "postgres" | "sqlite";
+  readonly columnNamingStrategy: ColumnNamingStrategy;
+  /** Drives the timestamp column TS type (Date vs string) in the view declaration. */
+  readonly timestampMode: "date" | "string";
+  /** Resolve a value-object short name → its import module specifier. */
+  readonly voModule: (refBase: string) => string;
+}
+
+/**
+ * The typed view column map for a Drizzle `.existing()` declaration — keyed by
+ * field name, valued by the column builder for the (renamed) physical view column,
+ * so `db.select().from(<view>)` is typed. Honors `@dbColumnType`; `.existing()`
+ * views carry type + physical name only (no PK/default/notNull DDL modifiers).
+ */
+function viewColumnLine(f: MetaField, opts: ViewDeclOpts): Code {
+  const { dialect, columnNamingStrategy, timestampMode, voModule } = opts;
+  const spec = mapColumnType(f, dialect, columnNamingStrategy, timestampMode);
+  const colSym = imp(`${spec.fnName}@${spec.importModule}`);
+  const optsArg =
+    spec.fnOptions && Object.keys(spec.fnOptions).length > 0
+      ? `, ${JSON.stringify(spec.fnOptions)}`
+      : "";
+  // #204 — of the table modifiers, only `.array()` (postgres native array element
+  // typing) and `.notNull()` (shapes the SELECT type) carry to an existing view;
+  // `.primaryKey()`/`.default()`/`.references()`/`.unique()` are table-DDL concerns
+  // and invalid on a `.existing()` view declaration. Preserve the canonical order.
+  const viewModifiers = spec.modifiers
+    .filter((m) => m === ".array()" || m === ".notNull()")
+    .join("");
+  // Narrow the column to its resolved element/value type — `.$type<…>()` — mirroring
+  // the entity column so the read row is typed (not `unknown`) and an array column
+  // reads as `T[]`, not `T`.
+  let dollarType: Code | string = "";
+  const dtr = spec.dollarTypeRef;
+  if (dtr?.kind === "scalar") {
+    dollarType = `.$type<${dtr.tsType}${dtr.array ? "[]" : ""}>()`;
+  } else if (dtr?.kind === "objectRef") {
+    const voTypeSym = imp(`${dtr.name}@${voModule(dtr.name)}`);
+    dollarType = dtr.array ? code`.$type<${voTypeSym}[]>()` : code`.$type<${voTypeSym}>()`;
+  } else if (dtr?.kind === "map") {
+    dollarType = "scalar" in dtr.value
+      ? `.$type<Record<string, ${dtr.value.scalar}>>()`
+      : code`.$type<Record<string, ${imp(`${dtr.value.objectRef}@${voModule(dtr.value.objectRef)}`)}>>()`;
+  }
+  return code`  ${f.name}: ${colSym}(${JSON.stringify(spec.dbName)}${optsArg})${dollarType}${viewModifiers}`;
+}
+
+/**
+ * Emit `export const <viewVar> = <viewFn>(<viewName>, { …cols }).existing();` for a
+ * view-backed read model (projection or write-through replica view). `fields` are the
+ * view's exposed columns (already resolved to effective fields by the caller).
+ */
+export function renderExistingViewDecl(
+  fields: readonly MetaField[],
+  viewName: string,
+  viewVar: string,
+  opts: ViewDeclOpts,
+): Code {
+  const viewFn = opts.dialect === "postgres" ? "pgView" : "sqliteView";
+  const viewModule = opts.dialect === "postgres" ? "drizzle-orm/pg-core" : "drizzle-orm/sqlite-core";
+  const viewSym = imp(`${viewFn}@${viewModule}`);
+  const viewColumnLines = fields.map((f) => viewColumnLine(f, opts));
+  return code`
+// View declaration — Drizzle uses this for typed SELECT queries.
+// The SQL view is created/managed by migrate-ts; .existing() tells Drizzle
+// not to attempt DDL for this declaration.
+export const ${viewVar} = ${viewSym}(${JSON.stringify(viewName)}, {
+${joinCode(viewColumnLines, { on: ",\n" })}
+}).existing();
+`;
+}
+
+/**
+ * The Zod object body for a view-backed read model — one `field: z.<type>[.nullable()]`
+ * line per column, the read counterpart of {@link renderExistingViewDecl}. A column that
+ * is not `.notNull()` in the view is `.nullable()` (Drizzle's SELECT infers `T | null`),
+ * so `z.infer<>` of the object equals the view row type. This is the dialect-agnostic read
+ * type (a Drizzle view exposes `$inferSelect` on Postgres but not SQLite). A `field.object`
+ * passthrough carries the value-object's schema so the read type exposes the VO shape.
+ * `voModule` resolves a value-object short name → its import module.
+ */
+export function renderViewReadZodObject(fields: readonly MetaField[], opts: ViewDeclOpts): Code {
+  const { dialect, columnNamingStrategy, timestampMode, voModule } = opts;
+  const z = imp("z@zod");
+  const lines: Code[] = fields.map((f) => {
+    const nullable =
+      mapColumnType(f, dialect, columnNamingStrategy, timestampMode).modifiers.includes(".notNull()")
+        ? ""
+        : ".nullable()";
+    const refBase =
+      f.subType === FIELD_SUBTYPE_OBJECT
+        ? (() => {
+            const ref = f.attr(FIELD_ATTR_OBJECT_REF);
+            return typeof ref === "string" && ref.length > 0 ? stripPackage(ref) : undefined;
+          })()
+        : undefined;
+    if (refBase) {
+      const schemaSym = imp(`${refBase}InsertSchema@${voModule(refBase)}`);
+      const base = f.resolvedIsArray() ? code`${z}.array(${schemaSym})` : code`${schemaSym}`;
+      return code`  ${f.name}: ${base}${nullable}`;
+    }
+    // #204 — an array passthrough reads as `T[]`; zodTypeFor returns the ELEMENT type.
+    const inner = code`${z}.${zodTypeFor(f).replace(/^z\./, "")}`;
+    const zbase = f.resolvedIsArray() ? code`${z}.array(${inner})` : inner;
+    return code`  ${f.name}: ${zbase}${nullable}`;
+  });
+  return code`${z}.object({
+${joinCode(lines, { on: ",\n" })}
+})`;
+}