uql-orm 0.56.0 → 0.57.0

package/dist/type/query.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, IdKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
+import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -25,16 +25,6 @@ export type QueryOptions = {
      */
     autoPrefix?: boolean;
 };
-export type QuerySelectOptions = {
-    /**
-     * prefix the query with this.
-     */
-    prefix?: string;
-    /**
-     * automatically add the prefix for the alias.
-     */
-    autoPrefixAlias?: boolean;
-};
 /**
  * Query field selection - `{ name: true }` whitelists specific fields. Fields only: a relation is a
  * sub-query rather than a projection flag, and a whitelist naming one could not say whether the
@@ -66,9 +56,8 @@ export type QueryPopulate<E> = {
 export declare const COUNT_RESULT_KEY = "_count";
 /**
  * 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.
+ * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes
+ * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.
  */
 export type QueryCount<E> = {
     [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
@@ -82,7 +71,7 @@ export type QueryConflictPaths<E> = {
 /**
  * Options to populate a relation declared as `V`, by its cardinality.
  */
-export type QueryPopulateRelationOptions<V> = (IsMany<V> extends true ? Except<Query<RelationTarget<V>>, '$lock'> : QueryUnique<RelationTarget<V>>) & {
+export type QueryPopulateRelationOptions<V> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>> : QueryUnique<RelationTarget<V>> & {
     $required?: boolean;
 };
 /**
@@ -276,14 +265,13 @@ export type Query<E> = {
  * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
  * rather than the runtime if a clause is ever renamed.
  *
- * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's
- * query accepts, so leaving it out is what excludes it from both.
+ * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
+ * accepts it.
  */
 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.
+ * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
+ * so a `$count` inside one would have no `_count` to land in.
  */
 export declare const QUERY_ROOT_OBJECT_CLAUSES: readonly ["$count"];
 export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
@@ -294,6 +282,16 @@ export declare const QUERY_NUMBER_CLAUSES: readonly ["$skip", "$limit"];
  */
 export declare const QUERY_ROOT_NUMBER_CLAUSES: readonly ["$candidates"];
 export declare const QUERY_BOOLEAN_CLAUSES: readonly ["$distinct"];
+/** The clauses that describe the statement, which a populated relation's own query refuses by name. */
+export declare const QUERY_STATEMENT_CLAUSES: readonly ["$lock", "$count", "$candidates"];
+type RelationClause = (typeof QUERY_OBJECT_CLAUSES | typeof QUERY_NUMBER_CLAUSES | typeof QUERY_BOOLEAN_CLAUSES)[number];
+/**
+ * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot
+ * drift, and a clause added to {@link Query} stays off it until it joins one of them.
+ */
+export type RelationQuery<E = object> = Pick<Query<E>, RelationClause> & {
+    $required?: boolean;
+};
 /**
  * options to get a single record.
  */
@@ -315,18 +313,7 @@ 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>, 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>> = {
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
     $select?: {
         [K in S]?: V;
     } | readonly QueryRaw[];
@@ -336,12 +323,10 @@ type QueryStreamProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P
     $populate?: {
         [K in P]?: QueryPopulate<E>[K];
     };
+    $count?: {
+        [K in C & keyof QueryCount<E>]?: QueryCount<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.
  */
@@ -357,15 +342,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, 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
- * hand the caller a row claiming fields the query never fetched. Missing an id costs a `$select`
- * entry; promising absent fields is the bug this type exists to prevent.
- * @internal
- */
-type NamedIdKey<E> = [FieldKey<E>] extends [IdKey<E>] ? never : IdKey<E>;
+type ProjectedKeys<E, S, V, X, P> = ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S) | P;
 /**
  * Whether every entry of the captured map says the same thing: all selected, or all subtracted.
  * @internal
@@ -394,8 +371,8 @@ type CountedRelations<C extends PropertyKey> = [C] extends [never] ? unknown : {
     };
 };
 /** @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] ? Pick<E, ProjectedKeys<E, S, V, X, P, C> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
-Pick<E, Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> & keyof E> & {
+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] ? Pick<E, ProjectedKeys<E, S, V, X, P> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
+Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E> & {
     [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;
 } : E;
 /** The to-many relations a query populated, which come back as lists rather than as optional ones. */

package/dist/type/query.js

@@ -9,8 +9,8 @@ export const COUNT_RESULT_KEY = '_count';
  * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
  * rather than the runtime if a clause is ever renamed.
  *
- * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's
- * query accepts, so leaving it out is what excludes it from both.
+ * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
+ * accepts it.
  */
 export const QUERY_OBJECT_CLAUSES = [
     '$select',
@@ -20,9 +20,8 @@ export const QUERY_OBJECT_CLAUSES = [
     '$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.
+ * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
+ * so a `$count` inside one would have no `_count` to land in.
  */
 export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
@@ -33,3 +32,9 @@ export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
  */
 export const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];
+/** The clauses that describe the statement, which a populated relation's own query refuses by name. */
+export const QUERY_STATEMENT_CLAUSES = [
+    '$lock',
+    ...QUERY_ROOT_OBJECT_CLAUSES,
+    ...QUERY_ROOT_NUMBER_CLAUSES,
+];

package/dist/type/queryAggregate.d.ts

@@ -37,7 +37,7 @@ export type QueryAggregateOp = (typeof QUERY_AGGREGATE_OPS)[number];
 export declare function isQueryAggregateOp(op: string): op is QueryAggregateOp;
 /**
  * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` → `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
+ * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
  * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
  * are omitted: DISTINCT is a no-op for them.
  */
@@ -91,11 +91,11 @@ type ExactlyOne<T> = {
  * compile error). Only `$count` accepts `'*'` (i.e. `COUNT(*)`); every other op requires a field.
  * DISTINCT variants are flat ops (`$countDistinct`/`$sumDistinct`/`$avgDistinct`) taking a field.
  *
- * @example { $count: '*' }            → COUNT(*)
- * @example { $countDistinct: 'id' }   → COUNT(DISTINCT "id")
- * @example { $sum: 'amount' }         → SUM("amount")
- * @example { $sumDistinct: 'amount' } → SUM(DISTINCT "amount")
- * @example { $avg: 'age' }            → AVG("age")
+ * @example { $count: '*' }            -> COUNT(*)
+ * @example { $countDistinct: 'id' }   -> COUNT(DISTINCT "id")
+ * @example { $sum: 'amount' }         -> SUM("amount")
+ * @example { $sumDistinct: 'amount' } -> SUM(DISTINCT "amount")
+ * @example { $avg: 'age' }            -> AVG("age")
  */
 export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
 /** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
@@ -113,7 +113,7 @@ type CountingOp = OpsOf<'$count' | '$countDistinct'>;
  *
  * @example
  * ```ts
- * { status: true } // → GROUP BY "status"
+ * { status: true } // -> GROUP BY "status"
  * ```
  */
 export type QueryGroupMap<E> = {
@@ -127,7 +127,7 @@ export type QueryGroupMap<E> = {
  * @example
  * ```ts
  * { count: { $count: '*' }, avgAge: { $avg: 'age' } }
- * // → COUNT(*) AS "count", AVG("age") AS "avgAge"
+ * // -> COUNT(*) AS "count", AVG("age") AS "avgAge"
  * ```
  */
 export type QueryAggMap<E> = {
@@ -172,11 +172,11 @@ export type QueryAggregateResult<E, G, A> = Simplify<{
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
 /**
- * Erased runtime shape of a HAVING clause (alias → comparison), consumed by the dialect builders.
+ * Erased runtime shape of a HAVING clause (alias -> comparison), consumed by the dialect builders.
  * Values are `unknown` because the SQL is built generically; the typed, per-column value checking
  * lives in {@link QueryAggregate.$having}.
  *
- * @example { count: { $gt: 5 } }   → HAVING COUNT(*) > 5
+ * @example { count: { $gt: 5 } }   -> HAVING COUNT(*) > 5
  */
 export type QueryHavingMap = {
     readonly [alias: string]: QueryWhereFieldValue<unknown> | undefined;

package/dist/type/queryAggregate.js

@@ -8,7 +8,7 @@ export function isQueryAggregateOp(op) {
 }
 /**
  * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` → `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
+ * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
  * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
  * are omitted: DISTINCT is a no-op for them.
  */

package/dist/type/universalQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
-import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
+import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult } 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';
@@ -97,14 +97,14 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
  */
 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
+     * streams the records matching the given search parameters as an async iterable, each with the
+     * relations and counts `findMany` reads. Fires no lifecycle hooks, and holds one row at a time, for
      * 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>>;
+    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, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     /**
      * Insert a single record and return its ID (provided, `onInsert`-generated, or
      * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).

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

@@ -128,7 +128,7 @@ export type ParsedGroupEntry = {
     readonly alias: string;
     readonly op: QueryAggregateOp;
     readonly fieldRef: string;
-    /** `true` for a flat distinct op (`$countDistinct`, ...) → `COUNT(DISTINCT field)`. */
+    /** `true` for a flat distinct op (`$countDistinct`, ...) -> `COUNT(DISTINCT field)`. */
     readonly distinct: boolean;
 };
 /**

package/dist/util/field.util.d.ts

@@ -22,6 +22,11 @@ export declare const COLUMN_TYPES_BY_FAMILY: {
 };
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
+/**
+ * Whether a field's column holds whole numbers: a declared integer type, or a `Number` or `BigInt`
+ * with no scale, which every engine here stores as BIGINT.
+ */
+export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'columnType' | 'precision' | 'scale'>): boolean;
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -

package/dist/util/field.util.js

@@ -46,6 +46,25 @@ for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
 export function columnFamily(type) {
     return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
+/** The numeric column types that hold whole numbers. */
+const INTEGER_COLUMN_TYPES = new Set([
+    'int',
+    'integer',
+    'tinyint',
+    'smallint',
+    'bigint',
+]);
+/**
+ * Whether a field's column holds whole numbers: a declared integer type, or a `Number` or `BigInt`
+ * with no scale, which every engine here stores as BIGINT.
+ */
+export function isIntegerColumn(field) {
+    const type = field.columnType ?? field.type;
+    if (typeof type === 'string') {
+        return INTEGER_COLUMN_TYPES.has(type.toLowerCase());
+    }
+    return type === BigInt || (type === Number && !field.precision && !field.scale);
+}
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -

package/dist/util/object.util.d.ts

@@ -19,6 +19,8 @@ export declare function someValue(obj: object, pred: (value: unknown) => boolean
 export declare function isOperatorObject(value: unknown): value is Record<string, unknown>;
 /** Whether every key of the non-empty object `value` is an operator (no plain field names mixed in). */
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
+/** Whether `value` is an object that is not an array, whose keys can be read. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
 /** The entries of `record` holding a value: a key declared but left `undefined` is no entry at all. */
 export declare function definedEntries<K extends string, V>(record: Partial<Record<K, V>>): [K, V][];

package/dist/util/object.util.js

@@ -49,6 +49,10 @@ export function isOperatorObject(value) {
 export function isOperatorOnlyObject(value) {
     return hasKeys(value) && !Array.isArray(value) && !someKey(value, (key) => !isOperatorKey(key));
 }
+/** Whether `value` is an object that is not an array, whose keys can be read. */
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 export function getKeys(obj) {
     return obj ? Object.keys(obj) : [];
 }

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

@@ -1,4 +1,4 @@
-import type { EntityMeta, FieldMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
+import type { EntityMeta, QueryCount, QueryPopulate, RelationKey, RelationMeta, RelationQuery, QueryWhere } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: readonly RelationKey<E>[];
     readonly joinableKeys: readonly RelationKey<E>[];
@@ -32,67 +32,10 @@ export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | '
  * which is the mistake this module exists to prevent.
  */
 export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
-/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
-export declare function joinedColumns(joins: readonly ParentJoin[]): Record<string, true>;
-/**
- * One side's columns: `'parent'` for the columns a parent is keyed by, `'joined'` for the ones a
- * child or tally row carries that key in. Matching the two halves means agreeing on every column, so
- * each side is read through `joins` rather than through the parent's own key list - the same set only
- * for a to-many, and silently a different one otherwise. `keyof ParentJoin` is what keeps the two
- * sides from being spelled apart.
- *
- * Lifted out of `joins` once per relation, not once per row: {@link rowKey} takes the list and reads
- * each row itself, so a page of children costs one key each and nothing else.
- */
-export declare function keyColumns(joins: readonly ParentJoin[], side: keyof ParentJoin): string[];
-/**
- * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
- * children in one statement.
- *
- * A composite over-selects, because the lists are independent and a pairing no parent has can still
- * match. Regrouping the rows keys on every column, so those rows find no parent and are dropped -
- * cheaper than the row-value comparison no engine spells the same way.
- */
-export declare function parentsIn(joins: readonly ParentJoin[], parents: readonly unknown[]): Record<string, unknown[]>;
-/**
- * The parents a bounded to-many read fans out over: the rows themselves, the columns matching them to
- * their children.
- */
-export type ParentPartition = {
-    readonly joins: readonly ParentJoin[];
-    readonly parents: readonly unknown[];
-    /** The parent's own fields: a `LATERAL` row source has to spell its key column's type. */
-    readonly parentFields: Readonly<Record<string, FieldMeta | undefined>>;
-};
-/**
- * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
- * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
- * correct and cheaper.
- */
-export declare function isBoundedPerParent(query: Pick<RelationQuery, '$limit' | '$skip'>): boolean;
-/**
- * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
- * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
- * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
- */
-export declare function queryChildrenOf<E>(query: Query<E>, joins: readonly ParentJoin[], parent: unknown): Query<E>;
-/**
- * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
- * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
- */
-export declare function queryChildrenOfAll<E>(query: Query<E>, joins: readonly ParentJoin[], parents: readonly unknown[]): Query<E>;
-/**
- * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
- * the parents it is being read for, whether the filter names their keys as values or, for a correlated
- * shape, as a reference to a row source.
- */
-export declare function queryNarrowedTo<E>(query: Query<E>, filter: Record<string, unknown>): Query<E>;
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
- * column a single key contributes, an OR of key maps for several.
- *
- * Exact, unlike {@link parentsIn}: a read absorbs over-selection by regrouping its rows, and a write
- * has nothing to regroup - a pairing no parent has would delete a child of a parent that survives.
+ * column a single key contributes, an OR of whole key maps for several - lists of each column apart
+ * would pair values no parent has, and a delete would take a child of a parent that survives.
  */
 export declare function childrenOf(joins: readonly ParentJoin[], parentIds: readonly unknown[]): Record<string, unknown>;
 /**
@@ -107,11 +50,15 @@ export type JoinedRelationRejectedKey = (typeof JOINED_RELATION_REJECTIONS)[numb
 export declare function getRelationRequestSummary<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): RelationRequestSummary<E>;
 /** True when `$populate` includes at least one relation key. */
 export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
-export type RelationQuery<E extends object = object> = Except<Query<E>, StatementOnlyClause> & {
-    $required?: boolean;
-};
-/** The clauses that describe the statement rather than what a query selects. */
-type StatementOnlyClause = '$lock' | '$candidates';
+/**
+ * Each relation a `$count` tallies, and the filter narrowing what it counts: the target's, whose type
+ * only the metadata knows this far down, as for a relation filter reaching the same subquery.
+ */
+export declare function countedRelations<E>(meta: EntityMeta<E>, counts: QueryCount<E> | undefined): {
+    readonly relKey: RelationKey<E>;
+    readonly relation: RelationMeta;
+    readonly where: QueryWhere<unknown>;
+}[];
 export type ParsedRelationQuery<E extends object = object> = {
     query: RelationQuery<E>;
     required: boolean;

package/dist/util/relationQuery.util.js

@@ -1,5 +1,5 @@
-import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, } from '../type/query.js';
-import { getKeys, someKey } from './object.util.js';
+import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_STATEMENT_CLAUSES, } from '../type/query.js';
+import { getKeys, isRecord, someKey } from './object.util.js';
 /** What a query populating nothing requests, shared: most reads populate nothing, and ask on every one. */
 const NOTHING_REQUESTED = Object.freeze({
     requestedKeys: Object.freeze([]),
@@ -40,86 +40,19 @@ export function parentJoins(relOpts, parentKeyCount) {
 export function targetKeyColumns(relOpts, parentKeyCount) {
     return relOpts.references.slice(parentKeyCount).map(({ local }) => local);
 }
-/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
-export function joinedColumns(joins) {
-    return Object.fromEntries(keyColumns(joins, 'joined').map((column) => [column, true]));
-}
-/**
- * One side's columns: `'parent'` for the columns a parent is keyed by, `'joined'` for the ones a
- * child or tally row carries that key in. Matching the two halves means agreeing on every column, so
- * each side is read through `joins` rather than through the parent's own key list - the same set only
- * for a to-many, and silently a different one otherwise. `keyof ParentJoin` is what keeps the two
- * sides from being spelled apart.
- *
- * Lifted out of `joins` once per relation, not once per row: {@link rowKey} takes the list and reads
- * each row itself, so a page of children costs one key each and nothing else.
- */
-export function keyColumns(joins, side) {
-    return joins.map((join) => join[side]);
-}
-/**
- * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
- * children in one statement.
- *
- * A composite over-selects, because the lists are independent and a pairing no parent has can still
- * match. Regrouping the rows keys on every column, so those rows find no parent and are dropped -
- * cheaper than the row-value comparison no engine spells the same way.
- */
-export function parentsIn(joins, parents) {
-    return Object.fromEntries(joins.map(({ parent, joined }) => [joined, parents.map((it) => read(it, parent))]));
-}
-/**
- * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
- * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
- * correct and cheaper.
- */
-export function isBoundedPerParent(query) {
-    return query.$limit !== undefined || query.$skip !== undefined;
-}
-/**
- * The `$where` naming exactly one parent's children: every joined column equal to that parent's value.
- * What a per-parent bounded read filters each of its branches by, and the composite half of
- * {@link childrenOf}.
- */
-function childOf(joins, parent) {
-    return Object.fromEntries(joins.map(({ parent: key, joined }) => [joined, read(parent, key)]));
-}
-/**
- * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
- * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
- * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
- */
-export function queryChildrenOf(query, joins, parent) {
-    return queryNarrowedTo(query, childOf(joins, parent));
-}
-/**
- * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
- * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
- */
-export function queryChildrenOfAll(query, joins, parents) {
-    return queryNarrowedTo(query, parentsIn(joins, parents));
-}
-/**
- * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
- * the parents it is being read for, whether the filter names their keys as values or, for a correlated
- * shape, as a reference to a row source.
- */
-export function queryNarrowedTo(query, filter) {
-    return { ...query, $where: { ...query.$where, ...filter } };
-}
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
- * column a single key contributes, an OR of key maps for several.
- *
- * Exact, unlike {@link parentsIn}: a read absorbs over-selection by regrouping its rows, and a write
- * has nothing to regroup - a pairing no parent has would delete a child of a parent that survives.
+ * column a single key contributes, an OR of whole key maps for several - lists of each column apart
+ * would pair values no parent has, and a delete would take a child of a parent that survives.
  */
 export function childrenOf(joins, parentIds) {
     const [first] = joins;
     if (joins.length === 1) {
         return { [first.joined]: parentIds };
     }
-    return { $or: parentIds.map((id) => childOf(joins, id)) };
+    return {
+        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
+    };
 }
 function read(row, key) {
     return row[key];
@@ -178,8 +111,24 @@ export function populatesRelations(meta, populate) {
         return false;
     return someKey(populate, (key) => !!populate[key] && key in meta.relations);
 }
-/** Their runtime half, so the check below cannot drift from the type above. */
-const STATEMENT_ONLY_CLAUSES = ['$lock', ...QUERY_ROOT_NUMBER_CLAUSES];
+/**
+ * Each relation a `$count` tallies, and the filter narrowing what it counts: the target's, whose type
+ * only the metadata knows this far down, as for a relation filter reaching the same subquery.
+ */
+export function countedRelations(meta, counts) {
+    if (!counts) {
+        return [];
+    }
+    return getKeys(counts).flatMap((relKey) => {
+        const count = counts[relKey];
+        const relation = meta.relations[relKey];
+        if (!count || !relation) {
+            return [];
+        }
+        const where = typeof count === 'object' ? count.$where : undefined;
+        return [{ relKey, relation, where: where ?? {} }];
+    });
+}
 // Taken from the clause groups declared beside `Query` itself, so a renamed clause fails to compile
 // here instead of quietly narrowing what a relation query accepts. `$required` is the one key that
 // is not a `Query` clause at all - it says how the relation joins, not what it selects.
@@ -198,7 +147,7 @@ export function parseRelationQueryValue(value) {
     // Caught before the shape check so the message names the key, rather than reporting the whole
     // object as an unrecognized relation query value.
     if (isRecord(value)) {
-        const statementOnly = STATEMENT_ONLY_CLAUSES.find((clause) => clause in value);
+        const statementOnly = QUERY_STATEMENT_CLAUSES.find((clause) => clause in value);
         if (statementOnly) {
             throw new TypeError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
         }
@@ -227,9 +176,6 @@ export function forEachRequestedRelation(meta, populate, fn) {
         fn(relKey, populate?.[relKey]);
     }
 }
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
 function isBooleanLikeValue(value) {
     return value === true || value === false || value === 0 || value === 1;
 }
@@ -243,7 +189,7 @@ function isValidRelationQueryShape(query) {
         if (RELATION_QUERY_BOOLEAN_KEYS.has(key) && !isBooleanLikeValue(value)) {
             return false;
         }
-        if (RELATION_QUERY_OBJECT_KEYS.has(key) && !isRecord(value)) {
+        if (RELATION_QUERY_OBJECT_KEYS.has(key) && !isRecord(value) && !(key === '$select' && Array.isArray(value))) {
             return false;
         }
         if (RELATION_QUERY_NUMBER_KEYS.has(key) && (typeof value !== 'number' || !Number.isFinite(value))) {

package/dist/util/rowKey.util.d.ts

@@ -1,5 +1,5 @@
 /**
- * A row's key as a string, for matching rows to each other in a {@link dataKeyed} lookup.
+ * A row's key as a string, for matching rows to each other.
  *
  * Reads the columns off the row rather than taking their values, because every caller matches a
  * whole page of rows against one fixed column list: taking an array would make each of them build
@@ -11,13 +11,3 @@
  * key are not treated as one row.
  */
 export declare function rowKey(row: unknown, columns: readonly string[]): string;
-/**
- * A lookup keyed by data rather than by a name this code chose, so a key that spells `__proto__` or
- * `constructor` is an ordinary entry instead of the prototype: on `{}` those threw when a bucket was
- * pushed to, and a `_count` tally under one silently read back as an object. Cheaper than a `Map`
- * here, and faster than `{}`, which walks the prototype chain on every miss.
- *
- * It carries none of `Object.prototype`, which no type can say: index it and spread it, but calling
- * `hasOwnProperty` on one type-checks and throws.
- */
-export declare function dataKeyed<V>(): Record<string, V>;

package/dist/util/rowKey.util.js

@@ -1,7 +1,7 @@
 /** Separates the parts of a composite key: a unit separator, which no column value carries. */
 const KEY_SEPARATOR = '\u001f';
 /**
- * A row's key as a string, for matching rows to each other in a {@link dataKeyed} lookup.
+ * A row's key as a string, for matching rows to each other.
  *
  * Reads the columns off the row rather than taking their values, because every caller matches a
  * whole page of rows against one fixed column list: taking an array would make each of them build
@@ -23,18 +23,6 @@ export function rowKey(row, columns) {
     }
     return key;
 }
-/**
- * A lookup keyed by data rather than by a name this code chose, so a key that spells `__proto__` or
- * `constructor` is an ordinary entry instead of the prototype: on `{}` those threw when a bucket was
- * pushed to, and a `_count` tally under one silently read back as an object. Cheaper than a `Map`
- * here, and faster than `{}`, which walks the prototype chain on every miss.
- *
- * It carries none of `Object.prototype`, which no type can say: index it and spread it, but calling
- * `hasOwnProperty` on one type-checks and throws.
- */
-export function dataKeyed() {
-    return Object.create(null);
-}
 function keyPart(value) {
     if (value instanceof Date) {
         return value.toISOString();