uql-orm 0.54.0 → 0.56.0

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
@@ -658,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,4 +1,4 @@
-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 { 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';
@@ -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
@@ -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 });
             }
         });
@@ -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;
@@ -1238,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.
@@ -1764,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.js

@@ -1,5 +1,5 @@
 import { getMeta } from '../entity/index.js';
-import { getFieldKeys } from '../util/index.js';
+import { textSearchFields } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { COUNT_ALIAS, JSON_PULL_ALIAS } from './aliases.js';
@@ -135,8 +135,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * `@Index([...], { type: 'fulltext' })`.
      */
     appendTextSearch(ctx, _entity, meta, search) {
-        const searchFields = search.$fields ?? getFieldKeys(meta.fields);
-        const columns = searchFields.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
         ctx.append(`MATCH(${columns.join(', ')}) AGAINST(`);
         ctx.addValue(search.$value);
         ctx.append(')');

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

@@ -1,6 +1,6 @@
 import { canonicalToSql, fieldOptionsToCanonical } from '../schema/canonicalType.js';
 import { QueryRaw, } from '../type/index.js';
-import { hasVectorNear } from '../util/dialect.util.js';
+import { hasVectorNear, textSearchFields } from '../util/dialect.util.js';
 import { raw } from '../util/raw.js';
 import { queryNarrowedTo } from '../util/relationQuery.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
@@ -147,7 +147,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      * rejects anything unparseable - including a plain two-word search.
      */
     appendTextSearch(ctx, _entity, meta, search) {
-        const fields = (search.$fields ?? [])
+        const fields = textSearchFields(meta, search)
             .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
             .join(` || ' ' || `);
         // The config is bound once and its numbered placeholder reused by both calls.
@@ -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/dialect/queryJoins.js

@@ -1,4 +1,4 @@
-import { getMeta } from '../entity/index.js';
+import { getMeta, relationOf } from '../entity/index.js';
 import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey, } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
@@ -54,9 +54,7 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
 }
 function addPopulateJoins(joins, meta, populate, parent) {
     for (const key of getRelationRequestSummary(meta, populate).joinableKeys) {
-        const relation = meta.relations[key];
-        if (!relation)
-            continue;
+        const relation = relationOf(meta, key);
         const { query, required } = parseRelationAtKey(key, populate);
         const join = addJoin(joins, parent, key, relation, query, required, true);
         addPopulateJoins(joins, join.meta, query.$populate, join);

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, relationOf, 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, relationOf, 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, RelationKey, RelationMeta, 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,10 @@ 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: FieldKey<E>): FieldMeta;
+/** The relation `key` names, for a caller that took `key` from the metadata itself. */
+export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
 /**
  * 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

@@ -1,6 +1,6 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
-import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
+import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -95,9 +95,7 @@ export function defineFilter(entity, name, opts) {
  * API converge on one registration path before anything is finalized.
  */
 export function applyMembers(entity, specs) {
-    for (const [key, spec] of Object.entries(specs?.fields ?? {})) {
-        if (!spec)
-            continue;
+    for (const [key, spec] of definedEntries(specs?.fields ?? {})) {
         if (spec.isId) {
             defineId(entity, key, spec);
         }
@@ -105,12 +103,11 @@ export function applyMembers(entity, specs) {
             defineField(entity, key, spec);
         }
     }
-    for (const [key, spec] of Object.entries(specs?.relations ?? {})) {
-        if (spec)
-            defineRelation(entity, key, spec);
+    for (const [key, spec] of definedEntries(specs?.relations ?? {})) {
+        defineRelation(entity, key, spec);
     }
-    for (const [event, methodNames] of Object.entries(specs?.hooks ?? {})) {
-        for (const methodName of methodNames ?? []) {
+    for (const [event, methodNames] of definedEntries(specs?.hooks ?? {})) {
+        for (const methodName of methodNames) {
             defineHook(entity, methodName, event);
         }
     }
@@ -143,9 +140,8 @@ export function defineEntity(entity, opts = {}) {
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }
-    for (const [name, filter] of Object.entries(opts.filters ?? {})) {
-        if (filter)
-            defineFilter(entity, name, filter);
+    for (const [name, filter] of definedEntries(opts.filters ?? {})) {
+        defineFilter(entity, name, filter);
     }
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
@@ -219,6 +215,22 @@ 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;
+}
+/** The relation `key` names, for a caller that took `key` from the metadata itself. */
+export function relationOf(meta, key) {
+    const relation = meta.relations[key];
+    if (!relation) {
+        throw new TypeError(`'${meta.entity.name}' has no relation '${key}'`);
+    }
+    return relation;
+}
 /**
  * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
  *
@@ -295,11 +307,9 @@ export function getMeta(entity) {
     return fillRelations(meta);
 }
 function fillRelations(meta) {
-    for (const relKey in meta.relations) {
+    for (const [relKey, relation] of definedEntries(meta.relations)) {
         // The authored view: `mappedBy` may still be the callback and `references` unset until this settles them.
-        const relOpts = meta.relations[relKey];
-        if (!relOpts)
-            continue;
+        const relOpts = relation;
         const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
             fillInverseSide(at, meta, relOpts);
@@ -355,7 +365,7 @@ function fillOwningSide(at, meta, relKey, relOpts) {
     for (const { local, foreign } of relOpts.references) {
         fields[local] ??= {
             name: local,
-            type: relMeta.fields[foreign]?.type ?? Number,
+            type: fieldOf(relMeta, foreign).type ?? Number,
             references: relOpts.entity,
             referencedKey: foreign,
             typeFromReference: true,
@@ -405,9 +415,8 @@ function fillInverseSide(at, meta, relOpts) {
  * own cardinality and `cascade`.
  */
 function fillForeignKeyRelations(meta) {
-    const joined = new Set(getKeys(meta.relations).flatMap((key) => meta.relations[key]?.references.map(({ local }) => local) ?? []));
-    for (const fieldKey of getKeys(meta.fields)) {
-        const references = meta.fields[fieldKey]?.references;
+    const joined = new Set(definedEntries(meta.relations).flatMap(([, relation]) => relation.references.map(({ local }) => local)));
+    for (const [fieldKey, { references }] of definedEntries(meta.fields)) {
         if (!references || joined.has(fieldKey))
             continue;
         const target = ensureMeta(references());
@@ -437,7 +446,7 @@ function fillForeignKeyRelations(meta) {
 }
 /** `<entityName><IdColumn>`, not the `<relationKey>Id` an owning to-one derives: a junction row has no relation key to borrow from. */
 function junctionColumn(meta, idKey) {
-    return lowerFirst(entityName(meta)) + upperFirst(meta.fields[idKey]?.name ?? idKey);
+    return lowerFirst(entityName(meta)) + upperFirst(fieldOf(meta, idKey).name ?? idKey);
 }
 /** A callback only reads one property off the key map, and that property is the key, so one serves every entity. */
 const RELATION_KEY_MAP = new Proxy({}, { get: (_, key) => key });
@@ -470,11 +479,8 @@ function extendMeta(target, source) {
     if (source.hooks) {
         if (!target.hooks)
             target.hooks = {};
-        for (const event of Object.keys(source.hooks)) {
-            const sourceList = source.hooks[event];
-            if (sourceList?.length) {
-                target.hooks[event] = [...sourceList, ...(target.hooks[event] ?? [])];
-            }
+        for (const [event, sourceList] of definedEntries(source.hooks)) {
+            target.hooks[event] = [...sourceList, ...(target.hooks[event] ?? [])];
         }
     }
 }

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>;