uql-orm 0.36.0 → 0.37.0

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.
      */
@@ -246,10 +264,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 +296,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 +361,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 +390,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 +402,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 +416,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 +424,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>;

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,17 @@ 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.
+     */
+    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 +75,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,8 +1,14 @@
+import { COUNT_ALIAS } from '../dialect/abstractSqlDialect.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
+/**
+ * The column a paged read carries its unpaged total in. Prefixed the way the other internal aliases
+ * are, since it rides in the same row as the entity's own columns and must not shadow one.
+ */
+const TOTAL_ALIAS = '_uql_total';
 export class AbstractSqlQuerier extends AbstractQuerier {
     dialect;
     extra;
@@ -76,11 +82,32 @@ 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.
+     */
+    async internalFindManyAndCount(entity, q, opts) {
+        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 +193,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,111 @@
+import { getMeta } from '../entity/index.js';
+import { COUNT_RESULT_KEY } from '../type/index.js';
+import { asSelectMap, COUNT_AGG_ALIAS, getKeys, parentKeyColumn, targetKeyColumn } from '../util/index.js';
+/**
+ * The one place the counting path crosses from the caller's type to a structural one: a relation's
+ * entity comes from metadata, which names its columns only as strings. Everything past this is
+ * checked against {@link CountedRow} normally.
+ */
+function countable(entity) {
+    return entity;
+}
+/**
+ * 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, countable(through()), ids, where);
+    }
+    const foreign = parentKeyColumn(relOpts);
+    return groupedCount(querier, countable(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 = countable(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_AGG_ALIAS]: { $count: '*' } };
+    const rows = await querier.aggregate(entity, { $group: { [groupKey]: true }, $agg, $where: where });
+    const byParent = {};
+    for (const row of rows) {
+        byParent[String(row[groupKey])] = Number(row[COUNT_AGG_ALIAS]);
+    }
+    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

@@ -65,6 +65,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';
 /**
@@ -113,8 +113,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 +123,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';