uql-orm 0.27.0 → 0.28.0

package/README.md

@@ -7,9 +7,9 @@
   </picture>
 </a>
 
-<h3>The smartest TypeScript ORM</h3>
+<h3>The ORM with type-safe JSON queries</h3>
 
-<p>Serializable queries, type-safe to the leaf, no codegen, and one API across every SQL database, MongoDB, and every runtime. And the <a href="https://uql-orm.dev/benchmark">fastest</a>.</p>
+<p>Queries are plain JSON values, typed to the leaf. Build them, store them, send them from the browser, and run them unchanged on every SQL database and MongoDB. And it is the <a href="https://uql-orm.dev/benchmark">fastest</a>.</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·
@@ -56,9 +56,9 @@ from the browser to the server. The same object runs on every supported database
 - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) loads a to-many with one query for all parents, not one per parent. Nothing is lazy, so nothing fires behind your back in a serializer.
 - **Migrations you read before they run.** Edit an entity, run `uql-migrate generate:entities`, review the SQL in the PR like any other file. [`drift:check`](https://uql-orm.dev/migrations) catches a database that no longer matches.
 - **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [virtual fields](https://uql-orm.dev/entities/virtual-fields) are sub-queries you can filter on, and a migration can be plain SQL.
-- **Light.** Zero runtime dependencies, 305 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
+- **Light.** Zero runtime dependencies, 269 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
 - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
-- **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark): 239µs, against 812µs for the next closest and 2,286µs for the slowest.
+- **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark): 206µs, against 644µs for the next closest and 2,236µs for the slowest.
 
 ## Get started
 

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,6 +1,7 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
+import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
 type PersistKind = 'plain' | 'json' | 'vector';
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
@@ -34,7 +35,8 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * straight into `ctx`'s own values array - shared by reference, not copied - so `addValue` numbers
      * its placeholder correctly against the real query from the start; a fresh, empty array would
      * instead number from `1` regardless of how many values `ctx` already has, misnumbering every
-     * bound value on `$n`-placeholder dialects once `ctx` isn't otherwise empty.
+     * bound value on `$n`-placeholder dialects once `ctx` isn't otherwise empty. Generated aliases are
+     * shared for the same reason - see {@link SqlQueryContext}.
      */
     protected buildFragment(ctx: QueryContext, build: (fragmentCtx: QueryContext) => void): string;
     addValue(values: unknown[], value: unknown): string;
@@ -51,7 +53,7 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     normalizeValues(values: unknown[] | undefined): unknown[] | undefined;
     placeholder(_index: number): string;
     returningId<E>(entity: Type<E>): string;
-    search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
+    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;
     /**
      * The expression a scalar field is read through, the plain column by default. MariaDB reads a
@@ -65,19 +67,11 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * 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>, select: QuerySelectValue<E> | undefined, exclude?: QueryExclude<E>, populate?: QueryPopulate<E>, opts?: QueryOptions, distinct?: boolean, sort?: QuerySortMap<E>): void;
+    select<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, joins?: QueryJoins): void;
+    /** Columns are alias-qualified once anything else is in play: a join, or a to-many being filled. */
     private resolveRelationAwarePrefix;
-    protected selectRelationFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelect<E> | undefined, populate: QueryPopulate<E> | undefined, opts?: {
-        prefix?: string;
-    }): void;
-    protected selectRelationJoins<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelect<E> | undefined, populate: QueryPopulate<E> | undefined, opts?: {
-        prefix?: string;
-    }): void;
-    /**
-     * Iterates over joinable (11/m1) relations for a given select, resolving shared metadata.
-     * Used by both `selectRelationFields` and `selectRelationJoins` to avoid duplicated iteration logic.
-     */
-    private forEachJoinableRelation;
+    protected selectRelationFields(ctx: QueryContext, joins: QueryJoins): void;
+    protected selectRelationJoins<E>(ctx: QueryContext, meta: EntityMeta<E>, tableName: 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 `$and`/`$or` recursion). */
     protected renderWhere<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
@@ -87,39 +81,57 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     private readonly escapedColumns;
     private static readonly NEGATE_OP_MAP;
     private static readonly COMPARE_OP_MAP;
-    private static readonly LIKE_OP_MAP;
     /**
-     * The case-insensitive `LIKE_OP_MAP` keys - the value is lowercased, so the comparison must use
-     * `ilikeExpr` (Postgres's `ILIKE`) rather than `LIKE`. `$includes` is deliberately excluded even
-     * though it starts with the substring `$i`: it is case-sensitive, unlike `$iincludes`.
+     * 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
+     * two can never drift apart - and neither one decides case folding, which is
+     * {@link caseInsensitiveMatch}'s single call.
+     */
+    private static readonly LIKE_OPS;
+    /**
+     * How this engine matches case-insensitively. One decision, not two: folding the pattern while the
+     * comparison leaves the column alone matches neither case, which is what `$istartsWith: 'Some'`
+     * used to do wherever `LIKE` is case-sensitive.
+     *
+     * - `ilike`: the engine has a case-insensitive operator (`ILIKE`), so the pattern goes through as written.
+     * - `native`: plain `LIKE` already ignores case (SQLite, for ASCII). Folding the pattern in JS would
+     *   only break the non-ASCII characters the engine cannot fold anyway - `'É'` would become an `'é'`
+     *   that matches nothing.
+     * - `fold`: nothing ignores case on its own, so both sides are lowered explicitly. Not indexable as
+     *   such; an expression index over `LOWER(column)` is what makes it so.
      */
-    private static readonly LIKE_CASE_INSENSITIVE_OPS;
-    /** Builds `prefix.column` from an already-resolved field. */
+    protected readonly caseInsensitiveMatch: 'ilike' | 'native' | 'fold';
+    /**
+     * A `$like`-family condition, or `undefined` when `op` is not one of them. Shared by columns and
+     * JSON paths, and the only place a pattern is folded - always together with the column it is
+     * compared against.
+     */
+    protected likeCondition(ctx: QueryContext, operand: string, op: string, val: unknown): string | undefined;
+    /** Builds `prefix.column` from an already-resolved field, through the same memo writes use. */
     private columnWithPrefix;
     /**
-     * Resolves the SQL operand for a field comparison.
-     * For QueryRaw virtuals, appends the raw expression to ctx and returns undefined.
+     * The SQL a field comparison reads its left-hand side from. A virtual field builds its expression
+     * as text rather than appending it, so every operator gets a real operand to wrap - `LOWER(...)`,
+     * `NOT (... <=> ...)` - instead of having to fall back to a form that takes none.
      */
-    protected resolveOperandField<E>(ctx: QueryContext, entity: Type<E>, key: string, opts: QueryOptions): string | undefined;
-    private appendFieldSql;
+    protected resolveOperandField<E>(ctx: QueryContext, entity: Type<E>, key: string, opts: QueryOptions): string;
     compareFieldOperator<E, K extends keyof QueryWhereFieldOperatorMap<E>>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: K, val: QueryWhereFieldOperatorMap<E>[K], opts?: QueryOptions): void;
     /**
-     * Render `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, and
-     * report whether `op` was one of them.
+     * `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, or
+     * `undefined` when `op` is not one of them.
      *
      * One implementation for three callers that each had their own: a WHERE column, a HAVING aggregate
-     * expression, and a `$size` count (which passes no operand, since its expression is already in the
-     * context). They previously disagreed - HAVING carried a second comparison-operator map and threw
-     * `unsupported HAVING operator` on the `$like` that `QueryHavingMap` accepts, and neither of the
-     * other two turned `$eq: null` into `IS NULL` the way the WHERE path does.
+     * expression, and a `$size` count (whose expression is already in the context, so it passes an
+     * empty operand). They previously disagreed - HAVING carried a second comparison-operator map and
+     * threw `unsupported HAVING operator` on the `$like` that `QueryHavingMap` accepts, and neither of
+     * the other two turned `$eq: null` into `IS NULL` the way the WHERE path does.
      *
      * The operators kept out are the ones that need more than an operand: `$not` recurses through the
      * entity, and `$all`/`$size`/`$elemMatch` address a JSON document.
      */
-    protected appendOperatorCondition(ctx: QueryContext, operand: string | undefined, op: string, val: unknown): boolean;
-    private appendLikeOp;
-    private appendEqNe;
-    private appendInNin;
+    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.
@@ -181,23 +193,36 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
      */
     protected jsonScalarParam(ctx: QueryContext, value: unknown): string;
-    getComparisonKey<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, { prefix }?: QueryOptions): void;
-    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, { prefix }: QueryOptions): void;
+    /** {@link resolveOperandField}, appended. */
+    getComparisonKey<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, opts?: QueryOptions): void;
+    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): void;
+    /**
+     * 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
+     * through its own `@Field({ name })`, and only that way is `tax.category` the one alias the join
+     * carries instead of two quoted identifiers.
+     */
+    private collectSortTerms;
+    /** The join an `ORDER BY` term addresses, or why the statement cannot order by it. */
+    private resolveSortJoin;
+    /**
+     * The `ORDER BY` operand for one key. A key that is not a column of `meta` - a virtual field, a
+     * `raw()` projection - is an output alias, which is never table-qualified and needs no resolving.
+     */
+    private sortColumn;
     pager(ctx: QueryContext, opts: QueryPager): void;
     /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
     readonly supportsRowLocks: boolean;
     /** MariaDB is the one engine here that cannot narrow a lock to one table of a join. */
     readonly supportsLockOf: boolean;
-    /** Whether this statement joins, which is what forces the lock to be narrowed to one table. */
-    private joinsRelations;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
-    assertLockSupported<E>(entity: Type<E>, q: Query<E>): void;
+    assertLockSupported<E>(entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
     /**
      * The trailing `FOR UPDATE`. Narrowing to the queried table is not a nicety once a relation is
      * 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>): void;
+    protected appendLock<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
     count<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     /** `$group` aggregate operator → SQL function name. An allowlist, not a formatter: the op key
      * comes from query data, so anything outside this map must be rejected rather than passed
@@ -205,7 +230,9 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     private static readonly AGGREGATE_FN_MAP;
     aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): void;
     /**
-     * ORDER BY for aggregate queries - handles both entity-field and alias references.
+     * ORDER BY for aggregate queries - handles both entity-field and alias references. A grouped
+     * statement has no joins to address, so a relation key is rejected rather than emitted as an alias
+     * nothing defines.
      */
     private aggregateSort;
     protected having(ctx: QueryContext, having: QueryHavingMap, aggregateExpressions: Record<string, string>): void;
@@ -253,7 +280,7 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     protected getUpsertUpdateAssignments<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], callback?: (columnName: string) => string): string;
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
-    escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
+    escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /**
      * Bind one persisted value, classifying its column on the spot. Dialects override
      * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
@@ -386,6 +413,7 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * metadata is shared between dialects while this result is not, since `escapeIdChar` and the naming
      * strategy differ. Weakly keyed so a transient entity's metadata stays collectable.
      */
+    private escapedColumnOf;
     private escapedColumnName;
     private escapedColumn;
     /** As {@link escapedColumn}, but qualified by the query alias when the parent is nested. */
@@ -428,7 +456,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      */
     protected get neOp(): string;
     protected neExpr(field: string, ph: string): string;
-    protected ilikeExpr(f: string, ph: string): string;
     /**
      * Formats an IN/NOT IN expression, binding each value individually.
      * Postgres overrides to use `= ANY($1)` / `<> ALL($1)` with a single array parameter.