uql-orm 0.65.1 → 0.67.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,9 +1,9 @@
 import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
-import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
+import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, columnFamily, countedRelations, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
-import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS, relationSortColumn } from './aliases.js';
+import { COUNT_ALIAS, COUNTED_ROWS_ALIAS, JSON_ELEM_ALIAS, relationSortColumn } from './aliases.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
@@ -35,13 +35,6 @@ function inOperands(op, value) {
     return value;
 }
 export class AbstractSqlDialect extends VectorSqlDialect {
-    /**
-     * Whether {@link autoIncrementSuffix} states `PRIMARY KEY` itself, so the table must not state it again.
-     *
-     * True on SQLite alone, where `AUTOINCREMENT` is legal only in the exact phrase
-     * `INTEGER PRIMARY KEY AUTOINCREMENT` - the key cannot be lifted out of the column there.
-     */
-    serialDeclaresPrimaryKey = false;
     /**
      * How this engine declares a namespace, so a generated migration creates the schemas its tables
      * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
@@ -87,13 +80,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return new SqlQueryContext(this, [], undefined, options.inlineValues);
     }
     /**
-     * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
-     * `"col" = <text>`) instead of appending it at the end of `ctx`. The fragment binds any value
-     * 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. Generated aliases are
-     * shared for the same reason - see {@link SqlQueryContext}.
+     * The SQL `build` writes, as text to embed rather than appended to `ctx`. It binds into `ctx`'s own values
+     * and aliases, so `$n` placeholders number against the whole statement.
      */
     buildFragment(ctx, build) {
         const fragmentCtx = ctx.createFragment();
@@ -105,12 +93,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, { value, prefix, entity }));
     }
     /**
-     * Each operand rendered into its own fragment, keeping only those that emitted SQL.
-     *
-     * Nothing reaches `ctx` until every one has rendered, because an operand that emits nothing - an
-     * empty `$and`, an `{}` entry - must leave behind neither a dangling separator nor a clause with no
-     * condition after it. How many terms really emit is also what decides the parentheses, which is why
-     * the caller counts what comes back rather than what it passed in.
+     * Each operand rendered on its own, keeping those that emitted SQL: an empty one leaves no dangling
+     * separator, and the count of what emitted decides the parentheses.
      */
     renderOperands(ctx, operands, render) {
         return operands
@@ -147,14 +131,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     placeholder(_index) {
         return '?';
     }
-    /**
-     * `RETURNING <id column> AS id`, or nothing at all for a composite key.
-     *
-     * The alias names one column, and every column of a composite came from the caller, so there is no
-     * id the statement could report that the payload does not already carry - the same "no id to give"
-     * a `firstId` dialect already answers with. Empty rather than a refusal, so an insert and an upsert
-     * of a composite row both run, and the querier names those rows with `idOf`.
-     */
+    /** `RETURNING <id column> id`, or nothing on a composite key, whose every column the payload already names. */
     returningId(meta) {
         const expression = this.returningIdExpression(meta);
         return expression ? `RETURNING ${expression}` : '';
@@ -524,16 +501,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         [insensitive, { pattern, insensitive: true }],
     ]));
     /**
-     * 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.
+     * How the engine matches case-insensitively: `ilike` has the operator, `native` ignores case already
+     * (SQLite, where folding in JS would break non-ASCII), and `fold` lowers both sides.
      */
     caseInsensitiveMatch = 'fold';
     /**
@@ -577,6 +546,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const inlined = field && isInlinedExpression(field) ? field.computed : undefined;
         return inlined ? this.rawFragment(ctx, inlined, prefix, entity) : undefined;
     }
+    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
         const field = this.resolveOperandField(ctx, entity, key, opts);
         if (this.appendOperatorCondition(ctx, field, op, val)) {
@@ -605,17 +575,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
     }
     /**
-     * `<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 (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.
+     * `<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.
      */
     operatorCondition(ctx, operand, op, val) {
         const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
@@ -635,7 +596,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 return this.regexCondition(operand, this.addValue(ctx, val));
             case '$in':
             case '$nin':
-                return operand + this.formatIn(ctx, inOperands(op, val), op === '$nin');
+                return this.formatIn(ctx, operand, inOperands(op, val), op === '$nin');
             case '$between': {
                 const [min, max] = val;
                 return `${operand} BETWEEN ${this.addValue(ctx, min)} AND ${this.addValue(ctx, max)}`;
@@ -706,7 +667,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const values = inOperands(op, value);
         const negate = op === '$nin';
         if (!asJson) {
-            return `${comparand(values)}${this.formatIn(ctx, values, negate)}`;
+            return this.formatIn(ctx, comparand(values), values, negate);
         }
         // JSON values have no portable array literal, so the set expands into explicit comparisons.
         const comparisons = values.map((val) => `${jsonField} ${negate ? '<>' : '='} ${this.jsonScalarParam(ctx, val)}`);
@@ -717,32 +678,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx, value);
     }
     /**
-     * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
-     * *includes* the given keys, as PostgreSQL's `@>` and MySQL's `JSON_CONTAINS` do. SQLite compares
-     * elements as whole JSON text, so it cannot express a partial match and always expands the
-     * per-field form below.
-     */
-    jsonContainmentIsPartial = true;
-    /**
-     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `JSON_EACH` yields JSON
-     * booleans as `0`/`1` integers and numbers as numbers, so such an element compares directly to a
-     * bound value; PostgreSQL and MySQL explode scalars to text, losing the type, so a non-string
-     * operand there has to compare as JSON (see {@link isJsonbOp}).
-     */
-    jsonScalarElemKeepsType = false;
-    /**
-     * `$elemMatch`: at least one element of the JSON array satisfies `match`. Three shapes, decided
-     * here so every dialect only supplies {@link jsonElemFrom} / {@link jsonElemRef}:
-     * - keys are operators (`{ $startsWith: 'ad' }`) - scalar elements, conditions on the element;
-     * - a plain object with no nested operators - containment, which is the only form an index serves;
-     * - otherwise - per-field conditions over the exploded objects.
+     * `$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.
      */
     jsonElemMatch(ctx, jsonField, match) {
         // Conditions on the element itself. One `FROM` serves them all, so the element is read as JSON
         // only when *every* operand needs it - the same all-operands rule the comparison classifier uses.
         if (isOperatorOnlyObject(match)) {
             const entries = Object.entries(match);
-            const asJson = !this.jsonScalarElemKeepsType && entries.every(([op, val]) => isJsonbOp(op, val));
+            const asJson = !this.features.typedJsonElements && entries.every(([op, val]) => isJsonbOp(op, val));
             const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
             const conditions = entries.map(([op, val]) => this.buildJsonFieldCondition(ctx, this.elemAccessor(alias, asJson), '', op, val, asJson));
             return jsonElemExists(this.jsonElemFrom(jsonField, [], alias, asJson), conditions);
@@ -752,7 +696,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         // A plain object with no nested operators is containment, which is also the only form an index
         // can serve. SQLite compares elements exactly, so it always expands the per-field form below.
-        if (this.jsonContainmentIsPartial && !someValue(match, isOperatorObject)) {
+        if (this.features.partialJsonContainment && !someValue(match, isOperatorObject)) {
             return this.jsonAll(ctx, jsonField, [match]);
         }
         const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
@@ -897,26 +841,16 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             ctx.append(` OFFSET ${assertNonNegativeInteger(opts.$skip, '$skip')}`);
         }
     }
-    /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
-    supportsRowLocks = true;
-    /**
-     * Whether a `FOR UPDATE` may share a statement with a window function. The MySQL family runs the
-     * pair; the Postgres family rejects it outright ("FOR UPDATE is not allowed with window functions"),
-     * which is what a paged read carrying its own `COUNT(*) OVER ()` total becomes under a `$lock`.
-     */
-    supportsWindowWithRowLock = true;
-    /** MariaDB is the one engine here that cannot narrow a lock to one table of a join. */
-    supportsLockOf = true;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
     assertLockSupported(entity, q, joins) {
         if (!parseQueryLock(q.$lock)) {
             return;
         }
-        if (!this.supportsRowLocks) {
+        if (!this.features.rowLocks) {
             throw new TypeError(`${this.dialectName} does not support row-level locking ($lock)`);
         }
         joins ??= resolveQueryJoins(getMeta(entity), q);
-        if (!this.supportsLockOf && joins.size > 0) {
+        if (!this.features.rowLockOf && joins.size > 0) {
             throw new TypeError(`${this.dialectName} cannot narrow a row lock to one table, so $lock cannot be combined with a joined relation`);
         }
     }
@@ -945,30 +879,36 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const suffix = wait === 'skip' ? ' SKIP LOCKED' : wait === 'nowait' ? ' NOWAIT' : '';
         ctx.append(` FOR UPDATE${target}${suffix}`);
     }
-    // `QueryFilter`, not `QueryPage`: a count orders nothing and pages nothing, and an `OFFSET`
-    // would push its single row out of the result set. The type only stops a statically-checked
-    // caller though - the HTTP handler hands this `q` straight from the wire - so `$where` is read
-    // off it explicitly rather than forwarding `q` itself into `search()`, which would honor a
-    // `$sort`/`$skip`/`$limit` an untyped caller snuck in regardless of what TypeScript allowed them.
+    /**
+     * `COUNT(*)` over the filter, or over the rows a page settles. The clauses are read off `q` one by one:
+     * `/http` hands it over untyped, and a smuggled `$sort` changes no count.
+     */
     count(ctx, entity, q, opts) {
-        this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(COUNT_ALIAS)] });
-        this.search(ctx, entity, { $where: q.$where }, opts);
+        const { $where, $skip, $limit } = q;
+        if ($skip === undefined && $limit === undefined) {
+            this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(COUNT_ALIAS)] });
+            this.search(ctx, entity, { $where }, opts);
+            return;
+        }
+        const page = idOnlyQuery(getMeta(entity), { $where, $skip, $limit });
+        this.countRows(ctx, () => this.find(ctx, entity, page, opts));
     }
     /**
-     * How many rows a `$distinct` read returns, which `COUNT(*)` cannot answer: the deduplication
-     * happens after it counts, and a window function is no better - it counts before `DISTINCT` too.
-     * So the deduplicated set is made a derived table and its rows are counted. Every engine here
-     * supports one; MySQL is the reason it is aliased.
-     *
-     * The inner query takes the projection and the filter but never the page: the caller is asking how
-     * many rows there are beyond the page it already has.
+     * How many rows a `$distinct` read returns: the deduplication runs after `COUNT(*)` and a window
+     * alike, so the deduplicated set is counted as a derived table, never paged.
      */
     countDistinct(ctx, entity, q, opts) {
         const read = this.readOptions(ctx, getMeta(entity), opts);
+        this.countRows(ctx, () => {
+            this.select(ctx, entity, q, read);
+            this.search(ctx, entity, { $where: q.$where }, read);
+        });
+    }
+    /** `SELECT COUNT(*)` over the rows `rows` appends, as a derived table. */
+    countRows(ctx, rows) {
         ctx.append(`SELECT COUNT(*) ${this.escapeId(COUNT_ALIAS, true)} FROM (`);
-        this.select(ctx, entity, q, read);
-        this.search(ctx, entity, { $where: q.$where }, read);
-        ctx.append(`) ${this.escapeId(DISTINCT_DERIVED_ALIAS, true)}`);
+        rows();
+        ctx.append(`) ${this.escapeId(COUNTED_ROWS_ALIAS, true)}`);
     }
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
@@ -1132,21 +1072,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             ctx.append(` ${returning}`);
         }
     }
-    /**
-     * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
-     * of the statement, which every engine here but one spells that way; SQL Server's `OUTPUT` has no
-     * trailing form and sits between the column list and `VALUES`.
-     *
-     * A knob rather than a pair of hooks: one concept decides where the string {@link returningId}
-     * already built ends up, so the two ends cannot disagree.
-     */
+    /** Where an insert's id clause goes: `RETURNING` at the end, or SQL Server's `OUTPUT` before `VALUES`. */
     returningPosition = 'suffix';
-    /**
-     * Whether a multi-row upsert's `RETURNING` lists its rows in payload order. Where it does not, the
-     * ids are read back by the conflict columns instead, since placing them in order would name the
-     * wrong rows.
-     */
-    upsertReturningOrdered = true;
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
@@ -1159,13 +1086,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         ctx.append(`INSERT INTO ${tableName} (${shape.columns.join(', ')})${afterTarget ? ` ${afterTarget}` : ''} VALUES `);
         this.appendValueRows(ctx, shape);
     }
-    /**
-     * The columns an insert writes and the records it writes them from, resolved once.
-     *
-     * Split out of {@link appendInsertValues} because a `MERGE` needs the same rows as a `VALUES` row
-     * source rather than as an `INSERT`, and both have to apply `onInsert` defaults and the
-     * JSON/vector binding rules identically.
-     */
+    /** The columns an insert writes and the rows it writes, resolved once, and shared with a `MERGE`'s row source. */
     insertShape(entity, payload) {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
@@ -1243,15 +1164,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.search(ctx, entity, q, opts);
     }
     /**
-     * `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...`, which SQLite adopted from Postgres
-     * and which every dialect here speaks except the MySQL family (see {@link MysqlLikeSqlDialect}).
-     *
-     * Two orderings matter, and they pull in opposite directions. The assignments are computed *before*
-     * the insert, because `appendInsertValues` fills `onInsert` fields into the payload and a column that
-     * exists only there - `createdAt` - must not join the update set. Their bound values are pushed
-     * *after* it, because a `?` placeholder is positional and the clause comes last in the statement.
-     * {@link PgLikeSqlDialect} overrides this: `$N` placeholders make array order irrelevant, so it can
-     * bind into the main context and skip the second one.
+     * `INSERT ... ON CONFLICT ... DO UPDATE/NOTHING RETURNING`. The assignments are built before the insert
+     * fills `onInsert` columns, which must stay out of them, and their values bound after it, where a `?` reads them.
      */
     upsert(ctx, entity, conflictPaths, payload, 
     /** One more `RETURNING` item, as a bare expression: this joins the list and adds the keyword. */
@@ -1270,14 +1184,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             ctx.pushValue(...updateCtx.values);
         }
     }
-    /**
-     * Whether the upsert's update assignments can bind straight into the statement's own context.
-     *
-     * They cannot on a `?`-placeholder dialect: the assignments are built before the insert but read
-     * after it, so their values have to be pushed afterwards to land in the right positional order.
-     * A `$n` placeholder carries its own index, so there is nothing to reorder - but it also cannot use
-     * the scratch context, whose numbering would restart at `$1` and collide with the insert's.
-     */
+    /** Whether the upsert's assignments bind straight into the statement, as numbered `$n` placeholders can. */
     upsertUpdateBindsInPlace = false;
     /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
     upsertExcluded = (columnName) => `EXCLUDED.${columnName}`;
@@ -1291,7 +1198,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             .map((col) => {
             const field = meta.fields[col];
             const columnName = this.resolveColumnName(col, field);
-            if (callback && Object.hasOwn(sample, col)) {
+            if (Object.hasOwn(sample, col)) {
                 return `${this.escapeId(columnName)} = ${callback(this.escapeId(columnName))}`;
             }
             const text = this.buildFragment(ctx, (fragmentCtx) => this.formatPersistableValue(fragmentCtx, field, filledPayload[col]));
@@ -1347,35 +1254,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     formatPersistableValue(ctx, field, value) {
         this.writePersistableValue(ctx, this.persistKind(field), field, value);
     }
-    /**
-     * How a column's values are written. A function of the column, not of the value, so a bulk insert
-     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert used to ask
-     * 120 times to get the same six answers.
-     */
+    /** How a column's values are written: a function of the column, so a bulk insert classifies each once. */
     persistKind(field) {
         const family = columnFamily(field?.type);
         return family === 'json' || family === 'vector' ? family : 'plain';
     }
     /**
-     * Which of an entity's columns need decoding on READ, and how: the inverse of {@link persistKind},
-     * cached per entity for the same reason it classifies per column. A 1000-row read of a 10-field
-     * entity otherwise asks {@link columnFamily} (which lowercases a string on every call) 10,000 times
-     * to get the same ten answers. Most entities land here for their numeric columns alone, where the
-     * per-row cost is one `typeof` against a value the driver usually decoded already.
-     *
-     * Dialect-aware exactly like {@link supportedVectorType}, because it has to be: a `sparsevec` field
-     * is written as a plain dense vector everywhere but Postgres, so reading it back by the field's own
-     * declared cast would look for a sparse literal that was never stored.
-     *
-     * A type lands here rather than at the driver when the wire type alone cannot decide it, and only
-     * the declaration can: `Boolean` is 0/1 in a SQLite INTEGER and a MySQL `TINYINT(1)`, both
-     * indistinguishable from a genuine small integer; a decimal is text from pg *and* mysql2, and only
-     * the field says it was meant as a number; and `type: BigInt` shares BIGINT with `type: Number`, so
-     * the wire decode has to be undone for it. All are no-ops where the driver already decoded.
-     *
-     * Classified through the same {@link columnFamily} the rest of the library uses, not against the
-     * constructors: `type` accepts a string logical type for every one of these (`@Field({ type:
-     * 'decimal' })`), and matching `=== Number` alone left those reading back as text.
+     * The columns a read decodes, and how, cached per entity and revision. They are the ones the wire cannot
+     * decide alone: a boolean stored as an integer, a decimal read as text, a `BigInt`, and a related row's
+     * values, which cross JSON as text.
      */
     hydratableFields(entity) {
         const meta = getMeta(entity);
@@ -1396,14 +1283,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return decoded;
     }
     /**
-     * The same classification for an aggregate row. Not cached, because these columns are a shape of the
-     * query rather than of the entity, and it is computed once per call either way.
-     *
-     * Mirrors `QueryAggregateFnResult`, which is the contract callers already compile against:
-     * `$count`/`$sum`/`$avg` are a number whatever they aggregate, while `$min`/`$max` and every
-     * `$group` column keep the aggregated field's own type, so they decode as that field would. Without
-     * it a `$sum` over a BIGINT column came back as `'500'` from a result type that says `number`, since
-     * Postgres widens that sum to NUMERIC and no driver can know it was meant as a JS number.
+     * The same for an aggregate's row, per query: a count or total is a number however the engine widened
+     * it, and `$min`/`$max` or a grouped column decodes as its field does.
      */
     hydratableAggregates(entity, q) {
         const { fields } = getMeta(entity);
@@ -1423,13 +1304,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         return decoded;
     }
-    /**
-     * 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.
-     */
+    /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
     hydrateKind(field) {
         const type = field?.type;
         if (type === BigInt) {
@@ -1481,17 +1356,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return `CAST(${operand} AS JSON)`;
     }
     /**
-     * Generate the full `"col" = <expression>` assignment for a JSON update operator payload.
-     * Called from `update()` when a field value is a {@link JsonUpdateOp}.
-     *
-     * Each operator wraps the expression built so far, innermost-first in the order stated on
-     * {@link JsonUpdateOp} (`$pull` -> `$set` -> `$push` -> `$unset`), so dialects only supply the
-     * four SQL fragments below. Two invariants keep every dialect consistent and keep bound values in
-     * step with their placeholders:
-     * - `$pull` is innermost and its subquery reads `escapedCol`, so its value binds exactly once.
-     * - Later fragments reference `expr` at most once, so a `$pull` subquery is never duplicated
-     *   (which would bind its value twice on positional-placeholder dialects). PostgreSQL's `$push`
-     *   is the one exception, and is safe there because its placeholders are numbered.
+     * `"col" = <expr>` for a JSON update, each operator wrapping the last: `$pull`, `$set`, `$push`, `$unset`.
+     * `$pull` reads the column and every later one its expression once, so no value binds twice.
      */
     formatJsonUpdate(ctx, escapedCol, value, field) {
         // Centralizes the one narrowing cast: the payload's keys are typed against the entity's JSON
@@ -1778,11 +1644,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             target: this.escapedColumn(alias, junctionMeta, target),
         };
     }
-    /**
-     * 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.
-     */
-    orderedAggregates = true;
     /**
      * 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
@@ -1790,7 +1651,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     derivedRelation(ctx, rows) {
         const rowsCtx = ctx.createFragment();
-        const readOpts = { alias: rows.alias, json: true, carried: this.orderedAggregates };
+        const readOpts = { alias: rows.alias, json: true, carried: this.features.orderedJsonAggregates };
         const { terms, order = [] } = this.read(rowsCtx, rows.entity, rows.query, readOpts, rows.joins);
         const alias = this.escapeId(rows.alias, true);
         return {
@@ -1861,13 +1722,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         this.buildExprComparison(ctx, sizeExprFn, sizeVal, (op, val) => this.appendSizeOp(ctx, op, val));
     }
-    /**
-     * `<distance expr> <op> ?` - the `$where` half of vector search, where `$sort` is the ranking half.
-     *
-     * The bounds are validated here rather than left to the shared renderer, which also knows `$like`
-     * and `$in`; and `$eq`/`$ne` are absent on purpose, since a distance is a float. `/http` casts
-     * client JSON straight to `Query`, so an unknown key has to be refused rather than ignored.
-     */
+    /** `<distance> <op> ?`, the `$where` half of a vector search, its bounds checked here since `/http` input is untyped. */
     compareVectorNear(ctx, meta, key, near) {
         const bounds = {};
         for (const [op, val] of Object.entries(near)) {
@@ -1903,14 +1758,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         '$lte',
         '$between',
     ]);
-    /**
-     * Append a single size comparison operator and value. No operand: the count expression is already
-     * in the context, so this contributes only the ` <op> <value>` tail.
-     *
-     * Gated on {@link SIZE_COMPARE_OPS} rather than on whatever the shared renderer accepts, because
-     * that renderer also knows `$like`, `$regex` and `$in`, none of which mean anything against a
-     * count. `$size: { $like: 5 }` has to stay the error it always was.
-     */
+    /** ` <op> <value>` after a count already written, refusing any operator a count cannot be compared with. */
     appendSizeOp(ctx, op, val) {
         if (!AbstractSqlDialect.SIZE_COMPARE_OPS.has(op)) {
             throw TypeError(`unsupported $size comparison operator: ${op}`);
@@ -1952,15 +1800,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     neExpr(field, ph) {
         return `${field} ${this.neOp} ${ph}`;
     }
-    /**
-     * Formats an IN/NOT IN expression, binding each value individually.
-     * Postgres overrides to use `= ANY($1)` / `<> ALL($1)` with a single array parameter.
-     */
-    formatIn(ctx, values, negate) {
-        if (values.length === 0)
-            return negate ? ' NOT IN (NULL)' : ' IN (NULL)';
+    /** `operand IN (...)` binding each value, or the constant an empty set reduces to: no value is in it. */
+    formatIn(ctx, operand, values, negate) {
+        if (!values.length) {
+            return negate ? '1 = 1' : '1 = 0';
+        }
         const phs = values.map((v) => this.addValue(ctx, v)).join(', ');
-        return ` ${negate ? 'NOT IN' : 'IN'} (${phs})`;
+        return `${operand} ${negate ? 'NOT IN' : 'IN'} (${phs})`;
     }
     toString() {
         return this.dialectName;

package/dist/dialect/aliases.d.ts

@@ -1,19 +1,9 @@
-/**
- * Every identifier UQL invents for itself: a column a statement answers in, a derived table it wraps
- * a set in, a temporary field a pipeline parks a value on.
- *
- * All of them share the `_uql` prefix, which is what keeps them off a user's own column or field, and
- * all of them are declared here rather than beside the code that emits them: the end that writes one
- * and the end that reads it back are usually in different modules, and a drift between the two fails
- * silently - a count of zero, or an ordering that ranks everything equal. Collected in one file so
- * the whole reserved namespace can be read at a glance before a new name is added to it.
- */
 /** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
 export declare const COUNT_ALIAS = "_uql_count";
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export declare const TOTAL_ALIAS = "_uql_total";
-/** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
-export declare const DISTINCT_DERIVED_ALIAS = "_uql_distinct";
+/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
+export declare const COUNTED_ROWS_ALIAS = "_uql_rows";
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export declare const RELATION_ROW_ALIAS = "_uql_row";
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/aliases.js

@@ -1,19 +1,11 @@
-/**
- * Every identifier UQL invents for itself: a column a statement answers in, a derived table it wraps
- * a set in, a temporary field a pipeline parks a value on.
- *
- * All of them share the `_uql` prefix, which is what keeps them off a user's own column or field, and
- * all of them are declared here rather than beside the code that emits them: the end that writes one
- * and the end that reads it back are usually in different modules, and a drift between the two fails
- * silently - a count of zero, or an ordering that ranks everything equal. Collected in one file so
- * the whole reserved namespace can be read at a glance before a new name is added to it.
- */
+// Every identifier UQL invents, `_uql`-prefixed to stay off a user's own, collected in one place:
+// the ends writing and reading one sit in different modules, and a drift between them fails silently.
 /** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
 export const COUNT_ALIAS = '_uql_count';
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export const TOTAL_ALIAS = '_uql_total';
-/** The derived table a `$distinct` count wraps its deduplicated set in. MySQL requires the alias. */
-export const DISTINCT_DERIVED_ALIAS = '_uql_distinct';
+/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
+export const COUNTED_ROWS_ALIAS = '_uql_rows';
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export const RELATION_ROW_ALIAS = '_uql_row';
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/hydrateColumn.d.ts

@@ -7,12 +7,8 @@ import { type VectorCast } from './vectorCast.js';
  */
 export type HydrateKind = 'json' | 'boolean' | 'number' | 'bigint' | 'date' | 'bytes' | VectorCast;
 /**
- * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
- * row walk, so classifying a column and decoding it stay one subject in one file.
- *
- * Every branch is a no-op on a value the driver already decoded, because which types arrive as text
- * varies per driver and the entity is the only thing that says what they were meant to be. A value
- * that does not match its column's format is returned untouched rather than replaced by a guess.
+ * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
+ * and untouched where it does not match its column's format.
  */
 export declare function decodeColumn(value: unknown, kind: HydrateKind): unknown;
 /**

package/dist/dialect/hydrateColumn.js

@@ -1,12 +1,8 @@
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { parseVectorLiteral } from './vectorCast.js';
 /**
- * Decode one non-null cell. Kept beside {@link HydrateKind} rather than inlined into the querier's
- * row walk, so classifying a column and decoding it stay one subject in one file.
- *
- * Every branch is a no-op on a value the driver already decoded, because which types arrive as text
- * varies per driver and the entity is the only thing that says what they were meant to be. A value
- * that does not match its column's format is returned untouched rather than replaced by a guess.
+ * Decodes one non-null cell. A no-op where the driver already decoded it, since that varies per driver,
+ * and untouched where it does not match its column's format.
  */
 export function decodeColumn(value, kind) {
     if (kind === 'boolean') {
@@ -79,13 +75,7 @@ function hexBytes(hex) {
 }
 /** Lazy so a consumer that never reads an encoded column never constructs one. */
 let decoder;
-/**
- * The text a driver returned, or `undefined` when it returned something already decoded.
- *
- * Bytes count as text: `bun:sql` hands a MySQL DECIMAL, and any `SUM` over one, back as a `Buffer`,
- * so a string-only check left those as raw bytes. `TextDecoder` rather than `Buffer.toString`, because
- * this module is reachable from the browser entry and may not name a Node builtin.
- */
+/** The text a driver returned, bytes included (`bun:sql` hands a MySQL decimal as a `Buffer`), or `undefined`. */
 function asText(value) {
     if (typeof value === 'string') {
         return value;

package/dist/dialect/jsonArrayElemMatchUtils.d.ts

@@ -1,8 +1,2 @@
-/**
- * Expands an `$elemMatch` object into per-field conditions: a field whose value is an operator
- * object contributes one condition per operator, and a plain value contributes an `$eq`.
- *
- * Treating plain equality as `$eq` is what keeps `{ count: 5 }` and `{ count: { $eq: 5 } }`
- * identical - they used to take different code paths and emit different SQL.
- */
+/** An `$elemMatch` as per-field conditions, a plain value as `$eq`, so both spellings emit the same SQL. */
 export declare function buildElemMatchConditions(match: Record<string, unknown>, onCondition: (field: string, op: string, value: unknown) => string): string[];

package/dist/dialect/jsonArrayElemMatchUtils.js

@@ -1,11 +1,5 @@
 import { isOperatorObject } from '../util/object.util.js';
-/**
- * Expands an `$elemMatch` object into per-field conditions: a field whose value is an operator
- * object contributes one condition per operator, and a plain value contributes an `$eq`.
- *
- * Treating plain equality as `$eq` is what keeps `{ count: 5 }` and `{ count: { $eq: 5 } }`
- * identical - they used to take different code paths and emit different SQL.
- */
+/** An `$elemMatch` as per-field conditions, a plain value as `$eq`, so both spellings emit the same SQL. */
 export function buildElemMatchConditions(match, onCondition) {
     return Object.entries(match).flatMap(([field, value]) => isOperatorObject(value)
         ? Object.entries(value).map(([op, opVal]) => onCondition(field, op, opVal))