uql-orm 0.24.6 → 0.25.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,12 @@
 import { getMeta } from '../entity/index.js';
 import { QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
-import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
+import { isJsonbOp, JSON_ELEM_ALIAS_PREFIX, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { isVectorFieldType } from './vectorCast.js';
+import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
 export class AbstractSqlDialect extends IndexSqlDialect {
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
@@ -433,44 +433,15 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
         const field = this.resolveOperandField(ctx, entity, key, opts);
-        const simpleOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
-        if (simpleOp) {
-            this.appendFieldSql(ctx, field, `${simpleOp}${this.addValue(ctx.values, val)}`);
-            return;
-        }
-        const likeWrap = AbstractSqlDialect.LIKE_OP_MAP.get(op);
-        if (likeWrap) {
-            this.appendLikeOp(ctx, field, op, likeWrap(val));
+        if (this.appendOperatorCondition(ctx, field, op, val)) {
             return;
         }
         switch (op) {
-            case '$eq':
-            case '$ne':
-                this.appendEqNe(ctx, field, op, val);
-                break;
-            case '$regex':
-                this.appendFieldSql(ctx, field, ` ${this.regexpOp} ${this.addValue(ctx.values, val)}`);
-                break;
             case '$not':
                 ctx.append('NOT (');
                 this.compare(ctx, entity, key, val, opts);
                 ctx.append(')');
                 break;
-            case '$in':
-            case '$nin':
-                this.appendInNin(ctx, field, op, val);
-                break;
-            case '$between': {
-                const [min, max] = val;
-                this.appendFieldSql(ctx, field, ` BETWEEN ${this.addValue(ctx.values, min)} AND ${this.addValue(ctx.values, max)}`);
-                break;
-            }
-            case '$isNull':
-                this.appendFieldSql(ctx, field, val ? ' IS NULL' : ' IS NOT NULL');
-                break;
-            case '$isNotNull':
-                this.appendFieldSql(ctx, field, val ? ' IS NOT NULL' : ' IS NULL');
-                break;
             case '$all':
                 ctx.append(this.jsonAll(ctx, field ?? '', val));
                 break;
@@ -484,6 +455,57 @@ export class AbstractSqlDialect extends IndexSqlDialect {
                 throw TypeError(`unknown operator: ${op}`);
         }
     }
+    /**
+     * Render `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, and
+     * report whether `op` was one of them.
+     *
+     * One implementation for three callers that each had their own: a WHERE column, a HAVING aggregate
+     * expression, and a `$size` count (which passes no operand, since its expression is already in the
+     * context). They previously disagreed - HAVING carried a second comparison-operator map and threw
+     * `unsupported HAVING operator` on the `$like` that `QueryHavingMap` accepts, and neither of the
+     * other two turned `$eq: null` into `IS NULL` the way the WHERE path does.
+     *
+     * The operators kept out are the ones that need more than an operand: `$not` recurses through the
+     * entity, and `$all`/`$size`/`$elemMatch` address a JSON document.
+     */
+    appendOperatorCondition(ctx, operand, op, val) {
+        const simpleOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
+        if (simpleOp) {
+            this.appendFieldSql(ctx, operand, `${simpleOp}${this.addValue(ctx.values, val)}`);
+            return true;
+        }
+        const likeWrap = AbstractSqlDialect.LIKE_OP_MAP.get(op);
+        if (likeWrap) {
+            this.appendLikeOp(ctx, operand, op, likeWrap(val));
+            return true;
+        }
+        switch (op) {
+            case '$eq':
+            case '$ne':
+                this.appendEqNe(ctx, operand, op, val);
+                return true;
+            case '$regex':
+                this.appendFieldSql(ctx, operand, ` ${this.regexpOp} ${this.addValue(ctx.values, val)}`);
+                return true;
+            case '$in':
+            case '$nin':
+                this.appendInNin(ctx, operand, op, val);
+                return true;
+            case '$between': {
+                const [min, max] = val;
+                this.appendFieldSql(ctx, operand, ` BETWEEN ${this.addValue(ctx.values, min)} AND ${this.addValue(ctx.values, max)}`);
+                return true;
+            }
+            case '$isNull':
+                this.appendFieldSql(ctx, operand, val ? ' IS NULL' : ' IS NOT NULL');
+                return true;
+            case '$isNotNull':
+                this.appendFieldSql(ctx, operand, val ? ' IS NOT NULL' : ' IS NULL');
+                return true;
+            default:
+                return false;
+        }
+    }
     appendLikeOp(ctx, field, op, wrappedVal) {
         const isIlike = AbstractSqlDialect.LIKE_CASE_INSENSITIVE_OPS.has(op);
         const ph = this.addValue(ctx.values, wrappedVal);
@@ -512,7 +534,11 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
     }
     appendInNin(ctx, field, op, val) {
-        this.appendFieldSql(ctx, field, this.formatIn(ctx, Array.isArray(val) ? val : [], op === '$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}`);
+        }
+        this.appendFieldSql(ctx, field, this.formatIn(ctx, val, op === '$nin'));
     }
     /**
      * Build a comparison condition for a JSON field.
@@ -588,29 +614,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      * {@link jsonCompareMode} for why each mode exists.
      */
     jsonComparand(jsonField, value) {
-        return this.jsonCompareMode(value) === 'numeric' ? this.numericCast(jsonField) : jsonField;
-    }
-    /**
-     * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
-     * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
-     * compared in the representation every engine agrees on:
-     * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
-     *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
-     * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
-     *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
-     * - `text` - compare as extracted, which is also what the string operators need.
-     *
-     * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
-     */
-    jsonCompareMode(value) {
-        const operands = Array.isArray(value) ? value : [value];
-        if (operands.length === 0) {
-            return 'text';
-        }
-        if (operands.every((operand) => typeof operand === 'boolean')) {
-            return 'json';
-        }
-        return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
+        return jsonCompareMode(value) === 'numeric' ? this.numericCast(jsonField) : jsonField;
     }
     /**
      * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
@@ -638,7 +642,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         // only when *every* operand needs it - the same all-operands rule the comparison classifier uses.
         if (isOperatorOnlyObject(match)) {
             const entries = Object.entries(match);
-            const asJson = !this.jsonScalarElemKeepsType && entries.every(([op, val]) => this.isJsonbOp(op, val));
+            const asJson = !this.jsonScalarElemKeepsType && entries.every(([op, val]) => isJsonbOp(op, val));
             const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
             const conditions = entries.map(([op, val]) => this.buildJsonFieldCondition(ctx, () => this.jsonElemRef(alias, undefined, asJson), '', op, val, asJson));
             return jsonElemExists(this.jsonElemFrom(jsonField, [], alias, asJson), conditions);
@@ -653,28 +657,11 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
         const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
         const conditions = buildElemMatchConditions(match, (field, op, opVal) => {
-            const asJson = this.isJsonbOp(op, opVal);
+            const asJson = isJsonbOp(op, opVal);
             return this.buildJsonFieldCondition(ctx, (f) => this.jsonElemRef(alias, f, asJson), field, op, opVal, asJson);
         });
         return jsonElemExists(this.jsonElemFrom(jsonField, Object.keys(match), alias), conditions);
     }
-    /**
-     * Whether the operator reads the JSON *value* instead of its text form. The array operators always
-     * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
-     * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
-     * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
-     * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
-     *
-     * Numbers stay on the text accessor with a numeric cast ({@link jsonComparand}), which keeps
-     * `1` equal to `1.0` - JSON equality would not.
-     */
-    isJsonbOp(op, value) {
-        if (op === '$all' || op === '$size' || op === '$elemMatch') {
-            return true;
-        }
-        const comparesValue = op === '$eq' || op === '$ne' || op === '$in' || op === '$nin';
-        return comparesValue && this.jsonCompareMode(value) === 'json';
-    }
     /**
      * A JSON-encoded bound parameter, cast to the dialect's JSON type. Only the positional-placeholder
      * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
@@ -856,51 +843,17 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         return direction;
     }
     /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
-    static comparisonOpMap = new Map([
-        ['$eq', '='],
-        ['$ne', '<>'],
-        ['$gt', '>'],
-        ['$gte', '>='],
-        ['$lt', '<'],
-        ['$lte', '<='],
-    ]);
     havingCondition(ctx, expr, condition) {
         if (typeof condition !== 'object' || condition === null) {
-            ctx.append(`${expr} = `);
-            ctx.addValue(condition);
+            this.appendOperatorCondition(ctx, expr, '$eq', condition);
             return;
         }
         const ops = condition;
-        const keys = getKeys(ops);
-        keys.forEach((op, i) => {
+        getKeys(ops).forEach((op, i) => {
             if (i > 0)
                 ctx.append(' AND ');
-            const val = ops[op];
-            if (op === '$between') {
-                const [min, max] = val;
-                ctx.append(`${expr} BETWEEN `);
-                ctx.addValue(min);
-                ctx.append(' AND ');
-                ctx.addValue(max);
-            }
-            else if (op === '$in' || op === '$nin') {
-                ctx.append(`${expr}${this.formatIn(ctx, Array.isArray(val) ? val : [], op === '$nin')}`);
-            }
-            else if (op === '$isNull') {
-                ctx.append(`${expr}${val ? ' IS NULL' : ' IS NOT NULL'}`);
-            }
-            else if (op === '$isNotNull') {
-                ctx.append(`${expr}${val ? ' IS NOT NULL' : ' IS NULL'}`);
-            }
-            else if (op === '$ne') {
-                ctx.append(this.neExpr(expr, this.addValue(ctx.values, val)));
-            }
-            else {
-                const sqlOp = AbstractSqlDialect.comparisonOpMap.get(op);
-                if (!sqlOp)
-                    throw TypeError(`unsupported HAVING operator: ${op}`);
-                ctx.append(`${expr} ${sqlOp} `);
-                ctx.addValue(val);
+            if (!this.appendOperatorCondition(ctx, expr, op, ops[op])) {
+                throw TypeError(`unsupported HAVING operator: ${op}`);
             }
         });
     }
@@ -1008,14 +961,25 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      */
     upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);
-        const updateCtx = this.createContext();
+        const updateCtx = this.upsertUpdateBindsInPlace ? ctx : this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, this.upsertExcluded);
         const keys = this.getUpsertConflictPathsStr(meta, conflictPaths);
         const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
         this.appendInsertValues(ctx, entity, payload);
         ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
-        ctx.pushValue(...updateCtx.values);
+        if (updateCtx !== ctx) {
+            ctx.pushValue(...updateCtx.values);
+        }
     }
+    /**
+     * Whether the upsert's update assignments can bind straight into the statement's own context.
+     *
+     * They cannot on a `?`-placeholder dialect: the assignments are built before the insert but read
+     * after it, so their values have to be pushed afterwards to land in the right positional order.
+     * A `$n` placeholder carries its own index, so there is nothing to reorder - but it also cannot use
+     * the scratch context, whose numbering would restart at `$1` and collide with the insert's.
+     */
+    upsertUpdateBindsInPlace = false;
     /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
     upsertExcluded = (columnName) => `EXCLUDED.${columnName}`;
     getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, callback) {
@@ -1089,6 +1053,95 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
         return isVectorFieldType(type) ? 'vector' : 'plain';
     }
+    /**
+     * Which of an entity's columns need decoding on READ, and how: the inverse of {@link persistKind},
+     * cached per entity for the same reason it classifies per column. A 1000-row read of a 10-field
+     * entity otherwise asks `isJsonType` (which lowercases a string on every call) 10,000 times to get
+     * the same ten answers. Most entities land here for their numeric columns alone, where the per-row
+     * cost is one `typeof` against a value the driver usually decoded already.
+     *
+     * Dialect-aware exactly like {@link supportedVectorType}, because it has to be: a `sparsevec` field
+     * is written as a plain dense vector everywhere but Postgres, so reading it back by the field's own
+     * declared cast would look for a sparse literal that was never stored.
+     *
+     * A type lands here rather than at the driver when the wire type alone cannot decide it, and only
+     * the declaration can: `Boolean` is 0/1 in a SQLite INTEGER and a MySQL `TINYINT(1)`, both
+     * indistinguishable from a genuine small integer; a decimal is text from pg *and* mysql2, and only
+     * the field says it was meant as a number; and `type: BigInt` shares BIGINT with `type: Number`, so
+     * the wire decode has to be undone for it. All are no-ops where the driver already decoded.
+     *
+     * Classified through the same `isNumericType`/`isBooleanType`/`isJsonType` the rest of the library
+     * uses, not against the constructors: `type` accepts a string logical type for every one of these
+     * (`@Field({ type: 'decimal' })`), and matching `=== Number` alone left those reading back as text.
+     */
+    hydratableFields(entity) {
+        const cached = this.hydratable.get(entity);
+        if (cached) {
+            return cached;
+        }
+        const decoded = [];
+        for (const [key, field] of Object.entries(getMeta(entity).fields)) {
+            const kind = this.hydrateKind(field);
+            if (kind) {
+                decoded.push([key, kind]);
+            }
+        }
+        this.hydratable.set(entity, decoded);
+        return decoded;
+    }
+    /**
+     * The same classification for an aggregate row. Not cached, because these columns are a shape of the
+     * query rather than of the entity, and it is computed once per call either way.
+     *
+     * Mirrors `QueryAggregateFnResult`, which is the contract callers already compile against:
+     * `$count`/`$sum`/`$avg` are a number whatever they aggregate, while `$min`/`$max` and every
+     * `$group` column keep the aggregated field's own type, so they decode as that field would. Without
+     * it a `$sum` over a BIGINT column came back as `'500'` from a result type that says `number`, since
+     * Postgres widens that sum to NUMERIC and no driver can know it was meant as a JS number.
+     */
+    hydratableAggregates(entity, q) {
+        const { fields } = getMeta(entity);
+        const decoded = [];
+        for (const entry of parseGroupMap(q.$group, q.$agg)) {
+            if (entry.kind === 'fn' && entry.op !== '$min' && entry.op !== '$max') {
+                decoded.push([entry.alias, 'number']);
+                continue;
+            }
+            // `$min`/`$max` read the field they aggregate; a `$group` column is that field. Only `$count`
+            // takes `'*'`, and it went down the numeric path above, so there is always a field to look up.
+            const key = entry.kind === 'fn' ? entry.fieldRef : entry.alias;
+            const kind = this.hydrateKind(fields[key]);
+            if (kind) {
+                decoded.push([entry.alias, kind]);
+            }
+        }
+        return decoded;
+    }
+    /**
+     * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode.
+     *
+     * Ordered for correctness, not for speed - this runs once per entity, cached, never per row. The
+     * one order that is load-bearing is `BigInt` before {@link isNumericType}, which answers true for
+     * `BigInt` as well as `Number`: swap them and every `type: BigInt` property silently decodes to a
+     * JS number again.
+     */
+    hydrateKind(field) {
+        const type = field?.type;
+        if (isJsonType(type)) {
+            return 'json';
+        }
+        if (isVectorFieldType(type)) {
+            return this.supportedVectorType(resolveVectorCast(field));
+        }
+        if (isBooleanType(type)) {
+            return 'boolean';
+        }
+        if (type === BigInt) {
+            return 'bigint';
+        }
+        return isNumericType(type) ? 'number' : undefined;
+    }
+    hydratable = new WeakMap();
     /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
     writePersistableValue(ctx, kind, field, value) {
         if (value instanceof QueryRaw) {
@@ -1218,7 +1271,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         operators.forEach((op, index) => {
             if (index > 0)
                 ctx.append(' AND ');
-            const asJson = this.isJsonbOp(op, value[op]);
+            const asJson = isJsonbOp(op, value[op]);
             const sql = this.buildJsonFieldCondition(ctx, () => accessor(asJson), jsonPath, op, value[op], asJson);
             if (sql) {
                 ctx.append(sql);
@@ -1366,24 +1419,35 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             ctx.append(')');
         }
     }
+    /** The runtime half of {@link QuerySizeComparisonOps}: what a count can sensibly be compared with. */
+    static SIZE_COMPARE_OPS = new Set([
+        '$eq',
+        '$ne',
+        '$gt',
+        '$gte',
+        '$lt',
+        '$lte',
+        '$between',
+    ]);
     /**
-     * Append a single size comparison operator and value to the context.
+     * Append a single size comparison operator and value. No operand: the count expression is already
+     * in the context, so this contributes only the ` <op> <value>` tail.
+     *
+     * Gated on {@link SIZE_COMPARE_OPS} rather than on whatever the shared renderer accepts, because
+     * that renderer also knows `$like`, `$regex` and `$in`, none of which mean anything against a
+     * count. `$size: { $like: 5 }` has to stay the error it always was.
      */
     appendSizeOp(ctx, op, val) {
-        if (op === '$between') {
-            const [min, max] = val;
-            ctx.append(' BETWEEN ');
-            ctx.addValue(min);
-            ctx.append(' AND ');
-            ctx.addValue(max);
-            return;
-        }
-        const sqlOp = AbstractSqlDialect.comparisonOpMap.get(op);
-        if (!sqlOp) {
+        if (!AbstractSqlDialect.SIZE_COMPARE_OPS.has(op)) {
             throw TypeError(`unsupported $size comparison operator: ${op}`);
         }
-        ctx.append(` ${sqlOp} `);
-        ctx.addValue(val);
+        // A COUNT is never NULL, so equality stays plain here instead of taking the shared renderer's
+        // null-safe `$ne` (`IS DISTINCT FROM` on Postgres, `IS NOT` on SQLite). Same rows, shorter SQL.
+        if (op === '$eq' || op === '$ne') {
+            this.appendFieldSql(ctx, undefined, ` ${op === '$eq' ? '=' : '<>'} ${this.addValue(ctx.values, val)}`);
+            return;
+        }
+        this.appendOperatorCondition(ctx, undefined, op, val);
     }
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value) {

package/dist/dialect/hydrateColumn.d.ts

@@ -0,0 +1,16 @@
+import { type VectorCast } from './vectorCast.js';
+/**
+ * How a stored column is decoded on read: the inverse of `AbstractSqlDialect.persistKind`. `json`
+ * parses; a {@link VectorCast} says which literal; `boolean` undoes an engine with no boolean type,
+ * `number` and `bigint` a driver that hands a wide integer or a decimal back as text.
+ */
+export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | VectorCast;
+/**
+ * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
+ * row walk, so classifying a column and decoding it stay one subject in one file.
+ *
+ * Every branch is a no-op on a value the driver already decoded, because which types arrive as text
+ * varies per driver and the entity is the only thing that says what they were meant to be. A value
+ * that does not match its column's format is returned untouched rather than replaced by a guess.
+ */
+export declare function decodeColumn(value: unknown, kind: HydrateKind): unknown;

package/dist/dialect/hydrateColumn.js

@@ -0,0 +1,66 @@
+import { parseVectorLiteral } from './vectorCast.js';
+/**
+ * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
+ * row walk, so classifying a column and decoding it stay one subject in one file.
+ *
+ * Every branch is a no-op on a value the driver already decoded, because which types arrive as text
+ * varies per driver and the entity is the only thing that says what they were meant to be. A value
+ * that does not match its column's format is returned untouched rather than replaced by a guess.
+ */
+export function decodeColumn(value, kind) {
+    if (kind === 'boolean') {
+        // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
+        return typeof value === 'boolean' ? value : Boolean(value);
+    }
+    const text = asText(value);
+    if (kind === 'bigint') {
+        if (typeof value === 'bigint') {
+            return value;
+        }
+        try {
+            // A number, not just text: `type: BigInt` is BIGINT, which the pg pools decode at the wire.
+            return BigInt(text ?? value);
+        }
+        catch {
+            // Not an integer after all (a fractional column declared `bigint`); keep what the driver gave.
+            return value;
+        }
+    }
+    // Everything below decodes text; anything else the driver already returned correctly.
+    if (text === undefined) {
+        return value;
+    }
+    if (kind === 'number') {
+        const decoded = Number(text);
+        return Number.isNaN(decoded) ? value : decoded;
+    }
+    if (kind === 'json') {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            // Keep the original value when the driver returns non-JSON text.
+            return value;
+        }
+    }
+    return parseVectorLiteral(text, kind) ?? value;
+}
+/** Lazy so a consumer that never reads an encoded column never constructs one. */
+let decoder;
+/**
+ * The text a driver returned, or `undefined` when it returned something already decoded.
+ *
+ * Bytes count as text: `bun:sql` hands a MySQL DECIMAL, and any `SUM` over one, back as a `Buffer`,
+ * so a string-only check left those as raw bytes. `TextDecoder` rather than `Buffer.toString`, because
+ * this module is reachable from the browser entry and may not name a Node builtin.
+ */
+function asText(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        decoder ??= new TextDecoder();
+        return decoder.decode(value);
+    }
+    return undefined;
+}

package/dist/dialect/jsonSql.d.ts

@@ -41,3 +41,27 @@ export declare function jsonSetTarget(expr: string, field: FieldOptions | undefi
 export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[]): string;
 /** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
 export declare function jsonElemExists(from: string, conditions: readonly string[]): string;
+/**
+ * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
+ * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
+ * compared in the representation every engine agrees on:
+ * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
+ *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
+ * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
+ *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
+ * - `text` - compare as extracted, which is also what the string operators need.
+ *
+ * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
+ */
+export declare function jsonCompareMode(value: unknown): 'json' | 'numeric' | 'text';
+/**
+ * Whether the operator reads the JSON *value* instead of its text form. The array operators always
+ * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
+ * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
+ * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
+ * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
+ *
+ * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON
+ * equality would not.
+ */
+export declare function isJsonbOp(op: string, value?: unknown): boolean;

package/dist/dialect/jsonSql.js

@@ -54,3 +54,42 @@ export function jsonElemExists(from, conditions) {
     const where = conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '';
     return `EXISTS (SELECT 1 FROM ${from}${where})`;
 }
+/**
+ * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
+ * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
+ * compared in the representation every engine agrees on:
+ * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
+ *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
+ * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
+ *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
+ * - `text` - compare as extracted, which is also what the string operators need.
+ *
+ * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
+ */
+export function jsonCompareMode(value) {
+    const operands = Array.isArray(value) ? value : [value];
+    if (operands.length === 0) {
+        return 'text';
+    }
+    if (operands.every((operand) => typeof operand === 'boolean')) {
+        return 'json';
+    }
+    return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
+}
+/**
+ * Whether the operator reads the JSON *value* instead of its text form. The array operators always
+ * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
+ * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
+ * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
+ * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
+ *
+ * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON
+ * equality would not.
+ */
+export function isJsonbOp(op, value) {
+    if (op === '$all' || op === '$size' || op === '$elemMatch') {
+        return true;
+    }
+    const comparesValue = op === '$eq' || op === '$ne' || op === '$in' || op === '$nin';
+    return comparesValue && jsonCompareMode(value) === 'json';
+}

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -36,6 +36,11 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * payload) has to land after the insert's for a `?`-placeholder driver.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
+    /**
+     * Appended to both branches above. Empty on MySQL, which has no `INSERT ... RETURNING`; MariaDB
+     * 10.5+ has it, and used to restate this whole method just to add it.
+     */
+    protected upsertReturning<E>(_entity: Type<E>): string;
     readonly maxBindValues: number;
     escape(value: unknown): string;
     /**

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -58,17 +58,26 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         const meta = getMeta(entity);
         const updateCtx = this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
+        const returning = this.upsertReturning(entity);
         if (update) {
             this.appendInsertValues(ctx, entity, payload);
-            ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
+            ctx.append(` ON DUPLICATE KEY UPDATE ${update}${returning}`);
             ctx.pushValue(...updateCtx.values);
             return;
         }
         const insertCtx = this.createContext();
         this.appendInsertValues(insertCtx, entity, payload);
         ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
+        ctx.append(returning);
         ctx.pushValue(...insertCtx.values);
     }
+    /**
+     * Appended to both branches above. Empty on MySQL, which has no `INSERT ... RETURNING`; MariaDB
+     * 10.5+ has it, and used to restate this whole method just to add it.
+     */
+    upsertReturning(_entity) {
+        return '';
+    }
     maxBindValues = 65535;
     escape(value) {
         return escapeMysqlSqlLiteral(value);

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type DialectFeatures, type EntityMeta, type FieldOptions, type IndexColumnSchema, type IndexFeature, type IndexSchema, type JsonColumnType, type QueryConflictPaths, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
+import { type DialectFeatures, type EntityMeta, type FieldOptions, type IndexColumnSchema, type IndexFeature, type IndexSchema, type JsonColumnType, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -19,6 +19,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly commitTransactionCommand = "COMMIT";
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly alterColumnStrategy = "separate-clauses";
+    /** `$N` placeholders carry their own index, so the upsert's assignments need no scratch context. */
+    protected readonly upsertUpdateBindsInPlace = true;
     readonly insertIdSource = "returning";
     readonly maxBindValues: number;
     /**
@@ -46,12 +48,6 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected indexInclude(index: IndexSchema): string;
     protected indexTuning(index: IndexSchema): string;
     placeholder(index: number): string;
-    /**
-     * The same statement as the base, binding the assignments into the main context instead of a second
-     * one: `$N` placeholders carry their own index, so the values need not be in statement order, and
-     * computing them first is what keeps `appendInsertValues`' `onInsert` fields out of the update set.
-     */
-    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
     /**
      * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
      * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which