uql-orm 0.36.1 → 0.37.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,6 +1,6 @@
 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 { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
@@ -8,6 +8,11 @@ import { isJsonbOp, JSON_ELEM_ALIAS_PREFIX, jsonCompareMode, jsonElemExists } fr
 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
@@ -171,7 +176,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 +191,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 +699,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.
@@ -767,11 +785,22 @@ 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);
+    }
+    /**
+     * 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 +911,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 +1422,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 +1462,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/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

@@ -1,7 +1,7 @@
 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 { AbstractSqlDialect, COUNT_ALIAS } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, 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 +33,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/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

@@ -20,7 +20,12 @@ export declare class MongoDialect extends AbstractDialect {
     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;
+    /**
+     * 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. */
@@ -60,6 +65,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 +123,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;
     /**

package/dist/mongo/mongoDialect.js

@@ -3,7 +3,7 @@ import { AbstractDialect } from '../dialect/abstractDialect.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, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, someKey, } from '../util/index.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';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -29,7 +29,14 @@ export class MongoDialect extends AbstractDialect {
     static ID_KEY = '_id';
     /** Temporary lookup fields for relation conditions, dropped with `$unset` after the `$match`. */
     static REL_TEMP_PREFIX = '__uql_rel_';
-    static REL_COUNT_KEY = 'n';
+    /**
+     * 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. */
@@ -145,7 +152,7 @@ export class MongoDialect extends AbstractDialect {
         const temp = `${MongoDialect.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: MongoDialect.REL_COUNT_KEY }];
+        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: COUNT_AGG_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
@@ -153,7 +160,18 @@ export class MongoDialect extends AbstractDialect {
         const targetCondition = (sizeVal === undefined ? val : {});
         const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, targetCondition), opts);
         lookups.temps.push(temp);
-        lookups.stages.push(relOpts.cardinality === 'mm' && relOpts.through
+        lookups.stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts));
+        return sizeVal === undefined
+            ? { [`${temp}.0`]: { $exists: true } }
+            : { $expr: this.compareRelationCount(temp, sizeVal) };
+    }
+    /**
+     * 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.
+     */
+    relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
+        return relOpts.cardinality === 'mm' && relOpts.through
             ? this.junctionLookup(relOpts, relMeta, relEntity, targetScope, temp, tail, opts)
             : {
                 $lookup: {
@@ -162,10 +180,7 @@ export class MongoDialect extends AbstractDialect {
                     pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), ...tail],
                     as: temp,
                 },
-            });
-        return sizeVal === undefined
-            ? { [`${temp}.0`]: { $exists: true } }
-            : { $expr: this.compareRelationCount(temp, sizeVal) };
+            };
     }
     /**
      * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
@@ -204,7 +219,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}.${MongoDialect.REL_COUNT_KEY}`, 0] }, 0] };
+        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_AGG_ALIAS}`, 0] }, 0] };
         if (typeof sizeVal === 'number') {
             return { $eq: [count, sizeVal] };
         }
@@ -397,10 +412,47 @@ export class MongoDialect extends AbstractDialect {
             // one: ordering by a relation nothing looked up reads a field that is not there, which MongoDB
             // ranks as all-equal rather than rejecting. The SQL dialects can add the join themselves.
             const relPath = `${path}${key}`;
+            const countDirection = parseSortByCount(value);
+            if (countDirection !== undefined) {
+                // The tally rides on a field {@link sortCountStages} adds, which only the queried entity's
+                // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
+                // parent document left to hang it off.
+                if (path) {
+                    throw new TypeError(`$sort by '${relPath}.$count' is only supported on the queried entity`);
+                }
+                out[MongoDialect.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`);
             this.collectSort(join.meta, relationSort, joins, `${relPath}.`, out);
         }
     }
+    /**
+     * 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(entity, sort, opts) {
+        const meta = getMeta(entity);
+        const stages = [];
+        const fields = [];
+        for (const [key, value] of Object.entries(sort ?? {})) {
+            const relOpts = meta.relations[key];
+            if (!relOpts || parseSortByCount(value) === undefined) {
+                continue;
+            }
+            const relEntity = relOpts.entity();
+            const relMeta = getMeta(relEntity);
+            const temp = MongoDialect.sortCountField(key);
+            const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, {}), opts);
+            const tail = [{ $count: COUNT_AGG_ALIAS }];
+            stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts), {
+                $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_AGG_ALIAS}`, 0] }, 0] } },
+            });
+            fields.push(temp);
+        }
+        return { stages, fields };
+    }
     /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
     sortsRelations(entity, sort) {
         if (!sort) {
@@ -459,7 +511,10 @@ export class MongoDialect extends AbstractDialect {
     readStages(entity, q, opts, extra = {}) {
         const meta = getMeta(entity);
         const joins = resolveQueryJoins(meta, q);
-        const lookups = this.lookupStages(meta, joins, undefined, opts);
+        // The tally an ordering by a relation's size reads, and the field it parks it on: both belong
+        // with the lookups, since the `$sort` right after them is what they exist for.
+        const counted = this.sortCountStages(entity, q.$sort, opts);
+        const lookups = [...this.lookupStages(meta, joins, undefined, opts), ...counted.stages];
         const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
         const pager = extra.pager ?? [];
         // Merged into the query's own projection rather than standing in for one: a query that asked
@@ -471,10 +526,14 @@ export class MongoDialect extends AbstractDialect {
         // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
         // it has run, so ordering by an unpopulated relation costs the same nothing it does there.
         const sortOnly = [...joins.values()].filter((join) => !join.projected).map((join) => join.path);
-        const unset = sortOnly.length ? [{ $unset: sortOnly }] : [];
+        const dropped = [...sortOnly, ...counted.fields];
+        const unset = dropped.length ? [{ $unset: dropped }] : [];
         // The grouping collapses rows onto the columns it projects, which leaves nothing for an ordering
         // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
         // the same terms the SQL dialects refuse `SELECT DISTINCT` ordered by an unselected column.
+        if (q.$distinct && counted.fields.length) {
+            throw new TypeError(`cannot $sort by a relation's $count with $distinct: the grouping keeps only the columns it projects`);
+        }
         if (q.$distinct && sortOnly.length) {
             throw new TypeError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
         }

package/dist/mongo/mongodbQuerier.d.ts

@@ -1,6 +1,6 @@
 import type { Document, MongoClient } from 'mongodb';
 import { AbstractQuerier } from '../querier/index.js';
-import type { EntityData, ExtraOptions, IdValue, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import type { MongoDialect } from './mongoDialect.js';
 export declare class MongodbQuerier extends AbstractQuerier {
     readonly dialect: MongoDialect;
@@ -22,7 +22,18 @@ 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>[]>;
-    protected internalCount<E extends Document>(entity: Type<E>, qm?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * The collection's metadata count, which the driver exposes as its own call and which takes no
+     * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
+     */
+    estimatedCount<E extends Document>(entity: Type<E>): Promise<number>;
     /**
      * The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on.
      * Built from the read pipeline rather than stages assembled here: that dropped `$sort`/`$limit` on

package/dist/mongo/mongodbQuerier.js

@@ -1,6 +1,15 @@
+import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { getMeta } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
+import { COUNT_AGG_ALIAS, 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
+ * collection. The reads answer it here instead, since no cursor can express it.
+ */
+function asksForNoRows(q) {
+    return q.$limit === 0;
+}
 export class MongodbQuerier extends AbstractQuerier {
     dialect;
     conn;
@@ -19,6 +28,9 @@ export class MongodbQuerier extends AbstractQuerier {
     }
     async internalFindMany(entity, q, opts) {
         this.dialect.assertNoLock(q);
+        if (asksForNoRows(q)) {
+            return [];
+        }
         return this.timed('internalFindMany', undefined, async () => {
             const meta = getMeta(entity);
             const vectorSort = this.dialect.extractVectorSort(q.$sort);
@@ -51,6 +63,9 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async *internalFindManyStream(entity, q, opts) {
+        if (asksForNoRows(q)) {
+            return;
+        }
         const meta = getMeta(entity);
         const { joinableKeys, toManyKeys } = getRelationRequestSummary(meta, q.$populate);
         if (joinableKeys.length || toManyKeys.length) {
@@ -99,6 +114,7 @@ export class MongodbQuerier extends AbstractQuerier {
         if (q.$skip) {
             cursor.skip(q.$skip);
         }
+        // Only a positive limit reaches the driver; `asksForNoRows` took the zero.
         if (q.$limit) {
             cursor.limit(q.$limit);
         }
@@ -134,14 +150,32 @@ export class MongodbQuerier extends AbstractQuerier {
             return this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
         });
     }
+    /**
+     * 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.
+     */
+    async internalFindManyAndCount(entity, q, opts) {
+        if (!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 })
+                .toArray()),
+        ]);
+        return [founds, counted[0]?.[COUNT_AGG_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: 'n' }], { session })
+                    .aggregate([...stages, { $match: filter }, { $count: COUNT_AGG_ALIAS }], { session })
                     .toArray());
-                return counted?.n ?? 0;
+                return counted?.[COUNT_AGG_ALIAS] ?? 0;
             }
             const filter = this.dialect.where(entity, qm.$where, opts);
             return this.execute((session) => this.collection(entity).countDocuments(filter, {
@@ -149,6 +183,13 @@ export class MongodbQuerier extends AbstractQuerier {
             }));
         });
     }
+    /**
+     * The collection's metadata count, which the driver exposes as its own call and which takes no
+     * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
+     */
+    async estimatedCount(entity) {
+        return this.timed('estimatedCount', undefined, async () => this.execute((session) => this.collection(entity).estimatedDocumentCount({ session })));
+    }
     /**
      * The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on.
      * Built from the read pipeline rather than stages assembled here: that dropped `$sort`/`$limit` on

package/dist/postgres/postgresDialect.d.ts

@@ -11,4 +11,11 @@ export declare class PostgresDialect extends PgLikeSqlDialect {
     readonly dialectName: SqlDialectName;
     readonly vectorExtension: string | undefined;
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
+    /**
+     * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist
+     * (mid-migration, say) where the cast throws. `GREATEST` because a table nothing has analyzed yet
+     * carries `reltuples = -1`, Postgres' "no statistic" (not `NULL`, and not `0`) since PG 14 - handed
+     * back raw it would read as a negative row count.
+     */
+    estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
 }

package/dist/postgres/postgresDialect.js

@@ -1,4 +1,6 @@
+import { COUNT_ALIAS } from '../dialect/abstractSqlDialect.js';
 import { PgLikeSqlDialect } from '../dialect/pgLikeSqlDialect.js';
+import { getMeta } from '../entity/index.js';
 /**
  * PostgreSQL dialect. For node-pg use PgDialect. Neon, Bun SQL, and Cockroach use driver-specific
  * subclasses. Shared Postgres-wire AST/quoting/JSONB/full-text-search/vector-search logic
@@ -13,4 +15,15 @@ export class PostgresDialect extends PgLikeSqlDialect {
         // The xmax system column is 0 for a newly inserted row and non-zero for an updated one (MVCC).
         super.upsert(ctx, entity, conflictPaths, payload, `, (xmax = 0) AS ${this.escapeId('_created')}`);
     }
+    /**
+     * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist
+     * (mid-migration, say) where the cast throws. `GREATEST` because a table nothing has analyzed yet
+     * carries `reltuples = -1`, Postgres' "no statistic" (not `NULL`, and not `0`) since PG 14 - handed
+     * back raw it would read as a negative row count.
+     */
+    estimatedCount(ctx, entity) {
+        ctx.append(`SELECT GREATEST(reltuples, 0)::bigint ${this.escapeId(COUNT_ALIAS, true)} FROM pg_class WHERE oid = to_regclass(`);
+        ctx.addValue(this.escapedTableName(getMeta(entity)));
+        ctx.append(')');
+    }
 }