uql-orm 0.37.0 → 0.37.1

package/dist/cockroachdb/cockroachDialect.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS } from '../dialect/abstractSqlDialect.js';
+import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 /**

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-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 QueryFilter, 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 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 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';
@@ -7,11 +7,6 @@ type PersistKind = 'plain' | 'json' | 'vector';
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
 type HydratableField = readonly [string, HydrateKind];
 export type { HydrateKind };
-/**
- * The column a counting statement answers in. Shared rather than spelled at each end: the dialects
- * emit it and `runCount` reads it back, and a rename on one side alone would quietly count zero.
- */
-export declare const COUNT_ALIAS = "count";
 export declare abstract class AbstractSqlDialect extends IndexSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
     abstract readonly escapeIdChar: '"' | '`';
@@ -49,7 +44,7 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * 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;
+    protected buildFragment(ctx: QueryContext, build: QueryBuildFn): string;
     addValue(values: unknown[], value: unknown): string;
     /**
      * Normalizes a parameter value for the database driver.
@@ -236,6 +231,12 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     pager(ctx: QueryContext, opts: QueryPager): void;
     /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
     readonly supportsRowLocks: boolean;
+    /**
+     * 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`.
+     */
+    readonly supportsWindowWithRowLock: boolean;
     /** MariaDB is the one engine here that cannot narrow a lock to one table of a join. */
     readonly supportsLockOf: boolean;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
@@ -247,6 +248,16 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      */
     protected appendLock<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, joins?: QueryJoins): 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
+     * 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.
+     */
+    countDistinct<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
      * keep one; the rest throw, because falling back to `COUNT(*)` would run exactly the scan the

package/dist/dialect/abstractSqlDialect.js

@@ -2,17 +2,13 @@ import { getMeta } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
 import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, 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_PREFIX } from './aliases.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
-import { isJsonbOp, JSON_ELEM_ALIAS_PREFIX, jsonCompareMode, jsonElemExists } from './jsonSql.js';
+import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
-/**
- * The column a counting statement answers in. Shared rather than spelled at each end: the dialects
- * emit it and `runCount` reads it back, and a rename on one side alone would quietly count zero.
- */
-export const COUNT_ALIAS = 'count';
 export class AbstractSqlDialect extends IndexSqlDialect {
     /**
      * How this engine declares a namespace, so a generated migration creates the schemas its tables
@@ -96,8 +92,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     returningId(entity) {
         const meta = getMeta(entity);
-        const idKey = (meta.id ?? 'id');
-        const idName = this.columnOf(meta, idKey);
+        const idName = this.columnOf(meta, meta.id);
         return `RETURNING ${this.escapeId(idName)} ${this.escapeId('id')}`;
     }
     search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS) {
@@ -753,6 +748,12 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     /** 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. */
@@ -794,6 +795,21 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         this.select(ctx, entity, { $select: [raw('COUNT(*)', COUNT_ALIAS)] });
         this.search(ctx, entity, { $where: q.$where }, 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.
+     */
+    countDistinct(ctx, entity, q, opts) {
+        ctx.append(`SELECT COUNT(*) ${this.escapeId(COUNT_ALIAS, true)} FROM (`);
+        this.select(ctx, entity, q, opts);
+        this.search(ctx, entity, { $where: q.$where }, opts);
+        ctx.append(`) ${this.escapeId(DISTINCT_DERIVED_ALIAS, true)}`);
+    }
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
      * keep one; the rest throw, because falling back to `COUNT(*)` would run exactly the scan the

package/dist/dialect/aliases.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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";
+/** Prefix for the alias an exploded JSON array element is read through. */
+export declare const JSON_ELEM_ALIAS_PREFIX = "_uql_elem";
+/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */
+export declare const JSON_PULL_ALIAS = "_uql_pull";
+/** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
+export declare const REL_TEMP_PREFIX = "_uql_rel_";
+/** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */
+export declare const REL_NESTED_KEY = "_uql_target";
+/**
+ * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
+ * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB
+ * ranks a field that is not there as all-equal rather than failing, so a drift would go unnoticed.
+ */
+export declare function sortCountField(relKey: string): string;

package/dist/dialect/aliases.js

@@ -0,0 +1,32 @@
+/**
+ * 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 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';
+/** Prefix for the alias an exploded JSON array element is read through. */
+export const JSON_ELEM_ALIAS_PREFIX = '_uql_elem';
+/** The alias a `$pull` reads its surviving elements through, kept distinct from {@link JSON_ELEM_ALIAS_PREFIX}. */
+export const JSON_PULL_ALIAS = '_uql_pull';
+/** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
+export const REL_TEMP_PREFIX = '_uql_rel_';
+/** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */
+export const REL_NESTED_KEY = '_uql_target';
+/**
+ * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
+ * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB
+ * ranks a field that is not there as all-equal rather than failing, so a drift would go unnoticed.
+ */
+export function sortCountField(relKey) {
+    return `_uql_sort_count_${relKey}`;
+}

package/dist/dialect/jsonSql.d.ts

@@ -1,24 +1,4 @@
 import type { FieldOptions } from '../type/index.js';
-/**
- * Alias prefix for the derived table a dialect explodes a JSON array into to test `$all`/
- * `$elemMatch` (e.g. SQLite's `json_each(col) AS _uql_elem_1`). Passed to
- * {@link QueryContext.nextAlias} for a fresh, uniquely-numbered name per call - `$elemMatch`/`$all`
- * can recurse into this on a nested array, so a single fixed alias would let the inner occurrence
- * shadow the outer one it needs to correlate against (confirmed on SQLite and MySQL: reusing one
- * literal alias at two nesting depths silently returned zero rows instead of the matching ones).
- * Leading underscore keeps it a valid unquoted identifier on every dialect (unlike a leading `$`,
- * which Postgres/SQLite only allow after the first character) while staying an unlikely real
- * column/relation/`$select` alias name.
- */
-export declare const JSON_ELEM_ALIAS_PREFIX = "_uql_elem";
-/**
- * Alias for the derived table a dialect explodes a JSON array into to evaluate `$pull` (e.g.
- * SQLite's `json_each(col) AS _uql_pull`). Kept distinct from {@link JSON_ELEM_ALIAS_PREFIX} since
- * the two subqueries have different shapes (an `EXISTS` boolean vs. a `json_group_array` rebuild)
- * and could in principle both be in scope if this ever supports nesting one inside the other's
- * condition.
- */
-export declare const JSON_PULL_ALIAS = "_uql_pull";
 /**
  * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
  * such as `[#]` or `[*]`. Shared across dialects unchanged: no dialect escapes a JSON path key

package/dist/dialect/jsonSql.js

@@ -1,24 +1,4 @@
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
-/**
- * Alias prefix for the derived table a dialect explodes a JSON array into to test `$all`/
- * `$elemMatch` (e.g. SQLite's `json_each(col) AS _uql_elem_1`). Passed to
- * {@link QueryContext.nextAlias} for a fresh, uniquely-numbered name per call - `$elemMatch`/`$all`
- * can recurse into this on a nested array, so a single fixed alias would let the inner occurrence
- * shadow the outer one it needs to correlate against (confirmed on SQLite and MySQL: reusing one
- * literal alias at two nesting depths silently returned zero rows instead of the matching ones).
- * Leading underscore keeps it a valid unquoted identifier on every dialect (unlike a leading `$`,
- * which Postgres/SQLite only allow after the first character) while staying an unlikely real
- * column/relation/`$select` alias name.
- */
-export const JSON_ELEM_ALIAS_PREFIX = '_uql_elem';
-/**
- * Alias for the derived table a dialect explodes a JSON array into to evaluate `$pull` (e.g.
- * SQLite's `json_each(col) AS _uql_pull`). Kept distinct from {@link JSON_ELEM_ALIAS_PREFIX} since
- * the two subqueries have different shapes (an `EXISTS` boolean vs. a `json_group_array` rebuild)
- * and could in principle both be in scope if this ever supports nesting one inside the other's
- * condition.
- */
-export const JSON_PULL_ALIAS = '_uql_pull';
 /**
  * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
  * such as `[#]` or `[*]`. Shared across dialects unchanged: no dialect escapes a JSON path key

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,8 +1,9 @@
 import { getMeta } from '../entity/index.js';
 import { getFieldKeys } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
-import { AbstractSqlDialect, COUNT_ALIAS } from './abstractSqlDialect.js';
-import { JSON_PULL_ALIAS, jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
+import { AbstractSqlDialect } from './abstractSqlDialect.js';
+import { COUNT_ALIAS, JSON_PULL_ALIAS } from './aliases.js';
+import { jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
 /** The row count MySQL's manual gives for "all rows from the offset on": the largest `BIGINT UNSIGNED`. */
 const MAX_LIMIT = BigInt.asUintN(64, -1n);
 /**

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -10,6 +10,8 @@ import { AbstractSqlDialect } from './abstractSqlDialect.js';
  * syntax; CockroachDB's vector type and `CREATE VECTOR INDEX` syntax are both native).
  */
 export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
+    /** `FOR UPDATE` and a window function cannot share a statement here. See the base declaration. */
+    readonly supportsWindowWithRowLock = false;
     /** Default {@link DialectFeatures} for Postgres-wire dialects. */
     protected readonly featureDefaults: DialectFeatures;
     readonly escapeIdChar = "\"";

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,7 +1,8 @@
 import { QueryRaw, } from '../type/index.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
-import { JSON_PULL_ALIAS, jsonSetTarget } from './jsonSql.js';
+import { JSON_PULL_ALIAS } from './aliases.js';
+import { jsonSetTarget } from './jsonSql.js';
 import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -13,6 +14,8 @@ import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
  * syntax; CockroachDB's vector type and `CREATE VECTOR INDEX` syntax are both native).
  */
 export class PgLikeSqlDialect extends AbstractSqlDialect {
+    /** `FOR UPDATE` and a window function cannot share a statement here. See the base declaration. */
+    supportsWindowWithRowLock = false;
     /** Default {@link DialectFeatures} for Postgres-wire dialects. */
     featureDefaults = {
         explicitJsonCast: false,

package/dist/mongo/mongoDialect.d.ts

@@ -18,15 +18,6 @@ export declare class MongoDialect extends AbstractDialect {
     readonly dialectName = "mongodb";
     readonly insertIdSource = "returning";
     private static readonly ID_KEY;
-    /** Temporary lookup fields for relation conditions, dropped with `$unset` after the `$match`. */
-    private static readonly REL_TEMP_PREFIX;
-    /**
-     * Where a `$sort` by a relation's size parks its tally, until the ordering has run. One spelling
-     * for both ends: the `$sort` names this field and {@link sortCountStages} produces it, and MongoDB
-     * ranks a field that is not there as all-equal rather than failing, so a drift would go unnoticed.
-     */
-    private static sortCountField;
-    private static readonly REL_NESTED_KEY;
     private static readonly VECTOR_INDEX_TYPES;
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     private static readonly MAX_NUM_CANDIDATES;

package/dist/mongo/mongoDialect.js

@@ -1,9 +1,10 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
+import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { getMeta } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, COUNT_AGG_ALIAS, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -27,17 +28,6 @@ export class MongoDialect extends AbstractDialect {
     // The MongoDB driver reports the exact `_id` of every inserted document (`insertedIds`).
     insertIdSource = 'returning';
     static ID_KEY = '_id';
-    /** Temporary lookup fields for relation conditions, dropped with `$unset` after the `$match`. */
-    static REL_TEMP_PREFIX = '__uql_rel_';
-    /**
-     * Where a `$sort` by a relation's size parks its tally, until the ordering has run. One spelling
-     * for both ends: the `$sort` names this field and {@link sortCountStages} produces it, and MongoDB
-     * ranks a field that is not there as all-equal rather than failing, so a drift would go unnoticed.
-     */
-    static sortCountField(relKey) {
-        return `__uql_sort_count_${relKey}`;
-    }
-    static REL_NESTED_KEY = '__uql_target';
     static VECTOR_INDEX_TYPES = new Set(['vectorSearch', 'hnsw', 'ivfflat', 'vector']);
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     static MAX_NUM_CANDIDATES = 10_000;
@@ -149,10 +139,10 @@ export class MongoDialect extends AbstractDialect {
         const relOpts = meta.relations[relKey];
         const relEntity = relOpts.entity();
         const relMeta = getMeta(relEntity);
-        const temp = `${MongoDialect.REL_TEMP_PREFIX}${lookups.temps.length}`;
+        const temp = `${REL_TEMP_PREFIX}${lookups.temps.length}`;
         const sizeVal = parseRelationSize(val);
         // `$count` for a size test, `$limit: 1` for existence: neither returns the matched documents.
-        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: COUNT_AGG_ALIAS }];
+        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: COUNT_ALIAS }];
         // Scope first, render once - merging the target's filters into an already-rendered filter would
         // leave their own keys unmapped. The caller's filter bypass is deliberately *not* passed down:
         // `withDeleted()` or `hardDelete` on the parent must not un-hide trashed rows of the target, the
@@ -190,7 +180,7 @@ export class MongoDialect extends AbstractDialect {
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
         const junctionScope = this.renderFilter(throughEntity, this.scopedWhereMap(throughMeta, {}), opts);
-        const nested = MongoDialect.REL_NESTED_KEY;
+        const nested = REL_NESTED_KEY;
         return {
             $lookup: {
                 from: this.resolveTableName(throughMeta),
@@ -219,7 +209,7 @@ export class MongoDialect extends AbstractDialect {
      * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
      */
     compareRelationCount(temp, sizeVal) {
-        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_AGG_ALIAS}`, 0] }, 0] };
+        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] };
         if (typeof sizeVal === 'number') {
             return { $eq: [count, sizeVal] };
         }
@@ -420,7 +410,7 @@ export class MongoDialect extends AbstractDialect {
                 if (path) {
                     throw new TypeError(`$sort by '${relPath}.$count' is only supported on the queried entity`);
                 }
-                out[MongoDialect.sortCountField(key)] = sortDirection(countDirection);
+                out[sortCountField(key)] = sortDirection(countDirection);
                 continue;
             }
             const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, value, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
@@ -443,11 +433,11 @@ export class MongoDialect extends AbstractDialect {
             }
             const relEntity = relOpts.entity();
             const relMeta = getMeta(relEntity);
-            const temp = MongoDialect.sortCountField(key);
+            const temp = sortCountField(key);
             const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, {}), opts);
-            const tail = [{ $count: COUNT_AGG_ALIAS }];
+            const tail = [{ $count: COUNT_ALIAS }];
             stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts), {
-                $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_AGG_ALIAS}`, 0] }, 0] } },
+                $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] } },
             });
             fields.push(temp);
         }

package/dist/mongo/mongodbQuerier.d.ts

@@ -23,9 +23,9 @@ export declare class MongodbQuerier extends AbstractQuerier {
     private buildVectorPipeline;
     protected internalAggregate<E extends Document, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     /**
-     * A `$required` relation drops parents that have no match, so the total has to be taken after the
-     * `$unwind` that drops them - which only the read pipeline builds. Every other query counts through
-     * {@link internalCount}, which needs no pipeline of its own.
+     * A `$required` relation drops parents that have no match, and `$distinct` collapses them, so both
+     * totals have to be taken after the stage that does it - which only the read pipeline builds. Every
+     * other query counts through {@link internalCount}, which needs no pipeline of its own.
      */
     protected internalFindManyAndCount<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     protected internalCount<E extends Document>(entity: Type<E>, qm?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;

package/dist/mongo/mongodbQuerier.js

@@ -1,7 +1,8 @@
+import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { getMeta } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { COUNT_AGG_ALIAS, clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
  * as *unlimited*, so a read that passed it straight to the driver came back with the whole
@@ -151,31 +152,33 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     /**
-     * A `$required` relation drops parents that have no match, so the total has to be taken after the
-     * `$unwind` that drops them - which only the read pipeline builds. Every other query counts through
-     * {@link internalCount}, which needs no pipeline of its own.
+     * A `$required` relation drops parents that have no match, and `$distinct` collapses them, so both
+     * totals have to be taken after the stage that does it - which only the read pipeline builds. Every
+     * other query counts through {@link internalCount}, which needs no pipeline of its own.
      */
     async internalFindManyAndCount(entity, q, opts) {
-        if (!hasRequiredJoin(getMeta(entity), q)) {
+        if (!q.$distinct && !hasRequiredJoin(getMeta(entity), q)) {
             return super.internalFindManyAndCount(entity, q, opts);
         }
         const { $sort: _sort, $skip: _skip, $limit: _limit, ...unpaged } = q;
         const [founds, counted] = await Promise.all([
             this.internalFindMany(entity, q, opts),
             this.execute((session) => this.collection(entity)
-                .aggregate([...this.dialect.aggregationPipeline(entity, unpaged, opts), { $count: COUNT_AGG_ALIAS }], { session })
+                .aggregate([...this.dialect.aggregationPipeline(entity, unpaged, opts), { $count: COUNT_ALIAS }], { session })
                 .toArray()),
         ]);
-        return [founds, counted[0]?.[COUNT_AGG_ALIAS] ?? 0];
+        return [founds, counted[0]?.[COUNT_ALIAS] ?? 0];
     }
     async internalCount(entity, qm = {}, opts) {
         return this.timed('internalCount', undefined, async () => {
             if (this.dialect.constrainsRelations(entity, qm.$where)) {
                 const { stages, filter } = this.dialect.whereWithRelations(entity, qm.$where, opts);
                 const [counted] = await this.execute((session) => this.collection(entity)
-                    .aggregate([...stages, { $match: filter }, { $count: COUNT_AGG_ALIAS }], { session })
+                    .aggregate([...stages, { $match: filter }, { $count: COUNT_ALIAS }], {
+                    session,
+                })
                     .toArray());
-                return counted?.[COUNT_AGG_ALIAS] ?? 0;
+                return counted?.[COUNT_ALIAS] ?? 0;
             }
             const filter = this.dialect.where(entity, qm.$where, opts);
             return this.execute((session) => this.collection(entity).countDocuments(filter, {

package/dist/postgres/postgresDialect.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS } from '../dialect/abstractSqlDialect.js';
+import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 /**

package/dist/querier/abstractQuerier.js

@@ -218,13 +218,12 @@ export class AbstractQuerier {
         const toInsert = [];
         const toUpdate = [];
         const existingIds = [];
-        const idKey = (meta.id ?? 'id');
         for (const it of payload) {
-            const id = it[idKey];
+            const id = it[meta.id];
             if (!id) {
                 toInsert.push(it);
             }
-            else if (!someKey(it, (key) => key !== idKey)) {
+            else if (!someKey(it, (key) => key !== meta.id)) {
                 existingIds.push(id);
             }
             else {
@@ -234,9 +233,9 @@ export class AbstractQuerier {
         const [insertedIds, updatedIds] = await Promise.all([
             toInsert.length ? this.insertMany(entity, toInsert) : [],
             Promise.all(toUpdate.map(async (it) => {
-                const id = it[idKey];
+                const id = it[meta.id];
                 const data = { ...it };
-                delete data[idKey];
+                delete data[meta.id];
                 await this.updateOneById(entity, id, data);
                 return id;
             })),

package/dist/querier/abstractSqlQuerier.d.ts

@@ -52,8 +52,18 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * the end, or a filter nothing matched.
      *
      * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for.
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
      */
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    private countedSeparately;
     protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     private selectRows;
     private hydrateRows;

package/dist/querier/abstractSqlQuerier.js

@@ -1,14 +1,9 @@
-import { COUNT_ALIAS } from '../dialect/abstractSqlDialect.js';
+import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
-/**
- * The column a paged read carries its unpaged total in. Prefixed the way the other internal aliases
- * are, since it rides in the same row as the entity's own columns and must not shadow one.
- */
-const TOTAL_ALIAS = '_uql_total';
 export class AbstractSqlQuerier extends AbstractQuerier {
     dialect;
     extra;
@@ -90,9 +85,31 @@ export class AbstractSqlQuerier extends AbstractQuerier {
      * the end, or a filter nothing matched.
      *
      * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for.
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
      */
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    countedSeparately(entity, q, opts) {
+        if (q.$distinct) {
+            return (ctx) => this.dialect.countDistinct(ctx, entity, q, opts);
+        }
+        if (q.$lock && !this.dialect.supportsWindowWithRowLock) {
+            return (ctx) => this.dialect.count(ctx, entity, q, opts);
+        }
+        return undefined;
+    }
     async internalFindManyAndCount(entity, q, opts) {
+        const separately = this.countedSeparately(entity, q, opts);
+        if (separately) {
+            return Promise.all([this.internalFindMany(entity, q, opts), this.runCount(separately)]);
+        }
         const rows = await this.selectRows(entity, q, opts, TOTAL_ALIAS);
         const total = rows.length ? Number(rows[0][TOTAL_ALIAS]) : await this.internalCount(entity, q, opts);
         for (const row of rows) {

package/dist/querier/relationCount.js

@@ -1,14 +1,7 @@
+import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { getMeta } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, COUNT_AGG_ALIAS, getKeys, parentKeyColumn, targetKeyColumn } from '../util/index.js';
-/**
- * The one place the counting path crosses from the caller's type to a structural one: a relation's
- * entity comes from metadata, which names its columns only as strings. Everything past this is
- * checked against {@link CountedRow} normally.
- */
-function countable(entity) {
-    return entity;
-}
+import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } from '../util/index.js';
 /**
  * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
  * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
@@ -78,10 +71,10 @@ export async function fillRelationCounts(querier, entity, payload, count) {
 async function countPerParent(querier, relOpts, ids, where) {
     const through = relOpts.through;
     if (through) {
-        return countThroughPerParent(querier, relOpts, countable(through()), ids, where);
+        return countThroughPerParent(querier, relOpts, through(), ids, where);
     }
     const foreign = parentKeyColumn(relOpts);
-    return groupedCount(querier, countable(relOpts.entity()), foreign, { ...where, [foreign]: ids });
+    return groupedCount(querier, relOpts.entity(), foreign, { ...where, [foreign]: ids });
 }
 /**
  * A many-to-many counts its junction rows, one per pairing. A filter names the target's columns,
@@ -92,7 +85,7 @@ async function countThroughPerParent(querier, relOpts, throughEntity, ids, where
     const local = parentKeyColumn(relOpts);
     const throughWhere = { [local]: ids };
     if (where) {
-        const target = countable(relOpts.entity());
+        const target = relOpts.entity();
         const targetId = getMeta(target).id;
         const targets = await querier.findMany(target, { $select: { [targetId]: true }, $where: where });
         throughWhere[targetKeyColumn(relOpts)] = targets.map((it) => it[targetId]);
@@ -101,11 +94,11 @@ async function countThroughPerParent(querier, relOpts, throughEntity, ids, where
 }
 /** `SELECT <key>, COUNT(*) ... GROUP BY <key>`, as a lookup from parent key to tally. */
 async function groupedCount(querier, entity, groupKey, where) {
-    const $agg = { [COUNT_AGG_ALIAS]: { $count: '*' } };
+    const $agg = { [COUNT_ALIAS]: { $count: '*' } };
     const rows = await querier.aggregate(entity, { $group: { [groupKey]: true }, $agg, $where: where });
     const byParent = {};
     for (const row of rows) {
-        byParent[String(row[groupKey])] = Number(row[COUNT_AGG_ALIAS]);
+        byParent[String(row[groupKey])] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

package/dist/sqlite/sqliteDialect.js

@@ -1,5 +1,6 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
+import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS } from '../dialect/aliases.js';
+import { jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget } from '../dialect/jsonSql.js';
 export class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     featureDefaults = {

package/dist/type/dialect.d.ts

@@ -22,6 +22,12 @@ export type QueryWhereOptions = QueryComparisonOptions & {
      */
     clause?: 'WHERE' | 'AND' | false;
 };
+/**
+ * Emits a statement, or a fragment of one, into the context it is handed. What a caller passes when
+ * it knows *what* to build but not *where*: the statement is assembled into whichever context the
+ * receiver opens, so the two ends cannot disagree about which one it went into.
+ */
+export type QueryBuildFn = (ctx: QueryContext) => void;
 export interface QueryContext {
     append(sql: string): this;
     addValue(value: unknown): this;

package/dist/util/dialect.util.d.ts

@@ -1,14 +1,4 @@
 import { type CascadeType, type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
-/**
- * The alias an internally-built count answers under - a batched relation tally, a MongoDB relation
- * lookup, a total taken past a `$required` unwind. Every one of those picks the alias and reads it
- * back a few lines later, so they share the spelling rather than each repeating it twice.
- *
- * Prefixed like every other internal alias here: a batched tally selects it alongside the column it
- * groups by, so a bare name would collide with a real column of that name and answer the grouped
- * value twice over, with no statement failing to say so.
- */
-export declare const COUNT_AGG_ALIAS = "_uql_count";
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /**

package/dist/util/dialect.util.js

@@ -1,16 +1,6 @@
 import { getContext, UqlSecurityError } from '../context/context.js';
 import { QueryRaw, resolveAggregateOp, } from '../type/index.js';
 import { getFieldKeys, getKeys, hasKeys, someKey } from './object.util.js';
-/**
- * The alias an internally-built count answers under - a batched relation tally, a MongoDB relation
- * lookup, a total taken past a `$required` unwind. Every one of those picks the alias and reads it
- * back a few lines later, so they share the spelling rather than each repeating it twice.
- *
- * Prefixed like every other internal alias here: a batched tally selects it alongside the column it
- * groups by, so a bare name would collide with a real column of that name and answer the grouped
- * value twice over, with no statement failing to say so.
- */
-export const COUNT_AGG_ALIAS = '_uql_count';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "type": "module",
   "engines": {
     "node": ">=24"