uql-orm 0.67.0 → 0.68.0

package/dist/dialect/hydrateColumn.js

@@ -1,54 +1,57 @@
 import { decodeWideNumber } from '../util/wideNumber.js';
-import { parseVectorLiteral } from './vectorCast.js';
+import { decodeFloat32s, parseVectorLiteral } from './vectorCast.js';
 /**
  * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
  * and untouched where it does not match its column's format.
  */
 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);
-    }
-    if (kind === 'date') {
-        return typeof value === 'string' ? (parseDate(value) ?? value) : value;
-    }
-    if (kind === 'bytes') {
-        return typeof value === 'string' && value.startsWith(BYTES_PREFIX)
-            ? hexBytes(value.slice(BYTES_PREFIX.length))
-            : value;
-    }
-    const text = asText(value);
-    if (kind === 'bigint') {
+    return DECODERS[kind](value);
+}
+/** A decoder of the text a driver returned; anything else it already decoded, and is kept. */
+function fromText(decode) {
+    return (value) => {
+        const text = asText(value);
+        return text === undefined ? value : decode(text, value);
+    };
+}
+/** A vector's text in the literal its cast writes, or its packed float32s in hex, which MariaDB reads. */
+function vectorDecoder(cast) {
+    return fromText((text, value) => text.startsWith(BYTES_PREFIX)
+        ? decodeFloat32s(hexBytes(text.slice(BYTES_PREFIX.length)))
+        : (parseVectorLiteral(text, cast) ?? value));
+}
+const DECODERS = {
+    // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
+    boolean: (value) => (typeof value === 'boolean' ? value : Boolean(value)),
+    date: (value) => (typeof value === 'string' ? (parseDate(value) ?? value) : value),
+    // Only a string can be bytes that crossed JSON: bytes a driver already decoded stay as they are.
+    bytes: (value) => typeof value === 'string' && value.startsWith(BYTES_PREFIX) ? hexBytes(value.slice(BYTES_PREFIX.length)) : value,
+    // A number too, not just text: `type: BigInt` is BIGINT, which the pg pools decode at the wire.
+    bigint: (value) => {
         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);
+            return BigInt(asText(value) ?? Number(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') {
-        return decodeWideNumber(text);
-    }
-    if (kind === 'json') {
+    },
+    number: fromText(decodeWideNumber),
+    json: fromText((text, value) => {
         try {
             return JSON.parse(text);
         }
         catch {
-            // Keep the original value when the driver returns non-JSON text.
             return value;
         }
-    }
-    return parseVectorLiteral(text, kind) ?? value;
-}
+    }),
+    vector: vectorDecoder('vector'),
+    halfvec: vectorDecoder('halfvec'),
+    sparsevec: vectorDecoder('sparsevec'),
+};
 /**
  * An ISO 8601 timestamp as a `Date`, its fraction cut to the milliseconds one holds, and a bare date at
  * local midnight, which is how `pg` reads a `date`. `undefined` for text that is neither.

package/dist/dialect/jsonSql.d.ts

@@ -1,10 +1,22 @@
 import type { FieldOptions, FieldType } from '../type/index.js';
 /**
- * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
- * such as `[#]` or `[*]`. Shared across dialects unchanged: no dialect escapes a JSON path key
- * differently from an ANSI string literal.
+ * A `'$.a.b'` JSON path literal, each dot-separated segment escaped, and `'$'` for an empty path, the
+ * document itself. `suffix` appends an accessor such as `[#]` or `[*]`. Shared across dialects
+ * unchanged: no dialect escapes a JSON path key differently from an ANSI string literal.
  */
 export declare function jsonPath(path: string, suffix?: string): string;
+/** A JSON value a condition reads: `path` of the JSON in `base`, `''` for all of it. */
+export type JsonSlot = {
+    readonly base: string;
+    readonly path: string;
+};
+/** `base, '$.a.b'`, how `JSON_EACH`, `OPENJSON` and the like take the value at `slot`: no path for the whole document. */
+export declare function jsonSlotArgs({ base, path }: JsonSlot): string;
+/**
+ * {@link jsonSlotArgs} reading a NULL document where `isArray` does not hold, for a function that would
+ * otherwise walk a scalar, or an object's values, as if they were elements.
+ */
+export declare function jsonArraySlotArgs({ base, path }: JsonSlot, isArray: string): string;
 /** How many argument groups of `size` fit in one call beside its target, under `maxArgs`. */
 export declare function groupsPerCall(maxArgs: number, size: number): number;
 /**
@@ -14,37 +26,34 @@ export declare function groupsPerCall(maxArgs: number, size: number): number;
  */
 export declare function chainedCall(fn: string, target: string, groups: readonly string[], size: number, maxArgs: number): string;
 /**
- * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`, nested past `maxArgs`. `pathSuffix` appends an
- * accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
- * `jsonScalarParam` bound to its `QueryContext`.
+ * `JSON_SET(target, path, value, ...)`, which MySQL and SQLite share, nested past `maxArgs`. `pathSuffix`
+ * appends an accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`.
  */
-export declare function jsonAssignCall(bindValue: (value: unknown) => string, fn: string, target: string, entries: Record<string, unknown>, maxArgs: number, pathSuffix?: string): string;
+export declare function jsonSetCall(bindValue: (value: unknown) => string, target: string, entries: Record<string, unknown>, maxArgs: number, pathSuffix?: string): string;
 /** The `$set` target: a nullable column needs a `COALESCE` fallback to build on. */
 export declare function jsonSetTarget(expr: string, field: FieldOptions | undefined, empty: string): string;
+/** `JSON_REMOVE(expr, path, ...)`, which MySQL and SQLite share, nested past `maxArgs`. */
+export declare function jsonRemoveCall(expr: string, keys: readonly string[], maxArgs: number): string;
 /**
- * `FN(expr, path, ...)` - the multi-path JSON removal shape shared by MySQL's `JSON_REMOVE` and
- * SQLite's `json_remove`, nested past `maxArgs`.
+ * `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. `hint` is
+ * an optimizer hint the subquery opens with, if any.
  */
-export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[], maxArgs: number): 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;
+export declare function jsonElemExists(from: string, conditions: readonly string[], hint: string): string;
 /**
  * How a JSON value is read out of its document: as the JSON value itself, as a number to compare
- * against, or as the text a path yields. One vocabulary for every operand of a comparison, so the
- * left side is read the way the right side is compared - see {@link jsonCompareMode}.
+ * against, or as the text a path yields. One vocabulary for both sides of a comparison, so a path is
+ * read the way its operand is compared - see {@link jsonCompareMode}.
  */
 export type JsonAccessMode = 'json' | 'numeric' | 'text';
 /**
- * How a JSON scalar compares against `value`, since extraction yields text: `numeric` casts (so `1` equals
- * `1.0`), `json` compares JSON values (the only portable boolean), and `text` compares as extracted,
- * also for mixed operands.
+ * How a JSON path compares for equality against `value`: `numeric` casts (so `1` equals `1.0`), `json`
+ * compares JSON values (the only portable boolean), and `text` compares as extracted, also for mixed
+ * operands.
  */
 export declare function jsonCompareMode(value: unknown): JsonAccessMode;
 /** The mode a declared type asks for, {@link jsonCompareMode}'s twin: an index over a path is reached only by a comparison extracting it alike. */
 export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
-/**
- * Whether the operator reads the JSON value rather than its text: the array operators, and equality
- * against a boolean, which no cast recovers portably from text.
- */
-export declare function isJsonbOp(op: string, value?: unknown): boolean;
+/** Whether `value` asks for more than JSON containment: an operator map anywhere in it. */
+export declare function holdsOperator(value: unknown): boolean;
+/** A value an array element is matched to by JSON containment: a string, a finite number or a boolean. */
+export declare function isJsonScalar(value: unknown): value is string | number | boolean;

package/dist/dialect/jsonSql.js

@@ -1,13 +1,26 @@
+import { isOperatorMap } from '../util/dialect.util.js';
 import { columnFamily } from '../util/field.util.js';
+import { isOperatorKey, someKey } from '../util/object.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 /**
- * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
- * such as `[#]` or `[*]`. Shared across dialects unchanged: no dialect escapes a JSON path key
- * differently from an ANSI string literal.
+ * A `'$.a.b'` JSON path literal, each dot-separated segment escaped, and `'$'` for an empty path, the
+ * document itself. `suffix` appends an accessor such as `[#]` or `[*]`. Shared across dialects
+ * unchanged: no dialect escapes a JSON path key differently from an ANSI string literal.
  */
 export function jsonPath(path, suffix = '') {
-    const segments = path.split('.').map(escapeSingleQuotes).join('.');
-    return `'$.${segments}${suffix}'`;
+    const segments = path && `.${path.split('.').map(escapeSingleQuotes).join('.')}`;
+    return `'$${segments}${suffix}'`;
+}
+/** `base, '$.a.b'`, how `JSON_EACH`, `OPENJSON` and the like take the value at `slot`: no path for the whole document. */
+export function jsonSlotArgs({ base, path }) {
+    return path ? `${base}, ${jsonPath(path)}` : base;
+}
+/**
+ * {@link jsonSlotArgs} reading a NULL document where `isArray` does not hold, for a function that would
+ * otherwise walk a scalar, or an object's values, as if they were elements.
+ */
+export function jsonArraySlotArgs({ base, path }, isArray) {
+    return jsonSlotArgs({ base: `CASE WHEN ${isArray} THEN ${base} END`, path });
 }
 /** How many argument groups of `size` fit in one call beside its target, under `maxArgs`. */
 export function groupsPerCall(maxArgs, size) {
@@ -27,35 +40,33 @@ export function chainedCall(fn, target, groups, size, maxArgs) {
     return call;
 }
 /**
- * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`, nested past `maxArgs`. `pathSuffix` appends an
- * accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
- * `jsonScalarParam` bound to its `QueryContext`.
+ * `JSON_SET(target, path, value, ...)`, which MySQL and SQLite share, nested past `maxArgs`. `pathSuffix`
+ * appends an accessor per key (SQLite's `[#]` append). Values bind in key order through `bindValue`.
  */
-export function jsonAssignCall(bindValue, fn, target, entries, maxArgs, pathSuffix = '') {
+export function jsonSetCall(bindValue, target, entries, maxArgs, pathSuffix = '') {
     const pairs = Object.entries(entries).map(([key, value]) => `${jsonPath(key, pathSuffix)}, ${bindValue(value)}`);
-    return chainedCall(fn, target, pairs, 2, maxArgs);
+    return chainedCall('JSON_SET', target, pairs, 2, maxArgs);
 }
 /** The `$set` target: a nullable column needs a `COALESCE` fallback to build on. */
 export function jsonSetTarget(expr, field, empty) {
     return field?.nullable === false ? expr : `COALESCE(${expr}, ${empty})`;
 }
+/** `JSON_REMOVE(expr, path, ...)`, which MySQL and SQLite share, nested past `maxArgs`. */
+export function jsonRemoveCall(expr, keys, maxArgs) {
+    return chainedCall('JSON_REMOVE', expr, keys.map((key) => jsonPath(key)), 1, maxArgs);
+}
 /**
- * `FN(expr, path, ...)` - the multi-path JSON removal shape shared by MySQL's `JSON_REMOVE` and
- * SQLite's `json_remove`, nested past `maxArgs`.
+ * `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. `hint` is
+ * an optimizer hint the subquery opens with, if any.
  */
-export function jsonRemoveCall(fn, expr, keys, maxArgs) {
-    return chainedCall(fn, expr, keys.map((key) => jsonPath(key)), 1, maxArgs);
-}
-/** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
-export function jsonElemExists(from, conditions) {
+export function jsonElemExists(from, conditions, hint) {
     const where = conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '';
-    return `EXISTS (SELECT 1 FROM ${from}${where})`;
+    return `EXISTS (SELECT ${hint && `${hint} `}1 FROM ${from}${where})`;
 }
 /**
- * How a JSON scalar compares against `value`, since extraction yields text: `numeric` casts (so `1` equals
- * `1.0`), `json` compares JSON values (the only portable boolean), and `text` compares as extracted,
- * also for mixed operands.
+ * How a JSON path compares for equality against `value`: `numeric` casts (so `1` equals `1.0`), `json`
+ * compares JSON values (the only portable boolean), and `text` compares as extracted, also for mixed
+ * operands.
  */
 export function jsonCompareMode(value) {
     const operands = Array.isArray(value) ? value : [value];
@@ -75,14 +86,14 @@ export function jsonTypeMode(type) {
     }
     return family === 'boolean' ? 'json' : 'text';
 }
-/**
- * Whether the operator reads the JSON value rather than its text: the array operators, and equality
- * against a boolean, which no cast recovers portably from text.
- */
-export function isJsonbOp(op, value) {
-    if (op === '$all' || op === '$size' || op === '$elemMatch') {
-        return true;
+/** Whether `value` asks for more than JSON containment: an operator map anywhere in it. */
+export function holdsOperator(value) {
+    if (Array.isArray(value)) {
+        return value.some(holdsOperator);
     }
-    const comparesValue = op === '$eq' || op === '$ne' || op === '$in' || op === '$nin';
-    return comparesValue && jsonCompareMode(value) === 'json';
+    return isOperatorMap(value) && someKey(value, (key) => isOperatorKey(key) || holdsOperator(value[key]));
+}
+/** A value an array element is matched to by JSON containment: a string, a finite number or a boolean. */
+export function isJsonScalar(value) {
+    return typeof value === 'string' || typeof value === 'boolean' || Number.isFinite(value);
 }

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,5 +1,6 @@
-import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, SqlDialectFeatures, Type } from '../type/index.js';
+import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QueryTextSearchOptions, SqlDialectFeatures, Type } from '../type/index.js';
 import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from './abstractSqlDialect.js';
+import { type JsonSlot } from './jsonSql.js';
 /** What the MySQL-family engines have. */
 export declare const MYSQL_FEATURES: SqlDialectFeatures;
 /** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
@@ -63,13 +64,15 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     protected jsonObject(pairs: DerivedRelation['pairs']): string;
     /**
      * A number and bytes cross JSON as text, where JSON would round the one and spell the other as base64,
-     * and a vector as the engine reads one back: text on MariaDB, which stores it packed.
+     * and a vector as the engine reads one back: its packed bytes on MariaDB.
      */
     protected readonly carriedFields: {
         numeric: (expr: string) => string;
         blob: (expr: string) => string;
         vector: (expr: string, field: FieldOptions) => string;
     };
+    /** Bytes as the hex text `decodeColumn` reads back, whole. */
+    protected bytesAsText(expr: string): string;
     escape(value: unknown): string;
     /**
      * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
@@ -77,17 +80,9 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * `@Index((post) => [...], { type: 'fulltext' })`.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /** `DOUBLE`, never a bare `DECIMAL`, which is `DECIMAL(10,0)` and rounds `1.4` to `1`. */
     protected numericCast(expr: string): string;
     protected neExpr(field: string, ph: string): string;
-    /** How a surviving element is fed back into the array a `$pull` rebuilds. */
-    protected jsonPullElem(alias: string): string;
-    /** Condition keeping the elements a `$pull` does *not* remove, given the bound pulled value. */
-    protected jsonPullKeep(alias: string, operand: string): string;
-    /**
-     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched, which is what makes `$pull`
-     * a no-op there. The subquery reads the column, so its value binds exactly once.
-     */
-    protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
     /**
      * Omitting the `COALESCE` on a NOT NULL column keeps MySQL's partial in-place JSON update
      * applicable: it requires the target column as the direct `JSON_SET` input.
@@ -99,20 +94,21 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * second reference for the array source and returns NULL on MariaDB for an absent key.
      */
     protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
-    protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
     /**
-     * MySQL's `->`/`->>` take a full JSON path (`'$.a.b'`, never a bare key) and only apply to a
-     * column reference, so the whole dotted path goes into a single accessor instead of the base's
-     * chained `col->'a'->>'b'`, which the server rejects with "Invalid JSON path expression".
+     * `->` for the value and `->>` for its text, each taking the whole path (`'$.a.b'`): a bare key, as
+     * Postgres chains them, is "Invalid JSON path expression" here.
      */
-    protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
-    protected getJsonPathJsonbExpr(escapedColumn: string, jsonPathStr: string): string;
-    protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
-    protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
+    protected jsonPathReading(escapedColumn: string, path: string, mode: 'json' | 'text'): string;
+    /** `JSON_CONTAINS` of the array as the path reads it, which is what a multi-valued index is matched by. */
+    protected jsonContains(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
+    protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
+    /** Only an array's, where `JSON_LENGTH` counts a scalar as 1 and an object by its keys. */
+    protected jsonLength(slot: JsonSlot): string;
+    protected jsonIsArray(slot: JsonSlot): string;
     /**
-     * `JSON_TABLE` with its columns declared up front. A scalar element reads as `JSON` where `asJson`,
-     * since `TEXT` reads a nested array as `NULL`.
+     * Each element of the array at the path as one `JSON` column, which any path then reads the way it reads
+     * a column's document.
      */
-    protected jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
-    protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
+    protected jsonElemFrom(slot: JsonSlot, alias: string): string;
+    protected jsonElemDoc(alias: string): string;
 }

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -2,9 +2,9 @@ import { getMeta } from '../entity/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';
+import { COUNT_ALIAS } from './aliases.js';
 import { BYTES_PREFIX } from './hydrateColumn.js';
-import { jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
+import { jsonSetCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
 import { aggregatesRelations } from './queryJoins.js';
 /**
  * The largest `BIGINT UNSIGNED`: the row count MySQL's manual gives for "all rows from the offset on",
@@ -32,12 +32,12 @@ export const MYSQL_FEATURES = {
     rowLockOf: true,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
-    partialJsonContainment: true,
-    typedJsonElements: false,
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: false,
 };
+/** The one `JSON_TABLE` column an exploded array reads each element through, as a JSON document. */
+const ELEM_COLUMN = 'v';
 /** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
 export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     features = MYSQL_FEATURES;
@@ -156,13 +156,17 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     }
     /**
      * A number and bytes cross JSON as text, where JSON would round the one and spell the other as base64,
-     * and a vector as the engine reads one back: text on MariaDB, which stores it packed.
+     * and a vector as the engine reads one back: its packed bytes on MariaDB.
      */
     carriedFields = {
         numeric: (expr) => `CAST(${expr} AS CHAR)`,
-        blob: (expr) => `CONCAT(${this.escape(BYTES_PREFIX)}, HEX(${expr}))`,
+        blob: (expr) => this.bytesAsText(expr),
         vector: (expr, field) => this.selectFieldExpr(expr, field),
     };
+    /** Bytes as the hex text `decodeColumn` reads back, whole. */
+    bytesAsText(expr) {
+        return `CONCAT(${this.escape(BYTES_PREFIX)}, HEX(${expr}))`;
+    }
     escape(value) {
         return escapeMysqlSqlLiteral(value);
     }
@@ -177,36 +181,20 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         ctx.addValue(search.$value);
         ctx.append(')');
     }
+    /** `DOUBLE`, never a bare `DECIMAL`, which is `DECIMAL(10,0)` and rounds `1.4` to `1`. */
     numericCast(expr) {
-        return `CAST(${expr} AS DECIMAL)`;
+        return `CAST(${expr} AS DOUBLE)`;
     }
     neExpr(field, ph) {
         // MySQL/MariaDB null-safe inequality: true when values differ or one side is NULL.
         return `NOT (${field} <=> ${ph})`;
     }
-    /** How a surviving element is fed back into the array a `$pull` rebuilds. */
-    jsonPullElem(alias) {
-        return `${alias}.v`;
-    }
-    /** Condition keeping the elements a `$pull` does *not* remove, given the bound pulled value. */
-    jsonPullKeep(alias, operand) {
-        return `${alias}.v <> ${operand}`;
-    }
-    /**
-     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched, which is what makes `$pull`
-     * a no-op there. The subquery reads the column, so its value binds exactly once.
-     */
-    jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const elements = `JSON_TABLE(${escapedCol}, ${jsonPath(key, '[*]')} COLUMNS (v JSON PATH '$')) ${JSON_PULL_ALIAS}`;
-        const kept = `SELECT COALESCE(JSON_ARRAYAGG(${this.jsonPullElem(JSON_PULL_ALIAS)}), JSON_ARRAY()) FROM ${elements} WHERE ${this.jsonPullKeep(JSON_PULL_ALIAS, this.jsonScalarParam(ctx, value))}`;
-        return `JSON_REPLACE(${expr}, ${jsonPath(key)}, (${kept}))`;
-    }
     /**
      * Omitting the `COALESCE` on a NOT NULL column keeps MySQL's partial in-place JSON update
      * applicable: it requires the target column as the direct `JSON_SET` input.
      */
     jsonSet(ctx, expr, set, field) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', jsonSetTarget(expr, field, `'{}'`), set, this.maxFunctionArgs);
+        return jsonSetCall((value) => this.jsonScalarParam(ctx, value), jsonSetTarget(expr, field, `'{}'`), set, this.maxFunctionArgs);
     }
     /**
      * `JSON_MERGE_PRESERVE` concatenates arrays and creates absent keys, so every pushed key is
@@ -217,40 +205,35 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         const entries = Object.entries(push).map(([key, value]) => `'${escapeSingleQuotes(key)}', JSON_ARRAY(${this.jsonScalarParam(ctx, value)})`);
         return `JSON_MERGE_PRESERVE(${expr}, JSON_OBJECT(${entries.join(', ')}))`;
     }
-    jsonUnset(_ctx, expr, unset) {
-        return jsonRemoveCall('JSON_REMOVE', expr, unset, this.maxFunctionArgs);
-    }
     /**
-     * MySQL's `->`/`->>` take a full JSON path (`'$.a.b'`, never a bare key) and only apply to a
-     * column reference, so the whole dotted path goes into a single accessor instead of the base's
-     * chained `col->'a'->>'b'`, which the server rejects with "Invalid JSON path expression".
+     * `->` for the value and `->>` for its text, each taking the whole path (`'$.a.b'`): a bare key, as
+     * Postgres chains them, is "Invalid JSON path expression" here.
      */
-    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        return `(${escapedColumn}->>${jsonPath(jsonPathStr)})`;
+    jsonPathReading(escapedColumn, path, mode) {
+        return mode === 'json' ? `${escapedColumn}->${jsonPath(path)}` : `(${escapedColumn}->>${jsonPath(path)})`;
     }
-    getJsonPathJsonbExpr(escapedColumn, jsonPathStr) {
-        return `${escapedColumn}->${jsonPath(jsonPathStr)}`;
+    /** `JSON_CONTAINS` of the array as the path reads it, which is what a multi-valued index is matched by. */
+    jsonContains(ctx, slot, values) {
+        return `JSON_CONTAINS(${this.jsonValue(slot)}, ${this.addValue(ctx, JSON.stringify(values))})`;
+    }
+    jsonUnset(_ctx, expr, unset) {
+        return jsonRemoveCall(expr, unset, this.maxFunctionArgs);
     }
-    jsonAll(ctx, jsonField, value) {
-        return `JSON_CONTAINS(${jsonField}, ${this.addValue(ctx, JSON.stringify(value))})`;
+    /** Only an array's, where `JSON_LENGTH` counts a scalar as 1 and an object by its keys. */
+    jsonLength(slot) {
+        return `CASE WHEN ${this.jsonIsArray(slot)} THEN JSON_LENGTH(${this.jsonValue(slot)}) END`;
     }
-    jsonSize(ctx, jsonField, value) {
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSON_LENGTH(${jsonField})`), value));
+    jsonIsArray(slot) {
+        return `JSON_TYPE(${this.jsonValue(slot)}) = 'ARRAY'`;
     }
     /**
-     * `JSON_TABLE` with its columns declared up front. A scalar element reads as `JSON` where `asJson`,
-     * since `TEXT` reads a nested array as `NULL`.
+     * Each element of the array at the path as one `JSON` column, which any path then reads the way it reads
+     * a column's document.
      */
-    jsonElemFrom(jsonField, fields, alias, asJson = false) {
-        const columns = fields.length
-            ? fields.map((field) => `${this.escapeId(field, true)} TEXT PATH ${jsonPath(field)}`).join(', ')
-            : `elem_text ${asJson ? 'JSON' : 'TEXT'} PATH '$'`;
-        return `JSON_TABLE(${jsonField}, '$[*]' COLUMNS (${columns})) AS ${alias}`;
+    jsonElemFrom(slot, alias) {
+        return `JSON_TABLE(${slot.base}, ${jsonPath(slot.path, '[*]')} COLUMNS (${ELEM_COLUMN} JSON PATH '$')) AS ${alias}`;
     }
-    jsonElemRef(alias, field, asJson = false) {
-        const ref = field === undefined ? `${alias}.elem_text` : `${alias}.${this.escapeId(field, true)}`;
-        // `JSON_TABLE` columns stay `TEXT` so the string operators keep working; the JSON form reads
-        // that text back as JSON.
-        return asJson ? this.jsonCast(ref) : ref;
+    jsonElemDoc(alias) {
+        return `${alias}.${ELEM_COLUMN}`;
     }
 }

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,10 +1,13 @@
-import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type SqlDialectFeatures, type Type } from '../type/index.js';
+import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
 import type { DialectOptions } from './abstractDialect.js';
 import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
+import { type JsonAccessMode, type JsonSlot } from './jsonSql.js';
 /** A Postgres-wire dialect's options: the base's, and how its driver binds a parameter. */
 export type PgLikeDialectOptions = DialectOptions & {
     readonly driverCapabilities?: Partial<DriverCapabilities>;
 };
+/** Each metric's pgvector distance operator, and the infix of the operator class its index is built with. */
+export declare const PG_VECTOR_METRICS: ReadonlyMap<VectorDistance, VectorMetric>;
 /** What the Postgres-wire engines have. */
 export declare const PG_FEATURES: SqlDialectFeatures;
 /** What Postgres and CockroachDB share: JSONB, full-text search, pgvector's operators, and the upsert. */
@@ -40,10 +43,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected readonly upsertUpdateBindsInPlace = true;
     readonly insertIdSource = "returning";
     readonly maxBindValues: number;
-    readonly vectorMetrics: ReadonlyMap<import("../type/vector.js").VectorDistance, {
-        readonly op: string;
-        readonly opsSuffix: string;
-    }>;
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /**
      * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
@@ -63,19 +63,26 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * rejects anything unparseable - including a plain two-word search.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
-    protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
-    protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
-    /**
-     * Object elements stay `jsonb` so each field can pick `->` or `->>`. Scalar elements are exploded
-     * as text unless they are compared as JSON, where `_text` would yield `text = jsonb`.
-     */
-    protected jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
-    protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
+    protected jsonContains(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
+    protected jsonLength(slot: JsonSlot): string;
+    /** Each element stays `jsonb`, so it is read as any path is: `->` for the value, `->>` for its text. */
+    protected jsonElemFrom(slot: JsonSlot, alias: string): string;
+    protected jsonIsArray(slot: JsonSlot): string;
+    /** The array at `slot`, NULL where the value there is none: the array functions fail the whole read on one. */
+    private jsonArray;
+    protected jsonElemDoc(alias: string): string;
+    /** `->` down the path and `->>` for its text, the document's own text being `#>> '{}'`. */
+    protected jsonPathReading(escapedColumn: string, path: string, mode: 'json' | 'text'): string;
+    /** A number only where the value is one: the cast throws on any other text, failing the whole read. */
+    jsonPathExpr(escapedColumn: string, path: string, mode: JsonAccessMode): string;
     protected get regexpOp(): string;
     protected readonly caseInsensitiveMatch = "ilike";
     protected get neOp(): string;
-    /** One array parameter, which a context that inlines values has none of: it lists them instead. */
-    protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean): string;
+    /**
+     * One array parameter, which a context that inlines values has none of: it lists them instead. The
+     * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.
+     */
+    protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean, bind: (value: unknown) => string): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;
     /**
@@ -84,8 +91,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], field?: FieldOptions): void;
     /**
-     * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
-     * ORDINALITY` keeps the surviving elements in their original order.
+     * `create_if_missing => false` keeps an absent key (and a NULL column) untouched, and a value that is no
+     * array is set back as it is; `WITH ORDINALITY` keeps the surviving elements in their original order.
      */
     protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
     /**