uql-orm 0.56.0 → 0.58.0

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();

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.56.0",
+  "version": "0.58.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 {};

package/dist/querier/relationCount.js

@@ -1,121 +0,0 @@
-import { COUNT_ALIAS } from '../dialect/aliases.js';
-import { getMeta, soleIdOf } from '../entity/index.js';
-import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, dataKeyed, getKeys, joinedColumns, keyColumns, parentJoins, parentsIn, rowKey, targetKeyColumns, } from '../util/index.js';
-/**
- * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
- * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
- * `$exclude` loses it; the raw-array `$select` form has nothing to augment, so it is refused.
- */
-export function withIdForCounts(entity, q) {
-    const meta = getMeta(entity);
-    if (!q.$count) {
-        return q;
-    }
-    const { ids } = meta;
-    const named = ids.join(', ');
-    if (q.$distinct) {
-        // The keys would have to join the projection for the tallies to group by, and that is the set
-        // `$distinct` collapses on: adding them silently stops the grouping collapsing anything at all.
-        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${named}', which the grouping does not keep.`);
-    }
-    if (Array.isArray(q.$select)) {
-        // Nothing to add the keys to, and without them every tally would be looked up by `undefined` and
-        // come back zero. Refused rather than answered wrong, the way an unorderable clause is.
-        throw new TypeError(`$count needs the '${named}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
-    }
-    const next = { ...q };
-    const select = asSelectMap(q.$select);
-    const missing = select ? ids.filter((key) => !select[key]) : [];
-    if (missing.length) {
-        next.$select = { ...select, ...Object.fromEntries(missing.map((key) => [key, true])) };
-    }
-    const excluded = ids.filter((key) => q.$exclude?.[key]);
-    if (excluded.length) {
-        const kept = { ...q.$exclude };
-        for (const key of excluded) {
-            delete kept[key];
-        }
-        next.$exclude = kept;
-    }
-    return next;
-}
-/**
- * How many rows each counted relation holds, under `_count` on every parent. One grouped aggregate
- * per relation over every parent at once - the batching a populated to-many already gets - so the
- * cost stays flat in the number of rows the read returned rather than one statement per row.
- */
-export async function fillRelationCounts(querier, entity, payload, count) {
-    if (!payload.length || !count) {
-        return;
-    }
-    const meta = getMeta(entity);
-    // The tallies come back keyed by the columns *this relation* joins from, so those columns are kept
-    // beside them: reading the parent through `meta.ids` instead matches only where the two coincide,
-    // which is a to-many and nothing else.
-    const counted = new Map();
-    for (const relKey of getKeys(count)) {
-        const value = count[relKey];
-        const relOpts = meta.relations[relKey];
-        if (!value || !relOpts) {
-            continue;
-        }
-        const where = typeof value === 'object' ? value.$where : undefined;
-        const joins = parentJoins(relOpts, meta.ids.length);
-        counted.set(relKey, {
-            parentKeys: keyColumns(joins, 'parent'),
-            byParent: await countPerParent(querier, relOpts, joins, payload, where),
-        });
-    }
-    for (const parent of payload) {
-        // A plain object, unlike the tallies below: this one is keyed by relation names the entity
-        // declares, not by data, and it is handed to the caller - who would meet a null prototype.
-        const row = {};
-        for (const [relKey, { parentKeys, byParent }] of counted) {
-            // A parent the grouped result has no row for matched nothing, which is a zero rather than a
-            // gap: `_count` names what the caller asked to count, so every key it asked for is present.
-            row[relKey] = byParent[rowKey(parent, parentKeys)] ?? 0;
-        }
-        parent[COUNT_RESULT_KEY] = row;
-    }
-}
-async function countPerParent(querier, relOpts, joins, parents, where) {
-    const through = relOpts.through;
-    if (through) {
-        return countThroughPerParent(querier, relOpts, through(), joins, parents, where);
-    }
-    return groupedCount(querier, relOpts.entity(), joins, {
-        ...where,
-        ...parentsIn(joins, parents),
-    });
-}
-/**
- * A many-to-many counts its junction rows, one per pairing. A filter names the target's columns,
- * which the junction does not have, so the matching targets are resolved first and the junction
- * counted against them - the one shape here that costs a second statement, and only when filtered.
- */
-async function countThroughPerParent(querier, relOpts, throughEntity, joins, parents, where) {
-    const throughWhere = parentsIn(joins, parents);
-    if (where) {
-        const target = relOpts.entity();
-        const targetId = soleIdOf(getMeta(target), 'a many-to-many target');
-        const targets = await querier.findMany(target, { $select: { [targetId]: true }, $where: where });
-        const [targetColumn] = targetKeyColumns(relOpts, joins.length);
-        throughWhere[targetColumn] = targets.map((it) => it[targetId]);
-    }
-    return groupedCount(querier, throughEntity, joins, throughWhere);
-}
-/** `SELECT <keys>, COUNT(*) ... GROUP BY <keys>`, as a lookup from parent key to tally. */
-async function groupedCount(querier, entity, joins, where) {
-    const $agg = { [COUNT_ALIAS]: { $count: '*' } };
-    const $group = joinedColumns(joins);
-    const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
-    const byParent = dataKeyed();
-    // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
-    // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
-    const joinedKeys = keyColumns(joins, 'joined');
-    for (const row of rows) {
-        byParent[rowKey(row, joinedKeys)] = Number(row[COUNT_ALIAS]);
-    }
-    return byParent;
-}