uql-orm 0.41.1 → 0.42.1

package/dist/sqlite/sqliteDialect.js

@@ -13,6 +13,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
+        primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
         columnComment: false, // SQLite does not support column comments
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
@@ -21,7 +22,9 @@ export class SqliteDialect extends AbstractSqlDialect {
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
-    serialPrimaryKey = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    serialType = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    // `AUTOINCREMENT` is only legal in that exact phrase, so the key cannot be lifted to table level.
+    serialDeclaresPrimaryKey = true;
     tableOptions = '';
     beginTransactionCommand = 'BEGIN TRANSACTION';
     commitTransactionCommand = 'COMMIT';

package/dist/type/dialect.d.ts

@@ -91,6 +91,12 @@ export interface EngineFeatures {
     readonly dropTableCascade: boolean;
     readonly renameColumn: boolean;
     readonly foreignKeyAlter: boolean;
+    /**
+     * Whether a table's primary key can be changed on an existing table. False on SQLite, whose only
+     * route is rebuilding the table - so a migration that would change one is refused by name rather
+     * than emitting DDL the engine rejects.
+     */
+    readonly primaryKeyAlter: boolean;
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**

package/dist/type/entity.d.ts

@@ -182,7 +182,7 @@ export type FieldValue<E> = E[FieldKey<E>];
 /**
  * Infers the name of the key identifier on an entity
  */
-export type IdKey<E> = E extends {
+export type IdKey<E> = (E extends {
     [idKey]?: infer K;
 } ? K & FieldKey<E> : E extends {
     _id?: unknown;
@@ -190,15 +190,39 @@ export type IdKey<E> = E extends {
     id?: unknown;
 } ? 'id' & FieldKey<E> : E extends {
     uuid?: unknown;
-} ? 'uuid' & FieldKey<E> : FieldKey<E>;
+} ? 'uuid' & FieldKey<E> : FieldKey<E>) & string;
 /**
  * Infers the value of the key identifier on an entity.
  *
+ * A composite key is addressed by an object carrying every key, which is also the `$where` map it
+ * reduces to - so both spellings are one type. Completeness is checked at run time by
+ * `assertIdValue`: TypeScript cannot accumulate `@Id` across properties into the class type, so it
+ * cannot know how many keys there are.
+ *
  * Nullable, because an entity declares its id optional - nothing has assigned one before the
  * insert. That puts `undefined` inside every by-id method's parameter, where it would mean "no
  * filter"; `assertIdValue` is what rejects it.
  */
 export type IdValue<E> = E[IdKey<E>];
+/**
+ * How a row is addressed by its primary key: the value for a single key, an object carrying every
+ * key for a composite - which is also the `$where` map it reduces to, so both spellings are one type.
+ *
+ * Distinct from {@link IdValue}, the *column's* value, which stays a scalar: an id column holds a
+ * number, never an object. The two read alike on a single-key entity and are not the same thing -
+ * `findOneById` takes an `EntityId`, while the inserts return `IdValue | undefined`, which is why a
+ * composite insert reports no id rather than the map.
+ *
+ * The keys stay optional, and completeness is checked at run time by `assertIdValue`. Requiring them
+ * needs `IdKey` to be precise, which it is not: with no `id`/`_id`/`uuid` and no `idKey` brand it
+ * falls back to every field, so `IdKey<Membership>` accepts `'role'` and requiring the map would
+ * demand fields that are not keys. Making it conditional on the brand was tried and reverted - a
+ * conditional type does not reduce for an unresolved `E`, which left `QueryWhere<E>` opaque and broke
+ * assignability across the dialects.
+ */
+export type EntityId<E> = IdValue<E> | {
+    [K in IdKey<E>]?: E[K];
+};
 /**
  * Infers the values of the relations on an entity
  */
@@ -254,22 +278,34 @@ export type FieldType = StringConstructor | NumberConstructor | BooleanConstruct
  */
 export type TypeFor<V, T = NonNullable<V>> = IsJson<T> extends true ? JsonColumnType : IsJson<NonNullable<Unpacked<T>>> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
 /**
- * Configurable options for a field, carrying `V`, the value the column holds: what a generator returns
- * and what a default is has to be that value, checked the same way the declared `type` is. `Scalar` by
- *  by default, for the places that handle a field without knowing which one it is.
+ * A field as the registry holds it: what the user authored, plus what registration worked out.
+ *
+ * Separate from {@link FieldOptions} so neither of these can be written in a decorator. They used to
+ * live there behind an `@internal` tag and a "do not set this" note, which is a comment standing in
+ * for a type boundary.
  */
-export type FieldOptions<V = TsTypeOf<FieldType>> = {
-    readonly name?: string;
-    readonly isId?: true;
-    readonly type?: FieldType;
+export type FieldMeta<V = TsTypeOf<FieldType>> = FieldOptions<V> & {
     /**
      * Set by `defineField` when the field gave `references` but no `type`, so schema generation resolves
      * the column from the referenced primary key rather than from whatever ended up in `type`. That is
      * what keeps a `uuid` primary key from becoming TEXT on every foreign key pointing at it.
-     * Internal bookkeeping - do not set this from a decorator.
-     * @internal
      */
     readonly typeFromReference?: boolean;
+    /**
+     * Which key of the referenced entity this column points at, where that entity has more than one.
+     * Set by `fillOwningSide`; without it a composite target's columns would all take the first key's type.
+     */
+    readonly referencedKey?: string;
+};
+/**
+ * Configurable options for a field, carrying `V`, the value the column holds: what a generator returns
+ * and what a default is has to be that value, checked the same way the declared `type` is. `Scalar` by
+ * default, for the places that handle a field without knowing which one it is.
+ */
+export type FieldOptions<V = TsTypeOf<FieldType>> = {
+    readonly name?: string;
+    readonly isId?: true;
+    readonly type?: FieldType;
     /**
      * Dimensions for vector fields. Used in schema generation.
      * @example `@Field({ type: 'vector', dimensions: 1536 })`
@@ -697,14 +733,21 @@ export type EntityMeta<E> = {
     name?: string;
     /** Set only when the entity named one; unset defers to the pool where it is used. See `AbstractDialect.resolveSchema`. */
     schema?: string;
-    id: IdKey<E>;
+    /**
+     * Every key of the primary key, in declaration order. One unless the entity declares a composite.
+     *
+     * The only stored form: a single `id` beside it could only ever be right for a single-key entity,
+     * so every reader had to know whether it was safe. Asking whether *this* field is part of the key
+     * is `fields[key].isId`, which is O(1) and the source this list is derived from.
+     */
+    ids: readonly IdKey<E>[];
     softDelete?: FieldKey<E>;
     /** Named, default-on `$where` filters applied to every query unless bypassed. */
     filters?: Record<string, FilterOptions<E>>;
     fields: {
-        [K in FieldKey<E>]?: FieldOptions;
+        [K in FieldKey<E>]?: FieldMeta;
     } & {
-        [key: string]: FieldOptions | undefined;
+        [key: string]: FieldMeta | undefined;
     };
     relations: {
         [K in RelationKey<E>]?: RelationMeta;

package/dist/type/migration.d.ts

@@ -123,7 +123,14 @@ export interface ColumnSchema {
 export interface TableSchema {
     readonly name: string;
     readonly columns: ColumnSchema[];
+    /** The key's columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
     readonly primaryKey?: string[];
+    /**
+     * What the engine calls the key's constraint, where it names one at all - Postgres's `Member_pkey`,
+     * MySQL's literal `PRIMARY`, nothing on SQLite. Only a `DROP` needs it, and only the name the
+     * database actually reported will do: a derived one would name a constraint that is not there.
+     */
+    readonly primaryKeyName?: string;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
 }
@@ -176,6 +183,18 @@ export interface SchemaDiff {
      */
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
+    /**
+     * The key the table has against the key the entity declares, set only when they differ.
+     *
+     * Compared by columns, never by name: the engine named the existing one, so requiring a derived
+     * name to match would rewrite the primary key of every table on the first migration after
+     * upgrading. `fromName` is what the database reported, and the only name a `DROP` can use.
+     */
+    readonly primaryKey?: {
+        readonly from: string[];
+        readonly to: string[];
+        readonly fromName?: string;
+    };
     readonly columnsToAdd?: ColumnSchema[];
     readonly columnsToAlter?: {
         from: ColumnSchema;

package/dist/type/queryWhere.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, IdValue, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
+import type { EntityId, FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
@@ -316,5 +316,10 @@ export type QueryWhereArray<E> = (QueryWhereMap<E> | QueryRaw)[];
 /**
  * query filter.
  */
-export type QueryWhere<E> = IdValue<E> | IdValue<E>[] | QueryWhereMap<E> | QueryWhereArray<E> | QueryRaw;
+/**
+ * `EntityId` rather than `IdValue`: a by-id method reduces to `$where: id`, and a composite key is
+ * addressed by an object carrying every key. That object is a where map naming those columns, so the
+ * two spellings meet here rather than needing a conversion.
+ */
+export type QueryWhere<E> = EntityId<E> | EntityId<E>[] | QueryWhereMap<E> | QueryWhereArray<E> | QueryRaw;
 export {};

package/dist/type/universalQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, FieldKey, IdValue, RelationKey, UpdatePayload } from './entity.js';
+import type { EntityData, EntityId, FieldKey, IdValue, RelationKey, UpdatePayload } from './entity.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';
@@ -22,7 +22,7 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
      * @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, 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>;
+    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: EntityId<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
@@ -68,7 +68,7 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
      * @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>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
     /**
      * updates many records partially.
      * @param entity the entity to persist on
@@ -83,7 +83,7 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
      * @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>;
+    deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: DO): QuerierResult<W, number>;
     /**
      * delete or SoftDelete records.
      * @param entity the entity to persist on
@@ -130,7 +130,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the IDs
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
     /**
      * Insert or update a record based on the conflict paths.
      * @param entity the entity to persist on
@@ -153,19 +153,19 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.
      */
-    restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;
+    restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
     /**
      * runs an aggregate query (GROUP BY with aggregate functions).

package/dist/util/dialect.util.js

@@ -1,7 +1,8 @@
 import { getContext, UqlSecurityError } from '../context/context.js';
+import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
-import { entityName, getFieldKeys, getKeys, hasKeys, someKey } from './object.util.js';
+import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, someKey } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -112,7 +113,7 @@ export function isPagedQuery(q) {
  * compiler - so it is spelled once here rather than in each querier.
  */
 export function idOnlyQuery(meta, q) {
-    return { ...q, $select: { [meta.id]: true } };
+    return { ...q, $select: Object.fromEntries(meta.ids.map((key) => [key, true])) };
 }
 /**
  * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
@@ -235,10 +236,18 @@ export function buildQueryWhereAsMap(meta, filter = {}) {
     if (filter instanceof QueryRaw) {
         return { $and: [filter] };
     }
-    if (isIdValue(filter)) {
-        return {
-            [meta.id]: filter,
-        };
+    if (Array.isArray(filter)) {
+        // A list of bare ids is an `IN` over the one key column; a list of anything else is a list of
+        // `$where`s, which is an OR - and that is how a composite's id objects name a settled set of rows.
+        return filter.every(isScalarId)
+            ? { [soleIdOf(meta, 'addressing by a bare id value')]: filter }
+            : { $or: filter };
+    }
+    if (isScalarId(filter)) {
+        // A scalar can only name one column, so on a composite it would address every row agreeing on
+        // that one. A composite is addressed by a map, which falls through below as the `$where` it
+        // already is - an id object and a where map are the same shape by design.
+        return { [soleIdOf(meta, 'addressing by a bare id value')]: filter };
     }
     return filter;
 }
@@ -311,14 +320,6 @@ export function applyFilters(meta, whereMap, opts) {
     }
     return result;
 }
-function isIdValue(filter) {
-    const type = typeof filter;
-    return (type === 'string' ||
-        type === 'number' ||
-        type === 'bigint' ||
-        typeof filter.toHexString === 'function' ||
-        Array.isArray(filter));
-}
 /**
  * The `$size` of a relation condition (`{ comments: { $size: { $gte: 2 } } }`), or `undefined` when the
  * condition constrains the target's fields instead. Shared so every dialect agrees on which of the two

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

@@ -1,4 +1,4 @@
-import type { FieldOptions } from '../type/index.js';
+import type { EntityMeta, FieldOptions } from '../type/index.js';
 /**
  * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
  */
@@ -11,6 +11,16 @@ export declare function isBooleanType(type: unknown): boolean;
  * Checks if a field type is JSON
  */
 export declare function isJsonType(type: unknown): boolean;
+/**
+ * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
+ * and the only one that may state `PRIMARY KEY` in its own column definition.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
+ */
+export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
  * Checks if a field should be treated as auto-incrementing.
  */

package/dist/util/field.util.js

@@ -52,6 +52,18 @@ export function isJsonType(type) {
     }
     return false;
 }
+/**
+ * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
+ * and the only one that may state `PRIMARY KEY` in its own column definition.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
+ */
+export function isSoleIdField(meta, field) {
+    return field.isId === true && meta.ids.length === 1;
+}
 /**
  * Checks if a field should be treated as auto-incrementing.
  */

package/dist/util/index.d.ts

@@ -6,6 +6,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';
 export * from './string.util.js';

package/dist/util/index.js

@@ -6,6 +6,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';
 export * from './string.util.js';

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

@@ -29,3 +29,9 @@ export declare function entityName<E>(meta: EntityMeta<E>): string;
 export declare function getFieldKeys<E>(fields: {
     [K in FieldKey<E>]?: FieldOptions;
 }): FieldKey<E>[];
+/**
+ * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
+ * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which
+ * is what a `$where` map and a composite key's id object both are; an array is a list of either.
+ */
+export declare function isScalarId(value: unknown): boolean;

package/dist/util/object.util.js

@@ -63,3 +63,21 @@ export function entityName(meta) {
 export function getFieldKeys(fields) {
     return getKeys(fields).filter((field) => fields[field].eager ?? true);
 }
+/**
+ * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
+ * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which
+ * is what a `$where` map and a composite key's id object both are; an array is a list of either.
+ */
+export function isScalarId(value) {
+    if (typeof value !== 'object' || value === null) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    // `null` as well as `Object.prototype`: an object with no prototype is what a query-string parser
+    // hands back (`qs`, express's `req.params`), and reading one as a bare id would name one column
+    // with a map of several.
+    const proto = Object.getPrototypeOf(value);
+    return proto !== Object.prototype && proto !== null;
+}

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

@@ -9,15 +9,56 @@ 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;
+/** One column of a parent's key, paired with the column matching it on the table being joined. */
+export type ParentJoin = {
+    readonly parent: string;
+    readonly joined: string;
+};
+/**
+ * How a relation joins to its parent: `parent` is a column of the parent's own table, `joined` the
+ * column matching it on the table the relation reads - a junction's own column for a relation that
+ * goes through one, the child's foreign key otherwise.
+ *
+ * The two are spelled from opposite ends of `references` (`local` names a column of the table the
+ * relation is declared on, `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. One pair per key of the parent.
+ */
+export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | 'through'>, parentKeyCount: number): ParentJoin[];
+/**
+ * The junction columns holding the target's key, the other half of {@link parentJoins}.
+ *
+ * `parentKeyCount` is required: the target's columns start after the parent's, so guessing the
+ * boundary returned the parent's *second* column as the target's - a real column of the wrong side,
+ * 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>;
+/**
+ * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
+ * columns it carries that key in. The two halves of matching children to parents: they must agree on
+ * every column, so each is read through `joins` rather than through the parent's own key list - which
+ * is the same set only for a to-many, and silently a different one otherwise.
+ */
+export declare function parentRowKey(joins: readonly ParentJoin[], parent: unknown): string;
+export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown): 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 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.
+ * 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.
  */
-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;
+export declare function childrenOf(joins: readonly ParentJoin[], parentIds: readonly unknown[]): Record<string, unknown>;
 /**
  * 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

@@ -1,5 +1,6 @@
 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 { rowKey } from './rowKey.util.js';
 /**
  * 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.
@@ -8,17 +9,77 @@ 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.
+ * How a relation joins to its parent: `parent` is a column of the parent's own table, `joined` the
+ * column matching it on the table the relation reads - a junction's own column for a relation that
+ * goes through one, the child's foreign key otherwise.
+ *
+ * The two are spelled from opposite ends of `references` (`local` names a column of the table the
+ * relation is declared on, `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. One pair per key of the parent.
  */
-export function parentKeyColumn(relOpts) {
-    return relOpts.through ? relOpts.references[0].local : relOpts.references[0].foreign;
+export function parentJoins(relOpts, parentKeyCount) {
+    if (!relOpts.through) {
+        return relOpts.references.map(({ local, foreign }) => ({ parent: local, joined: foreign }));
+    }
+    // A junction's pairs are the parent's followed by the target's, and how many the parent has is
+    // something its caller already knows - so the boundary is passed rather than stored on a relation.
+    return relOpts.references.slice(0, parentKeyCount).map(({ local, foreign }) => ({ parent: foreign, joined: local }));
+}
+/**
+ * The junction columns holding the target's key, the other half of {@link parentJoins}.
+ *
+ * `parentKeyCount` is required: the target's columns start after the parent's, so guessing the
+ * boundary returned the parent's *second* column as the target's - a real column of the wrong side,
+ * which is the mistake this module exists to prevent.
+ */
+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(joins.map(({ joined }) => [joined, true]));
+}
+/**
+ * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
+ * columns it carries that key in. The two halves of matching children to parents: they must agree on
+ * every column, so each is read through `joins` rather than through the parent's own key list - which
+ * is the same set only for a to-many, and silently a different one otherwise.
+ */
+export function parentRowKey(joins, parent) {
+    return rowKey(joins.map(({ parent: key }) => read(parent, key)));
+}
+export function joinedRowKey(joins, row) {
+    return rowKey(joins.map(({ joined }) => read(row, joined)));
+}
+/**
+ * `{ 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))]));
+}
+/**
+ * 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.
+ */
+export function childrenOf(joins, parentIds) {
+    const [first] = joins;
+    if (joins.length === 1) {
+        return { [first.joined]: parentIds };
+    }
+    return {
+        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
+    };
 }
-/** 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;
+function read(row, key) {
+    return row[key];
 }
 /**
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is

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

@@ -0,0 +1,9 @@
+/**
+ * A row's key as a string, for matching rows to each other in a `Map`.
+ *
+ * Values are normalized before joining, not stringified: `String(date)` is locale- and
+ * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
+ * bytes with commas. Every part is included, so two rows agreeing on one column of a composite key
+ * are not treated as one row.
+ */
+export declare function rowKey(values: readonly unknown[]): string;

package/dist/util/rowKey.util.js

@@ -0,0 +1,24 @@
+/** 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 `Map`.
+ *
+ * Values are normalized before joining, not stringified: `String(date)` is locale- and
+ * timezone-dependent, so two equal dates could key apart, and a `Uint8Array` stringifies to its
+ * bytes with commas. Every part is included, so two rows agreeing on one column of a composite key
+ * are not treated as one row.
+ */
+export function rowKey(values) {
+    return values.map(keyPart).join(KEY_SEPARATOR);
+}
+function keyPart(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    // Hex by hand rather than through `Buffer`, which is undefined on the browser and edge runtimes
+    // this module reaches through `AbstractQuerier`.
+    if (value instanceof Uint8Array) {
+        return Array.from(value, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    }
+    return String(value);
+}