uql-orm 0.67.1 → 0.68.1

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,6 +1,6 @@
-import { type ColumnFamily, type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPage, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type ColumnFamily, type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPage, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
-import { type JsonAccessMode } from './jsonSql.js';
+import { type JsonAccessMode, type JsonSlot } from './jsonSql.js';
 import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
@@ -171,8 +171,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected selectModifier<E>(_q: Query<E>): string;
     /**
      * The expression a scalar field is read through in the statement's own rows, the plain column by
-     * default. MariaDB reads a vector column back with `VEC_ToText`, since selecting it raw yields its
-     * binary form. A related row's column crosses JSON through {@link carriedFields} instead.
+     * default. MariaDB reads a vector column back as hex, since selecting it raw yields its binary form.
+     * A related row's column crosses JSON through {@link carriedFields} instead.
      */
     protected selectFieldExpr(escapedColumn: string, _field: FieldOptions): string;
     /**
@@ -224,6 +224,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** Renders a `$where` tree without applying entity filters (used for same-scope group-operator recursion). */
     protected renderWhere<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
     compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
+    /** Conditions joined by `AND`, parenthesized where there is more than one. */
+    private static conjunction;
     protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: QueryGroupOp, val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
     /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
     private readonly escapedColumns;
@@ -231,11 +233,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** What a `$near` says about the search itself; everything else in it is a bound. */
     private static readonly VECTOR_QUERY_KEYS;
     /**
-     * The runtime half of {@link QueryVectorNear}'s bounds, derived from the map above rather than
-     * spelled again: both are `QueryOrderedOp`, so `$near` can never accept a comparison the renderer
-     * below has no operator for.
+     * The ordered comparisons, `QueryOrderedOp` at runtime, derived from the map above rather than spelled
+     * again: {@link QueryVectorNear}'s bounds, so `$near` never accepts one the renderer has no operator
+     * for, and the operators that read a JSON path as a number.
      */
-    private static readonly NEAR_BOUND_OPS;
+    private static readonly ORDERED_OPS;
+    /** The operators an equality compares by value, which a JSON path reads the way that value compares. */
+    private static readonly EQUALITY_OPS;
     /**
      * Every `$like`-family operator: the pattern it wraps its value in, and whether it ignores case.
      * Each case-sensitive operator is paired here with the `$i` twin that shares its pattern, so the
@@ -269,51 +273,69 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
      */
     private inlinedOperand;
-    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
+    /** {@link fieldCondition}, appended. */
     compareFieldOperator<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: string, val: unknown, opts?: QueryOptions): void;
+    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
+    private fieldCondition;
     /**
      * `<operand> <op> <value>` for every operator that needs only its left-hand SQL, shared by a column, a
-     * `HAVING` expression and a `$size` count; `undefined` for the rest.
-     */
-    protected operatorCondition(ctx: QueryContext, operand: string, op: string, val: unknown): string | undefined;
-    /** {@link operatorCondition}, appended; `false` when `op` needs more than an operand. */
-    protected appendOperatorCondition(ctx: QueryContext, operand: string, op: string, val: unknown): boolean;
-    /**
-     * Build a comparison condition for a JSON field.
-     * Used by both `$elemMatch` and dot-notation paths.
-     * All dialect-specific behavior comes from overridable methods on `this`.
-     */
-    protected buildJsonFieldCondition(ctx: QueryContext, fieldAccessor: (path: string, mode: JsonAccessMode) => string, jsonPath: string, op: string, value: unknown, asJson?: boolean): string;
-    private jsonInNin;
-    /** The bound operand of a JSON comparison: JSON-encoded when comparing against the JSON value. */
-    protected jsonOperand(ctx: QueryContext, value: unknown, asJson: boolean): string;
-    /** `$all`: the JSON array at `jsonField` contains every value (also serves element containment). */
-    protected abstract jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
-    /** `$size`: the length of the JSON array at `jsonField`, compared against `value`. */
-    protected abstract jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
-    /**
-     * The JSON array at `jsonField` as rows, the `FROM` of an `EXISTS`, under a fresh `alias` so a nested
-     * one cannot shadow it. `fields` are an object element's keys (MySQL lists them up front), empty for
-     * scalars, which `asJson` reads as JSON rather than text.
-     */
-    protected abstract jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
-    /**
-     * References an exploded element under `alias` (the same one passed to the {@link jsonElemFrom}
-     * call it explodes): the element itself, or one `field` of it. `asJson` asks for the JSON-valued
-     * form instead of the text one - see {@link isJsonbOp} for when that matters.
-     */
-    protected abstract jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
-    /**
-     * `$elemMatch`: an element satisfies `match`. Operator keys test a scalar element; a plain object is
-     * containment, which an index can serve; anything else tests each exploded object's fields.
-     */
-    protected jsonElemMatch(ctx: QueryContext, jsonField: string, match: Record<string, unknown>): string;
-    /**
-     * How a `$elemMatch` reads one exploded element: {@link jsonPathExpr}'s counterpart, over a column
-     * of the derived table rather than a path of the document. An empty field names the element itself,
-     * which is what the operator-only form matches on.
-     */
-    private elemAccessor;
+     * JSON path, a `HAVING` expression, a count and a distance; `undefined` for the rest. `bind` renders
+     * each compared value, a plain placeholder unless a JSON path reads it otherwise.
+     */
+    protected operatorCondition(ctx: QueryContext, operand: string, op: string, val: unknown, bind?: (value: unknown) => string): string | undefined;
+    /** `$all`, `$size` and `$elemMatch`, which read the JSON array at `slot`; `undefined` for the rest. */
+    private jsonArrayCondition;
+    /** A path of a JSON document, read the way each operator reads it. */
+    private jsonPathTarget;
+    /** Every operator `target` is compared with, `AND`-joined. */
+    private jsonConditions;
+    private jsonCondition;
+    /**
+     * How `op` reads a JSON value: an ordered comparison as a number, an equality as its operand compares,
+     * and a pattern or a null check as text.
+     */
+    private static jsonOperatorMode;
+    /** A bound operand of a JSON comparison, read the way `mode` reads the value it is compared with. */
+    private jsonOperand;
+    /** The JSON value at `slot`, as an array operator reads it. */
+    protected jsonValue(slot: JsonSlot): string;
+    /**
+     * `$all`: the JSON array at `slot` has an element holding each value, as Postgres's `@>` and MySQL's
+     * `JSON_CONTAINS` read one: a scalar equal, an array each of its elements, an object each of its keys.
+     * Plain JSON goes to {@link jsonContains}; an operator anywhere in it is matched element by element.
+     */
+    private jsonAll;
+    /** `$all` over plain JSON, which an engine with containment of its own spells natively, for an index to serve. */
+    protected jsonContains(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
+    /** One `EXISTS` per value, over the elements of the array at `slot`: a scalar equal, anything else held. */
+    private jsonElemsHold;
+    /**
+     * What the JSON `target` reads satisfies to hold `value`: an array each of its elements, an object each
+     * of its keys as a path, and an operator map or a scalar compared as a path is.
+     */
+    private jsonHolds;
+    /** An element of the array at `slot` equal to `value`, both read as JSON. */
+    protected jsonElemEquals(ctx: QueryContext, slot: JsonSlot, alias: string, value: unknown): string;
+    /** The JSON array at `slot` contains at least one of `values`, each as `$all` reads it. */
+    protected jsonAny(ctx: QueryContext, slot: JsonSlot, values: readonly unknown[]): string;
+    /** How many elements the JSON array at `slot` has, which `$size` compares. */
+    protected abstract jsonLength(slot: JsonSlot): string;
+    /** Whether the value at `slot` is a JSON array: the array operators match, and `$pull` changes, no other. */
+    protected abstract jsonIsArray(slot: JsonSlot): string;
+    /** The JSON array at `slot` as one row per element under `alias`, the `FROM` of an `EXISTS`. */
+    protected abstract jsonElemFrom(slot: JsonSlot, alias: string): string;
+    /** An exploded element as a JSON document, which its fields are paths into. */
+    protected abstract jsonElemDoc(alias: string): string;
+    /** An element of the array at `slot` itself, read the way `mode` reads a path: its document, or its root. */
+    protected jsonElemValue(_slot: JsonSlot, alias: string, mode: JsonAccessMode): string;
+    /**
+     * `$elemMatch`: an element holds `match`, as `$all` reads one value, its operators testing the element
+     * itself. An element equal to one value, or to one of several, is containment whatever the operator
+     * says, which compares by JSON type and is what an array index serves.
+     */
+    protected jsonElemMatch(ctx: QueryContext, slot: JsonSlot, match: Record<string, unknown>): string;
+    /** The optimizer hint a `$elemMatch` subquery opens with, where the engine plans one wrong without it. */
+    protected readonly jsonElemHint: string;
     /**
      * 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.
@@ -337,10 +359,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private collectSortTerms;
     /**
-     * The `ORDER BY` operand for one key. A key that is not a field of `meta` - a `raw()` projection, a
-     * `$select` alias - is an output alias, which is never table-qualified and needs no resolving.
+     * The `ORDER BY` operands for one key: a JSON path's in each of {@link jsonSortModes}. A key that is
+     * not a field of `meta` - a `raw()` projection, a `$select` alias - is an output alias, which is never
+     * table-qualified and needs no resolving.
+     */
+    private sortColumns;
+    /**
+     * How a JSON path is sorted by: as the JSON value, which the engine orders by type and a number by its
+     * value. An engine that orders JSON as text reads a number first, then the text.
      */
-    private sortColumn;
+    protected readonly jsonSortModes: readonly JsonAccessMode[];
     /**
      * `LIMIT`/`OFFSET`. `sorted` says whether an `ORDER BY` was emitted just before, which
      * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
@@ -392,7 +420,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected having(ctx: QueryContext, having: QueryHavingMap, emittedColumns: Record<string, string>): void;
     private static readonly SORT_DIRECTION_MAP;
     private resolveSortDirection;
-    /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
+    /** Every operator of one `HAVING` condition, `AND`-joined. */
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     /**
      * How many rows the filter matched, on every row of the page. A window function runs before
@@ -495,8 +523,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * `escapedCol` rather than the accumulated expression, values bind once, in key order.
      */
     protected jsonPull(ctx: QueryContext, expr: string, escapedCol: string, pull: Record<string, unknown>): string;
-    /** Wrap `expr` so the array at `key` no longer contains `value`. */
-    protected abstract jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
+    /**
+     * Wrap `expr` so the array at `key` no longer contains `value`: the array rebuilt from the elements that
+     * differ from it, and any other value put back as it is. `JSON_REPLACE` leaves an absent key, and a NULL
+     * column, untouched.
+     */
+    protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
+    /** The elements a `$pull` keeps, back in one array, and an empty one where it keeps none. */
+    protected jsonArrayOf(elem: string): string;
+    /** Whether an element is not the pulled value, both read as JSON. */
+    protected jsonDiffers(elem: string, operand: string): string;
     /** Shallow assignment of top-level keys, matching PostgreSQL's `jsonb || jsonb`. */
     protected abstract jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, field?: FieldOptions): string;
     /** Append one value per array key, creating the array when the key is absent. */
@@ -513,37 +549,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     getRawValue(ctx: QueryContext, opts: QueryRawFnOptions & {
         value: QueryRaw;
     }): void;
-    /**
-     * Resolves a dot-notation key to its JSON field metadata.
-     * Shared by `where()` and `sort()` to detect 'column.path' keys where 'column' is a JSON/JSONB field.
-     *
-     * @returns resolved metadata or `undefined` if the key is not a JSON dot-notation path
-     */
-    protected resolveJsonDotPath<E>(meta: EntityMeta<E>, key: string, prefix?: string): {
-        jsonPath: string;
-        column: string;
-    } | undefined;
+    /** A `column.path` key of `meta`'s JSON field as the path it names, shared by `where` and `sort`; else `undefined`. */
+    protected resolveJsonDotPath<E>(meta: EntityMeta<E>, key: string, prefix?: string): JsonSlot | undefined;
     /**
      * One JSON path, read the way `mode` asks for: the one place the three readings are chosen between,
      * so `$where`, `$sort` and every operator reach a path the same way. Public because a JSON index
      * is matched back by its own text, so the migrator's `CREATE INDEX` has to spell it from here too.
      */
-    jsonPathExpr(escapedColumn: string, jsonPath: string, mode: JsonAccessMode): string;
-    /**
-     * Compare a JSONB dot-notation path, e.g. `'settings.isArchived': { $ne: true }`.
-     * Receives a pre-resolved `resolveJsonDotPath` result to avoid redundant computation.
-     */
-    protected compareJsonPath(ctx: QueryContext, resolved: {
-        jsonPath: string;
-        column: string;
-    }, val: unknown): void;
-    /**
-     * Returns SQL that extracts a scalar value from a JSON path.
-     * Dialects can override this to customize path access syntax while preserving
-     * the shared comparison/operator pipeline.
-     */
-    protected getJsonPathScalarExpr(escapedColumn: string, jsonPath: string): string;
-    protected getJsonPathJsonbExpr(escapedColumn: string, jsonPath: string): string;
+    jsonPathExpr(escapedColumn: string, path: string, mode: JsonAccessMode): string;
+    /** A path of the JSON in `escapedColumn`, `''` for the document itself, as its JSON value or its text. */
+    protected abstract jsonPathReading(escapedColumn: string, path: string, mode: 'json' | 'text'): string;
     /**
      * Normalizes a raw WHERE value into an operator map.
      * Arrays become `$in`, operator maps pass through, everything else becomes `$eq`.
@@ -624,23 +639,18 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, relKey: string, sizeVal: number | QuerySizeComparisonOps, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /**
-     * `<expr> <op> <value>` for each operator, AND-joined and parenthesized when there is more than
-     * one. `exprFn` is re-run per operator because what it appends is an expression, not a column:
-     * a `WHERE` has no output alias to refer back to, so the only way to compare it twice is to spell
-     * it twice. Shared by `$size`, which counts, and `$near`, which measures a distance.
+     * `<expr> <op> <value>` for each bound, `AND`-joined. `expr` is spelled once per bound because it is an
+     * expression, not a column: a `WHERE` has no output alias to refer back to. Shared by `$size`, which
+     * counts, and `$near`, which measures a distance.
      */
-    private buildExprComparison;
+    private boundConditions;
     /**
-     * Build a complete `$size` comparison expression.
-     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `JSONB_ARRAY_LENGTH("col")`)
+     * A count compared with `size`, a number or its bounds. A count is never NULL, so its equality stays
+     * plain rather than the null-safe `$ne` (`IS DISTINCT FROM`, `IS NOT`): same rows, shorter SQL.
      */
-    protected buildSizeComparison(ctx: QueryContext, sizeExprFn: () => void, sizeVal: number | QuerySizeComparisonOps): void;
+    private sizeCondition;
     /** `<distance> <op> ?`, the `$where` half of a vector search, its bounds checked here since `/http` input is untyped. */
-    protected compareVectorNear<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, near: QueryVectorNear): void;
-    /** The runtime half of {@link QuerySizeComparisonOps}: what a count can sensibly be compared with. */
-    private static readonly SIZE_COMPARE_OPS;
-    /** ` <op> <value>` after a count already written, refusing any operator a count cannot be compared with. */
-    private appendSizeOp;
+    private vectorNearCondition;
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value: unknown): string;
     protected get regexpOp(): string;
@@ -658,8 +668,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected get neOp(): string;
     protected neExpr(field: string, ph: string): string;
-    /** `operand IN (...)` binding each value, or the constant an empty set reduces to: no value is in it. */
-    protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean): string;
+    /** `operand IN (...)` of each value as `bind` renders it, or the constant an empty set reduces to: no value is in it. */
+    protected formatIn(_ctx: QueryContext, operand: string, values: unknown[], negate: boolean, bind: (value: unknown) => string): string;
     /** Reads extracted JSON text as a number, which every engine spells its own way. */
     protected abstract numericCast(expr: string): string;
     toString(): string;