uql-orm 0.55.0 → 0.57.0

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

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, 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 QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, 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 QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
@@ -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;
 };
 /**
@@ -171,3 +171,9 @@ export declare function assertNonNegativeInteger(value: number, clause: string):
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export declare function assertAggregateColumns(clauseMap: object, emitted: ReadonlySet<string>, clause: string): void;
+/**
+ * The fields a `$text` searches: those it names, or else the columns of the entity's fulltext index,
+ * the declaration MySQL's `MATCH` has to name exactly and a MongoDB text index already is. Refused
+ * where neither says, rather than guessed: every engine answers a guess with an error of its own.
+ */
+export declare function textSearchFields<E>(meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): readonly string[];

package/dist/util/dialect.util.js

@@ -424,3 +424,22 @@ export function assertAggregateColumns(clauseMap, emitted, clause) {
         }
     }
 }
+/**
+ * The fields a `$text` searches: those it names, or else the columns of the entity's fulltext index,
+ * the declaration MySQL's `MATCH` has to name exactly and a MongoDB text index already is. Refused
+ * where neither says, rather than guessed: every engine answers a guess with an error of its own.
+ */
+export function textSearchFields(meta, search) {
+    if (search.$fields?.length) {
+        return search.$fields;
+    }
+    const fulltext = (meta.indexes ?? []).filter((index) => index.type === 'fulltext');
+    if (fulltext.length === 1) {
+        return fulltext[0].columns.map((entry) => entry.column);
+    }
+    const name = entityName(meta);
+    const declared = fulltext.length
+        ? `${fulltext.length} fulltext indexes to choose from`
+        : 'no fulltext index to search';
+    throw new TypeError(`$text on '${name}' names no $fields, and '${name}' declares ${declared}. Name them with $fields.`);
+}

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/logger.d.ts

@@ -34,7 +34,7 @@ export declare class LoggerWrapper implements Logger {
     private readonly loggerFunction?;
     private readonly logValues;
     private readonly slowQuery?;
-    constructor(options: LoggingOptions, config?: LoggerWrapperConfig);
+    constructor(options?: LoggingOptions, config?: LoggerWrapperConfig);
     /** Whether `logQuery` would ever actually surface bound values, given the configured levels/slowQuery/logValues. */
     willLogValues(): boolean;
     logQuery(query: string, values?: unknown[], duration?: number): void;
@@ -46,6 +46,15 @@ export declare class LoggerWrapper implements Logger {
     logSkippedMigration(message: string): void;
     private log;
 }
+/**
+ * The wrapper a querier logs through, one per options object and read once: a pool builds a querier
+ * for every statement, and all of them log by the same options.
+ */
+export declare function queryLoggerFor(extra?: {
+    readonly logger?: LoggingOptions;
+    readonly logValues?: boolean;
+    readonly slowQuery?: number;
+}): LoggerWrapper;
 /**
  * Structural type for any EventEmitter-like connection pool that emits an
  * `'error'` event on a dropped connection (node-postgres, `mariadb`, etc.).

package/dist/util/logger.js

@@ -136,6 +136,24 @@ export class LoggerWrapper {
         }
     }
 }
+const wrappersByOptions = new WeakMap();
+let unconfigured;
+/**
+ * The wrapper a querier logs through, one per options object and read once: a pool builds a querier
+ * for every statement, and all of them log by the same options.
+ */
+export function queryLoggerFor(extra) {
+    if (!extra) {
+        unconfigured ??= new LoggerWrapper();
+        return unconfigured;
+    }
+    let wrapper = wrappersByOptions.get(extra);
+    if (!wrapper) {
+        wrapper = new LoggerWrapper(extra.logger, { logValues: extra.logValues, slowQuery: extra.slowQuery });
+        wrappersByOptions.set(extra, wrapper);
+    }
+    return wrapper;
+}
 /**
  * Attaches an error listener to a connection pool so a dropped connection is logged instead of left
  * unhandled - which crashes the process for drivers that don't guard against it themselves

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

@@ -19,7 +19,11 @@ 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][];
 /**
  * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
  * the fallback is what an entity that named no table is called - which is why the sites spelling this

package/dist/util/object.util.js

@@ -49,9 +49,17 @@ 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) : [];
 }
+/** The entries of `record` holding a value: a key declared but left `undefined` is no entry at all. */
+export function definedEntries(record) {
+    return Object.entries(record).filter((entry) => entry[1] !== undefined);
+}
 /**
  * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
  * the fallback is what an entity that named no table is called - which is why the sites spelling this

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

@@ -1,8 +1,8 @@
-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: RelationKey<E>[];
-    readonly joinableKeys: RelationKey<E>[];
-    readonly toManyKeys: RelationKey<E>[];
+    readonly requestedKeys: readonly RelationKey<E>[];
+    readonly joinableKeys: readonly RelationKey<E>[];
+    readonly toManyKeys: readonly RelationKey<E>[];
 };
 /**
  * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
@@ -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,11 @@
-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([]),
+    joinableKeys: Object.freeze([]),
+    toManyKeys: Object.freeze([]),
+});
 /**
  * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
  * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
@@ -34,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];
@@ -142,11 +81,11 @@ function assertJoinableRelationQuery(relKey, value) {
     }
 }
 export function getRelationRequestSummary(meta, populate) {
+    if (!populate)
+        return NOTHING_REQUESTED;
     const requestedKeys = [];
     const joinableKeys = [];
     const toManyKeys = [];
-    if (!populate)
-        return { requestedKeys, joinableKeys, toManyKeys };
     for (const key of getKeys(populate)) {
         if (!populate[key])
             continue;
@@ -172,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.
@@ -192,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.`);
         }
@@ -221,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;
 }
@@ -237,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();

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/dist/querier/relationCount.d.ts

@@ -1,16 +0,0 @@
-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 {};