uql-orm 0.36.1 → 0.37.1

package/dist/querier/abstractQuerierPool.js

@@ -121,9 +121,15 @@ export class AbstractQuerierPool {
     count(entity, q, opts) {
         return this.withQuerier((querier) => querier.count(entity, q, opts));
     }
+    exists(entity, q, opts) {
+        return this.withQuerier((querier) => querier.exists(entity, q, opts));
+    }
     aggregate(entity, q, opts) {
         return this.withQuerier((querier) => querier.aggregate(entity, q, opts));
     }
+    estimatedCount(entity) {
+        return this.withQuerier((querier) => querier.estimatedCount(entity));
+    }
     insertOne(entity, payload) {
         return this.withQuerier((querier) => querier.insertOne(entity, payload));
     }

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -46,6 +46,27 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     protected assertLockable<E>(entity: Type<E>, q: Query<E>): void;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
+    /**
+     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
+     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
+     * the end, or a filter nothing matched.
+     *
+     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
+     */
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    private countedSeparately;
+    protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
+    private selectRows;
+    private hydrateRows;
     protected internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<Awaited<E>, void, unknown>;
     /**
      * Internal streaming query - returns an async iterable of raw rows.
@@ -64,7 +85,14 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * which cost more than the decoding it guards, on a flat read.
      */
     private hydrateFields;
-    protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
+     * a catalog that does not know the table answers with no row, which is nothing counted.
+     */
+    private runCount;
+    protected internalCount<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
+    estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     protected 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>[]>;
     internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;

package/dist/querier/abstractSqlQuerier.js

@@ -1,3 +1,4 @@
+import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
@@ -76,11 +77,54 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     async internalFindMany(entity, q, opts) {
+        return this.hydrateRows(entity, q, await this.selectRows(entity, q, opts));
+    }
+    /**
+     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
+     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
+     * the end, or a filter nothing matched.
+     *
+     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
+     */
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    countedSeparately(entity, q, opts) {
+        if (q.$distinct) {
+            return (ctx) => this.dialect.countDistinct(ctx, entity, q, opts);
+        }
+        if (q.$lock && !this.dialect.supportsWindowWithRowLock) {
+            return (ctx) => this.dialect.count(ctx, entity, q, opts);
+        }
+        return undefined;
+    }
+    async internalFindManyAndCount(entity, q, opts) {
+        const separately = this.countedSeparately(entity, q, opts);
+        if (separately) {
+            return Promise.all([this.internalFindMany(entity, q, opts), this.runCount(separately)]);
+        }
+        const rows = await this.selectRows(entity, q, opts, TOTAL_ALIAS);
+        const total = rows.length ? Number(rows[0][TOTAL_ALIAS]) : await this.internalCount(entity, q, opts);
+        for (const row of rows) {
+            delete row[TOTAL_ALIAS];
+        }
+        return [await this.hydrateRows(entity, q, rows), total];
+    }
+    async selectRows(entity, q, opts, totalAlias) {
         this.assertLockable(entity, q);
         const ctx = this.dialect.createContext();
-        this.dialect.find(ctx, entity, q, opts);
-        const res = await this.all(ctx.sql, ctx.values);
-        const founds = unflatObjects(res).map((row) => this.hydrateFields(entity, row));
+        this.dialect.find(ctx, entity, q, opts, totalAlias);
+        return this.all(ctx.sql, ctx.values);
+    }
+    async hydrateRows(entity, q, rows) {
+        const founds = unflatObjects(rows).map((row) => this.hydrateFields(entity, row));
         await this.fillToManyRelations(entity, founds, q.$populate);
         return founds;
     }
@@ -166,13 +210,22 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         return dto;
     }
-    async internalCount(entity, q = {}, opts) {
+    /**
+     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
+     * a catalog that does not know the table answers with no row, which is nothing counted.
+     */
+    async runCount(build) {
         const ctx = this.dialect.createContext();
-        this.dialect.count(ctx, entity, q, opts);
+        build(ctx);
         const res = await this.all(ctx.sql, ctx.values);
-        // `COUNT(*)` is BIGINT, which the pools decode at the wire - but a caller who supplies their own
-        // `types` replaces that, and the signature promises a number here regardless.
-        return Number(res[0].count);
+        return Number(res[0]?.[COUNT_ALIAS] ?? 0);
+    }
+    async internalCount(entity, q = {}, opts) {
+        return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));
+    }
+    async estimatedCount(entity) {
+        return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
     }
     async internalAggregate(entity, q, opts) {
         const ctx = this.dialect.createContext();

package/dist/querier/relationCount.d.ts

@@ -0,0 +1,16 @@
+import type { Querier, Query, QueryCount, Type } from '../type/index.js';
+/** What counting asks of a querier, rather than the whole interface: two reads, both batched. */
+type CountingQuerier = Pick<Querier, 'aggregate' | 'findMany'>;
+/**
+ * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
+ * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
+ * `$exclude` loses it; the raw-array `$select` form has nothing to augment, so it is refused.
+ */
+export declare function withIdForCounts<E extends object>(entity: Type<E>, q: Query<E>): Query<E>;
+/**
+ * How many rows each counted relation holds, under `_count` on every parent. One grouped aggregate
+ * per relation over every parent at once - the batching a populated to-many already gets - so the
+ * cost stays flat in the number of rows the read returned rather than one statement per row.
+ */
+export declare function fillRelationCounts<E>(querier: CountingQuerier, entity: Type<E>, payload: E[], count?: QueryCount<E>): Promise<void>;
+export {};

package/dist/querier/relationCount.js

@@ -0,0 +1,104 @@
+import { COUNT_ALIAS } from '../dialect/aliases.js';
+import { getMeta } from '../entity/index.js';
+import { COUNT_RESULT_KEY } from '../type/index.js';
+import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } from '../util/index.js';
+/**
+ * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
+ * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
+ * `$exclude` loses it; the raw-array `$select` form has nothing to augment, so it is refused.
+ */
+export function withIdForCounts(entity, q) {
+    const meta = getMeta(entity);
+    if (!q.$count || !meta.id) {
+        return q;
+    }
+    if (q.$distinct) {
+        // The id would have to join the projection for the tallies to group by, and that is the set
+        // `$distinct` collapses on: adding it silently stops the grouping collapsing anything at all.
+        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${String(meta.id)}', which the grouping does not keep.`);
+    }
+    if (Array.isArray(q.$select)) {
+        // Nothing to add the id to, and without it every tally would be looked up by `undefined` and
+        // come back zero. Refused rather than answered wrong, the way an unorderable clause is.
+        throw new TypeError(`$count needs the '${String(meta.id)}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
+    }
+    const next = { ...q };
+    const select = asSelectMap(q.$select);
+    if (select && !select[meta.id]) {
+        next.$select = { ...select, [meta.id]: true };
+    }
+    if (q.$exclude?.[meta.id]) {
+        const kept = { ...q.$exclude };
+        delete kept[meta.id];
+        next.$exclude = kept;
+    }
+    return next;
+}
+/**
+ * How many rows each counted relation holds, under `_count` on every parent. One grouped aggregate
+ * per relation over every parent at once - the batching a populated to-many already gets - so the
+ * cost stays flat in the number of rows the read returned rather than one statement per row.
+ */
+export async function fillRelationCounts(querier, entity, payload, count) {
+    if (!payload.length || !count) {
+        return;
+    }
+    const meta = getMeta(entity);
+    // The ids cross the same boundary the entity does: past here every column is named by metadata,
+    // so they are read as {@link CountedRow}'s values rather than as this entity's own id type.
+    const ids = payload.map((it) => it[meta.id]);
+    const counted = new Map();
+    for (const relKey of getKeys(count)) {
+        const value = count[relKey];
+        const relOpts = meta.relations[relKey];
+        if (!value || !relOpts) {
+            continue;
+        }
+        const where = typeof value === 'object' ? value.$where : undefined;
+        counted.set(relKey, await countPerParent(querier, relOpts, ids, where));
+    }
+    for (const parent of payload) {
+        const id = String(parent[meta.id]);
+        const row = {};
+        for (const [relKey, byParent] of counted) {
+            // A parent the grouped result has no row for matched nothing, which is a zero rather than a
+            // gap: `_count` names what the caller asked to count, so every key it asked for is present.
+            row[relKey] = byParent[id] ?? 0;
+        }
+        parent[COUNT_RESULT_KEY] = row;
+    }
+}
+async function countPerParent(querier, relOpts, ids, where) {
+    const through = relOpts.through;
+    if (through) {
+        return countThroughPerParent(querier, relOpts, through(), ids, where);
+    }
+    const foreign = parentKeyColumn(relOpts);
+    return groupedCount(querier, relOpts.entity(), foreign, { ...where, [foreign]: ids });
+}
+/**
+ * A many-to-many counts its junction rows, one per pairing. A filter names the target's columns,
+ * which the junction does not have, so the matching targets are resolved first and the junction
+ * counted against them - the one shape here that costs a second statement, and only when filtered.
+ */
+async function countThroughPerParent(querier, relOpts, throughEntity, ids, where) {
+    const local = parentKeyColumn(relOpts);
+    const throughWhere = { [local]: ids };
+    if (where) {
+        const target = relOpts.entity();
+        const targetId = getMeta(target).id;
+        const targets = await querier.findMany(target, { $select: { [targetId]: true }, $where: where });
+        throughWhere[targetKeyColumn(relOpts)] = targets.map((it) => it[targetId]);
+    }
+    return groupedCount(querier, throughEntity, local, throughWhere);
+}
+/** `SELECT <key>, COUNT(*) ... GROUP BY <key>`, as a lookup from parent key to tally. */
+async function groupedCount(querier, entity, groupKey, where) {
+    const $agg = { [COUNT_ALIAS]: { $count: '*' } };
+    const rows = await querier.aggregate(entity, { $group: { [groupKey]: true }, $agg, $where: where });
+    const byParent = {};
+    for (const row of rows) {
+        byParent[String(row[groupKey])] = Number(row[COUNT_ALIAS]);
+    }
+    return byParent;
+}

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,5 +1,5 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, QueryContext, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type, VectorDistance } from '../type/index.js';
 export declare class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     protected readonly featureDefaults: DialectFeatures;
@@ -30,6 +30,11 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly caseInsensitiveMatch = "native";
     protected get neOp(): string;
     normalizeValue(value: unknown): unknown;
+    /**
+     * `OFFSET` is only legal after a `LIMIT` here too, so a bare `$skip` needs one - `-1` being
+     * SQLite's own spelling of "no limit", where the MySQL family uses its largest `BIGINT`.
+     */
+    pager(ctx: QueryContext, opts: QueryPager): void;
     /**
      * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).

package/dist/sqlite/sqliteDialect.js

@@ -1,5 +1,6 @@
 import { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
-import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS, jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
+import { JSON_ELEM_ALIAS_PREFIX, JSON_PULL_ALIAS } from '../dialect/aliases.js';
+import { jsonAssignCall, jsonElemExists, jsonPath, jsonRemoveCall, jsonSetTarget } from '../dialect/jsonSql.js';
 export class SqliteDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for SQLite and SQLite-derived dialects. */
     featureDefaults = {
@@ -65,6 +66,16 @@ export class SqliteDialect extends AbstractSqlDialect {
             return value.getTime();
         return super.normalizeValue(value);
     }
+    /**
+     * `OFFSET` is only legal after a `LIMIT` here too, so a bare `$skip` needs one - `-1` being
+     * SQLite's own spelling of "no limit", where the MySQL family uses its largest `BIGINT`.
+     */
+    pager(ctx, opts) {
+        if (opts.$limit === undefined && opts.$skip !== undefined) {
+            ctx.append(' LIMIT -1');
+        }
+        super.pager(ctx, opts);
+    }
     /**
      * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).

package/dist/type/dialect.d.ts

@@ -1,5 +1,5 @@
 import type { UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOptions, QuerySearch } from './query.js';
+import type { Query, QueryConflictPaths, QueryFilter, QueryOptions, QuerySearch } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
@@ -22,6 +22,12 @@ export type QueryWhereOptions = QueryComparisonOptions & {
      */
     clause?: 'WHERE' | 'AND' | false;
 };
+/**
+ * Emits a statement, or a fragment of one, into the context it is handed. What a caller passes when
+ * it knows *what* to build but not *where*: the statement is assembled into whichever context the
+ * receiver opens, so the two ends cannot disagree about which one it went into.
+ */
+export type QueryBuildFn = (ctx: QueryContext) => void;
 export interface QueryContext {
     append(sql: string): this;
     addValue(value: unknown): this;
@@ -113,8 +119,9 @@ export interface QueryDialect {
      * @param entity the target entity
      * @param q the criteria options
      * @param opts the query options
+     * @param totalAlias when given, carry the unpaged match count on every row under this alias
      */
-    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
+    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
     /**
      * counts the number of records matching the given search parameters.
      * @param ctx the query context
@@ -122,7 +129,7 @@ export interface QueryDialect {
      * @param q the criteria options
      * @param opts the query options
      */
-    count<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): void;
     /**
      * insert records.
      * @param ctx the query context

package/dist/type/index.d.ts

@@ -15,3 +15,4 @@ export * from './queryWhere.js';
 export * from './universalQuerier.js';
 export * from './utility.js';
 export * from './vector.js';
+export * from './wire.js';

package/dist/type/index.js

@@ -15,3 +15,4 @@ export * from './queryWhere.js';
 export * from './universalQuerier.js';
 export * from './utility.js';
 export * from './vector.js';
+export * from './wire.js';

package/dist/type/querier.d.ts

@@ -4,7 +4,7 @@ import type { SqlDialectName } from './dialect.js';
 import type { FieldKey, HookEvent, RelationKey } from './entity.js';
 import type { LoggingOptions } from './logger.js';
 import type { NamingStrategy } from './namingStrategy.js';
-import type { QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryProjected, QuerySearch, QueryUpdateResult } from './query.js';
+import type { QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
 import type { UniversalQuerier } from './universalQuerier.js';
 import type { Type } from './utility.js';
 /**
@@ -35,39 +35,46 @@ export interface Querier extends UniversalQuerier {
     /**
      * Find one record. 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 many records. 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>[]>;
     /**
      * Stream records as an async iterable. Supports both patterns.
      * Does not fill relations or fire lifecycle hooks.
      */
-    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>>;
     /**
      * Find many records and count. Supports both 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. Supports both patterns.
      */
-    count<E extends object>(q: QueryFilter<E> & {
+    count<E extends object>(q: QueryPage<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
-    count<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * Whether anything matches. Supports both patterns.
+     */
+    exists<E extends object>(q: QueryFilter<E> & {
+        $entity: Type<E>;
+    }, opts?: QueryOptions): Promise<boolean>;
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     /**
      * Delete many records (soft-deletes when the entity has a soft-delete field, else removes them).
      * Supports both entity-as-argument and entity-as-field patterns.

package/dist/type/query.d.ts

@@ -59,6 +59,20 @@ export type QueryExclude<E> = QuerySelect<E>;
 export type QueryPopulate<E> = {
     [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
 };
+/**
+ * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
+ * which ones count. One statement per relation named here, batched over every parent at once, so it
+ * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
+ * a relation of the same name that `$populate` filled with rows.
+ */
+/**
+ * The key a read carries its relation tallies under. One spelling for the type and the runtime that
+ * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
+ */
+export declare const COUNT_RESULT_KEY = "_count";
+export type QueryCount<E> = {
+    [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
+};
 /**
  * query conflict paths - subset of field keys used to detect upsert conflicts.
  */
@@ -139,8 +153,15 @@ type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
  * against an intersection is repeated per constituent, which made this the single most expensive
  * type in the package to check.
  */
+/**
+ * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
+ * The tally is computed per parent as a correlated count, never by loading the rows.
+ */
+export type QuerySortByCount = {
+    $count: QuerySortDirection;
+};
 export type QuerySortMap<E, Vector extends boolean = true> = {
-    [K in FieldKey<E> | JsonFieldPaths<E> | ToOneRelationKey<E>]?: K extends RelationKey<E> ? QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
+    [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E> ? IsMany<E[K]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };
 /**
  * pager options.
@@ -156,8 +177,7 @@ export type QueryPager = {
     $limit?: number;
 };
 /**
- * Which rows a statement addresses. `count` takes exactly this: how many rows match is all a count
- * can answer, so an ordering or a page on it is a clause it could only drop or choke on.
+ * Which rows a statement addresses.
  */
 export type QueryFilter<E> = {
     /**
@@ -166,18 +186,22 @@ export type QueryFilter<E> = {
     $where?: QueryWhere<E>;
 };
 /**
- * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the rows they
- * picked with a SELECT before writing, so the page is portable rather than MySQL-only - and so a
+ * A filter plus the page `count` takes. No `$sort`: ordering picks *which* rows a page holds, never
+ * how many, so a count that accepted one would promise an influence it cannot have.
+ */
+export type QueryPage<E> = QueryFilter<E> & QueryPager;
+/**
+ * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the
+ * rows they address with a SELECT first, so the page is portable rather than MySQL-only, and a
  * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the
- * projection list to hold the distance. `$lock` is the clause that stays off these, declared on
- * {@link Query} instead.
+ * projection list to hold the distance. `$lock` stays off these, declared on {@link Query} instead.
  */
-export type QuerySearch<E> = QueryFilter<E> & {
+export type QuerySearch<E> = QueryPage<E> & {
     /**
      * sorting options.
      */
     $sort?: QuerySortMap<E>;
-} & QueryPager;
+};
 /**
  * query options.
  */
@@ -192,6 +216,10 @@ export type Query<E> = {
      * relation population options.
      */
     $populate?: QueryPopulate<E>;
+    /**
+     * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.
+     */
+    $count?: QueryCount<E>;
     /**
      * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
      * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
@@ -240,6 +268,12 @@ export type Query<E> = {
  * query accepts, so leaving it out is what excludes it from both.
  */
 export declare const QUERY_OBJECT_CLAUSES: readonly ["$select", "$populate", "$exclude", "$where", "$sort"];
+/**
+ * Object clauses only the statement itself takes, never a relation's own query - the mirror of
+ * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a
+ * populated relation's rows are assembled after that, so there is nothing for a nested one to count.
+ */
+export declare const QUERY_ROOT_OBJECT_CLAUSES: readonly ["$count"];
 export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
 export declare const QUERY_BOOLEAN_CLAUSES: readonly ["$distinct"];
 /**
@@ -263,7 +297,18 @@ export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$popula
  * populated relation's own query - stays the concrete {@link Query} it is today.
  * @internal
  */
-type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = {
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = QueryStreamProjection<E, S, V, X, P> & {
+    $count?: {
+        [K in C & keyof QueryCount<E>]?: QueryCount<E>[K];
+    };
+};
+/**
+ * {@link QueryProjection} without `$count`, which a stream cannot honor. Split out rather than
+ * subtracted afterwards: an optional key is a *known* key even when its value maps over `never`, so
+ * a statement that must not take the clause has to be built without it in the first place.
+ * @internal
+ */
+type QueryStreamProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = {
     $select?: {
         [K in S]?: V;
     } | readonly QueryRaw[];
@@ -274,14 +319,19 @@ type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P exten
         [K in P]?: QueryPopulate<E>[K];
     };
 };
+/**
+ * A {@link QueryProjected} a stream can honor: no `$count`, which is batched over a result set a
+ * stream never holds all of.
+ */
+export type QueryStreamProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = Except<Query<E>, '$count'> & QueryStreamProjection<E, S, V, X, P>;
 /**
  * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = Query<E> & QueryProjection<E, S, V, X, P>;
+export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = Query<E> & QueryProjection<E, S, V, X, P, C>;
 /**
  * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = QueryOne<E> & QueryProjection<E, S, V, X, P>;
+export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = QueryOne<E> & QueryProjection<E, S, V, X, P, C>;
 /**
  * The keys a query comes back with, mirroring what the runtime projects: the fields a positive
  * `$select` names, or every field minus what a falsy `$select` entry or a truthy `$exclude` entry
@@ -289,7 +339,7 @@ export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>
  * why `$exclude` is only read on the branch where there is none.
  * @internal
  */
-type ProjectedKeys<E, S, V, X, P> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P | ([P] extends [never] ? never : NamedIdKey<E>);
+type ProjectedKeys<E, S, V, X, P, C> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P | ([P | C] extends [never] ? never : NamedIdKey<E>);
 /**
  * The id key when it can be named, and nothing when it cannot: {@link IdKey} widens to *every* field
  * for an entity whose id is neither branded nor called `id`/`_id`/`uuid`, and adding that back would
@@ -315,11 +365,22 @@ type IsUniform<V> = [V] extends [true | 1] ? true : [V] extends [false | 0] ? tr
  * keep their declared type: narrowing them means capturing their queries as maps, which costs those
  * queries their own checks.
  */
-export type QueryFindResult<E, S extends FieldKey<E> = never, V = true, X extends FieldKey<E> = never, P extends RelationKey<E> = never> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? {
-    [K in keyof E as K extends ProjectedKeys<E, S, V, X, P> ? K : never]: E[K];
+export type QueryFindResult<E, S extends FieldKey<E> = never, V = true, X extends FieldKey<E> = never, P extends RelationKey<E> = never, C extends RelationKey<E> = never> = QueryProjectedRow<E, S, V, X, P, C> & CountedRelations<C>;
+/**
+ * The `_count` a query asked for, or an inert intersection member when it asked for none - so a read
+ * without `$count` keeps exactly the row type it had.
+ */
+type CountedRelations<C extends PropertyKey> = [C] extends [never] ? unknown : {
+    [K in typeof COUNT_RESULT_KEY]: {
+        [R in C]: number;
+    };
+};
+/** @internal */
+type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? {
+    [K in keyof E as K extends ProjectedKeys<E, S, V, X, P, C> ? K : never]: E[K];
 } : // A populated to-many is always a list, empty where the parent has no children, so it maps
 {
-    [K in keyof E as K extends Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> ? K : never]: E[K];
+    [K in keyof E as K extends Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> ? K : never]: E[K];
 } & {
     [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;
 } : E;