uql-orm 0.53.0 → 0.55.0

package/dist/d1/d1SqliteDialect.d.ts

@@ -6,6 +6,11 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  */
 export declare class D1SqliteDialect extends SqliteDialect {
     readonly maxBindValues: number;
+    /**
+     * D1's Worker API refuses a `bigint` bind ([workerd#4195](https://github.com/cloudflare/workerd/issues/4195)),
+     * so one goes as its exact text, which SQLite's INTEGER affinity stores as the same integer.
+     */
+    normalizeValue(value: unknown): unknown;
     /**
      * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
      * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile

package/dist/d1/d1SqliteDialect.js

@@ -7,6 +7,13 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export class D1SqliteDialect extends SqliteDialect {
     // Cloudflare D1 caps bound parameters at 100 per query.
     maxBindValues = 100;
+    /**
+     * D1's Worker API refuses a `bigint` bind ([workerd#4195](https://github.com/cloudflare/workerd/issues/4195)),
+     * so one goes as its exact text, which SQLite's INTEGER affinity stores as the same integer.
+     */
+    normalizeValue(value) {
+        return typeof value === 'bigint' ? String(value) : super.normalizeValue(value);
+    }
     /**
      * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
      * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile

package/dist/dialect/abstractSqlDialect.d.ts

@@ -84,6 +84,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * shared for the same reason - see {@link SqlQueryContext}.
      */
     protected buildFragment(ctx: QueryContext, build: QueryBuildFn): string;
+    /** A `raw()` operand, rendered in place: bound, it would reach the driver as the object itself. */
+    protected rawFragment(ctx: QueryContext, value: QueryRaw): string;
     /**
      * Each operand rendered into its own fragment, keeping only those that emitted SQL.
      *
@@ -95,10 +97,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected renderOperands<T>(ctx: QueryContext, operands: readonly T[], render: (ctx: QueryContext, operand: T) => void): string[];
     addValue(values: unknown[], value: unknown): string;
     /**
-     * Normalizes a parameter value for the database driver.
-     * Handles bigint, boolean, and serializes plain objects/arrays to JSON strings.
-     * Date values are preserved so SQL drivers can apply native date/time binding.
-     * Postgres overrides to pass objects through to its native JSONB driver.
+     * A parameter value as this engine's driver takes it: a boolean as the integer an engine with no
+     * boolean type stores, and everything else as it is - a `bigint` included, which every driver here
+     * binds exactly, where a number would round it past 2^53. A driver that refuses one (D1) overrides.
      */
     normalizeValue(value: unknown): unknown;
     /**
@@ -354,10 +355,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * caller reached for this to avoid, and only say so by taking a long time.
      */
     estimatedCount<E>(_ctx: QueryContext, _entity: Type<E>): void;
-    /** `$group` aggregate operator → SQL function name. An allowlist, not a formatter: the op key
-     * comes from query data, so anything outside this map must be rejected rather than passed
-     * through as a raw SQL function name. */
-    private static readonly AGGREGATE_FN_MAP;
+    /** `$group` aggregate operator to SQL function name, over ops `resolveAggregateOp` has already allowlisted. */
+    private static readonly AGGREGATE_FN;
     aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): void;
     /**
      * ORDER BY for aggregate queries - handles both entity-field and alias references. A grouped
@@ -388,6 +387,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * already built ends up, so the two ends cannot disagree.
      */
     readonly returningPosition: 'suffix' | 'after-target';
+    /**
+     * Whether a multi-row upsert's `RETURNING` lists its rows in payload order. Where it does not, the
+     * ids are read back by the conflict columns instead, since placing them in order would name the
+     * wrong rows.
+     */
+    readonly upsertReturningOrdered: boolean;
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
@@ -652,6 +657,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * Postgres overrides to use `= ANY($1)` / `<> ALL($1)` with a single array parameter.
      */
     protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
-    protected numericCast(expr: string): string;
+    /** Reads extracted JSON text as a number, which every engine spells its own way. */
+    protected abstract numericCast(expr: string): string;
     toString(): string;
 }

package/dist/dialect/abstractSqlDialect.js

@@ -1,6 +1,6 @@
-import { getMeta, soleIdOf } from '../entity/index.js';
+import { fieldOf, getMeta, soleIdOf } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
-import { computedExpression, isInlinedExpression } from '../util/field.util.js';
+import { isInlinedExpression } from '../util/field.util.js';
 import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, columnFamily, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, queryChildrenOf, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX, PER_PARENT_BRANCH_ALIAS } from './aliases.js';
@@ -10,6 +10,13 @@ import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
+/** An `$in`/`$nin` operand, which the types require to be an array but `/http` hands over untyped. */
+function inOperands(op, value) {
+    if (!Array.isArray(value)) {
+        throw TypeError(`${op} expects an array, got ${value === null ? 'null' : typeof value}`);
+    }
+    return value;
+}
 export class AbstractSqlDialect extends VectorSqlDialect {
     /**
      * Whether {@link autoIncrementSuffix} states `PRIMARY KEY` itself, so the table must not state it again.
@@ -99,6 +106,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         build(fragmentCtx);
         return fragmentCtx.sql;
     }
+    /** A `raw()` operand, rendered in place: bound, it would reach the driver as the object itself. */
+    rawFragment(ctx, value) {
+        return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, { value }));
+    }
     /**
      * Each operand rendered into its own fragment, keeping only those that emitted SQL.
      *
@@ -117,20 +128,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return this.placeholder(values.length);
     }
     /**
-     * Normalizes a parameter value for the database driver.
-     * Handles bigint, boolean, and serializes plain objects/arrays to JSON strings.
-     * Date values are preserved so SQL drivers can apply native date/time binding.
-     * Postgres overrides to pass objects through to its native JSONB driver.
+     * A parameter value as this engine's driver takes it: a boolean as the integer an engine with no
+     * boolean type stores, and everything else as it is - a `bigint` included, which every driver here
+     * binds exactly, where a number would round it past 2^53. A driver that refuses one (D1) overrides.
      */
     normalizeValue(value) {
-        if (value == null || value instanceof Date || value instanceof Uint8Array || value instanceof QueryRaw) {
-            return value;
-        }
-        if (typeof value === 'bigint') {
-            return Number(value);
-        }
-        if (typeof value === 'boolean') {
-            return this.booleanLiteral === 'native' ? value : value ? 1 : 0;
+        if (typeof value === 'boolean' && this.booleanLiteral !== 'native') {
+            return value ? 1 : 0;
         }
         return value;
     }
@@ -198,9 +202,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 });
             }
             else {
-                const field = meta.fields[key];
-                if (!field)
-                    return;
+                const field = fieldOf(meta, key);
                 if (isInlinedExpression(field)) {
                     // Qualified even when nothing else in this statement is: the expression is spliced in, and
                     // one that opens a correlated subquery has the inner table's columns in scope, so a bare
@@ -208,7 +210,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     // is valid on every engine, so naming the table costs nothing where it is not needed.
                     const qualified = opts.prefix ?? this.resolveTableAlias(meta);
                     this.getRawValue(ctx, {
-                        value: computedExpression(field).as(key),
+                        value: field.computed.as(key),
                         prefix: qualified,
                         escapedPrefix: this.escapeId(qualified, true, true),
                         autoPrefixAlias: opts.autoPrefixAlias,
@@ -427,7 +429,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             if (entry instanceof QueryRaw) {
                 this.getRawValue(fragmentCtx, { value: entry });
             }
-            else if (entry) {
+            else {
                 this.renderWhere(fragmentCtx, entity, entry, { prefix: opts.prefix, operand: childOperand, clause: false });
             }
         });
@@ -523,7 +525,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
      */
     inlinedOperand(ctx, field, prefix) {
-        const inlined = field && isInlinedExpression(field) ? computedExpression(field) : undefined;
+        const inlined = field && isInlinedExpression(field) ? field.computed : undefined;
         return inlined
             ? this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, {
                 value: inlined,
@@ -589,13 +591,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             case '$regex':
                 return this.regexCondition(operand, this.addValue(ctx.values, val));
             case '$in':
-            case '$nin': {
-                if (!Array.isArray(val)) {
-                    // Not covered by the types: `/http` casts client JSON straight to `Query`, so this arrives untyped.
-                    throw TypeError(`${op} expects an array, got ${val === null ? 'null' : typeof val}`);
-                }
-                return operand + this.formatIn(ctx, val, op === '$nin');
-            }
+            case '$nin':
+                return operand + this.formatIn(ctx, inOperands(op, val), op === '$nin');
             case '$between': {
                 const [min, max] = val;
                 return `${operand} BETWEEN ${this.addValue(ctx.values, min)} AND ${this.addValue(ctx.values, max)}`;
@@ -663,7 +660,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
     }
     jsonInNin(ctx, jsonField, comparand, op, value, asJson) {
-        const values = Array.isArray(value) ? value : [];
+        const values = inOperands(op, value);
         const negate = op === '$nin';
         if (!asJson) {
             return `${comparand(values)}${this.formatIn(ctx, values, negate)}`;
@@ -739,7 +736,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     jsonScalarParam(ctx, value) {
         if (value instanceof QueryRaw) {
-            return this.addValue(ctx.values, value);
+            return this.rawFragment(ctx, value);
         }
         ctx.pushValue(JSON.stringify(value));
         // The placeholder for the value just pushed, so a named or numbered one is spelled correctly.
@@ -917,16 +914,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     estimatedCount(_ctx, _entity) {
         throw new TypeError(`${this.dialectName} does not support estimatedCount`);
     }
-    /** `$group` aggregate operator → SQL function name. An allowlist, not a formatter: the op key
-     * comes from query data, so anything outside this map must be rejected rather than passed
-     * through as a raw SQL function name. */
-    static AGGREGATE_FN_MAP = new Map([
-        ['$count', 'COUNT'],
-        ['$sum', 'SUM'],
-        ['$avg', 'AVG'],
-        ['$min', 'MIN'],
-        ['$max', 'MAX'],
-    ]);
+    /** `$group` aggregate operator to SQL function name, over ops `resolveAggregateOp` has already allowlisted. */
+    static AGGREGATE_FN = {
+        $count: 'COUNT',
+        $sum: 'SUM',
+        $avg: 'AVG',
+        $min: 'MIN',
+        $max: 'MAX',
+    };
     aggregate(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
         const tableName = this.escapedTableName(meta);
@@ -946,10 +941,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 selectParts.push(columnName !== entry.alias ? `${escaped} ${this.escapeId(entry.alias)}` : escaped);
             }
             else {
-                const sqlFn = AbstractSqlDialect.AGGREGATE_FN_MAP.get(entry.op);
-                if (!sqlFn) {
-                    throw TypeError(`unsupported aggregate operator: ${entry.op}`);
-                }
+                const sqlFn = AbstractSqlDialect.AGGREGATE_FN[entry.op];
                 const sqlArg = entry.fieldRef === '*' ? '*' : this.escapeId(this.columnOf(meta, entry.fieldRef));
                 const expr = `${sqlFn}(${entry.distinct ? 'DISTINCT ' : ''}${sqlArg})`;
                 emittedColumns[entry.alias] = expr;
@@ -1065,6 +1057,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * already built ends up, so the two ends cannot disagree.
      */
     returningPosition = 'suffix';
+    /**
+     * Whether a multi-row upsert's `RETURNING` lists its rows in payload order. Where it does not, the
+     * ids are read back by the conflict columns instead, since placing them in order would name the
+     * wrong rows.
+     */
+    upsertReturningOrdered = true;
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
@@ -1232,14 +1230,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // Soft-delete (stamp only live rows) unless `hardDelete` is requested or the entity has no
         // soft-delete field (e.g. a cascade onto a non-soft-deletable child).
         if (!opts.hardDelete && meta.softDelete) {
-            const field = meta.fields[meta.softDelete];
-            if (field) {
-                const columnName = this.resolveColumnName(meta.softDelete, field);
-                ctx.append(`UPDATE ${tableName} SET ${this.escapeId(columnName)} = `);
-                this.formatPersistableValue(ctx, field, getSoftDeleteValue(field));
-                this.search(ctx, entity, q, opts);
-                return;
-            }
+            const field = fieldOf(meta, meta.softDelete);
+            const columnName = this.resolveColumnName(meta.softDelete, field);
+            ctx.append(`UPDATE ${tableName} SET ${this.escapeId(columnName)} = `);
+            this.formatPersistableValue(ctx, field, getSoftDeleteValue(field));
+            this.search(ctx, entity, q, opts);
+            return;
         }
         // Hard delete removes matching rows regardless of soft-delete state (keeps other filters, e.g. tenant).
         // Only rewrite the filters when there is a soft-delete filter to disable.
@@ -1758,9 +1754,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const phs = values.map((v) => this.addValue(ctx.values, v)).join(', ');
         return ` ${negate ? 'NOT IN' : 'IN'} (${phs})`;
     }
-    numericCast(expr) {
-        return expr;
-    }
     toString() {
         return this.dialectName;
     }

package/dist/dialect/hydrateColumn.js

@@ -1,3 +1,4 @@
+import { decodeWideNumber } from '../util/wideNumber.js';
 import { parseVectorLiteral } from './vectorCast.js';
 /**
  * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
@@ -31,8 +32,7 @@ export function decodeColumn(value, kind) {
         return value;
     }
     if (kind === 'number') {
-        const decoded = Number(text);
-        return Number.isNaN(decoded) ? value : decoded;
+        return Number.isNaN(Number(text)) ? value : decodeWideNumber(text);
     }
     if (kind === 'json') {
         try {

package/dist/dialect/mergeSqlDialect.d.ts

@@ -38,8 +38,8 @@ export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
      * holds it across both. Empty on Oracle, which does not have the hint and does not need it.
      */
     protected readonly mergeTargetHint: string;
-    /** How the merge reports the row it wrote. Oracle has no such clause on a `MERGE` and omits it. */
-    protected mergeReturning(expression: string): string;
+    /** How the merge reports the row it wrote: SQL Server's `OUTPUT`. Oracle has no such clause on a `MERGE`. */
+    protected abstract mergeReturning(expression: string): string;
     /** `MERGE` must be terminated on SQL Server; nothing else here cares. */
     protected readonly statementTerminator: string;
 }

package/dist/dialect/mergeSqlDialect.js

@@ -80,10 +80,6 @@ export class MergeSqlDialect extends AbstractSqlDialect {
      * holds it across both. Empty on Oracle, which does not have the hint and does not need it.
      */
     mergeTargetHint = '';
-    /** How the merge reports the row it wrote. Oracle has no such clause on a `MERGE` and omits it. */
-    mergeReturning(expression) {
-        return `RETURNING ${expression}`;
-    }
     /** `MERGE` must be terminated on SQL Server; nothing else here cares. */
     statementTerminator = '';
 }

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -9,9 +9,6 @@ import { AbstractSqlDialect } from './abstractSqlDialect.js';
  * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
  * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
  *   and `$pull` (JSON_REPLACE over JSON_TABLE)
- *
- * Neither has `FOR NO KEY UPDATE`/`FOR KEY SHARE`, PostgreSQL's weaker pair, so asking for one is
- * rejected rather than served a stronger lock.
  */
 export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -15,9 +15,6 @@ const MAX_LIMIT = BigInt.asUintN(64, -1n);
  * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
  * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
  *   and `$pull` (JSON_REPLACE over JSON_TABLE)
- *
- * Neither has `FOR NO KEY UPDATE`/`FOR KEY SHARE`, PostgreSQL's weaker pair, so asking for one is
- * rejected rather than served a stronger lock.
  */
 export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -93,6 +93,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * ORDINALITY` keeps the surviving elements in their original order.
      */
     protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
+    /**
+     * The plain values merge as one bound object; a `raw()` one is an SQL expression rather than JSON,
+     * so it merges through `JSONB_BUILD_OBJECT` and is evaluated in place - stringified with the rest,
+     * it would land as `{}`.
+     */
     protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, field?: FieldOptions): string;
     /** The only fragment that references `expr` twice - safe here because placeholders are numbered. */
     protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;

package/dist/dialect/pgLikeSqlDialect.js

@@ -213,8 +213,18 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const kept = `SELECT JSONB_AGG(${JSON_PULL_ALIAS}.val ORDER BY ${JSON_PULL_ALIAS}.ord) FROM JSONB_ARRAY_ELEMENTS(${escapedCol}->'${escapedKey}') WITH ORDINALITY AS ${JSON_PULL_ALIAS}(val, ord) WHERE ${JSON_PULL_ALIAS}.val <> ${this.jsonVal(ctx, value)}`;
         return `JSONB_SET(${expr}, '{${escapedKey}}', COALESCE((${kept}), '[]'::jsonb), false)`;
     }
+    /**
+     * The plain values merge as one bound object; a `raw()` one is an SQL expression rather than JSON,
+     * so it merges through `JSONB_BUILD_OBJECT` and is evaluated in place - stringified with the rest,
+     * it would land as `{}`.
+     */
     jsonSet(ctx, expr, set, field) {
-        return `${jsonSetTarget(expr, field, `'{}'::jsonb`)} || ${this.jsonVal(ctx, set)}`;
+        const entries = Object.entries(set);
+        const merged = this.jsonVal(ctx, Object.fromEntries(entries.filter(([, value]) => !(value instanceof QueryRaw))));
+        const raws = entries.flatMap(([key, value]) => value instanceof QueryRaw
+            ? [` || JSONB_BUILD_OBJECT('${escapeSingleQuotes(key)}', ${this.rawFragment(ctx, value)})`]
+            : []);
+        return `${jsonSetTarget(expr, field, `'{}'::jsonb`)} || ${merged}${raws.join('')}`;
     }
     /** The only fragment that references `expr` twice - safe here because placeholders are numbered. */
     jsonPush(ctx, expr, push) {
@@ -236,7 +246,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     jsonVal(ctx, value, type = 'jsonb') {
         if (value instanceof QueryRaw)
-            return this.addValue(ctx.values, value);
+            return this.rawFragment(ctx, value);
         if (value == null)
             return `${this.addValue(ctx.values, null)}::${type}`;
         const json = JSON.stringify(value);

package/dist/entity/decorator/members.d.ts

@@ -2,12 +2,6 @@ import type { EntityGetter, FieldOptions, FieldType, IdValue, NamedIdKey, Relati
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
-/**
- * The property type a set of field options describes, in the same order schema generation resolves the
- * column: a declared `type` wins, and otherwise the column - and so the property - is the referenced
- * primary key's own type. Which is what makes `@Field({ references: () => User })` on a `number`, where
- * `User.id` is a `uuid`, a compile error rather than a column that disagrees with its property.
- */
 /**
  * Maps any option the type does not declare to `never`, turning a typo into a compile error.
  *
@@ -17,10 +11,9 @@ type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext
  */
 type RejectUnknown<O, Known> = [Exclude<keyof O, keyof Known>] extends [never] ? unknown : Record<Exclude<keyof O, keyof Known> & string, never>;
 /**
- * The value type the options declare, which the decorated property is then checked against.
- *
- * `enum` narrows it to its own values, so the property must spell out the same set. Only the values
- * the declared `type` admits count, which is what keeps `enum: [2]` off a `String` field.
+ * The property type a set of field options describes: the declared `type`, narrowed by `enum` to the
+ * values that type admits (so `enum: [2]` stays off a `String`), or else the referenced key's own type,
+ * which makes `@Field({ references: () => User })` on a `number` an error when `User.id` is a `uuid`.
  */
 type DeclaredValue<O> = O extends {
     readonly type: infer T extends FieldType;

package/dist/entity/index.d.ts

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, idOf, namesKey, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, soleIdOf, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, idOf, namesKey, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, soleIdOf, } from './metadata/definition.js';

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type, WrittenId } from '../../type/index.js';
+import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
@@ -30,6 +30,8 @@ export declare function defineEntity<E>(entity: Type<E>, opts?: EntityOptions<E>
 export declare function assertSoleId<E>(meta: EntityMeta<E>, what: string): void;
 /** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
 export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>;
+/** The field `key` names, for a caller that took `key` from the metadata itself. */
+export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
 /**
  * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
  *

package/dist/entity/metadata/definition.js

@@ -17,10 +17,6 @@ function globalMap(key) {
 const metas = globalMap('uql-orm/entity/metadata/v1');
 export function defineField(entity, key, opts = {}) {
     const meta = ensureWritableMeta(entity);
-    if (opts.virtual !== undefined && opts.computed !== undefined) {
-        throw new TypeError(`'${entity.name}.${key}' gives both 'virtual' and 'computed'. They are one option under two names - ` +
-            "keep 'computed'; 'npx uql-codemod' rewrites the other.");
-    }
     // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
     // its expression being spliced in rather than declared.
     if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
@@ -223,6 +219,14 @@ export function soleIdOf(meta, what) {
     assertSoleId(meta, what);
     return meta.ids[0];
 }
+/** The field `key` names, for a caller that took `key` from the metadata itself. */
+export function fieldOf(meta, key) {
+    const field = meta.fields[key];
+    if (!field) {
+        throw new TypeError(`'${meta.entity.name}' has no field '${key}'`);
+    }
+    return field;
+}
 /**
  * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
  *

package/dist/libsql/index.d.ts

@@ -1,3 +1,2 @@
 export * from './libsqlDialect.js';
-export * from './libsqlQuerier.js';
 export * from './libsqlQuerierPool.js';

package/dist/libsql/index.js

@@ -1,3 +1,2 @@
 export * from './libsqlDialect.js';
-export * from './libsqlQuerier.js';
 export * from './libsqlQuerierPool.js';

package/dist/libsql/libsqlQuerierPool.d.ts

@@ -1,21 +1,19 @@
 import type { Config } from '@libsql/client';
-import type { HranaClient, HranaQuerierConnectionOptions } from '../sqlite/hranaQuerier.js';
+import { type HranaClient, HranaQuerier } from '../sqlite/hranaQuerier.js';
 import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { LibsqlDialect } from './libsqlDialect.js';
-import { LibsqlQuerier } from './libsqlQuerier.js';
 /** Embedded replica: local `file:` DB + `syncUrl` remote - DDL should run on the remote (sqld). */
 export declare function libsqlUseRemoteForMigrations(config: Pick<Config, 'url' | 'syncUrl'>): boolean;
-export declare class LibsqlQuerierPool extends AbstractHranaQuerierPool<LibsqlQuerier, LibsqlDialect> {
+export declare class LibsqlQuerierPool extends AbstractHranaQuerierPool<LibsqlDialect> {
     private readonly conf;
     constructor(conf: Config, extra?: ExtraOptions);
     protected openClient(): Promise<HranaClient>;
-    protected buildQuerier(client: HranaClient, connection?: HranaQuerierConnectionOptions): LibsqlQuerier;
     /**
      * For embedded replicas (`file:` + `syncUrl`), returns a querier connected to `syncUrl` so migrations hit sqld.
      * Otherwise same as `getQuerier`. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
      */
-    getMigrationQuerier(): Promise<LibsqlQuerier>;
+    getMigrationQuerier(): Promise<HranaQuerier>;
     /** Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed. */
     private createClient;
 }

package/dist/libsql/libsqlQuerierPool.js

@@ -1,7 +1,7 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { HranaQuerier } from '../sqlite/hranaQuerier.js';
 import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import { LibsqlDialect } from './libsqlDialect.js';
-import { LibsqlQuerier } from './libsqlQuerier.js';
 /** Embedded replica: local `file:` DB + `syncUrl` remote - DDL should run on the remote (sqld). */
 export function libsqlUseRemoteForMigrations(config) {
     return Boolean(config.syncUrl && config.url.startsWith('file:'));
@@ -20,9 +20,6 @@ export class LibsqlQuerierPool extends AbstractHranaQuerierPool {
     openClient() {
         return this.createClient(this.conf);
     }
-    buildQuerier(client, connection) {
-        return new LibsqlQuerier(client, this.dialect, this.extra, connection);
-    }
     /**
      * For embedded replicas (`file:` + `syncUrl`), returns a querier connected to `syncUrl` so migrations hit sqld.
      * Otherwise same as `getQuerier`. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
@@ -32,7 +29,7 @@ export class LibsqlQuerierPool extends AbstractHranaQuerierPool {
             return this.getQuerier();
         }
         const remote = await this.createClient(remoteMigrationClientConfig(this.conf));
-        return this.buildQuerier(remote, { closeClientOnRelease: true });
+        return new HranaQuerier(remote, this.dialect, this.extra, { closeClientOnRelease: true });
     }
     /** Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed. */
     async createClient(conf) {

package/dist/maria/mariadbQuerier.d.ts

@@ -1,9 +1,6 @@
 import type { PoolConnection } from 'mariadb';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
-import type { ExtraOptions } from '../type/index.js';
-import type { MariaDialect } from './mariaDialect.js';
 export declare class MariadbQuerier extends AbstractPoolQuerier<PoolConnection> {
-    constructor(connect: () => Promise<PoolConnection>, dialect: MariaDialect, extra?: ExtraOptions);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;

package/dist/maria/mariadbQuerier.js

@@ -1,23 +1,22 @@
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
+import { decodeBigInts } from '../util/wideNumber.js';
 export class MariadbQuerier extends AbstractPoolQuerier {
-    constructor(connect, dialect, extra) {
-        super(dialect, connect, extra);
-    }
     async internalAll(query, values) {
-        const res = await this.getConn().query(query, values);
-        return res;
+        const rows = await this.getConn().query(query, values);
+        return Array.from(rows, decodeBigInts);
     }
     async internalRun(query, values) {
         const res = await this.getConn().query(query, values);
         // MariaDB may not set `affectedRows` when RETURNING is used; fall back to row count.
         const changes = res.affectedRows ?? res.length ?? 0;
-        return this.buildUpdateResult({ rows: res.length ? res : [], changes, upsertStatus: res.affectedRows });
+        const rows = res.length ? Array.from(res, decodeBigInts) : [];
+        return this.buildUpdateResult({ rows, changes, upsertStatus: res.affectedRows });
     }
     async *internalStream(query, values) {
         const stream = this.getConn().queryStream(query, values);
         try {
             for await (const row of stream) {
-                yield row;
+                yield decodeBigInts(row);
             }
         }
         finally {

package/dist/maria/mariadbQuerierPool.js

@@ -8,19 +8,16 @@ export class MariadbQuerierPool extends AbstractSqlQuerierPool {
     pool;
     constructor(opts, extra) {
         super(new MariaDialect(dialectOptionsFrom(extra)), extra);
-        // `mariadb` defaults to handing BIGINT back as a BigInt, and uql maps `type: Number` to BIGINT
-        // (see `schema/canonicalType.ts`), so every auto-increment id reached a field declared `number`
-        // as `9n` without this. Same trade as the pg pools: exact to 2^53, and `...opts` wins for a
-        // caller who needs more. This belongs to the pool, not to the suites - it lived in
-        // `mariadbQuerier.test.ts`, which meant the tests passed on behaviour the library never shipped.
-        this.pool = createPool({ bigIntAsNumber: true, ...opts });
+        // BIGINT stays the driver's `bigint`, which `MariadbQuerier` decodes by the rule every driver here
+        // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word.
+        this.pool = createPool(opts);
         // `mariadb`'s own `createPool` already attaches a silent no-op 'error'
         // listener (so a dropped connection can't crash the process), but its
         // `Pool` type only declares `on` for 'acquire' | 'connection' | 'enqueue'
         // | 'release' - 'error' genuinely fires at runtime (see `lib/pool.js`)
         // but isn't in the declaration, hence the cast. Re-attaching our own
         // listener here just makes the error visible instead of a silent no-op.
-        attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error');
+        attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error', extra?.logger);
     }
     async getQuerier() {
         return new MariadbQuerier(() => this.pool.getConnection(), this.dialect, this.extra);