uql-orm 0.36.1 → 0.37.1

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, fillOnFields, filterFieldKeys, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, 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,10 +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_';
-    static REL_COUNT_KEY = 'n';
-    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;
@@ -142,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: MongoDialect.REL_COUNT_KEY }];
+        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
@@ -153,7 +150,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 +170,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
@@ -175,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),
@@ -204,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}.${MongoDialect.REL_COUNT_KEY}`, 0] }, 0] };
+        const count = { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] };
         if (typeof sizeVal === 'number') {
             return { $eq: [count, sizeVal] };
         }
@@ -397,10 +402,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[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 = sortCountField(key);
+            const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, {}), opts);
+            const tail = [{ $count: COUNT_ALIAS }];
+            stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts), {
+                $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_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 +501,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 +516,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, 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>;
+    /**
+     * 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,16 @@
+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 { 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 +29,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 +64,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 +115,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 +151,34 @@ 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, 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 (!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_ALIAS }], { session })
+                .toArray()),
+        ]);
+        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: 'n' }], { session })
+                    .aggregate([...stages, { $match: filter }, { $count: COUNT_ALIAS }], {
+                    session,
+                })
                     .toArray());
-                return counted?.n ?? 0;
+                return counted?.[COUNT_ALIAS] ?? 0;
             }
             const filter = this.dialect.where(entity, qm.$where, opts);
             return this.execute((session) => this.collection(entity).countDocuments(filter, {
@@ -149,6 +186,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/aliases.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(')');
+    }
 }

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPopulate, QueryProjected, QuerySearch, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 /**
  * Base class for all database queriers.
@@ -30,23 +30,23 @@ export declare abstract class AbstractQuerier implements Querier {
     protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
         $entity: Type<E>;
     }), maybeQueryOrOpts?: Q | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, Q, QueryOptions | undefined];
-    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
+    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * Find a single record matching the query.
      * Supports both entity-as-argument and entity-as-field patterns.
      */
-    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryOneProjected<E, S, V, X, P> & {
+    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryOneProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
-    }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
-    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
+    }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
+    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * Find multiple records matching the query.
      * Supports both entity-as-argument and entity-as-field patterns.
      */
-    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P> & {
+    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
-    }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P>[]>;
-    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P>[]>;
+    }, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
+    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     protected abstract internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     /**
      * Stream records as an async iterable.
@@ -60,33 +60,49 @@ export declare abstract class AbstractQuerier implements Querier {
      *
      * No `afterLoad` hooks on streamed rows.
      */
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P> & {
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryStreamProjected<E, S, V, X, P> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
     protected abstract internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
     /**
      * Find multiple records and return both the records and total count.
      * Supports both entity-as-argument and entity-as-field patterns.
      */
-    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P> & {
+    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(q: QueryProjected<E, S, V, X, P, C> & {
         $entity: Type<E>;
-    }, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P>[], number]>;
-    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P>[], number]>;
+    }, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
+    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
     /**
-     * Count records matching the query.
-     * Supports both entity-as-argument and entity-as-field patterns.
+     * The page and how many rows the filter matched beyond it. Two statements here, which is what a
+     * backend with no way to answer both at once is left with; SQL overrides it to answer from one.
+     */
+    protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
+    /**
+     * Count records matching the query, in both the entity-as-argument and entity-as-field patterns.
+     * A `$skip`/`$limit` settles the matching ids and counts those, rather than scanning every match;
+     * `$sort` never reaches that SELECT, since it changes which rows a page holds, never how many.
      */
-    count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    count<E extends object>(q: QuerySearch<E> & {
+    count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(q: QueryPage<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    protected abstract internalCount<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    protected abstract internalCount<E extends object>(entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * Whether anything matches, in both the entity-as-argument and entity-as-field patterns. A count
+     * capped at one row, so the engine stops at the first match instead of scanning every other one.
+     */
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
+    exists<E extends object>(q: QueryFilter<E> & {
+        $entity: Type<E>;
+    }, opts?: QueryOptions): Promise<boolean>;
     /**
      * Run an aggregate query.
      */
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     protected abstract internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
+    /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
+    abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,7 @@
 import { getMeta } from '../entity/index.js';
-import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, LoggerWrapper, parentKeyColumn, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
+import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
  * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
  * `{ $where: id }`, and a nullish `$where` is *no filter*, so an unchecked one addresses the whole
@@ -92,7 +93,8 @@ export class AbstractQuerier {
     async findMany(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const founds = await this.internalFindMany(entity, q, opts);
+        const founds = await this.internalFindMany(entity, withIdForCounts(entity, q), opts);
+        await fillRelationCounts(this, entity, founds, q.$count);
         await this.emitHook(entity, 'afterLoad', founds);
         return founds;
     }
@@ -104,18 +106,34 @@ export class AbstractQuerier {
     async findManyAndCount(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const { $sort: _, $limit: _l, $skip: _s, ...qCount } = q;
-        const [founds, count] = await Promise.all([
-            this.internalFindMany(entity, q, opts),
-            this.internalCount(entity, qCount, opts),
-        ]);
+        const [founds, count] = await this.internalFindManyAndCount(entity, withIdForCounts(entity, q), opts);
+        await fillRelationCounts(this, entity, founds, q.$count);
         await this.emitHook(entity, 'afterLoad', founds);
         return [founds, count];
     }
-    count(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
+    /**
+     * The page and how many rows the filter matched beyond it. Two statements here, which is what a
+     * backend with no way to answer both at once is left with; SQL overrides it to answer from one.
+     */
+    async internalFindManyAndCount(entity, q, opts) {
+        return Promise.all([
+            this.internalFindMany(entity, q, opts),
+            this.internalCount(entity, { $where: q.$where }, opts),
+        ]);
+    }
+    async count(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
+        if (q.$skip !== undefined || q.$limit !== undefined) {
+            const meta = getMeta(entity);
+            const rows = await this.internalFindMany(entity, idOnlyQuery(meta, { $where: q.$where, $skip: q.$skip, $limit: q.$limit }), opts);
+            return rows.length;
+        }
         return this.internalCount(entity, q, opts);
     }
+    async exists(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
+        const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
+        return (await this.count(entity, { $where: q.$where, $limit: 1 }, opts)) > 0;
+    }
     /**
      * Run an aggregate query.
      */
@@ -200,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 {
@@ -216,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;
             })),
@@ -246,10 +263,10 @@ export class AbstractQuerier {
         }
     }
     async fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery) {
-        const localField = relOpts.references[0].local;
+        const localField = parentKeyColumn(relOpts);
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
-        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === relOpts.references[1].local));
+        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetKeyColumn(relOpts)));
         const ids = payload.map((it) => it[meta.id]);
         // A relation query names the target's columns, not the join table's, so the projection and the
         // filter belong on the populate below - resolved there against the entity that has them. Spread
@@ -278,7 +295,7 @@ export class AbstractQuerier {
         this.putChildrenInParents(payload, founds, meta.id, localField, relKey);
     }
     async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
-        const foreignField = relOpts.references[0].foreign;
+        const foreignField = parentKeyColumn(relOpts);
         // The FK is what putChildrenInParents groups on, so it outlives the relation's projection
         // either way: added to a whitelisting `$select` (the raw-array form has nothing to augment),
         // dropped from a subtractive `$exclude`. `relationQuery` is already a clone.
@@ -343,15 +360,9 @@ export class AbstractQuerier {
             if (!relOpts)
                 continue;
             const relEntity = relOpts.entity();
-            const localField = relOpts.references[0].local;
-            if (relOpts.through) {
-                const throughEntity = relOpts.through();
-                await this.deleteMany(throughEntity, { $where: { [localField]: ids } }, opts);
-            }
-            else {
-                const foreignField = relOpts.references[0].foreign;
-                await this.deleteMany(relEntity, { $where: { [foreignField]: ids } }, opts);
-            }
+            const parentKey = parentKeyColumn(relOpts);
+            const target = relOpts.through ? relOpts.through() : relEntity;
+            await this.deleteMany(target, { $where: { [parentKey]: ids } }, opts);
         }
     }
     /**
@@ -378,9 +389,9 @@ export class AbstractQuerier {
         }
     }
     async saveToMany(relOpts, relEntity, ids, relPayload, isUpdate) {
-        const { references, through } = relOpts;
+        const { through } = relOpts;
         if (through) {
-            const localField = references[0].local;
+            const localField = parentKeyColumn(relOpts);
             const throughEntity = through();
             if (isUpdate) {
                 await this.deleteMany(throughEntity, { $where: { [localField]: ids } });
@@ -390,12 +401,12 @@ export class AbstractQuerier {
                 // would link every parent to a single shared row instead.
                 for (const id of ids) {
                     const savedIds = await this.saveMany(relEntity, relPayload);
-                    await this.insertMany(throughEntity, savedIds.map((relId) => ({ [references[0].local]: id, [references[1].local]: relId })));
+                    await this.insertMany(throughEntity, savedIds.map((relId) => ({ [localField]: id, [targetKeyColumn(relOpts)]: relId })));
                 }
             }
             return;
         }
-        const foreignField = references[0].foreign;
+        const foreignField = parentKeyColumn(relOpts);
         if (isUpdate) {
             await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
         }
@@ -404,7 +415,7 @@ export class AbstractQuerier {
         }
     }
     async saveOneToOne(relEntity, relOpts, ids, relPayload) {
-        const foreignField = relOpts.references[0].foreign;
+        const foreignField = parentKeyColumn(relOpts);
         if (relPayload === null) {
             await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
             return;
@@ -412,6 +423,8 @@ export class AbstractQuerier {
         await this.saveMany(relEntity, ids.map((id) => ({ ...relPayload, [foreignField]: id })));
     }
     async saveManyToOne(entity, relEntity, relOpts, ids, relPayload) {
+        // Not `parentKeyColumn`: a many-to-one points the other way, so this is the *parent's* own column
+        // holding the child's id - the one place `references[0].local` does not name a key of the parent.
         const localField = relOpts.references[0].local;
         // Per parent: each gets its own reference row, so each `SET` carries a different value.
         for (const id of ids) {

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, ExtraOptions, FieldKey, IdValue, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryProjected, QuerySearch, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, FieldKey, IdValue, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -24,17 +24,19 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     withQuerier<T>(callback: (querier: Q) => Promise<T>, opts?: PoolRunOptions): Promise<T>;
     /** Run `fn` under `context` (an enclosing {@link withContext}) when provided, else run it as-is. */
     private runScoped;
-    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
-    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
-    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P>[]>;
+    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
+    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
+    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     /**
      * The connection outlives the call here: it is held until the iterator is drained or closed by a
      * `break`/`throw`. Abandoning the iterator instead leaks it until GC, so consume it in a `for await`.
      */
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncGenerator<QueryFindResult<E, S, V, X, P>>;
-    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P>[], number]>;
-    count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncGenerator<QueryFindResult<E, S, V, X, P>>;
+    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
+    count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
+    estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;