uql-orm 0.41.0 → 0.42.0

package/dist/schema/types.d.ts

@@ -40,6 +40,26 @@ export interface CanonicalType {
  * Actions for foreign key ON DELETE and ON UPDATE clauses.
  */
 export type ForeignKeyAction = 'CASCADE' | 'SET NULL' | 'SET DEFAULT' | 'RESTRICT' | 'NO ACTION';
+/**
+ * The values a column accepts, rendered as `CHECK (col IN (...))`.
+ *
+ * Strings and numbers only: those are what `IN (...)` can state, and each is escaped by the
+ * dialect's own literal rules, so a number stays bare where a string is quoted.
+ */
+export type EnumValues = readonly (string | number)[];
+/**
+ * A `CHECK` constraint as the schema holds it, its expression already text. Declared here rather
+ * than beside the entity types because a table node also comes from introspection, where there is
+ * no entity to have authored one.
+ *
+ * Only ever compared by presence, never by content: a check is SQL text, and a database reprints
+ * text from its parse tree, so `CHECK ("balance" >= 0)` reads back as `CHECK ((balance >= (0)::numeric))`.
+ */
+export interface CheckSchema {
+    /** Absent when nothing named it, which the generator fills in with `derivedCheckName`. */
+    readonly name?: string;
+    readonly expression: string;
+}
 /**
  * Default action for foreign key ON DELETE and ON UPDATE clauses.
  */
@@ -84,6 +104,8 @@ export interface ColumnNode {
     readonly isAutoIncrement: boolean;
     /** Whether this column has a unique constraint */
     readonly isUnique: boolean;
+    /** The values the column accepts. See {@link EnumValues}. */
+    readonly enum?: EnumValues;
     /** Column comment/description */
     readonly comment?: string;
     /** Reference to the parent table */
@@ -115,6 +137,8 @@ export interface TableNode {
     readonly primaryKey: ColumnNode[];
     /** Indexes on this table */
     readonly indexes: IndexNode[];
+    /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
+    readonly checks?: CheckSchema[];
     /** Optional table comment */
     readonly comment?: string;
     /** Relationships pointing TO this table (other tables referencing this one) */

package/dist/type/entity.d.ts

@@ -1,4 +1,4 @@
-import type { ForeignKeyAction, IndexType } from '../schema/types.js';
+import type { CheckSchema, EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { Except, IsMany, Json, Scalar, Type, Unpacked } from './utility.js';
@@ -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 })`
@@ -292,6 +328,20 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * @example `@Field({ references: () => Company, onDelete: 'CASCADE' }) companyId?: string;`
      */
     readonly onDelete?: ForeignKeyAction;
+    /**
+     * The values the column accepts, enforced by the database as well as by TypeScript.
+     *
+     * Emitted as a column `CHECK (col IN (...))` on every SQL dialect rather than a native enum type:
+     * one code path, no separate schema object to order, and adding a value stays an ordinary column
+     * change instead of Postgres's irreversible `ALTER TYPE ... ADD VALUE`.
+     *
+     * Not constrained against the field's own type here: the decorator narrows the property to these
+     * values instead, which reports a mismatch where the mistake is rather than as an unrelated
+     * `never`. `as const` is what makes them literal, and so what makes any of it check.
+     *
+     * @example `@Field({ type: String, enum: ['draft', 'paid'] as const })`
+     */
+    readonly enum?: EnumValues;
     readonly virtual?: QueryRaw;
     readonly updatable?: boolean;
     readonly eager?: boolean;
@@ -683,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;
@@ -699,6 +756,8 @@ export type EntityMeta<E> = {
     };
     /** Composite indexes defined via @Index decorator */
     indexes?: EntityIndexMeta[];
+    /** `CHECK` constraints, their expressions already reduced to text. */
+    checks?: CheckSchema[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
     processed?: boolean;
@@ -709,6 +768,15 @@ export type EntityMeta<E> = {
  * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
  * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
  */
+/**
+ * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
+ * this is DDL, so there is no placeholder a bound value could go into.
+ */
+export type CheckOptions = {
+    /** Derived from the table and the constraint's position when absent. */
+    readonly name?: string;
+    readonly expression: QueryRaw;
+};
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**
@@ -726,6 +794,8 @@ export type EntityOptions<E = unknown> = {
         readonly [K in RelationKey<E>]?: RelationOptionsFor<E[K]>;
     };
     readonly indexes?: readonly EntityIndexInput<FieldKey<E>, E>[];
+    /** Table-level `CHECK` constraints. See {@link CheckOptions}. */
+    readonly checks?: readonly CheckOptions[];
     /** Map hook events to method names on the entity class. */
     readonly hooks?: Partial<Record<HookEvent, readonly MethodKey<E>[]>>;
 };

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

@@ -0,0 +1,15 @@
+import { type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
+/**
+ * SQL bound for DDL, as the text a generator renders. `raw` with no interpolation, or a bare string
+ * where one is still accepted: DDL is evaluated once at creation time, so there is no query context
+ * for the callback form and no placeholder a `CREATE` statement could bind a value into.
+ *
+ * `what` names the thing being declared, so the error says which one the caller got wrong.
+ */
+export declare function ddlText(value: string | QueryRaw, what: string): string;
+export declare function ddlText(value: string | QueryRaw | undefined, what: string): string | undefined;
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, an expression, or an options object - reach the dialects as one.
+ */
+export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;

package/dist/util/ddlExpression.util.js

@@ -0,0 +1,27 @@
+import { QueryRaw, RAW_VALUE } from '../type/index.js';
+export function ddlText(value, what) {
+    if (!(value instanceof QueryRaw)) {
+        return value;
+    }
+    const sql = value[RAW_VALUE];
+    if (typeof sql !== 'string') {
+        throw new TypeError(`${what} needs raw() with no interpolation, not a function or a bound value`);
+    }
+    return sql;
+}
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, an expression, or an options object - reach the dialects as one.
+ */
+export function normalizeIndexColumn(entry) {
+    if (typeof entry === 'string') {
+        return { column: entry };
+    }
+    if (entry instanceof QueryRaw) {
+        return { column: ddlText(entry, 'an index expression'), expression: true };
+    }
+    const { column, ...rest } = entry;
+    return column instanceof QueryRaw
+        ? { ...rest, column: ddlText(column, 'an index expression'), expression: true }
+        : { ...rest, column };
+}

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

@@ -2,10 +2,11 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
-export * from './indexColumn.util.js';
+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

@@ -2,10 +2,11 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
-export * from './indexColumn.util.js';
+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,13 @@ 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) {
+    return (typeof value !== 'object' ||
+        value === null ||
+        (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype));
+}

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

@@ -9,15 +9,46 @@ 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: 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

@@ -8,17 +8,58 @@ 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: 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) => it[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;
+/**
+ * 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, id[parent]]))),
+    };
 }
 /**
  * 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);
+}

package/dist/util/sql.util.d.ts

@@ -24,6 +24,8 @@ export declare function qualifyName(name: string, schema?: string): string;
  * `table` is the table's own name, never qualified - the result is a single identifier.
  */
 export declare function derivedIndexName(table: string, columns: readonly string[]): string;
+/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+export declare function derivedCheckName(table: string, position: number): string;
 /** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
 export declare function derivedForeignKeyName(table: string, columns: readonly string[]): string;
 /**

package/dist/util/sql.util.js

@@ -67,6 +67,10 @@ export function qualifyName(name, schema) {
 export function derivedIndexName(table, columns) {
     return `idx_${table}_${columns.join('_')}`;
 }
+/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+export function derivedCheckName(table, position) {
+    return `ck_${table}_${position}`;
+}
 /** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
 export function derivedForeignKeyName(table, columns) {
     return `fk_${table}_${columns.join('_')}`;