@drzl/analyzer 1.18.0 → 1.21.0

package/dist/index.d.ts

@@ -8,28 +8,93 @@ interface Issue {
     level: 'info' | 'warn' | 'error';
     message: string;
     hint?: string;
+    /**
+     * Where the issue is, as `table` or `table.column`.
+     *
+     * Declared since this interface existed and set by nothing, so every consumer wanting to group
+     * warnings by table had to read the names back out of the English in `message`. `drzl doctor` is
+     * the first such consumer and a report built by regex over prose breaks the first time a message
+     * is reworded, so the names are stated here instead.
+     *
+     * Still optional: an issue about the schema as a whole, such as an unidentifiable dialect, is
+     * about no table and says so by omitting this.
+     */
     path?: string;
 }
+/**
+ * Why a column has no type, where "nobody has modelled it" is not the answer.
+ *
+ * The distinction exists because it changes the advice. A column class this file has no arm for is
+ * a gap someone can close, and the warning tells its author to say so. A Gel temporal column is
+ * not: the value is an instance of a class from the `gel` package, DRZL cannot import that package,
+ * and no generator could emit a check for it even knowing the name. Leaving it `unknown` is the
+ * measured answer rather than an omission, and its warning should say that instead of asking for a
+ * bug report that is already closed.
+ */
+type UnnameableReason = 'gel-temporal';
 interface ColumnRef {
     table: string;
     column: string;
 }
+/**
+ * A link between two tables, each end named by `qualifiedTableName`.
+ *
+ * Qualified rather than bare, because a bare database name identifies a table only while no two
+ * SQL schemas hold it: `to: 'users'` cannot say whether it means `public.users` or
+ * `reporting.users`, and every consumer resolves these strings back to a table object. A table in
+ * the default schema has no prefix, so nothing about a single-schema analysis changes.
+ */
 interface Relation {
     kind: 'one' | 'many' | 'manyToMany';
+    /** Qualified table name: `users`, or `reporting.users`. */
     from: string;
+    /** Qualified table name: `users`, or `reporting.users`. */
     to: string;
+    /** Qualified name of the join table, for m2m. */
     via?: string;
 }
 interface Column {
     name: string;
     tsType: string;
+    /**
+     * A coarse label for the column's kind, not its type.
+     *
+     * `varchar`, `char` and `text` are all `TEXT` here, deliberately: two consumers read this and
+     * both ask coarse questions. `isIntegerColumn` asks whether a number is whole, and
+     * `comparisonWire` in `@drzl/validation-core` asks whether a string wire carries decimal text
+     * the database compares numerically, which is `NUMERIC` (every decimal family) and `BIGINT`
+     * (the v1 string mode). Use `sqlType` for the question this name suggests it answers.
+     */
     dbType: string;
+    /**
+     * The column's type as the database declares it, from Drizzle's own `getSQLType()`:
+     * `varchar(255)`, `numeric(10, 2)`, `timestamp with time zone`, `text[]`, or an enum's type
+     * name.
+     *
+     * The one fact about a column that no validator schema can carry, and the one every other fact
+     * here is a consequence of. A generator that emits metadata beside its schemas has nothing else
+     * to put in it: `dbType` is a label rather than a type, and the declared width lives in
+     * `maxLength`, the precision in `min`/`max`, and neither of those says which type produced it.
+     *
+     * The two Drizzle majors disagree about an array and are reconciled here, measured rather than
+     * assumed: 0.4x wraps the column in a `PgArray` whose own answer is already `text[]`, while v1
+     * leaves the class alone and raises `dimensions`, so its answer is the bare `text`. The suffix
+     * is added from `arrayDimensions` when the type does not already carry one, so a consumer
+     * cannot tell which major produced its metadata.
+     *
+     * Absent where the builder has no `getSQLType` or it throws. Nothing is guessed from the class
+     * name: an invented type string reads exactly like a real one, and there is no way for a
+     * consumer to tell them apart.
+     */
+    sqlType?: string;
     nullable: boolean;
     hasDefault: boolean;
     isGenerated: boolean;
     defaultExpression?: string;
     references?: {
         table: string;
+        /** SQL schema of the referenced table, absent for the default one. See `ForeignKey`. */
+        schema?: string;
         column: string;
         onDelete?: string;
         onUpdate?: string;
@@ -48,8 +113,16 @@ interface Column {
      *
      * Strings rather than numbers because a 64 bit bound is not representable as a JS number:
      * `9223372036854775807` rounds to `9223372036854775808` the moment it becomes one, so a
-     * numeric field here would silently emit a wrong bound. Absent for floats and for `numeric`,
-     * which have no integer range.
+     * numeric field here would silently emit a wrong bound. A 20 digit `numeric(20,0)` bound is
+     * further past that again.
+     *
+     * Not an integer range, despite the name this field used to be described by. An inexact column
+     * carries one too: a `real` is bounded by the magnitude the database refuses past, and a
+     * `numeric(10,2)` by the width its own declaration states. `integer` says which kind it is, and
+     * saying it is what stops a bounded float schema refusing 1.5.
+     *
+     * Absent where nothing declares a bound: an 8 byte float holds every finite JS number, and a
+     * `numeric` with no precision holds arbitrary precision.
      */
     min?: string;
     max?: string;
@@ -62,16 +135,57 @@ interface Column {
      * generators fall back to the old inference there.
      */
     integer?: boolean;
+    /**
+     * Whether the column stores and returns `NaN`, and whether it does the same for an infinity.
+     *
+     * A range cannot say this. `>=`/`<=` refuses `Infinity` whatever the two numbers are, and `NaN`
+     * compares false against both ends, so a bounded float column described by its range alone
+     * refused three values Postgres stores in it and hands back on SELECT. That is a read-path
+     * defect: every read of such a row fails validation on a column behaving exactly as documented.
+     * The generators render these as a union beside the range rather than as a wider range.
+     *
+     * Measured against PostgreSQL 18.3 through PGlite, on the bound-parameter path a validator
+     * guards. `real` and `double precision` return all three unchanged. An unconstrained `numeric`
+     * does too, but a `numeric(10,2)` refuses either infinity with `22003 numeric field overflow`
+     * while still taking `NaN`, and `integer`/`bigint` refuse all three.
+     *
+     * So `numeric` in `{ mode: 'number' }` answers each of the two separately: `allowsNaN` at any
+     * width, and `allowsInfinity` only where the declaration carries no precision. That used to be a
+     * flat `false`, and the recorded reason was that nothing here read a column's precision or scale,
+     * so the two declarations were indistinguishable and the narrower answer was the safer one.
+     * `declaredDecimalRange` reads both numbers now, the two are distinguishable, and each says what
+     * its own server does.
+     *
+     * Postgres and Gel. MySQL refuses all three on a `float`/`double`, and on a `decimal` refuses
+     * them outright rather than storing `0.00`: measured on MySQL 8.4.11 in `STRICT_TRANS_TABLES`,
+     * all three answer `Incorrect decimal value`. SQLite returns both infinities and silently turns
+     * `NaN` into NULL, which is real and is filed on its own: a column needs both halves of that
+     * answer or none.
+     *
+     * Gel joined on a measurement of its own rather than on being Postgres-backed: a live Gel 7.1
+     * stored `nan`, `inf` and `-inf` in both `std::float32` and `std::float64` and handed all three
+     * back unchanged, through a cast and through a stored property.
+     *
+     * Absent on every other column, including the string mode of `numeric`, which already carries the
+     * same fact as a pattern; see `COLUMN_FORMATS.numeric` in `@drzl/validation-core`.
+     */
+    allowsNaN?: boolean;
+    allowsInfinity?: boolean;
     /**
      * A string column whose contents have a shape the database enforces.
      *
-     * Only formats checked against Postgres itself appear here, and the list is short because most
+     * Only formats checked against a real server appear here, and the list is short because most
      * candidates failed: Postgres reads `'today'` and `'January 8, 1999'` as dates, pads
      * `'2020-01-01'` into a macaddr, and accepts `'10.1/16'` as an inet. A check for any of those
      * would reject input the database accepts, and turning away valid data is worse than not
      * checking at all. See `COLUMN_FORMATS` in `@drzl/validation-core`.
+     *
+     * Two of the keys name a dialect, because the same column has two different answers: a
+     * `bigint({ mode: 'string' })` is parsed by Postgres as an integer literal, `'0x1f'` and
+     * `'1_000'` included, and by MySQL as a decimal number it then rounds, so `'12.5'` is a row on
+     * one server and an error on the other.
      */
-    format?: 'uuid' | 'numeric';
+    format?: 'uuid' | 'numeric' | 'pgBigint' | 'mysqlBigint';
     /**
      * The column's default, when it is a literal a schema can reproduce.
      *
@@ -228,6 +342,17 @@ interface ForeignKey {
     name?: string;
     columns: string[];
     foreignTable: string;
+    /**
+     * The SQL schema the referenced table lives in, absent for the default one, exactly as
+     * `Table.schema` is.
+     *
+     * `foreignTable` is a bare database name and Postgres lets two schemas hold the same one, so a
+     * key pointing at `reporting.users` recorded the identical string a key pointing at
+     * `public.users` records. Every consumer that resolves a key back to a table object did so by
+     * that string, and therefore resolved to whichever of the two it saw first. Use
+     * `qualifiedForeignTable` rather than reading the two fields apart.
+     */
+    foreignSchema?: string;
     foreignColumns: string[];
     onDelete?: string;
     onUpdate?: string;
@@ -235,6 +360,15 @@ interface ForeignKey {
 interface Table {
     name: string;
     tsName: string;
+    /**
+     * The SQL schema the table was declared in, from `pgSchema('reporting').table(...)` and the
+     * MySQL and SingleStore equivalents. Absent for a table declared with plain `pgTable`, which is
+     * the only spelling of the default schema there is: Drizzle refuses `pgSchema('public')`
+     * outright, with "Postgres is using public schema by default".
+     *
+     * `name` stays bare, so two tables in two schemas share one. `qualifiedTableName` is what tells
+     * them apart, and is what every name-addressed surface in DRZL matches against.
+     */
     schema?: string;
     columns: Column[];
     primaryKey?: Key;
@@ -254,6 +388,28 @@ interface Enum {
     name: string;
     values: string[];
 }
+/**
+ * The one name that identifies a table across every SQL schema in an analysis.
+ *
+ * `reporting.users` where the table names a schema, and the bare `users` where it does not. The
+ * bare form for the default schema is deliberate and is what makes this safe to reach for
+ * everywhere: on a schema module that never calls `pgSchema`, and that is nearly all of them, this
+ * returns exactly `table.name`, so every file name, every export, every config pattern and every
+ * emitted path is byte for byte what it was.
+ *
+ * `public.users` is not produced here. Drizzle refuses `pgSchema('public')`, so no analysis can
+ * ever carry `schema: 'public'`, and a table with no schema *is* the public one. `public.` exists
+ * only as a spelling a config may use, resolved by `@drzl/cli`.
+ */
+declare function qualifiedTableName(table: {
+    name: string;
+    schema?: string;
+}): string;
+/** The same name, for the far end of a foreign key. */
+declare function qualifiedForeignTable(fk: {
+    foreignTable: string;
+    foreignSchema?: string;
+}): string;
 interface Analysis {
     drizzleVersion?: string;
     dialect: Dialect;
@@ -325,7 +481,14 @@ declare function isRelationsV2(val: any): boolean;
 declare function readRelationsV2(val: any, issues?: Issue[]): Relation[];
 declare class SchemaAnalyzer {
     private readonly schemaPath;
-    constructor(schemaPath: string);
+    /**
+     * One path or several. The plural exists for drizzle-kit interop: kit's `schema` key names
+     * files in the plural (arrays, globs), and the commonest multi-file layout is a directory of
+     * one file per table with no barrel, so there is no single module to point at. Entries are
+     * concrete files, never globs; expansion is the caller's job, so this class's contract stays
+     * "load exactly these modules and read their exports as one schema".
+     */
+    constructor(schemaPath: string | readonly string[]);
     private getSymbol;
     /**
      * Drizzle keys the Columns object by TypeScript property name, but every other piece of
@@ -415,6 +578,31 @@ declare class SchemaAnalyzer {
      * promise a precision that cannot survive the round trip.
      */
     private static readonly INT_RANGES;
+    /**
+     * The same widths with `{ unsigned: true }` set, which is the half the table above cannot see.
+     *
+     * On 0.4x the flag moves no class name: `int('x', { unsigned: true })` still builds a
+     * `MySqlInt`, and only `config.unsigned` and the ` unsigned` suffix on `getSQLType()` record
+     * the difference, measured off real 0.45.2 columns. So the table above answered every unsigned
+     * width with its signed range, and the emitted select schema refused every stored value in the
+     * upper half of the column: an `int unsigned` holding 4294967295 failed validation on a row the
+     * database returned, and the same one width up meant `bigint unsigned` refused
+     * 18446744073709551615n.
+     *
+     * The ceilings are the type's, verified against a live MySQL 8.4.11: 255, 65535, 16777215 and
+     * 4294967295 store and return, -1 and each ceiling plus one are refused with
+     * ER_WARN_DATA_OUT_OF_RANGE. The bigint pair keeps the two modes apart for the reason the
+     * signed pair above does: number mode tops out at the safe-integer bound the wire imposes,
+     * bigint mode at the column's own 2^64-1, which a bigint can spell. SingleStore is MySQL wire
+     * compatible, ships the same builders with the same `config.unsigned`, and v1 states the same
+     * `uintN` semantics for it, measured off real rc.4 columns; the entries keep the majors in
+     * agreement, which is what the cross-major diff in `scripts/verify-packed.sh` holds together.
+     *
+     * Keyed by class exactly like `INT_RANGES`, and consulted only when `config.unsigned` is
+     * `true`, so no Postgres or SQLite column can ever reach it: neither dialect has an unsigned
+     * spelling, neither builder accepts the flag, and no class of theirs is named here.
+     */
+    private static readonly UNSIGNED_INT_RANGES;
     /**
      * The numeric column classes that are not exact, and the magnitude each one can really hold.
      *
@@ -451,6 +639,52 @@ declare class SchemaAnalyzer {
      * `number double` on drizzle v1, which is where these pairings come from.
      */
     private static readonly INEXACT_RANGES;
+    /**
+     * The number columns whose server has an answer about a non-finite double, and what it is.
+     *
+     * Three states rather than two, and the third is the reason this table has a `false` half at all.
+     * A column present here with `true` stores the value and hands it back, so a schema refusing it
+     * refuses rows the column returns. A column present with `false` is one the server was asked
+     * about and refused, so a schema accepting it promises what the server will not take. A column
+     * *absent* is one nobody has measured, and the generators leave whatever their library does alone
+     * rather than guessing; `nonFiniteAccepted` and `nonFiniteRefused` in `@drzl/validation-core` are
+     * the two readings of that.
+     *
+     * The class-name half of what `describeV1Column` reads off the codec, and the two must agree: a
+     * fact stated on one path and not the other is a schema that changes when the user upgrades
+     * drizzle, which the cross-major diff in `verify-packed.sh` fails on. Every class name here is the
+     * same on both majors, read off real columns on 0.45.2 and on 1.0.0-rc.4, so this table also
+     * answers for a v1 column and the two answers are identical rather than merely compatible.
+     * non-finite-numbers.spec.ts asserts that agreement through the real analyzer.
+     *
+     * Postgres and Gel store all three. Gel joined on a measurement of its own rather than on being
+     * Postgres-backed: a live Gel 7.1 stored `nan`, `inf` and `-inf` in both `std::float32` and
+     * `std::float64` and handed all three back, through a cast and again through a stored property.
+     * Without them every row of such a column failed validation.
+     *
+     * MySQL and SingleStore refuse all three, and that used to be left unstated on the reasoning that
+     * a column stating nothing costs nothing. It cost two libraries: `v.number()` and ArkType's
+     * `number` take both infinities where `z.number()` and `Type.Number()` refuse them, so an
+     * unbounded `double` or `real` accepted a value the server answers `ER_WARN_DATA_OUT_OF_RANGE`
+     * for. Measured on MySQL 8.4.11 in `STRICT_TRANS_TABLES`, on the binary prepared path, which is
+     * the one that puts the real IEEE double on the wire: `float`, `double` and `real` refuse
+     * `Infinity`, `-Infinity` and `NaN` alike, while `double` and `real` store 1e300 and
+     * 3.4028235e38 unchanged. SingleStore is MySQL wire-compatible and unmeasured, and takes MySQL's
+     * answer here exactly as it already takes MySQL's float32 bound in `INEXACT_RANGES`.
+     *
+     * No SQLite class belongs here in either direction. A real SQLite 3.53.4 stores both infinities in
+     * a `real` and hands them back, and silently turns `NaN` into NULL, so it is neither the Postgres
+     * answer nor the MySQL one; it is filed on its own and a column needs both halves of it or none.
+     *
+     * The decimal families are absent too. `PgNumeric` is a string whose pattern already accepts `NaN`
+     * and `Infinity`. `PgNumericNumber` is a per-column question this table cannot ask: it takes `NaN`
+     * at any width and an infinity only where no precision is declared, and `columnConstraints`
+     * answers it beside the bound that decides it. MySQL's `decimal` is absent because the two client
+     * paths disagree: on the binary prepared path MySQL 8.4.11 silently stored `0.00` for all three,
+     * where the text path answers `Incorrect decimal value`, and "refuses" is only half true of a
+     * column that accepted the row.
+     */
+    private static readonly NON_FINITE_BY_CLASS;
     /**
      * Constraints the column definition already carries, which the analysis used to throw away.
      *
@@ -463,4 +697,4 @@ declare class SchemaAnalyzer {
     analyze(opts?: AnalyzeOptions): Promise<Analysis>;
 }
 
-export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, readRelationsV2 };
+export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, type UnnameableReason, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, qualifiedForeignTable, qualifiedTableName, readRelationsV2 };