@drzl/validation-core 3.17.0 → 3.20.0

package/dist/index.d.ts

@@ -1,4 +1,99 @@
-import { Relation, Table as Table$1, Column, Analysis } from '@drzl/analyzer';
+import { Table as Table$1, Column, Relation, Analysis } from '@drzl/analyzer';
+
+/**
+ * Which columns carry a nominal brand, and what that brand is called.
+ *
+ * A brand is a type-level marker with no runtime existence at all. Measured on zod 4.4.3,
+ * `z.number().brand('X')` returns the *same object* it was called on, and the parsed value of
+ * `1` is `1`; the same holds for valibot 1.4.2, arktype 2.2.3 and effect 3.x, each of which
+ * hands the value back unchanged. So everything decided here is decided for the benefit of
+ * `tsc`, and nothing in it can be checked by parsing a value.
+ *
+ * That is exactly why the decisions live in one module rather than five. A plan that gives
+ * `posts.authorId` the wrong token emits a schema whose types are confidently wrong in every
+ * generator at once, and no runtime assertion anywhere in this repository would notice.
+ *
+ * ## The token
+ *
+ * `<export name>.<column>`, verbatim: `users.id`, `orgMembers.orgId`. Nothing is transformed,
+ * singularised or re-cased, which is the whole reason to spell it this way. Two Drizzle tables
+ * cannot share an export name inside one schema module and two columns cannot share a name
+ * inside one table, so the token is unique by construction and the question of what to do when
+ * two names collide after a transformation does not arise. It also reads back as the thing the
+ * user wrote:
+ *
+ *     Type 'number & $brand<"posts.id">' is not assignable to type 'number & $brand<"users.id">'
+ *
+ * The transformation question does arise for the exported *alias*, which has to be a TypeScript
+ * identifier. See `aliasesFor`.
+ *
+ * ## What a foreign key gets
+ *
+ * The token of the column it references, not one of its own. `posts.authorId` holds a user's id,
+ * so it is a `users.id`; giving it `posts.authorId` would invent a type nothing else in the
+ * schema produces and the feature would check nothing. That rule is applied transitively and it
+ * beats the column being part of its own table's key, which is what makes a join table keyed on
+ * two foreign keys come out right.
+ */
+
+interface BrandingOptions {
+    enabled?: boolean;
+    /**
+     * Also brand foreign key columns with the brand of the column they reference, so a
+     * `Post.authorId` is a `users.id` rather than a `number`.
+     *
+     * On by default, because it is where nearly all of the value is: a primary key branded alone
+     * only stops you passing a `PostId` to something wanting a `UserId`, while branding the
+     * foreign keys is what makes the ids flowing between tables carry their origin.
+     */
+    foreignKeys?: boolean;
+    /**
+     * Also export a named alias per branded key, e.g. `export type UsersId = ...`.
+     *
+     * On by default. Without one the type is only nameable as an indexed access into the select
+     * type, which works and reads badly.
+     */
+    aliases?: boolean;
+}
+type BrandingOption = boolean | BrandingOptions;
+interface ResolvedBranding {
+    foreignKeys: boolean;
+    aliases: boolean;
+}
+/** One `export type <alias> = ...` line a table's module owns. */
+interface BrandAlias {
+    /** The identifier, e.g. `UsersId`. */
+    alias: string;
+    /** The column it is the type of, e.g. `id`. */
+    column: string;
+    /** The token that column carries, which for an owned alias is `<tsName>.<column>`. */
+    token: string;
+}
+interface BrandPlan {
+    /** The brand token for one column, or nothing when it carries none. */
+    brandOf(tsName: string, columnName: string): string | undefined;
+    /** The aliases this table's module exports. Empty when it owns no brand. */
+    aliasesFor(tsName: string): BrandAlias[];
+    /** Whether anything at all is branded, so a generator can skip its emit path entirely. */
+    readonly any: boolean;
+    /**
+     * What was withheld and why, in the words a user can act on.
+     *
+     * Withholding is the normal outcome for several shapes here and it is silent in the emitted
+     * file, so a run that quietly brands less than the user expects has to say so somewhere.
+     */
+    readonly notes: readonly string[];
+}
+/** `{ foreignKeys, aliases }`, or nothing when branding is off. Off is the default. */
+declare function resolveBranding(opt: BrandingOption | undefined): ResolvedBranding | undefined;
+/**
+ * Build the plan, or nothing when branding is off.
+ *
+ * Every path that cannot answer with certainty returns no brand rather than a guess. A wrong
+ * brand does not fail loudly: it compiles, and it makes two unrelated ids interchangeable or two
+ * related ones incompatible, either of which is worse than the column staying a plain number.
+ */
+declare function buildBrandPlan(tables: Table$1[], opt: BrandingOption | undefined): BrandPlan | undefined;
 
 /**
  * One place that decides what a generated module is called, on disk and in an import.
@@ -285,7 +380,137 @@ declare function parseCheck(expression: string | undefined, name?: string): Pars
 declare function describeSet(set: ColumnSet): string;
 
 /**
- * What a relations-aware nested schema describes, decided once for all four generators.
+ * The facts a generated schema can carry beside itself.
+ *
+ * A validator says what a value must look like. It does not say where the value came from, and a
+ * consumer holding only the schema cannot recover that: `z.string()` is a `text`, a `varchar(40)`,
+ * a `citext` and a `char(3)` alike, and nothing on it says which, nor whether the database fills
+ * it in, nor which columns key the row.
+ *
+ * Every key here had to pass one test: **it says something the emitted schema does not already
+ * say.** Two ways to pass it.
+ *
+ *   the schema never knew it     the SQL type, the primary key, the unique constraints, the
+ *                                dialect, whether the database generates or defaults the value.
+ *
+ *   the schema enforces it and   a declared width and every CHECK are `.refine()` calls, and
+ *   cannot show it               `z.toJSONSchema` drops a refinement in silence. Measured on zod
+ *                                4.4.3: `z.object({ s: z.string().refine(...) })` produces
+ *                                `{ s: { type: 'string' } }` with no warning and no trace. So a
+ *                                JSON Schema built from an emitted module is wrong by omission,
+ *                                and nothing in the document says so.
+ *
+ * Nullability is the counter-example, and its absence is the rule working: `.nullable()` is in the
+ * schema and `anyOf: [..., { type: 'null' }]` is in its JSON Schema, so a `nullable` key would be a
+ * second copy of an answer the consumer already has. Same for the enum values, the integer-ness of
+ * a number and every numeric bound.
+ *
+ * Nothing here is a user comment, because there are none to carry. Measured against drizzle-orm on
+ * both majors: no column, table or builder exposes one, and a `comment` key passed to a column's
+ * options object is dropped before the column is built. See the zod generator's documentation.
+ */
+
+/** What a column adds beside its schema. Every key is optional; an empty object is a real answer. */
+interface ColumnMetaFacts {
+    /** The type as the database declares it: `varchar(255)`, `numeric(10, 2)`, `text[]`. */
+    sqlType?: string;
+    /**
+     * The declared character limit.
+     *
+     * Also the JSON Schema keyword of the same name, which is why it is spelled this way: the
+     * emitted schema enforces the limit inside a `.refine()` closure, `toJSONSchema` drops that, and
+     * this key puts the constraint back in the one spelling every JSON Schema validator enforces.
+     *
+     * On an array column the limit is the *element's*, since that is where the emitted schema
+     * applies it.
+     */
+    maxLength?: number;
+    /** The declared byte limit, which only MySQL's TEXT and BLOB families carry. */
+    maxBytes?: number;
+    /**
+     * The database supplies a value when the write omits one.
+     *
+     * Not recoverable from the schema: a defaulted column and a nullable one are both `.optional()`
+     * on insert, so the wrapper cannot tell them apart, and on select neither leaves a trace.
+     */
+    hasDefault?: true;
+    /** The database computes the value and refuses to be given one. Absent from the write schemas. */
+    generated?: true;
+    /**
+     * The CHECK constraints this field enforces, named as the failure messages name them.
+     *
+     * Not a restatement of the bound beside it. DRZL deliberately folds a CHECK into the column's
+     * own range, so `minimum: 18` in the JSON Schema is indistinguishable from a type bound, and a
+     * set constraint renders as an enum indistinguishable from a declared one. The provenance is
+     * what this carries, along with the constraint name a database error will quote back.
+     */
+    checks?: string[];
+    /** Prose for a reader, from the constraints the schema enforces and cannot show. Opt-in. */
+    description?: string;
+}
+/** What a table's schema adds beside itself. */
+interface TableMetaFacts {
+    /** The SQL table name, which is not the Drizzle export name the schema is named after. */
+    table: string;
+    /**
+     * The SQL schema the table lives in, present only when it names one.
+     *
+     * Beside `table` rather than folded into it. `table` is the bare name in every emitted file
+     * that exists, and two tables in two schemas publish the same one, so without this a consumer
+     * reading the metadata of `reporting.users` cannot tell it from `public.users`. Absent for a
+     * table in the default schema, which is what `pgTable` declares and the only thing it can
+     * declare: Drizzle refuses `pgSchema('public')`.
+     */
+    schema?: string;
+    /** Which database this was analysed from. The same declaration means different things across them. */
+    dialect?: string;
+    /** Which of the three schemas this is. The export name says it; the schema object does not. */
+    mode: string;
+    /** The primary key columns, in order. A per-field flag cannot carry the order or the grouping. */
+    primaryKey?: string[];
+    /**
+     * The unique constraints.
+     *
+     * The one constraint a per-row validator structurally cannot check, which is why
+     * `duplicateFinder` exists at all. Carrying it lets a consumer see what the schema is silent
+     * about rather than assume it is silent because there is nothing to say.
+     */
+    unique?: string[][];
+    /** The relation refuses writes, which today means a materialized view. */
+    readOnly?: true;
+    /** Row-level CHECKs, enforced as object refinements and so invisible for the same reason. */
+    checks?: string[];
+    /**
+     * CHECK constraints the database enforces and this schema does not.
+     *
+     * Either the parser declined the expression, or it understood it and the column's shape has no
+     * way to state it. Both mean the same thing to a caller: the database can reject a row this
+     * schema accepted. Nothing else in the emitted module mentions these at all.
+     */
+    unenforcedChecks?: string[];
+    /** Prose for a reader. Opt-in. */
+    description?: string;
+}
+interface MetaFactOptions {
+    /** Also write a `description`, which is what an OpenAPI reader renders. Off by default. */
+    description?: boolean;
+}
+interface TableMetaOptions extends MetaFactOptions {
+    mode: string;
+    dialect?: string;
+}
+/**
+ * The metadata for one column.
+ *
+ * `table` is needed because a CHECK is declared on the table and only then attributed to a column,
+ * and because whether a constraint is enforced at all depends on the other columns it names.
+ */
+declare function columnMetaFacts(column: Column, table: Table$1, opts?: MetaFactOptions): ColumnMetaFacts;
+/** The metadata for one table's schema, in one mode. */
+declare function tableMetaFacts(table: Table$1, opts: TableMetaOptions): TableMetaFacts;
+
+/**
+ * What a relations-aware nested schema describes, decided once for all five generators.
  *
  * A caller who inserts a parent and its children in one payload, `{ ...user, posts: [...] }`, has
  * nothing to validate it against. Every first-party Drizzle validator emits columns only: measured
@@ -391,7 +616,7 @@ declare function buildNestedPlan(root: Table$1, tables: readonly Table$1[], rela
 /**
  * The comment lines that go above an arm, without their `//`.
  *
- * Shared so the four generators say the same thing about the same relation, and returned unmarked
+ * Shared so the five generators say the same thing about the same relation, and returned unmarked
  * because each of them indents its object literal differently.
  */
 declare function nestedArmNotes(arm: NestedArm): string[];
@@ -418,7 +643,7 @@ declare function nestedNodeColumns<T extends {
  * is worth checking, because it is the half a user can fix before sending anything.
  *
  * The emitted function is plain TypeScript with no reference to any validation library, so all
- * four generators emit the same thing. It is rendered from one place for that reason.
+ * five generators emit the same thing. It is rendered from one place for that reason.
  */
 
 /**
@@ -437,7 +662,7 @@ interface Table {
         columns: string[];
     };
 }
-type ValidationLibrary = 'zod' | 'valibot' | 'arktype' | 'typebox';
+type ValidationLibrary = 'zod' | 'valibot' | 'arktype' | 'typebox' | 'effect';
 interface FormatOptions {
     enabled?: boolean;
     engine?: 'auto' | 'prettier' | 'biome';
@@ -547,6 +772,25 @@ interface ValidationGenerateOptions {
      * what terminates a cycle, since `users -> posts -> users` simply stops here.
      */
     nestedDepth?: number;
+    /**
+     * Give every primary key, and every foreign key pointing at one, a nominal type, so a
+     * `users.id` cannot be passed where a `posts.id` is wanted.
+     *
+     * Type level only. The brand is a marker in the inferred type and nothing at all at runtime:
+     * measured on zod 4.4.3, `.brand()` returns the same schema object it was called on, and the
+     * parsed value of `1` is `1`, so two branded ids holding `1` are still `===`. Nothing about
+     * what a schema accepts or rejects changes here, and nothing is added to the bundle.
+     *
+     * Off by default, because it changes the inferred type of every consumer of the select
+     * schemas. Turning it on will produce errors in code that was passing the wrong id around,
+     * which is the point, but it is a change to existing call sites rather than an addition.
+     *
+     * `{ foreignKeys: false }` brands only the keys themselves. See `BrandingOptions`.
+     *
+     * TypeBox has no brand helper, so the marker there is an intersection carried by
+     * `Type.Unsafe<T>`, which leaves the runtime schema byte-identical. See the docs page.
+     */
+    branded?: BrandingOption;
     emit?: {
         select?: boolean;
         insert?: boolean;
@@ -701,11 +945,11 @@ declare function parsesToADate(expr: string): string;
  * Refusing a user's emoji is the failure mode this avoids, and it is the same rule applied
  * everywhere else here: never reject what the database accepts.
  *
- * All four generators count code points. `@sinclair/typebox` and ArkType cannot say it in their
- * declarative forms, so neither uses `maxLength` or `string <= n`: TypeBox intersects a registered
- * kind onto the field and ArkType puts a Type carrying a narrow there. Both cost something,
- * TypeBox's cap no longer serialising into a JSON Schema, and emitting a number that means a
- * different measurement is not a better trade.
+ * All five generators count code points. `@sinclair/typebox`, ArkType and Effect cannot say it in
+ * their declarative forms, so none of them uses `maxLength` or `string <= n`: TypeBox intersects a
+ * registered kind onto the field, ArkType puts a Type carrying a narrow there, and Effect pipes a
+ * `Schema.filter`. Each costs the same thing, the cap no longer serialising into a JSON Schema, and
+ * emitting a number that means a different measurement is not a better trade.
  *
  * MySQL's TEXT family is a byte budget rather than a character count, carried separately as
  * `maxBytes`. Two measurements on string columns in the same database, verified against a real
@@ -717,18 +961,24 @@ declare function isIntegerColumn(c: Column): boolean;
  * The non-finite doubles the emitted schema must admit beside the column's range, as the analyzer
  * stated them.
  *
- * One reading of two flags, shared so that four generators cannot drift on what they mean, and not
- * a shared *rendering*: the four libraries do not need the same repair. `z.number()` and
+ * One reading of two flags, shared so that five generators cannot drift on what they mean, and not
+ * a shared *rendering*: the five libraries do not need the same repair. `z.number()` and
  * `Type.Number()` refuse `NaN` and both infinities outright, `v.number()` and ArkType's `number`
- * refuse only `NaN`, and any bound at all makes all four refuse the infinities, so what each has to
- * add depends on the library and on whether the column carries a range.
+ * refuse only `NaN`, and any bound at all makes all of those refuse the infinities, so what each
+ * has to add depends on the library and on whether the column carries a range.
+ *
+ * Effect is the one that runs the other way, measured on 3.22.1: `Schema.Number` *accepts* `NaN`
+ * and both infinities, so the flags being false is what makes that generator emit something. It
+ * builds on `Schema.Finite` rather than `Schema.Number` for exactly that reason, and does so
+ * unconditionally rather than leaning on the range, since `Infinity >= 0` is true and a lower bound
+ * alone therefore excludes nothing.
  *
  * Guarded on `tsType` so an enum, a shape or a string can never pick these up from a stale
  * analysis. `@drzl/generator-json-schema` deliberately does not call this at all: JSON has no `NaN`
  * and no `Infinity`, so there is nothing for a JSON Schema to admit.
  *
  * A numeric CHECK folded into one end of the column's range does not take a branch away, in any of
- * the four. That is a decision rather than an oversight, and it is deliberately the loose one: what
+ * the five. That is a decision rather than an oversight, and it is deliberately the loose one: what
  * Postgres does with `CHECK (c >= 0)` and a `NaN` was not measured for this change, and dropping
  * the branch on a column that carries a CHECK would put back, for that column, exactly the
  * read-path failure this exists to remove.
@@ -780,4 +1030,4 @@ declare function selectColumns(table: Table): Column[];
  */
 declare function formatCode(code: string, filePath: string, fmt?: FormatOptions): Promise<any>;
 
-export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, MAX_NESTED_DEPTH, NAME_MODES, NESTED_PREFIX, type NameMode, type NestedArm, type NestedMode, type NestedNode, type ParsedCheck, type ResolvedAffix, type RowCheck, type Table, type TableCase, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, buildNestedPlan, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveConfiguredImport, resolveNestedDepth, schemaName, selectColumns, typeName, updateColumns, validateAffix };
+export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, type BrandAlias, type BrandPlan, type BrandingOption, type BrandingOptions, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnMetaFacts, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, MAX_NESTED_DEPTH, type MetaFactOptions, NAME_MODES, NESTED_PREFIX, type NameMode, type NestedArm, type NestedMode, type NestedNode, type ParsedCheck, type ResolvedAffix, type ResolvedBranding, type RowCheck, type Table, type TableCase, type TableMetaFacts, type TableMetaOptions, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, buildBrandPlan, buildNestedPlan, columnMetaFacts, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveBranding, resolveConfiguredImport, resolveNestedDepth, schemaName, selectColumns, tableMetaFacts, typeName, updateColumns, validateAffix };