@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/dist/names.d.ts

@@ -0,0 +1,275 @@
+/**
+ * §A2/§A3 — the ONE place a data name is resolved for a generator run.
+ *
+ * Both the names artifact (namesFile) and the entity generator that consumes it call this,
+ * so the constant and the binding it describes cannot be produced by different resolvers or
+ * different arguments. That is the whole rule; a name computed twice is a name that can
+ * disagree with itself.
+ */
+import { type ColumnNamingStrategy, type MetaObject } from "@metaobjectsdev/metadata";
+import { type Code } from "ts-poet";
+import type { RenderContext } from "./render-context.js";
+export interface FieldNames {
+    readonly name: string;
+    readonly column: string;
+}
+/**
+ * One `source.rdb` child, under the ROLE it plays.
+ *
+ * The physical name is carried under a key NAMED FOR THE KIND — `table`, `view`,
+ * `materializedView`, `proc`, `function` — and that key is not invented here: it is
+ * `PHYSICAL_NAME_ATTR_BY_KIND`, the metamodel's own FR-016/ADR-0018 alias map, the same
+ * one the canonical serializer rewrites through. So the artifact spells a physical name
+ * the way the metadata that declared it does.
+ *
+ * This is the half of the shape that earns the restructure. A single flat `name` held a
+ * table, a view and a stored procedure in the same run, told apart only by a sibling
+ * `kind`; under `as const`, `LedgerNames.sources.replica.table` is now a compile error,
+ * because that source is a view. The read site answers the question instead of the reader
+ * having to.
+ */
+export interface SourceNames {
+    readonly type: string;
+    readonly subType: string;
+    /** The `@kind` value, defaulted per ADR-0007 Rule 3 — the discriminator for the alias below. */
+    readonly kind: string;
+    readonly schema?: string | undefined;
+    /** The physical name, under the alias for `kind`. Exactly one of these is present. */
+    readonly table?: string | undefined;
+    readonly view?: string | undefined;
+    readonly materializedView?: string | undefined;
+    readonly proc?: string | undefined;
+    readonly function?: string | undefined;
+}
+/**
+ * One `identity.*` or `index.*` child.
+ *
+ * `subType` is load-bearing rather than decorative: it is the ONLY thing distinguishing a
+ * unique alternate key from a non-unique lookup index, which is the whole reason ADR-0040
+ * put uniqueness in the type rather than in an attribute.
+ *
+ * `index` — the database name — is present only where a shared resolver produces it:
+ * `identity.secondary` and `index.lookup`, via `resolveIndexName`. It is deliberately
+ * ABSENT on `identity.primary`, because no such name exists to carry: migrate hardcodes
+ * `<table>_pkey` on Postgres, emits an unnamed PK on SQLite, and no port's codegen names a
+ * primary key at all. Carrying it would restate a migrate-only, dialect-conditional
+ * formula in an artifact whose entire promise is that a name is spelled once — the #293
+ * defect, re-created by the mechanism built to prevent it.
+ */
+export interface KeyNames {
+    readonly type: string;
+    readonly subType: string;
+    readonly name: string;
+    /** The database index name. Present for `identity.secondary` and `index.lookup` only. */
+    readonly index?: string | undefined;
+}
+/** The object whose names artifact this one extends. */
+export interface SuperNames {
+    readonly name: string;
+    readonly package?: string | undefined;
+}
+export interface ObjectNames {
+    /** The metamodel type — always `object`. */
+    readonly type: string;
+    /** The metamodel subType — `entity` | `projection` | `value`. */
+    readonly subType: string;
+    /**
+     * The object's OWN name — `"Customer"`, not `"TBL_CUST_MASTER"`.
+     *
+     * It held the physical name until 0.25.0, which is the one change here that a hand-
+     * written consumer can adopt WITHOUT a compile error: `pgTable(CustomerNames.name, …)`
+     * still compiles and now binds a table called `Customer`. The release note leads with
+     * that; no gate here can see it, because the code that breaks is not generated.
+     */
+    readonly name: string;
+    /**
+     * Every `source.rdb` child, keyed by effective `@role` (`primary` | `replica`).
+     *
+     * Role is the honest axis: the loader requires exactly one primary, and every consumer
+     * that binds a second source picks it by role. Keying by role is also what finally gives
+     * a WRITE-THROUGH entity's replica view a home — it declares two physical names, the
+     * artifact carried one, and both TypeScript and C# emitted the second as a literal.
+     *
+     * Empty on a FRAGMENT: an abstract base with no source of its own contributes columns
+     * and must never acquire a physical name it never declared.
+     */
+    readonly sources: Readonly<Record<string, SourceNames>>;
+    /** The sources DECLARED HERE — what this artifact emits. See `ownFields`. */
+    readonly ownSources: Readonly<Record<string, SourceNames>>;
+    /**
+     * Every field, INHERITED INCLUDED. This is what a consumer looks a column up in, so a
+     * lookup for an inherited field must hit — miss and the caller falls back to a literal
+     * (see `columnExpr`), which is the whole defect this artifact exists to remove.
+     */
+    readonly fields: Readonly<Record<string, FieldNames>>;
+    /**
+     * The fields DECLARED HERE — what the artifact EMITS. Inherited ones are declared by
+     * the super's artifact and reached through it, so a subtype states each physical name
+     * once instead of restating its parent's.
+     *
+     * ADR-0039's ONE sanctioned own-accessor use, in the exact form the ADR names: codegen
+     * emitting a generated subclass, iterating own members so inherited ones are not
+     * re-emitted.
+     */
+    readonly ownFields: Readonly<Record<string, FieldNames>>;
+    /** Every `identity.*` child, inherited included; keyed by metamodel name. */
+    readonly identities: Readonly<Record<string, KeyNames>>;
+    /** The identities DECLARED HERE. See `ownFields`. */
+    readonly ownIdentities: Readonly<Record<string, KeyNames>>;
+    /** Every `index.*` child, inherited included; keyed by metamodel name. */
+    readonly indexes: Readonly<Record<string, KeyNames>>;
+    /** The indexes DECLARED HERE. See `ownFields`. */
+    readonly ownIndexes: Readonly<Record<string, KeyNames>>;
+    /** The nearest ancestor carrying an artifact of its own, when there is one. */
+    readonly superNames?: SuperNames | undefined;
+    /**
+     * True when the primary source is the SUPER's rather than declared here — a TPH
+     * subtype, which shares its base's single table. Structural (the two resolve to the
+     * SAME source node), never an equality test on the resolved strings: the physical
+     * name, kind and schema then all come from the super's artifact rather than being
+     * restated.
+     */
+    readonly inheritsSource: boolean;
+}
+/**
+ * The nearest ancestor of `obj` that carries a names artifact of its own, or undefined.
+ *
+ * Walks past an ancestor with nothing to contribute — an abstract marker with no fields,
+ * no keys and no source emits no artifact, so there is nothing to extend and the search
+ * continues upward rather than stopping at a name that does not exist.
+ */
+export declare function namesArtifactSuperOf(obj: MetaObject): MetaObject | undefined;
+export declare function resolveObjectNames(obj: MetaObject, strategy?: ColumnNamingStrategy): ObjectNames | undefined;
+/**
+ * The names FRAGMENT for an object that a sourced object extends but which declares no
+ * source of its own — the `BaseEntity` pattern: shared fields, no table.
+ *
+ * Separate from {@link resolveObjectNames} on purpose, and the separation is the #248 rule
+ * intact rather than weakened. "Has a primary source" still decides whether an object is a
+ * database participant, so an `object.value` carrying fields resolves to nothing here as it
+ * always has. A fragment is emitted only for an object REACHED from a participant by
+ * walking `extends` upward — which is the only context in which its fields are columns at
+ * all. It carries no `kind`/`name`/`readOnly`, because it has no physical name and must
+ * never acquire one.
+ *
+ * Returns undefined when the object declares nothing of its own: an abstract marker has
+ * nothing to extend, and emitting an empty artifact for it would put a name in the import
+ * graph that says nothing. "Nothing" is {@link declaresNamesContent} — fields OR keys, the
+ * same question {@link namesArtifactSuperOf} asks, so the walk and the emit cannot disagree
+ * about which ancestors exist.
+ */
+export declare function resolveSuperFragmentNames(obj: MetaObject, strategy?: ColumnNamingStrategy): ObjectNames | undefined;
+/**
+ * §B2 — the shared builder every `<Object>Names` reference call site used to hand-roll:
+ * check whether the artifact exists in this run (`ctx.includeNames`), resolve the
+ * constant (`resolveObjectNames`), and build the ts-poet import symbol pointing at
+ * `<Object>.names.ts`. Returns undefined whenever the artifact does not exist for this
+ * object in this run — a PRESENCE guard ("is the artifact in this run at all"), never the
+ * divergence refusal that `primaryRdbSource` owns: this function never compares a
+ * resolved value to a literal, it only asks whether the constant exists.
+ *
+ * `fromPackage` is the package of the FILE BEING EMITTED — the file that will hold the
+ * `import { <Object>Names } from …` line — and defaults to `obj.package`, correct for
+ * every site that emits `obj`'s OWN module (the entity generator referencing its own
+ * names artifact, same object on both ends). A caller emitting a DIFFERENT object's file
+ * and reaching across packages for `obj`'s names artifact — an M:N routes file, which
+ * lives in the SOURCE entity's package, importing the junction/target's `<X>Names` — MUST
+ * pass the emitting file's own package explicitly. Making this an explicit parameter
+ * (rather than assuming same-package the way a plain sibling specifier does) is what
+ * surfaces that choice: see routes-file.ts's `resolveJunctionColumn`, the one site that
+ * got it wrong by assuming same-package.
+ */
+export declare function namesRef(obj: MetaObject, ctx: RenderContext, fromPackage?: string | undefined): {
+    readonly resolved: ObjectNames;
+    readonly symbol: Code;
+} | undefined;
+/**
+ * Adapts a `namesRef()` result to the `{ name, symbol }` shape `renderEntityConstants` /
+ * `renderEntityMetaFile` accept. Kept as a separate, narrower shape from `namesRef`'s own
+ * `{ resolved, symbol }` rather than folded together: those two functions' parameter
+ * predates this helper, and an adopter who already ejected the ADR-0034 reference
+ * template calls them with exactly this `{ name, symbol }` shape — widening the required
+ * shape to `resolved` would fail to compile in every such copy.
+ */
+export declare function namesConstArg(names: {
+    readonly resolved: ObjectNames;
+    readonly symbol: Code;
+} | undefined, role?: string): {
+    readonly name: string;
+    readonly symbol: Code;
+} | undefined;
+/**
+ * The physical-name expression every §A6 `$table` / view-name site builds: the constant
+ * when the artifact is present, the literal otherwise. No equality guard — but the two
+ * branches earn that two different ways, and both are worth naming:
+ *
+ * - A TABLE literal (`drizzle-schema.ts`, `entity-constants.ts`) comes from
+ *   `dbTable`/`resolveTableName`, which delegate to `primaryRdbSource` — the same lookup
+ *   `resolveObjectNames` uses — so a disagreeing object has already thrown.
+ * - A VIEW literal (`projection-decl.ts`, `view-decl.ts`) comes from `viewName()`
+ *   (`extract-view-spec.ts`), which reads OWN read-only sources only. That cannot diverge:
+ *   a concrete projection may not inherit a source (`ERR_PROJECTION_INHERITED_SOURCE`) and
+ *   the loader allows one own primary, so there is nothing for it to disagree with.
+ *
+ * Either way a reference here is the single spelling, never a lookalike computed twice.
+ *
+ * `role` selects WHICH source — the parameter that did not exist while the artifact held
+ * one name. A write-through entity declares two physical names; passing `replica` is how
+ * the read view stops being a literal in TypeScript and C# alike.
+ */
+export declare function physicalNameExpr(names: {
+    readonly symbol: Code;
+} | undefined, literal: string, obj: MetaObject, role?: string): Code;
+/**
+ * The physical-name alias key for `obj`'s source in `role` — `table`, `view`, `proc`, …
+ *
+ * Derived from the object rather than taken as a parameter, so a call site cannot pass an
+ * alias that disagrees with the source it is describing. Reads the metamodel's own
+ * `PHYSICAL_NAME_ATTR_BY_KIND`; a local switch here would be a second answer to a
+ * question the metamodel already answers, which is the defect class this file exists for.
+ */
+export declare function sourceAliasOf(obj: MetaObject, role?: string): string | undefined;
+/**
+ * A source's `@schema` expression, or undefined when the source declares none.
+ *
+ * Undefined rather than a literal fallback: an absent `@schema` means "the dialect's
+ * default", which a caller expresses by omitting the qualifier entirely — emitting `""`
+ * or `"public"` would be this artifact inventing a name the author never wrote.
+ */
+export declare function sourceSchemaExpr(names: {
+    readonly resolved: ObjectNames;
+    readonly symbol: Code;
+} | undefined, role?: string): Code | undefined;
+/**
+ * An index's database-name expression — the constant when the artifact carries the node,
+ * the literal otherwise.
+ *
+ * The literal arm goes through `resolveIndexName` rather than reading `node.name`, so the
+ * names-off path and the names-on path answer with the same function. That is the whole
+ * lesson of `fdb4118f1`: two spellings of one name agree until they do not.
+ */
+export declare function indexNameExpr(names: {
+    readonly resolved: ObjectNames;
+    readonly symbol: Code;
+} | undefined, node: {
+    readonly name: string;
+    readonly type: string;
+    readonly subType: string;
+}): Code;
+/**
+ * A field's physical-column expression: the constant when the given artifact carries the
+ * field, the literal otherwise.
+ *
+ * The literal arm is a PRESENCE guard — "no artifact in this run", the documented ADR-0034
+ * opt-out — and NOT a divergence guard. It used to carry a second sanctioned case: a TPH
+ * fold emitting a subtype's own columns, which the BASE's artifact never saw. That was
+ * never a presence question; the constant existed the whole time, in the subtype's own
+ * artifact. Callers now resolve the declaring entity's ref before falling back
+ * (`drizzle-schema.ts`), so a miss no longer has a known-good explanation and the fallback
+ * is the last resort it was meant to be.
+ */
+export declare function columnExpr(names: {
+    readonly resolved: ObjectNames;
+    readonly symbol: Code;
+} | undefined, fieldName: string, literal: string): Code;
+//# sourceMappingURL=names.d.ts.map

package/dist/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"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"}