uql-orm 0.65.1 → 0.67.0

package/dist/util/field.util.d.ts

@@ -1,25 +1,4 @@
-import type { EntityMeta, FieldOptions } from '../type/index.js';
-/**
- * The kind of column a field lands on, which is what decides whether an option means anything on it:
- * `length` is a string's, `precision` a number's, `dimensions` a vector's. Named in the words an
- * error reports it in, so there is no second table of labels to keep in step.
- */
-export type ColumnFamily = 'string' | 'numeric' | 'boolean' | 'date' | 'json' | 'blob' | 'vector';
-/**
- * The runtime half of the column-type unions in `type/entity.ts`, which TypeScript erases. Each list
- * is checked against its own union, so a type cannot be filed under the wrong family, and
- * {@link UnplacedColumnType} refuses to compile if a new one is filed under none. Nothing here
- * restates the unions: the compile-time side of the same question reads them directly.
- */
-export declare const COLUMN_TYPES_BY_FAMILY: {
-    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real"];
-    readonly string: readonly ["char", "varchar", "text", "uuid"];
-    readonly date: readonly ["date", "time", "datetime", "timestamp", "timestamptz"];
-    readonly json: readonly ["json", "jsonb"];
-    readonly blob: readonly ["blob", "bytea"];
-    readonly boolean: readonly ["bool", "boolean"];
-    readonly vector: readonly ["vector", "halfvec", "sparsevec"];
-};
+import { type ColumnFamily, type EntityMeta, type FieldOptions } from '../type/index.js';
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
@@ -38,22 +17,11 @@ export declare function isInlinedExpression<F extends FieldOptions>(field: F): f
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
  */
 export declare function isDatabaseWritten(field: FieldOptions): boolean;
-/**
- * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
- * and the only one that may state `PRIMARY KEY` in its own column definition.
- *
- * One column of a composite is a value the caller supplies, and the table states the key over every
- * column at once. Asked in one place because the two schema paths - the AST that builds a
- * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
- * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
- */
+/** Whether the field is the whole primary key, the only kind a serial stands for and a column may declare. */
 export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
- * Whether the database generates this column's value.
- *
- * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
- * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
- * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
- * that states its width is still a generated key; one that states how it is filled is not.
+ * Whether the database generates this column's value: a numeric key nothing else fills. `onInsert` fills
+ * it from the application and `references` from the row it shares its key with; a `columnType` only
+ * states its width. The one answer the create statement and the diff both read.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;

package/dist/util/field.util.js

@@ -1,33 +1,5 @@
+import { COLUMN_TYPES, } from '../type/index.js';
 import { getKeys } from './object.util.js';
-/**
- * The runtime half of the column-type unions in `type/entity.ts`, which TypeScript erases. Each list
- * is checked against its own union, so a type cannot be filed under the wrong family, and
- * {@link UnplacedColumnType} refuses to compile if a new one is filed under none. Nothing here
- * restates the unions: the compile-time side of the same question reads them directly.
- */
-export const COLUMN_TYPES_BY_FAMILY = {
-    numeric: [
-        'int',
-        'integer',
-        'tinyint',
-        'smallint',
-        'bigint',
-        'float',
-        'float4',
-        'float8',
-        'double',
-        'double precision',
-        'decimal',
-        'numeric',
-        'real',
-    ],
-    string: ['char', 'varchar', 'text', 'uuid'],
-    date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
-    json: ['json', 'jsonb'],
-    blob: ['blob', 'bytea'],
-    boolean: ['bool', 'boolean'],
-    vector: ['vector', 'halfvec', 'sparsevec'],
-};
 // Constructors and type strings in one map: a logical type is either, and every caller asks the same
 // question of both.
 const FAMILY_OF = new Map([
@@ -36,12 +8,8 @@ const FAMILY_OF = new Map([
     [BigInt, 'numeric'],
     [Boolean, 'boolean'],
     [Date, 'date'],
+    ...getKeys(COLUMN_TYPES).flatMap((family) => COLUMN_TYPES[family].map((type) => [type, family])),
 ]);
-for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
-    for (const columnType of COLUMN_TYPES_BY_FAMILY[family]) {
-        FAMILY_OF.set(columnType, family);
-    }
-}
 /** The family of a logical field type, or `undefined` where it names none. */
 export function columnFamily(type) {
     return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
@@ -80,28 +48,17 @@ export function isInlinedExpression(field) {
 export function isDatabaseWritten(field) {
     return field.computed !== undefined;
 }
-/**
- * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
- * and the only one that may state `PRIMARY KEY` in its own column definition.
- *
- * One column of a composite is a value the caller supplies, and the table states the key over every
- * column at once. Asked in one place because the two schema paths - the AST that builds a
- * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
- * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
- */
+/** Whether the field is the whole primary key, the only kind a serial stands for and a column may declare. */
 export function isSoleIdField(meta, field) {
     return field.isId === true && meta.ids.length === 1;
 }
 /**
- * Whether the database generates this column's value.
- *
- * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
- * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
- * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
- * that states its width is still a generated key; one that states how it is filled is not.
+ * Whether the database generates this column's value: a numeric key nothing else fills. `onInsert` fills
+ * it from the application and `references` from the row it shares its key with; a `columnType` only
+ * states its width. The one answer the create statement and the diff both read.
  */
 export function isAutoIncrement(field, isPrimaryKey) {
     if (field.autoIncrement !== undefined)
         return field.autoIncrement;
-    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert;
+    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
 }

package/dist/util/fieldOption.util.d.ts

@@ -1,5 +1,4 @@
-import type { BlobColumnType, BooleanColumnType, DateColumnType, FieldOptions, JsonColumnType, NumericColumnType, QueryRaw, StringColumnType, VectorColumnType } from '../type/index.js';
-import { type ColumnFamily } from './field.util.js';
+import type { ColumnFamily, FamilyOf, FieldOptions, QueryRaw } from '../type/index.js';
 /**
  * The column family each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
@@ -54,13 +53,11 @@ type GeneratedWrite = (typeof GENERATED_WRITES)[number];
  */
 export declare function fieldOptionConflict(opts: FieldOptions): string | undefined;
 /** The family the options put the column in; every family where they name no type to put it in. */
-type FamilyOf<O> = O extends {
+type OptionsFamily<O> = O extends {
     readonly columnType: infer C;
-} ? FamilyOfType<C> : O extends {
+} ? FamilyOf<C> : O extends {
     readonly type: infer T;
-} ? FamilyOfType<T> : ColumnFamily;
-/** Read off the column-type unions themselves, which is what `COLUMN_TYPES_BY_FAMILY` is checked against. */
-type FamilyOfType<T> = T extends NumericColumnType | NumberConstructor | BigIntConstructor ? 'numeric' : T extends StringColumnType | StringConstructor ? 'string' : T extends VectorColumnType ? 'vector' : T extends JsonColumnType ? 'json' : T extends DateColumnType | DateConstructor ? 'date' : T extends BooleanColumnType | BooleanConstructor ? 'boolean' : T extends BlobColumnType ? 'blob' : ColumnFamily;
+} ? FamilyOf<T> : ColumnFamily;
 /** What the field's own values leave unread, matching {@link deadOn} line for line. */
 type DeadOptions<O> = (O extends {
     readonly stored: true;
@@ -74,16 +71,11 @@ type DeadOptions<O> = (O extends {
 } ? 'onUpdate' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
 type Offending<O> = {
-    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends FamilyOf<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
+    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
 }[Given<O>];
 /**
- * Maps every option `O` states but cannot use to `never`, the way `RejectUnknown` maps a typo'd one,
- * so an option that would be silently ignored reads as the same compile error. Resolves to `unknown`
- * - an inert intersection member - when there are none.
- *
- * `@Id` adds `{ nullable?: false }` of its own rather than passing the `isId` it stamps on, which
- * would have to reach `O` as an intersection - and a non-naked `O` in its own constraint stops it
- * inferring from the options at all.
+ * Every option `O` states but cannot use, mapped to `never`, so one that would be ignored does not compile.
+ * `@Id` states `{ nullable?: false }` itself, since `O` has to stay naked to be inferred.
  */
 export type RejectIncompatible<O> = [Offending<O>] extends [never] ? unknown : Record<Offending<O> & string, never>;
 export {};

package/dist/util/fieldOption.util.js

@@ -83,7 +83,7 @@ function deadOn(opts, key) {
 export function fieldOptionConflict(opts) {
     const family = columnFamily(opts.columnType ?? opts.type);
     // Walked in table order, not in the order the field happened to be written, so a field with two
-    // conflicts always reports the same one. An option no rule knows is a typo, which `RejectUnknown`
+    // conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check
     // reports where it can still be spelled right.
     for (const key of getKeys(FIELD_OPTION_FAMILY)) {
         const applies = FIELD_OPTION_FAMILY[key];

package/dist/util/filters.util.d.ts

@@ -1,10 +1,7 @@
 import type { QueryOptions } from '../type/index.js';
 /**
- * Query options that include soft-deleted rows in the result - disables the built-in `softDelete`
- * filter for this call. This is a server-side option: filter bypass is intentionally not serialized
- * over the wire. To list *only* trashed rows with a serializable query, constrain the field instead,
- * e.g. `querier.findMany(User, { $where: { deletedAt: { $ne: null } } })` - the filter steps aside
- * for any key you set in `$where`.
+ * Options including soft-deleted rows, server-side only. To list only deleted ones over the wire, filter
+ * the field: `{ $where: { deletedAt: { $ne: null } } }`.
  * @example `querier.findMany(User, {}, withDeleted())`
  */
 export declare function withDeleted(): QueryOptions;

package/dist/util/filters.util.js

@@ -1,9 +1,6 @@
 /**
- * Query options that include soft-deleted rows in the result - disables the built-in `softDelete`
- * filter for this call. This is a server-side option: filter bypass is intentionally not serialized
- * over the wire. To list *only* trashed rows with a serializable query, constrain the field instead,
- * e.g. `querier.findMany(User, { $where: { deletedAt: { $ne: null } } })` - the filter steps aside
- * for any key you set in `$where`.
+ * Options including soft-deleted rows, server-side only. To list only deleted ones over the wire, filter
+ * the field: `{ $where: { deletedAt: { $ne: null } } }`.
  * @example `querier.findMany(User, {}, withDeleted())`
  */
 export function withDeleted() {

package/dist/util/logger.d.ts

@@ -63,11 +63,7 @@ export interface ErrorEmittingPool {
     on(event: 'error', listener: (err: Error) => void): unknown;
 }
 /**
- * Attaches an error listener to a connection pool so a dropped connection is logged instead of left
- * unhandled - which crashes the process for drivers that don't guard against it themselves
- * (node-postgres, `mssql`), or is silently swallowed by those that install a no-op of their own
- * (`mariadb`). Reported through the pool's own logger when it has one, and through the default one
- * otherwise: never dropped, whatever levels were configured, since a swallowed pool error is exactly
- * the failure this guards against.
+ * Logs a pool's dropped connection, which some drivers would otherwise crash the process on, through
+ * the pool's logger or the default one, whatever levels were configured.
  */
 export declare function attachPoolErrorHandler(pool: ErrorEmittingPool, message: string, logging?: LoggingOptions): void;

package/dist/util/logger.js

@@ -155,12 +155,8 @@ export function queryLoggerFor(extra) {
     return wrapper;
 }
 /**
- * Attaches an error listener to a connection pool so a dropped connection is logged instead of left
- * unhandled - which crashes the process for drivers that don't guard against it themselves
- * (node-postgres, `mssql`), or is silently swallowed by those that install a no-op of their own
- * (`mariadb`). Reported through the pool's own logger when it has one, and through the default one
- * otherwise: never dropped, whatever levels were configured, since a swallowed pool error is exactly
- * the failure this guards against.
+ * Logs a pool's dropped connection, which some drivers would otherwise crash the process on, through
+ * the pool's logger or the default one, whatever levels were configured.
  */
 export function attachPoolErrorHandler(pool, message, logging) {
     const logger = new LoggerWrapper(isOwnLogger(logging) ? logging : true);

package/dist/util/object.util.d.ts

@@ -11,17 +11,13 @@ export declare function hasKeys<T>(obj: T): obj is NonNullable<T>;
 export declare function someKey<T extends object>(obj: T, pred: (key: keyof T & string) => boolean): boolean;
 /** Whether any enumerable value of `obj` satisfies `pred`, short-circuiting like {@link someKey}. */
 export declare function someValue(obj: object, pred: (value: unknown) => boolean): boolean;
-/**
- * Whether `value` is a non-empty object whose keys are query/update operators (`$eq`, `$push`, ...).
- * The single source of this test: the SQL dialects, the MongoDB dialect and the `$elemMatch` walker
- * all classify operator objects with it, and they used to disagree about `{}`.
- */
+/** Whether `value` is a non-empty object with an operator key (`$eq`, `$push`...): the one test every dialect classifies with. */
 export declare function isOperatorObject(value: unknown): value is Record<string, unknown>;
 /** Whether every key of the non-empty object `value` is an operator (no plain field names mixed in). */
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
 /** Whether `value` is an object that is not an array, whose keys can be read. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
-export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
+export declare function getKeys<T extends object>(obj: T | null | undefined): (keyof T & string)[];
 /** The entries of `record` holding a value: a key declared but left `undefined` is no entry at all. */
 export declare function definedEntries<K extends string, V>(record: Partial<Record<K, V>>): [K, V][];
 /**

package/dist/util/object.util.js

@@ -37,11 +37,7 @@ export function someValue(obj, pred) {
     return someKey(obj, (key) => pred(obj[key]));
 }
 const isOperatorKey = (key) => key.startsWith('$');
-/**
- * Whether `value` is a non-empty object whose keys are query/update operators (`$eq`, `$push`, ...).
- * The single source of this test: the SQL dialects, the MongoDB dialect and the `$elemMatch` walker
- * all classify operator objects with it, and they used to disagree about `{}`.
- */
+/** Whether `value` is a non-empty object with an operator key (`$eq`, `$push`...): the one test every dialect classifies with. */
 export function isOperatorObject(value) {
     return hasKeys(value) && !Array.isArray(value) && someKey(value, isOperatorKey);
 }

package/dist/util/raw.d.ts

@@ -1,28 +1,8 @@
 import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type RefMap, type Type } from '../type/index.js';
 /**
- * Create a raw SQL expression.
- *
- * As a tagged template the literal text is emitted as written and every interpolation is resolved by
- * what it is, so a value cannot become SQL whatever it holds:
- *
- * | Interpolated        | Becomes                                |
- * | :------------------ | :------------------------------------- |
- * | any value           | a bound parameter; in DDL, its literal |
- * | a {@link ColumnRef} | its column, escaped and qualified      |
- * | a {@link QueryRaw}  | that fragment, in place                |
- *
- * ```ts
- * const user = refs(User);
- * raw`GREATEST(0, ${user.creditsAllowance} - ${amount})`
- * raw`CONCAT(${user.firstName}, ' ', ${user.lastName})`
- * raw`LOG10(${points})`.as('score')
- * ```
- *
- * The callback form remains for SQL a template cannot express, such as a sub-query generated through
- * `dialect.find(...)`.
- *
- * **⚠️ Security:** the tag is safe because it binds; a callback is not, since it emits whatever it
- * writes, so never build one from user input. Inside a callback, bind with `ctx.addValue()`.
+ * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
+ * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
+ * never build one from user input. See the Raw SQL guide.
  */
 export declare function raw(strings: TemplateStringsArray, ...values: readonly unknown[]): QueryRaw;
 export declare function raw(value: QueryRawFn): QueryRaw;

package/dist/util/relationQuery.util.d.ts

@@ -15,22 +15,11 @@ export type ParentJoin = {
     readonly joined: string;
 };
 /**
- * How a relation joins to its parent: `parent` is a column of the parent's own table, `joined` the
- * column matching it on the table the relation reads - a junction's own column for a relation that
- * goes through one, the child's foreign key otherwise.
- *
- * The two are spelled from opposite ends of `references` (`local` names a column of the table the
- * relation is declared on, `foreign` a column of the other one), and getting that backwards reads a
- * real column of the wrong table, so it is answered once here. One pair per key of the parent.
+ * How a relation joins its parent, one pair per key: `parent` a column of the parent's table, `joined` the
+ * matching one on the table the relation reads, a junction's or the child's.
  */
 export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | 'through'>, parentKeyCount: number): ParentJoin[];
-/**
- * The junction columns holding the target's key, the other half of {@link parentJoins}.
- *
- * `parentKeyCount` is required: the target's columns start after the parent's, so guessing the
- * boundary returned the parent's *second* column as the target's - a real column of the wrong side,
- * which is the mistake this module exists to prevent.
- */
+/** The junction columns holding the target's key, after the parent's `parentKeyCount` ones. */
 export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one

package/dist/util/relationQuery.util.js

@@ -14,13 +14,8 @@ export function isToManyRelation(relation) {
     return relation.cardinality === '1m' || relation.cardinality === 'mm';
 }
 /**
- * How a relation joins to its parent: `parent` is a column of the parent's own table, `joined` the
- * column matching it on the table the relation reads - a junction's own column for a relation that
- * goes through one, the child's foreign key otherwise.
- *
- * The two are spelled from opposite ends of `references` (`local` names a column of the table the
- * relation is declared on, `foreign` a column of the other one), and getting that backwards reads a
- * real column of the wrong table, so it is answered once here. One pair per key of the parent.
+ * How a relation joins its parent, one pair per key: `parent` a column of the parent's table, `joined` the
+ * matching one on the table the relation reads, a junction's or the child's.
  */
 export function parentJoins(relOpts, parentKeyCount) {
     if (!relOpts.through) {
@@ -30,13 +25,7 @@ export function parentJoins(relOpts, parentKeyCount) {
     // something its caller already knows - so the boundary is passed rather than stored on a relation.
     return relOpts.references.slice(0, parentKeyCount).map(({ local, foreign }) => ({ parent: foreign, joined: local }));
 }
-/**
- * The junction columns holding the target's key, the other half of {@link parentJoins}.
- *
- * `parentKeyCount` is required: the target's columns start after the parent's, so guessing the
- * boundary returned the parent's *second* column as the target's - a real column of the wrong side,
- * which is the mistake this module exists to prevent.
- */
+/** The junction columns holding the target's key, after the parent's `parentKeyCount` ones. */
 export function targetKeyColumns(relOpts, parentKeyCount) {
     return relOpts.references.slice(parentKeyCount).map(({ local }) => local);
 }

package/dist/util/rowKey.util.d.ts

@@ -1,13 +1,5 @@
 /**
- * A row's key as a string, for matching rows to each other.
- *
- * Reads the columns off the row rather than taking their values, because every caller matches a
- * whole page of rows against one fixed column list: taking an array would make each of them build
- * one per row, which is what a page of 250 rows paid 56 KB for.
- *
- * Values are normalized before joining, not stringified: `String(date)` is locale- and
- * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
- * bytes with commas. Every column is included, so two rows agreeing on one column of a composite
- * key are not treated as one row.
+ * A row's key over `columns`, for matching rows: read off the row, so a page builds no array per row, and
+ * normalized rather than stringified, since `String(date)` depends on the locale.
  */
 export declare function rowKey(row: unknown, columns: readonly string[]): string;

package/dist/util/rowKey.util.js

@@ -1,16 +1,8 @@
 /** Separates the parts of a composite key: a unit separator, which no column value carries. */
 const KEY_SEPARATOR = '\u001f';
 /**
- * A row's key as a string, for matching rows to each other.
- *
- * Reads the columns off the row rather than taking their values, because every caller matches a
- * whole page of rows against one fixed column list: taking an array would make each of them build
- * one per row, which is what a page of 250 rows paid 56 KB for.
- *
- * Values are normalized before joining, not stringified: `String(date)` is locale- and
- * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
- * bytes with commas. Every column is included, so two rows agreeing on one column of a composite
- * key are not treated as one row.
+ * A row's key over `columns`, for matching rows: read off the row, so a page builds no array per row, and
+ * normalized rather than stringified, since `String(date)` depends on the locale.
  */
 export function rowKey(row, columns) {
     const values = row;

package/dist/util/sql.util.d.ts

@@ -17,18 +17,8 @@ export declare function obtainAttrsPaths<T extends object>(row: T): {
  */
 export declare function qualifyName(name: string, schema?: string): string;
 /**
- * The name a derived index or constraint gets when nothing named it: `Order__total_idx`.
- *
- * One owner for all four kinds, because it is a rule two layers apply and a third has to match: the
- * entity AST derives it, the DDL generator falls back to it, and a `DROP` names what it drops.
- * `table` is the table's own name, never qualified - the result is a single identifier.
- *
- * The kind goes last, as Postgres spells its own (`users_pkey`, `users_email_idx`), so a table's
- * constraints sort together under the table they belong to.
- *
- * Not overridable, deliberately: a `NamingStrategy` hook would have to reach the eight call sites
- * these have, an introspector and two builders among them, to replace a name any declaration can
- * already set outright with `name:`. Worth revisiting only for a case that option cannot express.
+ * The name a derived index or constraint gets, `Order__total_idx`, kind last as Postgres names its own.
+ * One rule for the AST, the DDL and a `DROP`; not a naming strategy hook, since `name:` already overrides it.
  */
 export declare function derivedConstraintName(table: string, parts: readonly (string | number)[], kind: ConstraintKind): string;
 /** The kinds of derived name, which is also what `indexNameStem` strips to compare them. */
@@ -49,13 +39,7 @@ export declare function derivedPrimaryKeyName(table: string, columns: readonly s
 export declare function derivedCheckName(table: string, position: number): string;
 /** The constraint name a foreign key gets when nothing named it: `Order__customerId_fk`. */
 export declare function derivedForeignKeyName(table: string, columns: readonly string[]): string;
-/**
- * Escape a SQL identifier (table name, column name, etc.)
- * @param val the identifier to escape
- * @param escapeIdChar the escape character to use (e.g. ` or ")
- * @param forbidQualified whether to forbid qualified identifiers (containing dots)
- * @param addDot whether to add a dot suffix
- */
+/** Escapes an identifier with `escapeIdChar`, refusing a dotted one where `forbidQualified`, with a trailing dot where `addDot`. */
 export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
 /**
  * Payload for building a QueryUpdateResult.
@@ -81,24 +65,9 @@ export interface BuildUpdateResultPayload {
     upsertStatus?: number;
 }
 /**
- * Unified utility to build a QueryUpdateResult from driver-specific results.
- *
- * UQL's SQL dialects always alias the entity's ID column to `id` in RETURNING clauses,
- * so the result rows always contain an `id` property regardless of the entity's @Id() key name.
- *
- * The header-derived ID path assumes the database allocated consecutive values for the
- * statement, which holds for a single multi-row `INSERT ... VALUES` on auto-increment keys
- * (with the standard `auto_increment_increment = 1`); the querier only maps these IDs onto
- * payloads when that assumption is safe.
- *
- * Caveat (MySQL/MariaDB-compatible engines with no `RETURNING`, i.e. `insertIdSource: 'firstId'`):
- * contiguous allocation across a statement's rows is only guaranteed under
- * `innodb_autoinc_lock_mode` 0 (`traditional`) or 1 (`consecutive`). Under mode 2 (`interleaved`,
- * MySQL 8.0's default), other connections inserting into the same table concurrently with this
- * statement can interleave with its auto-increment allocation, so the inferred IDs may not be
- * contiguous. There is no code-level fix for this (MySQL has no `RETURNING`); avoid relying on
- * inferred multi-row IDs for a table under heavy concurrent insert load, or set
- * `innodb_autoinc_lock_mode` to 0 or 1.
+ * A driver's result as a {@link QueryUpdateResult}: `RETURNING` rows name their id `id`; a MySQL header's
+ * first id is extended by the increment, which holds only where auto-increment allocation is contiguous
+ * (`innodb_autoinc_lock_mode` 0 or 1).
  */
 export declare function buildUpdateResult(payload: BuildUpdateResultPayload): QueryUpdateResult;
 /**

package/dist/util/sql.util.js

@@ -2,7 +2,7 @@ import { hasKeys } from './object.util.js';
 /** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
 const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
 export function unflatObjects(objects) {
-    if (!Array.isArray(objects) || !objects.length) {
+    if (!objects.length) {
         return objects;
     }
     const attrsPaths = obtainAttrsPaths(objects[0]);
@@ -66,40 +66,16 @@ const MAX_IDENTIFIER_LENGTH = 63;
 /** Hex chars of hash kept when a name has to be shortened. 24 bits over one table's constraints. */
 const NAME_HASH_LENGTH = 6;
 /**
- * The name a derived index or constraint gets when nothing named it: `Order__total_idx`.
- *
- * One owner for all four kinds, because it is a rule two layers apply and a third has to match: the
- * entity AST derives it, the DDL generator falls back to it, and a `DROP` names what it drops.
- * `table` is the table's own name, never qualified - the result is a single identifier.
- *
- * The kind goes last, as Postgres spells its own (`users_pkey`, `users_email_idx`), so a table's
- * constraints sort together under the table they belong to.
- *
- * Not overridable, deliberately: a `NamingStrategy` hook would have to reach the eight call sites
- * these have, an introspector and two builders among them, to replace a name any declaration can
- * already set outright with `name:`. Worth revisiting only for a case that option cannot express.
+ * The name a derived index or constraint gets, `Order__total_idx`, kind last as Postgres names its own.
+ * One rule for the AST, the DDL and a `DROP`; not a naming strategy hook, since `name:` already overrides it.
  */
 export function derivedConstraintName(table, parts, kind) {
     const body = parts.length ? `${table}${TABLE_SEPARATOR}${parts.join('_')}` : table;
     return clampIdentifier(`${body}_${kind}`);
 }
-/**
- * What separates the table from the columns, doubled where every other join is single.
- *
- * Postgres and SQLite keep index and constraint names in one flat namespace across the whole
- * database rather than scoping them to a table, so a single underscore lets two tables collide:
- * `user` + `profile_id` and `user_profile` + `id` both reduce to `user_profile_id_idx`. Doubling the
- * one ambiguous boundary settles it, on the same assumption Drupal made for the same engines - that
- * nothing sane carries `__` in a table or column name.
- */
+/** Between table and columns, doubled: index names share one namespace per database, where `a` + `b_c` and `a_b` + `c` would collide. */
 const TABLE_SEPARATOR = '__';
-/**
- * A name the engine will store whole, shortened around a hash of the full one when it is too long.
- *
- * Truncating alone collides - two long names over the same table differ only in their tail - and a
- * collision means one constraint silently replacing another. The hash is of the *whole* name, so it
- * stays the same on every run, which is what lets a later migration still recognise what it made.
- */
+/** A name the engine stores whole, shortened around a hash of the full one, which stays stable across runs. */
 function clampIdentifier(name) {
     if (name.length <= MAX_IDENTIFIER_LENGTH) {
         return name;
@@ -144,13 +120,7 @@ export function derivedCheckName(table, position) {
 export function derivedForeignKeyName(table, columns) {
     return derivedConstraintName(table, columns, 'fk');
 }
-/**
- * Escape a SQL identifier (table name, column name, etc.)
- * @param val the identifier to escape
- * @param escapeIdChar the escape character to use (e.g. ` or ")
- * @param forbidQualified whether to forbid qualified identifiers (containing dots)
- * @param addDot whether to add a dot suffix
- */
+/** Escapes an identifier with `escapeIdChar`, refusing a dotted one where `forbidQualified`, with a trailing dot where `addDot`. */
 export function escapeSqlId(val, escapeIdChar = '`', forbidQualified, addDot) {
     if (!val) {
         return '';
@@ -167,41 +137,16 @@ export function escapeSqlId(val, escapeIdChar = '`', forbidQualified, addDot) {
     return escaped + suffix;
 }
 /**
- * Unified utility to build a QueryUpdateResult from driver-specific results.
- *
- * UQL's SQL dialects always alias the entity's ID column to `id` in RETURNING clauses,
- * so the result rows always contain an `id` property regardless of the entity's @Id() key name.
- *
- * The header-derived ID path assumes the database allocated consecutive values for the
- * statement, which holds for a single multi-row `INSERT ... VALUES` on auto-increment keys
- * (with the standard `auto_increment_increment = 1`); the querier only maps these IDs onto
- * payloads when that assumption is safe.
- *
- * Caveat (MySQL/MariaDB-compatible engines with no `RETURNING`, i.e. `insertIdSource: 'firstId'`):
- * contiguous allocation across a statement's rows is only guaranteed under
- * `innodb_autoinc_lock_mode` 0 (`traditional`) or 1 (`consecutive`). Under mode 2 (`interleaved`,
- * MySQL 8.0's default), other connections inserting into the same table concurrently with this
- * statement can interleave with its auto-increment allocation, so the inferred IDs may not be
- * contiguous. There is no code-level fix for this (MySQL has no `RETURNING`); avoid relying on
- * inferred multi-row IDs for a table under heavy concurrent insert load, or set
- * `innodb_autoinc_lock_mode` to 0 or 1.
+ * A driver's result as a {@link QueryUpdateResult}: `RETURNING` rows name their id `id`; a MySQL header's
+ * first id is extended by the increment, which holds only where auto-increment allocation is contiguous
+ * (`innodb_autoinc_lock_mode` 0 or 1).
  */
 export function buildUpdateResult(payload) {
     const { rows, id, insertIdSource, upsertStatus } = payload;
     const changes = payload.changes ?? rows?.length ?? 0;
     const stride = payload.insertIdIncrement && payload.insertIdIncrement > 0 ? payload.insertIdIncrement : 1;
-    // ID mapping. RETURNING rows are exact. Otherwise the sequence is derived from the single id in
-    // the driver header: `firstId` dialects (MySQL) report the FIRST generated id, and the rest are
-    // inferred by incrementing it. A header id of `0`/`0n` means no id was generated (e.g. a
-    // non-auto-increment key), so we infer none.
-    //
-    // This arithmetic assumes `changes` equals the batch's row count, which always holds for a plain
-    // `insertMany` - but not for `upsertMany` on a `firstId` dialect (MySQL): its `ON DUPLICATE KEY
-    // UPDATE` convention makes `changes` a per-row weighted sum (1=insert, 2=update, 0=no-op), so a
-    // batch mixing an insert and an update would fabricate ids for rows that were never touched. This
-    // function has no way to tell the two call sites apart (`internalRun` reports the same header
-    // shape either way), so `AbstractSqlQuerier`'s `runUpsert` discards them for a multi-row `firstId`
-    // upsert and reads the ids back by the conflict columns instead.
+    // Ids from `RETURNING` are exact; otherwise from the header's first id onward, which assumes `changes`
+    // counts the rows (false for a MySQL upsert batch, whose querier reads ids back instead). `0` means none.
     let ids = [];
     if (rows?.length) {
         ids = rows.map((r) => r['id']);
@@ -215,13 +160,8 @@ export function buildUpdateResult(payload) {
             ids = sequentialIds(id, changes, stride);
         }
     }
-    // 2. Creation Status
-    // PostgreSQL: `(xmax = 0) AS "_created"` in the RETURNING clause provides a boolean per row.
-    // MySQL: `affectedRows` convention - 1 = insert, 2 = update, 0 = no-op. Gated on `!== 'returning'`
-    // since that convention is unreliable once RETURNING is in play (verified: MariaDB's affectedRows
-    // for an `ON DUPLICATE KEY UPDATE ... RETURNING` statement differs by driver and doesn't follow
-    // the 1/2/0 convention at all) - `insertIdSource === 'returning'` dialects without a `_created`
-    // column (MariaDB, SQLite, CockroachDB) correctly get `undefined` instead of a misleading guess.
+    // Whether the row was created: Postgres's `_created` column, or MySQL's 1/2/0 `affectedRows`,
+    // which is unreliable under `RETURNING`, so those dialects report nothing.
     const created = (rows?.length === 1 ? rows[0]?.['_created'] : undefined) ??
         (insertIdSource !== 'returning' && typeof upsertStatus === 'number' && upsertStatus >= 0 && upsertStatus <= 2
             ? upsertStatus === 1