uql-orm 0.56.0 → 0.57.0

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,5 +1,5 @@
-import { type EntityData, type EntityMeta, 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 QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
-import { type ParentPartition } from '../util/index.js';
+import { type EntityData, type EntityMeta, 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 QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type ColumnFamily } from '../util/field.util.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
 import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
@@ -17,6 +17,68 @@ type InsertShape<E> = {
 };
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
 type HydratableField = readonly [string, HydrateKind];
+/** A sort term of a relation's rows as their aggregate orders by it: the column carrying it out. */
+export type SortRef = {
+    readonly ref: string;
+    readonly direction: string;
+};
+/**
+ * One column of a read's projection: the key its row answers under, none for a raw expression written
+ * without an alias, and whether `sql` already answers under it, being a column of that very name.
+ */
+export type SelectTerm = {
+    readonly sql: string;
+    readonly key?: string;
+    readonly bare?: boolean;
+};
+/** What a read selected, and for a relation's rows, the columns carrying their sort terms out. */
+export type ReadProjection = {
+    readonly terms: readonly SelectTerm[];
+    readonly order?: readonly SortRef[];
+};
+/**
+ * A read's options as its statement takes them: the caller's and the alias its table reads as. A
+ * relation's rows read inside the parent's statement cross JSON, and where their aggregate orders them,
+ * carry their sort terms out as columns.
+ */
+type ReadOptions = QueryOptions & {
+    readonly alias?: string;
+    readonly json?: boolean;
+    readonly carried?: boolean;
+};
+/**
+ * A projection's options: the alias its columns are qualified by, whether its values cross JSON, and
+ * whether it is a joined row's, which keeps its id.
+ */
+type SelectOptions = {
+    readonly prefix?: string;
+    readonly json?: boolean;
+    readonly joined?: boolean;
+};
+/** A to-many's rows as the parent's statement reads them: an ordinary read of the related entity. */
+export type RelationRows = {
+    readonly entity: Type<object>;
+    readonly query: Query<object>;
+    readonly alias: string;
+    readonly joins: QueryJoins;
+    /** Whether the parent deduplicates its rows, which compares this value with the rest. */
+    readonly distinct: boolean;
+};
+/**
+ * A relation's rows as a derived table: `from` is the table clause, `pairs` each key of a row with the
+ * column holding it, and `order` what their aggregate orders them by.
+ */
+export type DerivedRelation = {
+    readonly from: string;
+    readonly pairs: readonly (readonly [key: string, sql: string])[];
+    readonly order: string;
+};
+/** How each column family's value is spelled to cross JSON: see {@link AbstractSqlDialect.carriedFields}. */
+export type CarriedFields = {
+    readonly [F in ColumnFamily]?: (expr: string, field: FieldOptions) => string;
+};
+/** The key a term answers under in a populated relation's row, which a raw expression has only once aliased. */
+export declare function relationTermKey({ sql, key }: SelectTerm): string;
 export type { HydrateKind };
 export declare abstract class AbstractSqlDialect extends VectorSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
@@ -60,19 +122,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * `insertMany` splits larger batches into multiple statements based on this limit.
      */
     readonly maxBindValues: number;
-    getBeginTransactionStatements(isolationLevel?: IsolationLevel): string[];
     /**
-     * Every parent's own bounded page in one statement: a subquery per parent, each filtered to that
-     * parent alone and carrying its own `ORDER BY`, `LIMIT` and `OFFSET`. Universal, and reads
-     * `parents x (skip + limit)` rows where a `ROW_NUMBER` window reads every matching child.
-     * [The design](../../../../architecture/populate-limits.md).
-     *
-     * Each branch is a wrapped derived table rather than a bare parenthesised select: SQLite rejects
-     * `ORDER BY`/`LIMIT` on the latter, and the wrapper costs nothing elsewhere.
+     * The most arguments one SQL function call takes. A variadic call past it, a wide relation row or JSON
+     * update, is spread over nested calls. No cap binds unless a dialect declares one.
      */
-    findPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, partition: ParentPartition): void;
-    /** The shape {@link findPerParent} emits, which the Postgres family replaces with a `LATERAL` join. */
-    protected appendPerParent<E extends object>(ctx: QueryContext, entity: Type<E>, q: Query<E>, { joins, parents }: ParentPartition): void;
+    readonly maxFunctionArgs: number;
+    getBeginTransactionStatements(isolationLevel?: IsolationLevel): string[];
     createContext(): QueryContext;
     /**
      * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
@@ -118,16 +173,32 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     returningId<E>(meta: EntityMeta<E>): string;
     /** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
-    search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, joins?: QueryJoins): void;
-    selectFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: QuerySelectOptions, exclude?: QueryExclude<E>): void;
+    search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: ReadOptions, joins?: QueryJoins, order?: readonly SortRef[]): void;
+    /**
+     * A relation's rows ordered by the columns their sort terms were carried out in, where they are
+     * paged: otherwise the aggregate reading them orders them, and sorting them first is wasted work.
+     */
+    private orderCarried;
+    /**
+     * The columns a projection reads: each field under its key, a raw expression under its alias, and
+     * `*` where nothing is left, or every field in a row crossing JSON, which answers only under keys. A
+     * joined row keeps its key, every column of a composite past any subtraction: it is what tells a
+     * matched row from no match.
+     */
+    selectTerms<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: SelectOptions, exclude?: QueryExclude<E>): SelectTerm[];
+    /** One field's column, or the expression an inlined one stands for, as the projection reads it. */
+    private fieldTerm;
+    /** A `raw()` rendered where it stands, without the alias a projection writes for it. */
+    private rawSql;
     /**
      * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
      * not take a zero and which spells "no rows" as `TOP (0)` instead.
      */
     protected selectModifier<E>(_q: Query<E>): string;
     /**
-     * The expression a scalar field is read through, the plain column by default. MariaDB reads a
-     * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
+     * 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.
      */
     protected selectFieldExpr(escapedColumn: string, _field: FieldOptions): string;
     /**
@@ -137,24 +208,43 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * than inheriting another engine's syntax.
      */
     protected appendTextSearch<E>(_ctx: QueryContext, _entity: Type<E>, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
-    select<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, joins?: QueryJoins, totalAlias?: string): void;
+    select<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: ReadOptions, joins?: QueryJoins, totalAlias?: string): ReadProjection;
+    /**
+     * Everything a read's rows answer under, in order: its own fields, each joined row's fields and to-many
+     * relations under its path, its own to-many relations and `$count`, and each vector distance a `$sort`
+     * projects.
+     */
+    protected projection<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts: SelectOptions, joins: QueryJoins): SelectTerm[];
+    /** A term as a projection writes it, aliased unless its SQL already answers under its key. */
+    private termSql;
+    /** The distance each vector `$sort` projects, under the name it asked for. */
+    private selectVectorProjections;
+    /**
+     * A relation's sort terms carried out beside its rows as columns, for the aggregate reading them to
+     * order by: a term that names a column of theirs already is ordered by that one.
+     */
+    private carrySort;
     /**
      * The table as a statement writes it, each part escaped on its own rather than as one dotted
      * string taken apart again by {@link escapeId}.
      */
     protected escapedTableName<E>(meta: EntityMeta<E>): string;
     /**
-     * A FROM or JOIN operand plus the alias to prefix its columns by, aliased only once a schema puts
-     * something in front of the name. See {@link resolveTableAlias} for why the prefix cannot be the
-     * qualified path.
+     * A FROM or JOIN operand plus the alias to prefix its columns by, aliased once a schema puts something
+     * in front of the name, or the read takes an alias of its own. See {@link resolveTableAlias} for why
+     * the prefix cannot be the qualified path.
      */
-    protected tableRef<E>(meta: EntityMeta<E>): {
+    protected tableRef<E>(meta: EntityMeta<E>, alias?: string): {
         alias: string;
         ref: string;
     };
-    /** Columns are alias-qualified once anything else is in play: a join, or a to-many being filled. */
+    /**
+     * Columns are qualified once anything else is in play: an alias of the read's own, a join, or a
+     * relation being read.
+     */
     private resolveRelationAwarePrefix;
-    protected selectRelationFields(ctx: QueryContext, joins: QueryJoins): void;
+    /** Each joined row's columns and to-many relations under its path, which is what unflattens it. */
+    protected selectJoinedRows(ctx: QueryContext, joins: QueryJoins, json: boolean | undefined, distinct: boolean): SelectTerm[];
     protected selectRelationJoins<E>(ctx: QueryContext, meta: EntityMeta<E>, rootAlias: string, joins: QueryJoins): void;
     where<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
     /** Renders a `$where` tree without applying entity filters (used for same-scope group-operator recursion). */
@@ -245,7 +335,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected abstract jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
     /**
      * Explodes the JSON array at `jsonField` into rows, as the `FROM` of an `EXISTS` subquery, under
-     * `alias` (from {@link QueryContext.nextAlias} - a fresh name per call, since `$elemMatch`/`$all`
+     * `alias` (from {@link QueryContext.claimAlias} - a fresh name per call, since `$elemMatch`/`$all`
      * can recurse into this on a nested array and a fixed, reused alias would let the inner occurrence
      * shadow the outer one it needs to correlate against). An empty `fields` means the elements are
      * scalars, in which case `asJson` says whether they are read as JSON or as text; otherwise they
@@ -297,6 +387,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** Appends the `ORDER BY`, reporting whether there was one - which {@link pager} needs on the
      * engines that refuse to page an unordered statement. */
     sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): boolean;
+    /**
+     * The terms of an `ORDER BY`, collected before anything is appended so an unorderable key is reported
+     * instead of half a clause, and because a vector distance is the primary ordering wherever it appears.
+     */
+    private sortTerms;
     /**
      * Walks `$sort` against the metadata of the entity each level addresses, rather than flattening it
      * to dotted strings and reading every key off the root: only that way does a related column resolve
@@ -337,7 +432,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * joined: Postgres refuses a bare `FOR UPDATE` over the nullable side of an outer join outright,
      * and the other engines quietly widen the lock to the joined rows.
      */
-    protected appendLock<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
+    protected appendLock<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, joins?: QueryJoins, alias?: string): void;
     count<E>(ctx: QueryContext, entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): void;
     /**
      * How many rows a `$distinct` read returns, which `COUNT(*)` cannot answer: the deduplication
@@ -377,6 +472,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected readonly totalOverExpr = "COUNT(*) OVER ()";
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    /**
+     * A read's whole statement. The lock is appended here rather than in `search`, which `count`,
+     * `update` and `delete` share: it belongs to a SELECT alone, and every engine spells it last.
+     */
+    protected read<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts: ReadOptions, joins: QueryJoins, totalAlias?: string): ReadProjection;
+    /**
+     * `opts` with the alias the read's table claims: its own name, which needs no alias written, unless
+     * another table of the statement took it first.
+     */
+    private readOptions;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
     /**
      * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
@@ -499,7 +604,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     hydratableAggregates<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>): readonly HydratableField[];
     /**
-     * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode.
+     * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode. A
+     * date and bytes decode because a related row crosses JSON, which spells both as text.
      *
      * `BigInt` is asked first because it shares the numeric family with `Number`: let the switch answer
      * it and every `type: BigInt` property silently decodes to a JS number again.
@@ -545,7 +651,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected abstract jsonUnset(ctx: QueryContext, expr: string, unset: readonly string[]): string;
     getRawValue(ctx: QueryContext, opts: QueryRawFnOptions & {
         value: QueryRaw;
-        autoPrefixAlias?: boolean;
     }): void;
     /**
      * Resolves a dot-notation key to its JSON field metadata.
@@ -591,8 +696,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     private escapedColumnOf;
     private escapedColumnName;
     private escapedColumn;
-    /** As {@link escapedColumn}, but qualified by the query alias when the parent is nested. */
-    private escapedParentColumn;
     /**
      * The single path from a relation operator to its target, so none can emit an unscoped subquery:
      * the target's `$where` is merged with its active filters, making a trashed or out-of-scope row
@@ -600,10 +703,70 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
     private appendRelationSubquery;
+    /**
+     * One equality per key of the parent, anded: a composite correlates on every column, and matching on
+     * part of one would find the rows of a different parent. `parentJoins` keeps the two ends the right
+     * way round, whether the join lands on the junction or on the target.
+     */
+    private correlation;
+    /**
+     * Each to-many a row populates, as a subquery of the statement's select list correlated to `parent`,
+     * the row's alias. [The design](../../../../architecture/relations-in-one-statement.md).
+     */
+    private selectToManyRelations;
+    /** Each relation a read's `$count` tallies, as a correlated count of its select list. */
+    private selectRelationCounts;
+    /**
+     * A to-many's rows as one JSON array: an ordinary read of the related entity under the relation's
+     * name, narrowed to the parent's rows, in the engine's own spelling.
+     */
+    private appendToManyRelation;
+    /**
+     * A relation that deduplicates its rows is sorted only by what it selects: `SELECT DISTINCT` orders by
+     * nothing else, and a column carrying a sort term out would join the set it deduplicates on.
+     */
+    private assertDistinctSort;
+    /**
+     * What makes a relation's row one of the parent's: its foreign key on the parent's key, or, through a
+     * junction, a pairing of the two that the junction's own filters let through.
+     */
+    private appendCorrelation;
+    /**
+     * A junction's rows pairing the parent with the relation's targets, as far as its own filters let them
+     * through, since a soft-deleted link is not a link; and the column naming each row's target.
+     */
+    private junctionRows;
+    /**
+     * A relation's rows as one JSON array, in the engine's own spelling: an aggregate over them read as
+     * a derived table ({@link derivedRelation}), or over the related table itself where the engine cannot
+     * correlate a derived table. [The design](../../../../architecture/relations-in-one-statement.md).
+     */
+    protected abstract appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
+    /**
+     * Whether the engine's JSON aggregate takes an `ORDER BY` of its own. Where it does not, a relation's
+     * rows carry no sort term out and keep their own order, which a derived table hands its aggregate.
+     */
+    protected readonly orderedAggregates: boolean;
+    /**
+     * The rows read as a derived table, their values crossing JSON and, where the aggregate orders, each
+     * sort term carried out beside them for it to order by, since a derived table's order is not promised
+     * past it. The table takes the relation's name, which nothing inside it can see.
+     */
+    protected derivedRelation(ctx: QueryContext, rows: RelationRows): DerivedRelation;
+    /**
+     * How each column family crosses JSON inside its parent's statement, where JSON would round it or
+     * cannot spell it: as text, which the field's hydrate kind decodes back, and bytes as `\x` and hex,
+     * the `BYTES_PREFIX`. A family missing here crosses as it is.
+     */
+    protected readonly carriedFields: CarriedFields;
+    /** `expr` as it crosses JSON, by its field's family: see {@link carriedFields}. */
+    private carried;
+    /** `'key', column, ...`: the arguments of a JSON object call over `pairs`. */
+    protected jsonObjectArgs(pairs: DerivedRelation['pairs']): string;
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
-    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, val: QueryWhere<unknown>, rel: RelationMeta, opts: QueryComparisonOptions): void;
+    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, relKey: string, val: QueryWhere<unknown>, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
-    protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, sizeVal: number | QuerySizeComparisonOps, rel: RelationMeta, opts: QueryComparisonOptions): void;
+    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: