uql-orm 0.36.1 → 0.37.1

package/dist/dialect/abstractSqlDialect.js

@@ -1,10 +1,11 @@
 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, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/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';
@@ -91,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) {
@@ -171,7 +171,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     appendTextSearch(_ctx, _entity, _meta, _search) {
         throw new TypeError(`${this.dialectName} does not support $text full-text search`);
     }
-    select(ctx, entity, q, opts = {}, joins = NO_JOINS) {
+    select(ctx, entity, q, opts = {}, joins = NO_JOINS, totalAlias) {
         const meta = getMeta(entity);
         const { alias, ref } = this.tableRef(meta);
         const prefix = this.resolveRelationAwarePrefix(alias, meta, opts, q.$populate, joins);
@@ -186,6 +186,9 @@ export class AbstractSqlDialect extends IndexSqlDialect {
                 this.appendVectorProjection(ctx, meta, key, val);
             }
         }
+        if (totalAlias) {
+            ctx.append(`, ${this.totalOverExpr} ${this.escapeId(totalAlias, true)}`);
+        }
         ctx.append(` FROM ${ref}`);
         // Add JOINs AFTER FROM clause
         this.selectRelationJoins(ctx, meta, alias, joins);
@@ -691,6 +694,16 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             const relation = meta.relations[key];
             if (relation) {
                 const relPath = path ? `${path}.${key}` : key;
+                const countDirection = parseSortByCount(value);
+                if (countDirection !== undefined) {
+                    // A correlated count, not a join: a parent has many of these, so what is being ordered by
+                    // is how many, and `SELECT DISTINCT` cannot order by an expression it did not select.
+                    if (opts.distinct) {
+                        throw new TypeError(`cannot $sort by '${relPath}.$count' with $distinct: it is not a selected column`);
+                    }
+                    columns.push(this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, relation, { prefix }, 'COUNT(*)', {})) + this.resolveSortDirection(countDirection));
+                    continue;
+                }
                 const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, value, opts.joins ?? NO_JOINS, `cannot $sort by relation '${relPath}': this statement joins no relations`);
                 // `SELECT DISTINCT` can only order by what it selected, on every engine here, so a join
                 // brought in for the sort alone has nothing to order by. Populating it selects its columns.
@@ -735,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. */
@@ -767,11 +786,37 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         const suffix = wait === 'skip' ? ' SKIP LOCKED' : wait === 'nowait' ? ' NOWAIT' : '';
         ctx.append(` FOR UPDATE${target}${suffix}`);
     }
-    // `QueryFilter`, not `QuerySearch`: a count orders nothing and pages nothing, and an `OFFSET`
-    // would push its single row out of the result set. The parameter type is what keeps them away.
+    // `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(ctx, entity, q, opts) {
-        this.select(ctx, entity, { $select: [raw('COUNT(*)', 'count')] });
-        this.search(ctx, entity, q, opts);
+        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
+     * caller reached for this to avoid, and only say so by taking a long time.
+     */
+    estimatedCount(_ctx, _entity) {
+        throw new TypeError(`${this.dialectName} does not support estimatedCount`);
     }
     /** `$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
@@ -882,11 +927,16 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             }
         });
     }
-    find(ctx, entity, q = {}, opts) {
+    /**
+     * How many rows the filter matched, on every row of the page. A window function runs before
+     * LIMIT/OFFSET, so what it counts is the whole match rather than the page cut out of it.
+     */
+    totalOverExpr = 'COUNT(*) OVER ()';
+    find(ctx, entity, q = {}, opts, totalAlias) {
         // The one statement that can join, so the one that resolves the join set; everything else renders
         // against `NO_JOINS` and rejects a `$sort` that would need one.
         const joins = resolveQueryJoins(getMeta(entity), q);
-        this.select(ctx, entity, q, opts, joins);
+        this.select(ctx, entity, q, opts, joins, totalAlias);
         this.search(ctx, entity, q, opts, joins);
         // Appended here rather than in `search`, which `count`/`update`/`delete` share: a lock belongs
         // to a SELECT alone. Every engine spells it after LIMIT/OFFSET, so it goes last.
@@ -1388,8 +1438,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      * invisible here just as it is to a joined `$populate`. The caller's filter bypass is deliberately
      * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
-    appendRelationSubquery(ctx, entity, rel, opts, projection, val) {
-        const meta = getMeta(entity);
+    appendRelationSubquery(ctx, meta, rel, opts, projection, val) {
         // Aliases, not paths, everywhere a column is prefixed; `tableRef` declares them in the FROM.
         const parentAlias = this.resolveTableAlias(meta);
         const references = rel.references;
@@ -1429,11 +1478,11 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
     compareRelation(ctx, entity, val, rel, opts) {
         ctx.append('EXISTS ');
-        this.appendRelationSubquery(ctx, entity, rel, opts, '1', val);
+        this.appendRelationSubquery(ctx, getMeta(entity), rel, opts, '1', val);
     }
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     compareRelationSize(ctx, entity, sizeVal, rel, opts) {
-        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, entity, rel, opts, 'COUNT(*)', {}), sizeVal);
+        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, getMeta(entity), rel, opts, 'COUNT(*)', {}), sizeVal);
     }
     /**
      * Build a complete `$size` comparison expression.

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.d.ts

@@ -13,6 +13,12 @@ import { AbstractSqlDialect } from './abstractSqlDialect.js';
 export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */
     protected readonly featureDefaults: DialectFeatures;
+    /**
+     * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before
+     * anything has been analyzed. `DATABASE()` where the entity names no schema, so the estimate comes
+     * from the connection's own database rather than a same-named table in another one.
+     */
+    estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
     /** `OFFSET` is only legal after a `LIMIT` here, so a bare `$skip` needs one. */
     pager(ctx: QueryContext, opts: QueryPager): void;
     readonly serialPrimaryKey = "BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY";

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -2,7 +2,8 @@ import { getMeta } from '../entity/index.js';
 import { getFieldKeys } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
-import { JSON_PULL_ALIAS, jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.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);
 /**
@@ -33,6 +34,24 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         supportsTimestamptz: false,
         defaultStringAsText: false,
     };
+    /**
+     * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before
+     * anything has been analyzed. `DATABASE()` where the entity names no schema, so the estimate comes
+     * from the connection's own database rather than a same-named table in another one.
+     */
+    estimatedCount(ctx, entity) {
+        const meta = getMeta(entity);
+        const schema = this.resolveSchema(meta);
+        ctx.append(`SELECT TABLE_ROWS ${this.escapeId(COUNT_ALIAS, true)} FROM information_schema.TABLES WHERE TABLE_SCHEMA = `);
+        if (schema) {
+            ctx.addValue(schema);
+        }
+        else {
+            ctx.append('DATABASE()');
+        }
+        ctx.append(' AND TABLE_NAME = ');
+        ctx.addValue(this.resolveTableAlias(meta));
+    }
     /** `OFFSET` is only legal after a `LIMIT` here, so a bare `$skip` needs one. */
     pager(ctx, opts) {
         if (opts.$limit === undefined && opts.$skip !== undefined) {

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/dialect/queryJoins.d.ts

@@ -40,6 +40,12 @@ export type QuerySortOptions = {
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
+/**
+ * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
+ * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
+ * it counts the parents the read will never hand back.
+ */
+export declare function hasRequiredJoin<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
 /**
  * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
  * Every backend answers this the same way - a to-many has no single value to order by, a relation

package/dist/dialect/queryJoins.js

@@ -16,6 +16,19 @@ export function resolveQueryJoins(meta, q) {
     addSortJoins(joins, meta, q.$sort);
     return joins;
 }
+/**
+ * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
+ * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
+ * it counts the parents the read will never hand back.
+ */
+export function hasRequiredJoin(meta, q) {
+    for (const join of resolveQueryJoins(meta, q).values()) {
+        if (join.required) {
+            return true;
+        }
+    }
+    return false;
+}
 function addJoin(joins, parent, key, relation, query, required, projected) {
     const path = parent ? `${parent.path}.${key}` : key;
     const existing = joins.get(path);

package/dist/http/contract.d.ts

@@ -78,13 +78,6 @@ export type RouteMatch = {
  * Resolve a (method, sub-path) pair to a CRUD operation. Literal sub-paths win over `:id`.
  */
 export declare function matchRoute(method: string, subPath: string | undefined): RouteMatch | undefined;
-export type RequestSuccessResponse<E> = {
-    data: E;
-    count?: number;
-};
-export type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {
-    count: number;
-};
 export type RequestErrorResponse = {
     readonly error: {
         readonly message: string;

package/dist/http/handler.d.ts

@@ -1,5 +1,5 @@
-import type { EntityMeta, QuerierPool, Query, Type, UqlContext } from '../type/index.js';
-import { type CrudOperation, type HttpMethod, type RequestSuccessResponse } from './contract.js';
+import type { EntityMeta, QuerierPool, Query, RequestSuccessResponse, Type, UqlContext } from '../type/index.js';
+import { type CrudOperation, type HttpMethod } from './contract.js';
 /**
  * Framework-normalized request: adapters (express, fetch, ...) reduce their native
  * request to this shape and get back a status + JSON body.

package/dist/http/handler.js

@@ -1,6 +1,6 @@
 import { withContext } from '../context/context.js';
 import { getEntities, getMeta } from '../entity/index.js';
-import { entityPath, matchRoute, } from './contract.js';
+import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
 function tableOf(entity) {

package/dist/http/query.js

@@ -1,5 +1,5 @@
 // the clause lists themselves, not the barrel: this module is in the browser bundle's graph
-import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES } from '../type/query.js';
+import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys } from '../util/object.util.js';
 /**
@@ -10,6 +10,7 @@ import { getKeys } from '../util/object.util.js';
  */
 const ALLOWED_QUERY_KEYS = new Set([
     ...QUERY_OBJECT_CLAUSES,
+    ...QUERY_ROOT_OBJECT_CLAUSES,
     ...QUERY_NUMBER_CLAUSES,
     ...QUERY_BOOLEAN_CLAUSES,
     'hardDelete',
@@ -36,7 +37,7 @@ export function parseQueryParams(params = {}) {
             query[key] = params[key];
         }
     }
-    for (const key of QUERY_OBJECT_CLAUSES) {
+    for (const key of [...QUERY_OBJECT_CLAUSES, ...QUERY_ROOT_OBJECT_CLAUSES]) {
         const value = query[key];
         if (typeof value === 'string') {
             try {

package/dist/mongo/mongoDialect.d.ts

@@ -18,10 +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;
-    private static readonly REL_COUNT_KEY;
-    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;
@@ -60,6 +56,12 @@ export declare class MongoDialect extends AbstractDialect {
      * relation subquery can no more read out-of-scope rows than a direct query on the target can.
      */
     private appendRelationLookup;
+    /**
+     * The correlated `$lookup` for one relation, as `temp`: through its junction for a ManyToMany, or
+     * straight at the target otherwise. `tail` decides what the lookup leaves behind - a row to test
+     * for existence, or a `$count` - so a filter and an ordering build the same stage.
+     */
+    private relationLookup;
     /**
      * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
      * lookup - the junction's filters apply too, since a soft-deleted link is not a link.
@@ -112,6 +114,15 @@ export declare class MongoDialect extends AbstractDialect {
     sort<E extends Document>(entity: Type<E>, sort?: QuerySortMap<E>, populate?: QueryPopulate<E>): Sort;
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
     private collectSort;
+    /**
+     * The stages a `$sort` by a relation's size needs: one correlated `$lookup` tallying the relation
+     * per parent, and the `$set` that lifts the tally onto the document as the field the `$sort` then
+     * orders by. A parent with no related row gets no lookup result at all, which is a zero.
+     */
+    sortCountStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QueryOptions): {
+        readonly stages: MongoAggregationPipelineEntry<Document>[];
+        readonly fields: string[];
+    };
     /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
     sortsRelations<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): boolean;
     /**