uql-orm 0.67.1 → 0.68.1

package/dist/mssql/mssqlDialect.js

@@ -1,7 +1,7 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
-import { COUNT_ALIAS, JSON_ELEM_ALIAS } from '../dialect/aliases.js';
+import { COUNT_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
-import { jsonPath } from '../dialect/jsonSql.js';
+import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { fieldOptionsToCanonical } from '../schema/canonicalType.js';
@@ -34,12 +34,17 @@ const MSSQL_FEATURES = {
     rowLockOf: true,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
-    partialJsonContainment: false,
-    typedJsonElements: false,
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: false,
 };
+/** The `type` `OPENJSON` reports for the JSON scalar an element is compared with; anything else binds as a string. */
+function openJsonType(value) {
+    if (typeof value === 'number') {
+        return 2;
+    }
+    return typeof value === 'boolean' ? 3 : 1;
+}
 /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
 export class MsSqlDialect extends MergeSqlDialect {
     features = MSSQL_FEATURES;
@@ -234,25 +239,19 @@ export class MsSqlDialect extends MergeSqlDialect {
         return `TRY_CAST(${expr} AS FLOAT)`;
     }
     /**
-     * `JSON_VALUE` returns `NVARCHAR(4000)` and, in the lax mode that is the default, answers NULL
-     * rather than erroring for anything longer - so a long string read through it disappears without a
-     * word. `OPENJSON` has no such bound, so the path is split and its last segment matched as a key.
+     * `OPENJSON` at the path's parent, matching its last segment as a key, in either reading: `JSON_VALUE`
+     * answers NULL for text past 4000 characters, and `JSON_QUERY` for a scalar. A value reads back as
+     * text, which {@link jsonScalarParam} binds its operand as, and an array or object as its own JSON.
      */
-    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        const dot = jsonPathStr.lastIndexOf('.');
-        const parent = dot === -1 ? '$' : `$.${jsonPathStr.slice(0, dot).split('.').map(escapeSingleQuotes).join('.')}`;
-        const leaf = escapeSingleQuotes(jsonPathStr.slice(dot + 1));
+    jsonPathReading(escapedColumn, path) {
+        if (!path) {
+            return escapedColumn;
+        }
+        const dot = path.lastIndexOf('.');
+        const parent = dot === -1 ? '$' : `$.${path.slice(0, dot).split('.').map(escapeSingleQuotes).join('.')}`;
+        const leaf = escapeSingleQuotes(path.slice(dot + 1));
         return `(SELECT ${this.#elem.value} FROM OPENJSON(${escapedColumn}, '${parent}') WHERE ${this.#elem.key} = N'${leaf}')`;
     }
-    /**
-     * The same read as the scalar one. `JSON_QUERY` answers NULL for anything that is not an object or
-     * an array, so it cannot serve the JSON access mode a boolean or a number operand asks for -
-     * `OPENJSON` returns both as text, and {@link jsonScalarParam} binds the operand as the matching
-     * text. An array or object comes back as its own JSON text, which is what `OPENJSON` takes next.
-     */
-    getJsonPathJsonbExpr(escapedColumn, jsonPathStr) {
-        return this.getJsonPathScalarExpr(escapedColumn, jsonPathStr);
-    }
     /**
      * A value compared against a JSON path, which reads back as text, so only a boolean needs spelling as
      * `'true'`; SQL Server has no cast that parses text as JSON.
@@ -286,24 +285,37 @@ export class MsSqlDialect extends MergeSqlDialect {
         }
         return `JSON_QUERY(${this.addValue(ctx, JSON.stringify(value))})`;
     }
-    jsonElemFrom(jsonField, _fields, alias) {
-        return `OPENJSON(${jsonField}) ${alias}`;
+    jsonElemFrom(slot, alias) {
+        return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
+    }
+    /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL. */
+    jsonIsArray(slot) {
+        return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '['`;
     }
-    /** `JSON_VALUE`'s 4000-character bound applies to an element's field, unlike a whole column. */
-    jsonElemRef(alias, field) {
-        return field === undefined
-            ? `${alias}.${this.#elem.value}`
-            : `JSON_VALUE(${alias}.${this.#elem.value}, ${jsonPath(field)})`;
+    /** An object element's `value` is its JSON text, which its fields are paths into. */
+    jsonElemDoc(alias) {
+        return `${alias}.${this.#elem.value}`;
     }
-    jsonAll(ctx, jsonField, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const conditions = value.map((val) => `EXISTS (SELECT 1 FROM OPENJSON(${jsonField}) ${alias} WHERE ${alias}.${this.#elem.value} = ${this.jsonScalarParam(ctx, val)})`);
-        return `(${conditions.join(' AND ')})`;
+    /**
+     * An element of the value's own JSON type: `OPENJSON` reads a string and a number back as the same text,
+     * so the `type` it reports is what tells `'5'` from `5`. A number compares by value, cast on both sides:
+     * text against a numeric parameter converts implicitly, which throws on an element that is no number.
+     */
+    jsonElemEquals(ctx, _slot, alias, value) {
+        const type = `${alias}.${this.#elem.type}`;
+        if (value === null) {
+            return `${type} = 0`;
+        }
+        const elem = this.jsonElemDoc(alias);
+        const param = this.jsonScalarParam(ctx, value);
+        const equal = typeof value === 'number' ? `${this.numericCast(elem)} = ${this.numericCast(param)}` : `${elem} = ${param}`;
+        return `${equal} AND ${type} = ${openJsonType(value)}`;
     }
-    jsonSize(ctx, jsonField, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`(SELECT COUNT(*) FROM OPENJSON(${jsonField}) ${alias})`), value));
+    jsonLength(slot) {
+        return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}))`;
     }
+    /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
+    jsonSortModes = ['numeric', 'text'];
     /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
     jsonSet(ctx, expr, set, _field) {
         for (const [key, value] of Object.entries(set)) {
@@ -323,25 +335,24 @@ export class MsSqlDialect extends MergeSqlDialect {
     }
     /**
      * The surviving elements are re-aggregated into an array and written back whole - there is no
-     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string.
+     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string. Only an
+     * array is rewritten: `JSON_MODIFY` would create an absent key, and any other value stays as it is.
      */
     jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const val = `${alias}.${this.#elem.value}`;
+        const slot = { base: escapedCol, path: key };
+        const val = this.jsonElemDoc(JSON_PULL_ALIAS);
         // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
         // re-encoded from its reported `type` before the array is put back together - concatenated raw,
         // the result is text the engine then refuses to parse as JSON.
-        const encoded = `CASE ${alias}.${this.#elem.type}` +
+        const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
             ` WHEN 0 THEN 'null'` +
             ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
             ` ELSE ${val} END`;
         // `IS NULL OR` because a JSON null element reads back as SQL NULL, and `<>` against one is
         // unknown rather than true - which silently dropped every null from the array it rebuilt.
-        const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM OPENJSON(${escapedCol}, ${jsonPath(key)}) ${alias}` +
+        const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)}` +
             ` WHERE ${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, value)}`;
-        // `JSON_MODIFY` creates a path it does not find, so a `$pull` against an absent key would add an
-        // empty array where the other engines leave the document alone.
-        const path = jsonPath(key);
-        return `CASE WHEN JSON_QUERY(${escapedCol}, ${path}) IS NULL THEN ${expr} ELSE JSON_MODIFY(${expr}, ${path}, JSON_QUERY(COALESCE((${kept}), '[]'))) END`;
+        const pulled = `JSON_MODIFY(${expr}, ${jsonPath(key)}, JSON_QUERY(COALESCE((${kept}), '[]')))`;
+        return `CASE WHEN ${this.jsonIsArray(slot)} THEN ${pulled} ELSE ${expr} END`;
     }
 }

package/dist/mysql/mysqlDialect.d.ts

@@ -1,4 +1,6 @@
+import type { JsonSlot } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
+import type { QueryContext } from '../type/index.js';
 export declare class MySqlDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mysql";
     /**
@@ -6,6 +8,19 @@ export declare class MySqlDialect extends MysqlLikeSqlDialect {
      * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
     protected readonly upsertNewRowAlias = "_uql_new";
-    /** A `SET_VAR` hint, which MySQL reads only in a statement's first `SELECT`. */
+    /**
+     * 26.7 may plan the correlated `JSON_TABLE` as a semijoin materialized once for the whole table, which
+     * answers every row with one row's elements. Verified in `mysqlJsonElemMatch.test.ts`.
+     */
+    protected readonly jsonElemHint = "/*+ NO_SEMIJOIN() */";
+    /**
+     * `JSON_OVERLAPS`, which a multi-valued index serves: verified in `mysqlJsonArrayIndex.test.ts`. It reads
+     * a scalar as an array of one, so the value must be an array.
+     */
+    protected jsonAny(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
+    /**
+     * A `SET_VAR` hint, which MySQL reads only right after the statement's own `SELECT` keyword - before
+     * `DISTINCT`, and never in a subquery - so it is anchored to the start rather than found.
+     */
     protected applySettings(sql: string, settings: readonly string[]): string;
 }

package/dist/mysql/mysqlDialect.js

@@ -7,8 +7,24 @@ export class MySqlDialect extends MysqlLikeSqlDialect {
      * "subject to removal in a future version"; aliasing the inserted row (8.0.19+) is its replacement.
      */
     upsertNewRowAlias = UPSERT_NEW_ROW_ALIAS;
-    /** A `SET_VAR` hint, which MySQL reads only in a statement's first `SELECT`. */
+    /**
+     * 26.7 may plan the correlated `JSON_TABLE` as a semijoin materialized once for the whole table, which
+     * answers every row with one row's elements. Verified in `mysqlJsonElemMatch.test.ts`.
+     */
+    jsonElemHint = '/*+ NO_SEMIJOIN() */';
+    /**
+     * `JSON_OVERLAPS`, which a multi-valued index serves: verified in `mysqlJsonArrayIndex.test.ts`. It reads
+     * a scalar as an array of one, so the value must be an array.
+     */
+    jsonAny(ctx, slot, values) {
+        const overlaps = `JSON_OVERLAPS(${this.jsonValue(slot)}, ${this.addValue(ctx, JSON.stringify(values))})`;
+        return `(${this.jsonIsArray(slot)} AND ${overlaps})`;
+    }
+    /**
+     * A `SET_VAR` hint, which MySQL reads only right after the statement's own `SELECT` keyword - before
+     * `DISTINCT`, and never in a subquery - so it is anchored to the start rather than found.
+     */
     applySettings(sql, settings) {
-        return sql.replace('SELECT ', `SELECT /*+ ${settings.map((setting) => `SET_VAR(${setting})`).join(' ')} */ `);
+        return sql.replace(/^SELECT /, `SELECT /*+ ${settings.map((setting) => `SET_VAR(${setting})`).join(' ')} */ `);
     }
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,5 +1,6 @@
 import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
-import type { EntityMeta, FieldOptions, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
+import type { EntityMeta, FieldOptions, QueryContext, QueryPager, QueryTextSearchOptions, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
 export declare const SQLITE_FEATURES: SqlDialectFeatures;
 export declare class SqliteDialect extends AbstractSqlDialect {
@@ -58,25 +59,25 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).
      */
     protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    protected jsonLength(slot: JsonSlot): string;
+    /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
+    protected jsonElemFrom(slot: JsonSlot, alias: string): string;
+    protected jsonIsArray(slot: JsonSlot): string;
+    /** An object element's `value` is its JSON text, which its fields are paths into. */
+    protected jsonElemDoc(alias: string): string;
     /**
-     * Each element is read back as JSON text through `->` at its own `fullkey`, so it compares
-     * correctly whatever its type. `JSON_EACH`'s `value` column would not: it unquotes strings (`a`
-     * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
+     * A scalar element's `value` is already typed, so a number and a string compare as such. Its JSON form
+     * is read back from the column at the element's own `fullkey`, since `value` flattens a boolean to 0/1.
      */
-    protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
-    protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
-    /** `JSON_EACH` yields both scalar and object elements, so one form covers each case. */
-    protected jsonElemFrom(jsonField: string, _fields: readonly string[], alias: string): string;
-    protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
-    protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
+    protected jsonElemValue(slot: JsonSlot, alias: string, mode: JsonAccessMode): string;
+    /** `JSON_EXTRACT` already answers a number as one, and orders it by value. */
+    protected readonly jsonSortModes: readonly JsonAccessMode[];
+    /** `->` for the JSON value, and `JSON_EXTRACT` for SQLite's own: a number as a number, a string as text. */
+    protected jsonPathReading(escapedColumn: string, path: string, mode: 'json' | 'text'): string;
     protected numericCast(expr: string): string;
     protected jsonCast(operand: string): string;
-    /**
-     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched. Elements are read back
-     * through `->` at their own `fullkey` so each keeps its JSON type - `JSON_EACH`'s `value` would
-     * flatten booleans to 0/1 and stringify objects.
-     */
-    protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
+    /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
+    protected jsonArrayOf(elem: string): string;
     protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, field?: FieldOptions): string;
     /** `[#]` appends, creating the array where it is absent: `JSON_SET`, since Turso's `JSON_INSERT` will not touch an existing array. */
     protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;

package/dist/sqlite/sqliteDialect.js

@@ -1,7 +1,6 @@
 import { AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
-import { JSON_ELEM_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
-import { chainedCall, groupsPerCall, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
+import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
 import { textSearchFields } from '../util/dialect.util.js';
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 /** What SQLite and the engines derived from it have. */
@@ -25,8 +24,6 @@ export const SQLITE_FEATURES = {
     rowLockOf: true,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
-    partialJsonContainment: false,
-    typedJsonElements: true,
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: true,
@@ -126,32 +123,38 @@ export class SqliteDialect extends AbstractSqlDialect {
         ctx.append(`${this.escapedTableName(meta)} MATCH {${columns.join(' ')}} : `);
         ctx.addValue(search.$value);
     }
+    jsonLength(slot) {
+        return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))})`;
+    }
+    /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
+    jsonElemFrom(slot, alias) {
+        return `JSON_EACH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
+    }
+    jsonIsArray(slot) {
+        return `JSON_TYPE(${jsonSlotArgs(slot)}) = 'array'`;
+    }
+    /** An object element's `value` is its JSON text, which its fields are paths into. */
+    jsonElemDoc(alias) {
+        return `${alias}.value`;
+    }
     /**
-     * Each element is read back as JSON text through `->` at its own `fullkey`, so it compares
-     * correctly whatever its type. `JSON_EACH`'s `value` column would not: it unquotes strings (`a`
-     * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
+     * A scalar element's `value` is already typed, so a number and a string compare as such. Its JSON form
+     * is read back from the column at the element's own `fullkey`, since `value` flattens a boolean to 0/1.
      */
-    jsonAll(ctx, jsonField, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const from = this.jsonElemFrom(jsonField, [], alias);
-        const conditions = value.map((val) => jsonElemExists(from, [`${jsonField} -> ${alias}.fullkey = ${this.jsonScalarParam(ctx, val)}`]));
-        return `(${conditions.join(' AND ')})`;
-    }
-    jsonSize(ctx, jsonField, value) {
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSON_ARRAY_LENGTH(${jsonField})`), value));
-    }
-    /** `JSON_EACH` yields both scalar and object elements, so one form covers each case. */
-    jsonElemFrom(jsonField, _fields, alias) {
-        return `JSON_EACH(${jsonField}) ${alias}`;
-    }
-    jsonElemRef(alias, field, asJson = false) {
-        if (field === undefined) {
-            return `${alias}.value`;
+    jsonElemValue(slot, alias, mode) {
+        if (mode === 'json') {
+            return `${slot.base} -> ${alias}.fullkey`;
         }
-        return asJson ? `${alias}.value -> ${jsonPath(field)}` : `JSON_EXTRACT(${alias}.value, ${jsonPath(field)})`;
+        const value = this.jsonElemDoc(alias);
+        return mode === 'numeric' ? this.numericCast(value) : value;
     }
-    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        return `JSON_EXTRACT(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
+    /** `JSON_EXTRACT` already answers a number as one, and orders it by value. */
+    jsonSortModes = ['text'];
+    /** `->` for the JSON value, and `JSON_EXTRACT` for SQLite's own: a number as a number, a string as text. */
+    jsonPathReading(escapedColumn, path, mode) {
+        return mode === 'json'
+            ? `(${escapedColumn} -> ${jsonPath(path)})`
+            : `JSON_EXTRACT(${escapedColumn}, ${jsonPath(path)})`;
     }
     numericCast(expr) {
         return `CAST(${expr} AS REAL)`;
@@ -159,25 +162,18 @@ export class SqliteDialect extends AbstractSqlDialect {
     jsonCast(operand) {
         return `JSON(${operand})`;
     }
-    /**
-     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched. Elements are read back
-     * through `->` at their own `fullkey` so each keeps its JSON type - `JSON_EACH`'s `value` would
-     * flatten booleans to 0/1 and stringify objects.
-     */
-    jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const path = jsonPath(key);
-        const elem = `${escapedCol} -> ${JSON_PULL_ALIAS}.fullkey`;
-        const kept = `SELECT JSON_GROUP_ARRAY(JSON(${elem})) FROM JSON_EACH(${escapedCol}, ${path}) ${JSON_PULL_ALIAS} WHERE ${elem} <> ${this.jsonScalarParam(ctx, value)}`;
-        return `JSON_REPLACE(${expr}, ${path}, (${kept}))`;
+    /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
+    jsonArrayOf(elem) {
+        return `JSON_GROUP_ARRAY(JSON(${elem}))`;
     }
     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);
     }
     /** `[#]` appends, creating the array where it is absent: `JSON_SET`, since Turso's `JSON_INSERT` will not touch an existing array. */
     jsonPush(ctx, expr, push) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', expr, push, this.maxFunctionArgs, '[#]');
+        return jsonSetCall((value) => this.jsonScalarParam(ctx, value), expr, push, this.maxFunctionArgs, '[#]');
     }
     jsonUnset(_ctx, expr, unset) {
-        return jsonRemoveCall('JSON_REMOVE', expr, unset, this.maxFunctionArgs);
+        return jsonRemoveCall(expr, unset, this.maxFunctionArgs);
     }
 }

package/dist/type/dialect.d.ts

@@ -135,10 +135,6 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly orderedUpsertReturning: boolean;
     /** Whether a JSON aggregate takes an `ORDER BY` of its own; where not, a relation's rows keep their derived table's order. */
     readonly orderedJsonAggregates: boolean;
-    /** Whether JSON array containment matches an object element that merely includes the given keys, as `@>` does. */
-    readonly partialJsonContainment: boolean;
-    /** Whether an exploded scalar JSON element keeps its SQL type, as SQLite's `JSON_EACH` does. */
-    readonly typedJsonElements: boolean;
     /** Whether the engine has pgvector's `halfvec` and `sparsevec`; elsewhere both map onto `vector`. */
     readonly narrowVectorTypes: boolean;
     /** Whether an ANN index's tuning `SET` applies only inside a transaction, as `SET LOCAL` does. */

package/dist/type/entity.d.ts

@@ -84,7 +84,7 @@ export type JsonUpdateOp<T = unknown> = {
  */
 type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : IsMany<T> extends true ? never : JsonUpdateOp<T>;
 /** What an update takes beyond the value: `null` to clear an optional member, `raw` SQL, and JSON operators. */
-type UpdateExtra<V> = (undefined extends V ? null : never) | QueryRaw | JsonUpdateOpFor<V>;
+type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | Raw | JsonUpdateOpFor<V>;
 /**
  * What a whole-record write persists: the fields and relations with their declared optionality, a
  * related row's alike, and no methods. Two mapped types, since asking each key costs a conditional.
@@ -97,10 +97,10 @@ export type EntityData<E, F extends keyof E = FieldKey<E>, R extends keyof E = R
 /** A relation's value as its rows' {@link EntityData}. */
 type RelationData<V> = V extends readonly (infer T)[] ? EntityData<T>[] : V extends object ? EntityData<V> : never;
 /** {@link EntityData} made partial, each member also taking its {@link UpdateExtra}. */
-export type UpdatePayload<E, F extends keyof E = FieldKey<E>, R extends keyof E = RelationKey<E>> = {
-    [P in F]?: E[P] | UpdateExtra<E[P]>;
+export type UpdatePayload<E, Raw = QueryRaw, F extends keyof E = FieldKey<E>, R extends keyof E = RelationKey<E>> = {
+    [P in F]?: E[P] | UpdateExtra<E[P], Raw>;
 } & {
-    [P in R]?: E[P] | RelationData<E[P]> | UpdateExtra<E[P]>;
+    [P in R]?: E[P] | RelationData<E[P]> | UpdateExtra<E[P], Raw>;
 };
 /** The key's name where the entity states it, by the `idKey` brand or a conventional name; `never` otherwise. */
 export type NamedIdKey<E> = E extends {
@@ -181,7 +181,10 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     readonly type?: FieldType;
     /** A vector column's dimensions: `@Field({ type: 'vector', dimensions: 1536 })`. */
     readonly dimensions?: number;
-    /** The metric a vector search on this field uses unless it names its own `$distance`; `'cosine'` by default. */
+    /**
+     * The metric a vector search on this field uses unless it names its own `$distance`; by default its
+     * vector index's metric, else `'cosine'`.
+     */
     readonly distance?: VectorDistance;
     /** The entity this column is a foreign key to. */
     readonly references?: EntityGetter;
@@ -445,10 +448,12 @@ export type IndexJsonPath = {
     readonly path: string;
     /** How the value is read, matching what the queries over it compare against. */
     readonly type: FieldType;
+    /** Length of a string value, which MySQL keys as `CHAR(n)` and so requires. */
+    readonly length?: number;
 };
 /**
- * MySQL's multi-valued index, one key per element of the JSON array at `path`, what `$all` and
- * `$elemMatch` containment use; refused on any other engine.
+ * MySQL's multi-valued index, one key per element of the JSON array at `path`, which `$all` and an
+ * `$elemMatch` on one value or several use; refused on any other engine.
  * @example `@Index((user) => [{ column: user.tags, jsonArray: { type: String, length: 64 } }])`
  */
 export type IndexJsonArray = {

package/dist/type/query.d.ts

@@ -37,7 +37,7 @@ export type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {
  * Accepted `$select` value: a field map, or raw SQL projections built with `raw()`
  * (e.g. ``[raw`*`, raw`LOG10(points)`.as('score')]``). The raw form is SQL-only.
  */
-export type QuerySelectValue<E> = QuerySelect<E> | readonly QueryRaw[];
+export type QuerySelectValue<E, Raw = QueryRaw> = QuerySelect<E> | readonly Raw[];
 /**
  * Fields to exclude from the query result - `{ name: true }` blacklists fields.
  * Mutually exclusive with positive field selections in `$select`.
@@ -46,8 +46,8 @@ export type QueryExclude<E> = QuerySelect<E>;
 /**
  * relation population map.
  */
-export type QueryPopulate<E, R extends keyof E = RelationKey<E>> = {
-    [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
+export type QueryPopulate<E, Raw = QueryRaw, R extends keyof E = RelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K], Raw>;
 };
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
@@ -59,8 +59,8 @@ export declare const COUNT_RESULT_KEY = "_count";
  * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes
  * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.
  */
-export type QueryCount<E, R extends keyof E = ToManyRelationKey<E>> = {
-    [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
+export type QueryCount<E, Raw = QueryRaw, R extends keyof E = ToManyRelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>, Raw>;
 };
 /**
  * query conflict paths - subset of field keys used to detect upsert conflicts.
@@ -69,7 +69,7 @@ export type QueryConflictPaths<E> = QuerySelect<E, FieldKey<E>, true>;
 /**
  * Options to populate a relation declared as `V`, by its cardinality.
  */
-export type QueryPopulateRelationOptions<V> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>> : QueryUnique<RelationTarget<V>> & {
+export type QueryPopulateRelationOptions<V, Raw = QueryRaw> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>, Raw> : QueryUnique<RelationTarget<V>, Raw> & {
     $required?: boolean;
 };
 /**
@@ -158,24 +158,24 @@ export type QueryPager = {
 /**
  * Which rows a statement addresses.
  */
-export type QueryFilter<E> = {
+export type QueryFilter<E, Raw = QueryRaw> = {
     /**
      * filtering options.
      */
-    $where?: QueryWhere<E>;
+    $where?: QueryWhere<E, Raw>;
 };
 /**
  * A filter plus the page `count` takes. No `$sort`: ordering picks *which* rows a page holds, never
  * how many, so a count that accepted one would promise an influence it cannot have.
  */
-export type QueryPage<E> = QueryFilter<E> & QueryPager;
+export type QueryPage<E, Raw = QueryRaw> = QueryFilter<E, Raw> & QueryPager;
 /**
  * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the
  * rows they address with a SELECT first, so the page is portable rather than MySQL-only, and a
  * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the
  * projection list to hold the distance. `$lock` stays off these, declared on {@link Query} instead.
  */
-export type QuerySearch<E> = QueryPage<E> & {
+export type QuerySearch<E, Raw = QueryRaw> = QueryPage<E, Raw> & {
     /**
      * sorting options.
      */
@@ -184,21 +184,21 @@ export type QuerySearch<E> = QueryPage<E> & {
 /**
  * query options.
  */
-export type Query<E> = {
+export type Query<E, Raw = QueryRaw> = {
     /**
      * field selection - `{ name: true }` whitelists fields, or raw SQL projections
      * (``[raw`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).
      * Mutually exclusive with `$exclude`.
      */
-    $select?: QuerySelectValue<E>;
+    $select?: QuerySelectValue<E, Raw>;
     /**
      * relation population options.
      */
-    $populate?: QueryPopulate<E>;
+    $populate?: QueryPopulate<E, Raw>;
     /**
      * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.
      */
-    $count?: QueryCount<E>;
+    $count?: QueryCount<E, Raw>;
     /**
      * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
      * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
@@ -227,7 +227,7 @@ export type Query<E> = {
     /**
      * filtering options.
      */
-    $where?: QueryWhere<E>;
+    $where?: QueryWhere<E, Raw>;
     /**
      * Index from where start the search
      */
@@ -237,6 +237,11 @@ export type Query<E> = {
      */
     $limit?: number;
 };
+/**
+ * A {@link Query} as it travels as JSON, which a `raw` SQL fragment cannot: what the browser client takes,
+ * and what an RPC contract (tRPC, oRPC, TanStack Start) declares as its input.
+ */
+export type WireQuery<E> = Query<E, never>;
 /**
  * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
  * check alike; `satisfies` keeps them in step with `Query`.
@@ -262,36 +267,36 @@ type RelationClause = (typeof QUERY_OBJECT_CLAUSES | typeof QUERY_NUMBER_CLAUSES
  * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot
  * drift, and a clause added to {@link Query} stays off it until it joins one of them.
  */
-export type RelationQuery<E = object> = Pick<Query<E>, RelationClause> & {
+export type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, RelationClause> & {
     $required?: boolean;
 };
 /**
  * options to get a single record.
  */
-export type QueryOne<E> = Except<Query<E>, '$limit'>;
+export type QueryOne<E, Raw = QueryRaw> = Except<Query<E, Raw>, '$limit'>;
 /**
  * options to get an unique record.
  */
-export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$populate' | '$where'>;
+export type QueryUnique<E, Raw = QueryRaw> = Pick<QueryOne<E, Raw>, '$select' | '$exclude' | '$populate' | '$where'>;
 /**
  * The clauses that shape a row, captured as key sets rather than maps: a naked type parameter skips
  * excess-property checks, while a key set fails its own constraint on a typo.
  * @internal
  */
-type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
-    $select?: QuerySelect<E, S, V> | readonly QueryRaw[];
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>, Raw = QueryRaw> = {
+    $select?: QuerySelect<E, S, V> | readonly Raw[];
     $exclude?: QuerySelect<E, X, V>;
-    $populate?: QueryPopulate<E, P>;
-    $count?: QueryCount<E, C & ToManyRelationKey<E>>;
+    $populate?: QueryPopulate<E, Raw, P>;
+    $count?: QueryCount<E, Raw, C & ToManyRelationKey<E>>;
 };
 /**
  * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = Query<E> & QueryProjection<E, S, V, X, P, C>;
+export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = Query<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
 /**
  * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = QueryOne<E> & QueryProjection<E, S, V, X, P, C>;
+export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = QueryOne<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
 /**
  * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every
  * field minus what `$select` or `$exclude` subtracts, plus the populated relations.