feat(ts): eject --undo, gen --strict, init --with-docs, entityTypeNames, api-docs follow the generator list (#490)

Author: dmealing

docs/ports/typescript.md

@@ -120,6 +120,19 @@ model walks, the naming and type-mapping tables), which the copies import from
 `meta eject docs-site` copies instead
 ([what the copy holds](../features/own-your-codegen.md#what-the-copy-holds)).
 
+A copy that never changed is a cost: it stays at the release it was copied from and misses
+every later fix. `meta gen` prints one line naming the owned copies that are still
+the shipped reference, unchanged, and `meta eject --undo` takes them back: with no names it
+removes every such copy (and the template modules only it used), and with names it removes
+those, refusing the whole call, and removing nothing, if a named copy differs (`--force`
+removes it anyway). It never edits `metaobjects.config.ts`; it prints the import to swap
+back to the package's. There is no `meta doctor`: `meta eject --list` is the report.
+A copy you changed stays yours.
+
+`meta gen` loads leniently, so an attribute the registry does not know (a typo such as
+`@sensitve`) is a warning and the run goes on. `meta gen --strict` makes it an error, as
+`meta verify` does: it exits 1 and writes nothing.
+
 Documentation is generated the same way, from the same list: there is no docs command
 (ADR-0034 Amendment 9). `docsFile()`, `apiDocsFile()`, `requirementsFile()`,
 `agentDocsFile()`, `metamodelDocsFile()` and `docsSiteFile()` write to the target named
@@ -473,6 +486,33 @@ operands by those options. `meta migrate` warns for a decimal declared with `@pr
 on SQLite or D1. `meta verify --codegen` names the `wire` block that reproduces committed output
 generated under another setting.
 
+### Types exported per entity
+
+Code that talks to a generated entity imports these names, so they are a contract. Each
+entity module (`<Entity>.ts`) exports six types. `entityTypeNames(obj)`, exported from
+`@metaobjectsdev/codegen-ts`, returns the same six spellings for an owned generator, so it
+need not rebuild them from the entity name.
+
+| Type | Derived from | Use it for |
+| --- | --- | --- |
+| `<Entity>` | the Drizzle table, `InferSelectModel` | a row read back from the database: what `find<Entity>ById` and `create<Entity>` return |
+| `<Entity>Insert` | the Drizzle table, `InferInsertModel` | a row as the database accepts it, before validation |
+| `<Entity>Update` | `Partial<<Entity>Insert>` | the same, every column optional |
+| `<Entity>Create` | `z.input` of `<Entity>InsertSchema` | **the argument of `create<Entity>`**, and what a client posts |
+| `<Entity>Patch` | `z.input` of `<Entity>UpdateSchema` | **the argument of `update<Entity>`**, and what a client patches |
+| `<Entity>Filter` | the `@filterable` and `@sortable` fields | the `filter`, `sort`, `limit` and `offset` options of `list<Entity>` and the generated hooks |
+
+`Create` and `Patch` are the pair to use at a call site. They come from the Zod schemas the
+functions validate with, so a renamed or dropped field is a compile error at every call.
+`Insert` and `Update` come from the table and describe what the database takes. They are
+looser than the validators, so prefer `Create` and `Patch` at the API boundary.
+
+When the entity is a TPH discriminator base, the row type is `<Entity>Row`, because
+`<Entity>` is the discriminated union over its subtypes. A read-only projection has no
+table to insert into, so do not expect `Create` or `Patch` there; read its generated module
+for what it exports. `test/entity-type-names.test.ts` in `codegen-ts` checks the table
+against the golden `Subscriber` module.
+
 ### `<Entity>Names` — the physical names, as constants
 
 `meta init` scaffolds a `names` generator, so a new project gets `<Entity>.names.ts`

examples/advanced-modeling/codegen/generators/queries.ts

@@ -160,6 +160,9 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat
 
   const generator: Generator = {
     name: "queries-file",
+    // Read by the api reference (`apiDocsFile()`): it documents the query helpers only when
+    // a generator in the run writes them.
+    emitsQueries: true,
     filter,
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {

examples/advanced-modeling/codegen/templates/entity-type-names.ts

@@ -0,0 +1,46 @@
+// The six type names the entity module exports for an entity. A client written against the
+// generated entity (a typed API client, a form, a service layer) imports these by name, so
+// the spelling is part of the generator's contract, not an accident of three templates.
+// `entityTypeNames` is the one place that spelling lives: the templates that emit the names
+// call it, and an owned generator that refers to them calls it too, so a rename cannot
+// leave one side behind. `docs/ports/typescript.md` ("Types exported per entity") is the
+// reader-facing table; test/entity-type-names.test.ts pins it to the golden output.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+
+export interface EntityTypeNames {
+  /** The row type read back from the table: `InferSelectModel` of the Drizzle table. */
+  row: string;
+  /** What an insert accepts: `InferInsertModel` of the Drizzle table. */
+  insert: string;
+  /** `Partial<Insert>`. */
+  update: string;
+  /** The Zod insert schema's INPUT type, the argument of `create<Entity>`. */
+  create: string;
+  /** The Zod update schema's INPUT type: every settable field optional, the argument of `update<Entity>`. */
+  patch: string;
+  /** The client filter object: filterable fields, `sort`, `limit`, `offset`, `or`, `and`. */
+  filter: string;
+}
+
+export interface EntityTypeNamesOpts {
+  /**
+   * The row type is `<Entity>Row` instead of `<Entity>` when the entity is a TPH
+   * discriminator base, because its discriminated-union type owns the bare name.
+   */
+  tphBase?: boolean;
+  /** Use this spelling instead of `obj.name` (a value object renamed on a name collision). */
+  name?: string;
+}
+
+export function entityTypeNames(obj: MetaData, opts: EntityTypeNamesOpts = {}): EntityTypeNames {
+  const base = opts.name ?? obj.name;
+  return {
+    row: opts.tphBase ? `${base}Row` : base,
+    insert: `${base}Insert`,
+    update: `${base}Update`,
+    create: `${base}Create`,
+    patch: `${base}Patch`,
+    filter: `${base}Filter`,
+  };
+}

examples/advanced-modeling/codegen/templates/filter-type.ts

@@ -16,6 +16,7 @@ import {
   opsForField,
 } from "@metaobjectsdev/metadata";
 import { isSortableField } from "./filter-shared.js";
+import { entityTypeNames } from "./entity-type-names.js";
 import { enumValues } from "@metaobjectsdev/codegen-ts/engine";
 
 // currency is integer minor units (allowlist `integer: true`, row schema `z.number().int()`).
@@ -79,6 +80,7 @@ function renderFieldUnion(field: MetaField): string {
  * the server's per-subtype allowlist.
  */
 export function renderFilterType(entity: MetaObject, exclude?: string): Code {
+  const filterName = entityTypeNames(entity).filter;
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in filter types.
   const allFields = entity.fields().filter((c) => c.name !== exclude);
   const filterableFieldsList = allFields.filter((c) => c.attr(FIELD_ATTR_FILTERABLE) === true);
@@ -93,12 +95,12 @@ export function renderFilterType(entity: MetaObject, exclude?: string): Code {
 
   if (fieldLines.length === 0 && sortFieldNames.length === 0) {
     return code`
-export type ${entity.name}Filter = {
+export type ${filterName} = {
   limit?: number;
   offset?: number;
   sort?: string;
-  or?: ${entity.name}Filter[];
-  and?: ${entity.name}Filter[];
+  or?: ${filterName}[];
+  and?: ${filterName}[];
 };
 `;
   }
@@ -112,13 +114,13 @@ export type ${entity.name}Filter = {
         })();
 
   return code`
-export type ${entity.name}Filter = {
+export type ${filterName} = {
   limit?: number;
   offset?: number;
   sort?: ${sortType};
 ${fieldLines.join("\n")}
-  or?: ${entity.name}Filter[];
-  and?: ${entity.name}Filter[];
+  or?: ${filterName}[];
+  and?: ${filterName}[];
 };
 `;
 }

examples/advanced-modeling/codegen/templates/inferred-types.ts

@@ -44,6 +44,7 @@ import { sharedEnumForField } from "@metaobjectsdev/codegen-ts/engine";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "@metaobjectsdev/codegen-ts/engine";
 import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine";
 import { effectivePackage } from "@metaobjectsdev/codegen-ts/engine";
+import { entityTypeNames } from "./entity-type-names.js";
 
 /**
  * Emit Drizzle's InferSelectModel / InferInsertModel aliases for an entity.
@@ -71,7 +72,7 @@ export function renderInferredTypes(
   const insertSym = imp("t:InferInsertModel@drizzle-orm");
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
-  const rowName = tphBase ? `${entity.name}Row` : entity.name;
+  const { row: rowName, insert: insertName, update: updateName } = entityTypeNames(entity, { tphBase });
   // #214 — a write-through entity read-view routes READS to the replica view, so the
   // read row type <Entity> is emitted from the VIEW's read schema (z.infer, carrying
   // the derived fields) by the entity-file composer, NOT here. `skipRow` suppresses
@@ -80,14 +81,14 @@ export function renderInferredTypes(
   // inferred from the write TABLE (derived-free, #213).
   if (skipRow) {
     return code`
-export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
-export type ${entity.name}Update = Partial<${entity.name}Insert>;
+export type ${insertName} = ${insertSym}<typeof ${varName}>;
+export type ${updateName} = Partial<${insertName}>;
 `;
   }
   return code`
 ${docsPrefix}export type ${rowName} = ${selectSym}<typeof ${varName}>;
-export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
-export type ${entity.name}Update = Partial<${entity.name}Insert>;
+export type ${insertName} = ${insertSym}<typeof ${varName}>;
+export type ${updateName} = Partial<${insertName}>;
 `;
 }
 

examples/advanced-modeling/codegen/templates/zod-validators.ts

@@ -9,6 +9,7 @@
 // object-array field collapsed to z.array(z.string()) and the JSON Schema sent
 // downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
+import { entityTypeNames } from "./entity-type-names.js";
 import { code, joinCode, imp, type Code } from "@metaobjectsdev/codegen-ts/engine";
 import { MetaObject, MetaField, type MetaRoot, stripPackage } from "@metaobjectsdev/metadata";
 import {
@@ -529,6 +530,7 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
   const insertSchemaName = `${objName}InsertSchema`;
   const updateSchemaName = `${objName}UpdateSchema`;
   const preservingSchemaName = `${objName}InsertPreservingSchema`;
+  const { create: createName, patch: patchName } = entityTypeNames(obj, { name: objName });
 
   const docs = renderDocsFor(obj);
   const docsPrefix = docs ? `${docs}\n` : "";
@@ -561,11 +563,11 @@ ${joinCode(updateFieldLines, { on: ",\n" })}
 /** Typed create shape for ${objName}: the insert schema's INPUT (pre-transform) type. A
  * renamed/dropped/misspelt field is a compile error at every \`create${objName}\` call site;
  * the schema still validates at runtime. */
-export type ${objName}Create = ${z}.input<typeof ${insertSchemaName}>;
+export type ${createName} = ${z}.input<typeof ${insertSchemaName}>;
 
 /** Typed patch shape for ${objName}: every settable field, optional (FR-035 PATCH). A
  * renamed/dropped field is a compile error at every \`update${objName}\` call site. */
-export type ${objName}Patch = ${z}.input<typeof ${updateSchemaName}>;${preservingBlock}
+export type ${patchName} = ${z}.input<typeof ${updateSchemaName}>;${preservingBlock}
 `;
 }
 

examples/showcase/codegen/generators/queries.ts

@@ -160,6 +160,9 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat
 
   const generator: Generator = {
     name: "queries-file",
+    // Read by the api reference (`apiDocsFile()`): it documents the query helpers only when
+    // a generator in the run writes them.
+    emitsQueries: true,
     filter,
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {

examples/showcase/codegen/templates/entity-type-names.ts

@@ -0,0 +1,46 @@
+// The six type names the entity module exports for an entity. A client written against the
+// generated entity (a typed API client, a form, a service layer) imports these by name, so
+// the spelling is part of the generator's contract, not an accident of three templates.
+// `entityTypeNames` is the one place that spelling lives: the templates that emit the names
+// call it, and an owned generator that refers to them calls it too, so a rename cannot
+// leave one side behind. `docs/ports/typescript.md` ("Types exported per entity") is the
+// reader-facing table; test/entity-type-names.test.ts pins it to the golden output.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+
+export interface EntityTypeNames {
+  /** The row type read back from the table: `InferSelectModel` of the Drizzle table. */
+  row: string;
+  /** What an insert accepts: `InferInsertModel` of the Drizzle table. */
+  insert: string;
+  /** `Partial<Insert>`. */
+  update: string;
+  /** The Zod insert schema's INPUT type, the argument of `create<Entity>`. */
+  create: string;
+  /** The Zod update schema's INPUT type: every settable field optional, the argument of `update<Entity>`. */
+  patch: string;
+  /** The client filter object: filterable fields, `sort`, `limit`, `offset`, `or`, `and`. */
+  filter: string;
+}
+
+export interface EntityTypeNamesOpts {
+  /**
+   * The row type is `<Entity>Row` instead of `<Entity>` when the entity is a TPH
+   * discriminator base, because its discriminated-union type owns the bare name.
+   */
+  tphBase?: boolean;
+  /** Use this spelling instead of `obj.name` (a value object renamed on a name collision). */
+  name?: string;
+}
+
+export function entityTypeNames(obj: MetaData, opts: EntityTypeNamesOpts = {}): EntityTypeNames {
+  const base = opts.name ?? obj.name;
+  return {
+    row: opts.tphBase ? `${base}Row` : base,
+    insert: `${base}Insert`,
+    update: `${base}Update`,
+    create: `${base}Create`,
+    patch: `${base}Patch`,
+    filter: `${base}Filter`,
+  };
+}

examples/showcase/codegen/templates/filter-type.ts

@@ -16,6 +16,7 @@ import {
   opsForField,
 } from "@metaobjectsdev/metadata";
 import { isSortableField } from "./filter-shared.js";
+import { entityTypeNames } from "./entity-type-names.js";
 import { enumValues } from "@metaobjectsdev/codegen-ts/engine";
 
 // currency is integer minor units (allowlist `integer: true`, row schema `z.number().int()`).
@@ -79,6 +80,7 @@ function renderFieldUnion(field: MetaField): string {
  * the server's per-subtype allowlist.
  */
 export function renderFilterType(entity: MetaObject, exclude?: string): Code {
+  const filterName = entityTypeNames(entity).filter;
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in filter types.
   const allFields = entity.fields().filter((c) => c.name !== exclude);
   const filterableFieldsList = allFields.filter((c) => c.attr(FIELD_ATTR_FILTERABLE) === true);
@@ -93,12 +95,12 @@ export function renderFilterType(entity: MetaObject, exclude?: string): Code {
 
   if (fieldLines.length === 0 && sortFieldNames.length === 0) {
     return code`
-export type ${entity.name}Filter = {
+export type ${filterName} = {
   limit?: number;
   offset?: number;
   sort?: string;
-  or?: ${entity.name}Filter[];
-  and?: ${entity.name}Filter[];
+  or?: ${filterName}[];
+  and?: ${filterName}[];
 };
 `;
   }
@@ -112,13 +114,13 @@ export type ${entity.name}Filter = {
         })();
 
   return code`
-export type ${entity.name}Filter = {
+export type ${filterName} = {
   limit?: number;
   offset?: number;
   sort?: ${sortType};
 ${fieldLines.join("\n")}
-  or?: ${entity.name}Filter[];
-  and?: ${entity.name}Filter[];
+  or?: ${filterName}[];
+  and?: ${filterName}[];
 };
 `;
 }

examples/showcase/codegen/templates/inferred-types.ts

@@ -44,6 +44,7 @@ import { sharedEnumForField } from "@metaobjectsdev/codegen-ts/engine";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "@metaobjectsdev/codegen-ts/engine";
 import type { RenderContext } from "@metaobjectsdev/codegen-ts/engine";
 import { effectivePackage } from "@metaobjectsdev/codegen-ts/engine";
+import { entityTypeNames } from "./entity-type-names.js";
 
 /**
  * Emit Drizzle's InferSelectModel / InferInsertModel aliases for an entity.
@@ -71,7 +72,7 @@ export function renderInferredTypes(
   const insertSym = imp("t:InferInsertModel@drizzle-orm");
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
-  const rowName = tphBase ? `${entity.name}Row` : entity.name;
+  const { row: rowName, insert: insertName, update: updateName } = entityTypeNames(entity, { tphBase });
   // #214 — a write-through entity read-view routes READS to the replica view, so the
   // read row type <Entity> is emitted from the VIEW's read schema (z.infer, carrying
   // the derived fields) by the entity-file composer, NOT here. `skipRow` suppresses
@@ -80,14 +81,14 @@ export function renderInferredTypes(
   // inferred from the write TABLE (derived-free, #213).
   if (skipRow) {
     return code`
-export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
-export type ${entity.name}Update = Partial<${entity.name}Insert>;
+export type ${insertName} = ${insertSym}<typeof ${varName}>;
+export type ${updateName} = Partial<${insertName}>;
 `;
   }
   return code`
 ${docsPrefix}export type ${rowName} = ${selectSym}<typeof ${varName}>;
-export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
-export type ${entity.name}Update = Partial<${entity.name}Insert>;
+export type ${insertName} = ${insertSym}<typeof ${varName}>;
+export type ${updateName} = Partial<${insertName}>;
 `;
 }