uql-orm 0.36.1 → 0.37.0

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;

package/dist/type/query.js

@@ -1,3 +1,14 @@
+/**
+ * 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 const COUNT_RESULT_KEY = '_count';
 /**
  * `Query`'s clauses grouped by the shape of their value - what a parser reading one off the wire and
  * a validator checking a relation's own query both need, and what each used to enumerate for itself.
@@ -14,5 +25,11 @@ export const QUERY_OBJECT_CLAUSES = [
     '$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 const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];

package/dist/type/universalQuerier.d.ts

@@ -1,11 +1,20 @@
 import type { EntityData, FieldKey, IdValue, RelationKey, UpdatePayload } from './entity.js';
-import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryProjected, QuerySearch, QueryUpdateResult } from './query.js';
+import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
+import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
 /**
- * A `querier` allows to interact with the datasource to perform persistence operations on any entity.
+ * The operations {@link UniversalQuerier} and `ClientQuerier` declare identically, written once and
+ * instantiated per transport: `SharedQuerier<'server', QueryOptions>` against
+ * `SharedQuerier<'client', RequestOptions, QueryOptions & RequestOptions>`. See {@link QuerierResult}
+ * for how the return type follows `W`.
+ *
+ * @typeParam W - which side of the wire, picking each method's return type.
+ * @typeParam O - the per-call options.
+ * @typeParam DO - the delete methods' options, which the client also lets carry {@link QueryOptions}
+ * (`hardDelete`, `filters`) since it has no other way to reach them.
  */
-export interface UniversalQuerier {
+export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
     /**
      * obtains the record with the given primary key.
      * @param entity the target entity
@@ -13,30 +22,21 @@ export interface UniversalQuerier {
      * @param q the additional criteria options
      * @return the record
      */
-    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?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the first record matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the record
      */
-    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>;
+    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?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the records matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the records
      */
-    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>[]>;
-    /**
-     * streams the records matching the given search parameters as an async iterable.
-     * Does not fill relations or fire lifecycle hooks - designed for high-performance
-     * bulk reads (ETL, exports, migrations).
-     * @param entity the target entity
-     * @param q the criteria options
-     * @return an async iterable of records
-     */
-    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>>;
+    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?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C>[]>;
     /**
      * obtains the records matching the given search parameters,
      * also counts the number of matches ignoring pagination.
@@ -44,14 +44,67 @@ export interface UniversalQuerier {
      * @param q the criteria options
      * @return the records and the count
      */
-    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]>;
+    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?: O): QuerierCountedResult<W, QueryFindResult<E, S, V, X, P, C>>;
     /**
-     * counts the number of records matching the given filter.
+     * counts the number of records matching the given filter, optionally paged - a `$skip`/`$limit`
+     * settles the matching rows first and counts them, rather than scanning every match.
      * @param entity the target entity
      * @param q the filter
      * @return the count
      */
-    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?: O): QuerierResult<W, number>;
+    /**
+     * whether any record matches the given filter - a count capped at one row, so the engine stops at
+     * the first match instead of scanning every other one.
+     * @param entity the target entity
+     * @param q the filter
+     * @return whether anything matched
+     */
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: O): QuerierResult<W, boolean>;
+    /**
+     * updates a record partially.
+     * @param entity the entity to persist on
+     * @param id the primary key of the record to be updated
+     * @param payload the data to be persisted
+     * @return the number of affected records
+     */
+    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    /**
+     * updates many records partially.
+     * @param entity the entity to persist on
+     * @param q the criteria to look for the records
+     * @param payload the data to be persisted
+     * @return the number of affected records
+     */
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    /**
+     * delete or SoftDelete a record.
+     * @param entity the entity to persist on
+     * @param id the primary key of the record
+     * @return the number of affected records
+     */
+    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: DO): QuerierResult<W, number>;
+    /**
+     * delete or SoftDelete records.
+     * @param entity the entity to persist on
+     * @param q the criteria to look for the records
+     * @return the number of affected records
+     */
+    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: DO): QuerierResult<W, number>;
+}
+/**
+ * A `querier` allows to interact with the datasource to perform persistence operations on any entity.
+ */
+export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions> {
+    /**
+     * streams the records matching the given search parameters as an async iterable.
+     * Does not fill relations or fire lifecycle hooks - designed for high-performance
+     * bulk reads (ETL, exports, migrations).
+     * @param entity the target entity
+     * @param q the criteria options
+     * @return an async iterable of records
+     */
+    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>>;
     /**
      * Insert a single record and return its ID (provided, `onInsert`-generated, or
      * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
@@ -78,22 +131,6 @@ export interface UniversalQuerier {
      * @return the IDs
      */
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    /**
-     * updates a record partially.
-     * @param entity the entity to persist on
-     * @param id the primary key of the record to be updated
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
-    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * updates many records partially.
-     * @param entity the entity to persist on
-     * @param q the criteria to look for the records
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Insert or update a record based on the conflict paths.
      * @param entity the entity to persist on
@@ -124,20 +161,6 @@ export interface UniversalQuerier {
      * @return the IDs
      */
     saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    /**
-     * delete or SoftDelete a record.
-     * @param entity the entity to persist on
-     * @param id the primary key of the record
-     * @return the number of affected records
-     */
-    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * delete or SoftDelete records.
-     * @param entity the entity to persist on
-     * @param q the criteria to look for the records
-     * @return the number of affected records
-     */
-    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.
@@ -151,4 +174,18 @@ export interface UniversalQuerier {
      * @return the aggregate results
      */
     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>[]>;
+    /**
+     * How many rows the engine's own statistics say the table holds, without reading one: Postgres'
+     * `pg_class.reltuples`, CockroachDB's table statistics, MySQL/MariaDB's `information_schema`,
+     * MongoDB's `estimatedDocumentCount`. For a table too big to {@link count} cheaply.
+     *
+     * The whole table, and only ever approximately. It takes no filter because none of those sources
+     * can answer one, which also puts soft-deleted rows and every entity `filters` inside the number.
+     * It is as stale as the last `ANALYZE`/autovacuum (Postgres reports nothing at all until the
+     * first one, which reads here as `0`), and a table SQLite can answer for does not exist - it
+     * throws there rather than quietly running the scan this exists to avoid.
+     * @param entity the target entity
+     * @return the estimated number of rows
+     */
+    estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
 }

package/dist/type/wire.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The envelope a wire response wraps its result in.
+ */
+export type RequestSuccessResponse<E> = {
+    data: E;
+    count?: number;
+};
+/**
+ * A {@link RequestSuccessResponse} whose `count` is always present - what `findManyAndCount` sends.
+ */
+export type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {
+    count: number;
+};
+/**
+ * Which side of the wire a querier sits on. A server querier hands the result back directly, a
+ * client one hands back the envelope its transport wrapped it in.
+ */
+export type QuerierTransport = 'server' | 'client';
+/**
+ * A querier method's result on the given transport, so one signature serves both:
+ * `QuerierResult<'server', User[]>` is `Promise<User[]>` and `QuerierResult<'client', User[]>` is
+ * `Promise<RequestSuccessResponse<User[]>>`. Indexing a map by the transport is what stands in for
+ * the higher-kinded wrapper TypeScript cannot express, and it resolves away: errors and hovers show
+ * the `Promise<User[]>` it picked, never this indirection.
+ */
+export type QuerierResult<W extends QuerierTransport, T> = {
+    server: Promise<T>;
+    client: Promise<RequestSuccessResponse<T>>;
+}[W];
+/**
+ * `findManyAndCount`'s result: the one shape the transports disagree on past the envelope, a tuple
+ * on the server against a counted envelope on the client.
+ */
+export type QuerierCountedResult<W extends QuerierTransport, T> = {
+    server: Promise<[T[], number]>;
+    client: Promise<RequestCountedSuccessResponse<T[]>>;
+}[W];

package/dist/type/wire.js

@@ -0,0 +1 @@
+export {};

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,14 @@
 import { type CascadeType, type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
+/**
+ * The alias an internally-built count answers under - a batched relation tally, a MongoDB relation
+ * lookup, a total taken past a `$required` unwind. Every one of those picks the alias and reads it
+ * back a few lines later, so they share the spelling rather than each repeating it twice.
+ *
+ * Prefixed like every other internal alias here: a batched tally selects it alongside the column it
+ * groups by, so a bare name would collide with a real column of that name and answer the grouped
+ * value twice over, with no statement failing to say so.
+ */
+export declare const COUNT_AGG_ALIAS = "_uql_count";
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /**
@@ -108,6 +118,12 @@ export type ParsedGroupEntry = {
  * through to field filtering and emit a condition on a `$size` *column*.
  */
 export declare function parseRelationSize(val: unknown): number | QuerySizeComparisonOps | undefined;
+/**
+ * The direction a `$sort` orders a to-many relation by its size, or `undefined` when the value is a
+ * map of the relation's own fields (which only a to-one can be ordered by). Mirrors
+ * {@link parseRelationSize}, the same clause spelled for a filter rather than an ordering.
+ */
+export declare function parseSortByCount(val: unknown): unknown;
 /**
  * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.

package/dist/util/dialect.util.js

@@ -1,6 +1,16 @@
 import { getContext, UqlSecurityError } from '../context/context.js';
 import { QueryRaw, resolveAggregateOp, } from '../type/index.js';
 import { getFieldKeys, getKeys, hasKeys, someKey } from './object.util.js';
+/**
+ * The alias an internally-built count answers under - a batched relation tally, a MongoDB relation
+ * lookup, a total taken past a `$required` unwind. Every one of those picks the alias and reads it
+ * back a few lines later, so they share the spelling rather than each repeating it twice.
+ *
+ * Prefixed like every other internal alias here: a batched tally selects it alongside the column it
+ * groups by, so a bare name would collide with a real column of that name and answer the grouped
+ * value twice over, with no statement failing to say so.
+ */
+export const COUNT_AGG_ALIAS = '_uql_count';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -290,6 +300,21 @@ export function parseRelationSize(val) {
     }
     return val.$size;
 }
+/**
+ * The direction a `$sort` orders a to-many relation by its size, or `undefined` when the value is a
+ * map of the relation's own fields (which only a to-one can be ordered by). Mirrors
+ * {@link parseRelationSize}, the same clause spelled for a filter rather than an ordering.
+ */
+export function parseSortByCount(val) {
+    if (!val || typeof val !== 'object' || !('$count' in val)) {
+        return undefined;
+    }
+    const siblings = getKeys(val).filter((key) => key !== '$count');
+    if (siblings.length) {
+        throw new TypeError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
+    }
+    return val.$count;
+}
 /**
  * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.

package/dist/util/relationQuery.util.d.ts

@@ -9,6 +9,15 @@ export type RelationRequestSummary<E> = {
  * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
  */
 export declare function isToManyRelation(relation: Pick<RelationMeta, 'cardinality'>): boolean;
+/**
+ * The column holding the parent's id: a junction's own for a relation that goes through one, the
+ * child's foreign key otherwise. The two are spelled from opposite ends - `local` names a column of
+ * the table the relation is declared to write, `foreign` a column of the other one - and getting
+ * that backwards reads a real column of the wrong table, so it is answered once here.
+ */
+export declare function parentKeyColumn(relOpts: Pick<RelationMeta, 'references' | 'through'>): string;
+/** The column on a junction table holding the target's id, the other half of {@link parentKeyColumn}. */
+export declare function targetKeyColumn(relOpts: Pick<RelationMeta, 'references'>): string;
 /**
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is
  * what gives these four a meaning there; a to-one is one row of the parent's, so every backend used

package/dist/util/relationQuery.util.js

@@ -7,6 +7,19 @@ import { getKeys, someKey } from './object.util.js';
 export function isToManyRelation(relation) {
     return relation.cardinality === '1m' || relation.cardinality === 'mm';
 }
+/**
+ * The column holding the parent's id: a junction's own for a relation that goes through one, the
+ * child's foreign key otherwise. The two are spelled from opposite ends - `local` names a column of
+ * the table the relation is declared to write, `foreign` a column of the other one - and getting
+ * that backwards reads a real column of the wrong table, so it is answered once here.
+ */
+export function parentKeyColumn(relOpts) {
+    return relOpts.through ? relOpts.references[0].local : relOpts.references[0].foreign;
+}
+/** The column on a junction table holding the target's id, the other half of {@link parentKeyColumn}. */
+export function targetKeyColumn(relOpts) {
+    return relOpts.references[1].local;
+}
 /**
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is
  * what gives these four a meaning there; a to-one is one row of the parent's, so every backend used