uql-orm 0.41.1 → 0.42.1

package/dist/mongo/mongoDialect.js

@@ -2,9 +2,9 @@ import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
-import { getMeta } from '../entity/index.js';
+import { assertSoleId, getMeta, soleIdOf } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -16,6 +16,7 @@ export const mongoDialectFeatures = {
     dropTableCascade: false,
     renameColumn: false,
     foreignKeyAlter: false,
+    primaryKeyAlter: false,
     columnComment: false,
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
@@ -44,7 +45,14 @@ export class MongoDialect extends AbstractDialect {
      * the document does not use.
      */
     columnOf(meta, key) {
-        if (key === MongoDialect.ID_KEY || key === meta.id) {
+        if (key === MongoDialect.ID_KEY) {
+            return MongoDialect.ID_KEY;
+        }
+        if (meta.fields[key]?.isId) {
+            // A document has one `_id`. A composite key is a different document shape - a sub-document,
+            // whose field order decides equality - rather than a translation, so it is refused here, which
+            // every read reaches, and in `getPersistables`, which every write reaches.
+            assertSoleId(meta, 'MongoDB');
             return MongoDialect.ID_KEY;
         }
         return super.columnOf(meta, key);
@@ -161,7 +169,7 @@ export class MongoDialect extends AbstractDialect {
      */
     relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
         return relOpts.cardinality === 'mm' && relOpts.through
-            ? this.junctionLookup(relOpts, relMeta, relEntity, targetScope, temp, tail, opts)
+            ? this.junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts)
             : {
                 $lookup: {
                     from: this.resolveTableName(relMeta),
@@ -175,22 +183,29 @@ export class MongoDialect extends AbstractDialect {
      * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
      * lookup - the junction's filters apply too, since a soft-deleted link is not a link.
      */
-    junctionLookup(relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
+    junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts) {
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
         const junctionScope = this.renderFilter(throughEntity, this.scopedWhereMap(throughMeta, {}), opts);
         const nested = REL_NESTED_KEY;
+        // Both ends are one column here - each `$lookup` matches one field against `_id` - so both sides
+        // must be sole-keyed. Sliced rather than indexed positionally: `references[1]` is the parent's
+        // *second* column on a composite, a real column of the wrong side.
+        assertSoleId(meta, 'MongoDB');
+        assertSoleId(relMeta, 'MongoDB');
+        const [parentJoin] = parentJoins(relOpts, meta.ids.length);
+        const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
         return {
             $lookup: {
                 from: this.resolveTableName(throughMeta),
                 localField: MongoDialect.ID_KEY,
-                foreignField: this.columnOf(throughMeta, relOpts.references[0].local),
+                foreignField: this.columnOf(throughMeta, parentJoin.joined),
                 pipeline: [
                     ...(hasKeys(junctionScope) ? [{ $match: junctionScope }] : []),
                     {
                         $lookup: {
                             from: this.resolveTableName(relMeta),
-                            localField: this.columnOf(throughMeta, relOpts.references[1].local),
+                            localField: this.columnOf(throughMeta, targetColumn),
                             foreignField: MongoDialect.ID_KEY,
                             pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), { $limit: 1 }],
                             as: nested,
@@ -250,7 +265,7 @@ export class MongoDialect extends AbstractDialect {
      */
     assertKnownPathRoot(meta, key) {
         const root = key.includes('.') ? key.slice(0, key.indexOf('.')) : key;
-        if (root === MongoDialect.ID_KEY || root === meta.id || meta.fields[root]) {
+        if (root === MongoDialect.ID_KEY || meta.fields[root]) {
             return;
         }
         throw new TypeError(`path ${key} does not exist in ${entityName(meta)}`);
@@ -372,7 +387,7 @@ export class MongoDialect extends AbstractDialect {
         // MongoDB returns `_id` unless it is explicitly excluded, so subtracting the primary key needs
         // `_id: 0` - the one inclusion/exclusion mix MongoDB allows - or `$exclude: { id: true }` would
         // have no effect at all.
-        if (this.subtractsKey(meta.id, selectMap, exclude)) {
+        if (this.subtractsKey(soleIdOf(meta, 'MongoDB'), selectMap, exclude)) {
             projection[MongoDialect.ID_KEY] = 0;
         }
         return projection;
@@ -652,9 +667,15 @@ export class MongoDialect extends AbstractDialect {
      * direction joins the parent's `_id` to the target's FK.
      */
     joinKeys(meta, relMeta, relOpts) {
-        return relOpts.cardinality === 'm1'
-            ? { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY }
-            : { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
+        if (relOpts.cardinality === 'm1') {
+            // The target's side, not this entity's: a lookup matches one `localField` against one
+            // `foreignField`, so a composite target would join on its first column alone and gather the
+            // rows of every key that agrees on it. The other branch is refused by `columnOf` below, whose
+            // key *is* an id column; this one names a plain foreign key, so it has to say so itself.
+            assertSoleId(relMeta, 'MongoDB');
+            return { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY };
+        }
+        return { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
     }
     /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
     renamedColumns(meta) {
@@ -679,8 +700,9 @@ export class MongoDialect extends AbstractDialect {
         const res = doc;
         const _id = MongoDialect.ID_KEY;
         if (res[_id]) {
-            res[meta.id] = res[_id];
-            if (meta.id !== _id) {
+            const idKey = soleIdOf(meta, 'MongoDB');
+            res[idKey] = res[_id];
+            if (idKey !== _id) {
                 delete res[_id];
             }
         }
@@ -797,6 +819,9 @@ export class MongoDialect extends AbstractDialect {
         return [{ $set: assignments }, ...(unset.size > 0 ? [{ $unset: [...unset] }] : [])];
     }
     getPersistables(meta, payload, callbackKey) {
+        // Not `columnOf`, which maps the primary key to `_id`: an update may not touch `_id` at all, and
+        // an insert leaves it to the driver. What that mapping refuses, a write has to refuse too.
+        assertSoleId(meta, 'MongoDB');
         const payloads = fillOnFields(meta, payload, callbackKey);
         // Keys are resolved per document so heterogeneous payloads keep every provided field.
         return payloads.map((it) => filterFieldKeys(meta, it, callbackKey).reduce((acc, key) => {

package/dist/mongo/mongodbQuerier.js

@@ -1,6 +1,6 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, idOf, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
 import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
@@ -202,7 +202,9 @@ export class MongodbQuerier extends AbstractQuerier {
         const meta = getMeta(entity);
         const pipeline = this.dialect.aggregationPipeline(entity, idOnlyQuery(meta, q), opts);
         const founds = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
-        return (this.dialect.normalizeIds(meta, founds) || []).map((found) => found[meta.id]);
+        // `normalizeIds` has already spread a compound `_id` back into its columns, so the settled rows
+        // are named the same way every other driver names them.
+        return (this.dialect.normalizeIds(meta, founds) || []).map((found) => idOf(meta, found));
     }
     async internalInsertMany(entity, payloads) {
         return this.timed('internalInsertMany', undefined, async () => {
@@ -214,8 +216,9 @@ export class MongodbQuerier extends AbstractQuerier {
             const persistables = this.dialect.getPersistables(meta, payloads, 'onInsert');
             const { insertedIds } = await this.execute((session) => this.collection(entity).insertMany(persistables, { session }));
             const ids = Object.values(insertedIds);
+            const idKey = soleIdOf(meta, 'insert');
             for (const [index, it] of payloads.entries()) {
-                it[meta.id] = ids[index];
+                it[idKey] = ids[index];
             }
             await this.insertRelations(entity, payloads);
             return ids;

package/dist/postgres/postgresDialect.js

@@ -15,7 +15,7 @@ export class PostgresDialect extends PgLikeSqlDialect {
     hasNarrowVectorTypes = true;
     upsert(ctx, entity, conflictPaths, payload) {
         // The xmax system column is 0 for a newly inserted row and non-zero for an updated one (MVCC).
-        super.upsert(ctx, entity, conflictPaths, payload, `, (xmax = 0) AS ${this.escapeId('_created')}`);
+        super.upsert(ctx, entity, conflictPaths, payload, `(xmax = 0) AS ${this.escapeId('_created')}`);
     }
     /**
      * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist

package/dist/querier/abstractQuerier.d.ts

@@ -1,5 +1,5 @@
-import type { EntityData, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
-import { LoggerWrapper } from '../util/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import { LoggerWrapper, type ParentJoin } from '../util/index.js';
 /**
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
@@ -30,7 +30,7 @@ export declare abstract class AbstractQuerier implements Querier {
     protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
         $entity: Type<E>;
     }), maybeQueryOrOpts?: Q | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, Q, QueryOptions | 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: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<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?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * Find a single record matching the query.
      * Supports both entity-as-argument and entity-as-field patterns.
@@ -104,16 +104,16 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
     abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    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>;
     abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
-    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
+    deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Delete records matching the query. Soft-deletes when the entity has a soft-delete field (unless
      * `opts.hardDelete`), otherwise removes the rows. Supports both entity-as-argument and entity-as-field patterns.
@@ -132,15 +132,19 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     private findDoomed;
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    saveOne<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>[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
-    protected putChildrenInParents<E>(parents: E[], children: RawRow[], parentIdKey: keyof E & string, referenceKey: string, relKey: keyof E & string): void;
+    protected putChildrenInParents<E>(parents: E[], children: RawRow[], joins: readonly ParentJoin[], relKey: keyof E & string): void;
     protected insertRelations<E extends object>(entity: Type<E>, payload: E[]): Promise<void>;
     protected updateRelations<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<void>;
-    protected deleteRelations<E extends object>(entity: Type<E>, ids: IdValue<E>[], opts?: QueryOptions): Promise<void>;
+    /**
+     * `EntityId` because a settled set names composite rows as objects, which is also what the parent's
+     * own delete takes - and what {@link childrenOf} reads each child's foreign key columns out of.
+     */
+    protected deleteRelations<E extends object>(entity: Type<E>, ids: EntityId<E>[], opts?: QueryOptions): Promise<void>;
     /**
      * Persists `relValue` against every id in `ids`, which an update hands the whole page of rows it
      * settled: the value is the same for all of them, so the statements are per relation rather than per

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
-import { getMeta } from '../entity/index.js';
-import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, LoggerWrapper, parentKeyColumn, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { assertSoleId, getMeta, idOf, soleIdOf } from '../entity/index.js';
+import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, joinedRowKey, LoggerWrapper, parentJoins, parentRowKey, parentsIn, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -15,6 +15,29 @@ function assertIdValue(entity, id) {
     if (id === undefined || id === null) {
         throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
     }
+    if (isScalarId(id)) {
+        // One value names one column, which `buildQueryWhereAsMap` refuses on a composite.
+        return;
+    }
+    // Every key, or the `$where` names only some of the columns and addresses each row that agrees on
+    // those - which for an update or a delete is silently far more than the one row asked for. `{}`
+    // reaches here too, and would otherwise be an unfiltered statement over the whole table.
+    const given = id;
+    const { ids } = getMeta(entity);
+    const missing = ids.filter((key) => given[key] == null);
+    if (missing.length) {
+        throw new TypeError(`'${entity.name}' is addressed by an object carrying every key of its primary key (${ids.join(', ')}); missing ${missing.join(', ')}.`);
+    }
+}
+/**
+ * The one column a write path matches a parent's key against.
+ *
+ * Every caller reaches its parents through a sole id - `soleIdOf` refused a composite before any of
+ * them - so the parent contributes exactly one column here, whether the relation goes through a
+ * junction or straight to the child.
+ */
+function soleParentColumn(relOpts) {
+    return parentJoins(relOpts, 1)[0].joined;
 }
 /**
  * Base class for all database queriers.
@@ -187,7 +210,11 @@ export class AbstractQuerier {
         // Where a snapshot was taken, the statement names those rows rather than resolving `q` a second
         // time. Two reads of one `$limit` with no total order are free to disagree, which would fire the
         // hooks for one row and delete another; naming them also spares the second read.
-        const target = doomed ? { $where: doomed.map((it) => it[getMeta(entity).id]) } : q;
+        let target = q;
+        if (doomed) {
+            const meta = getMeta(entity);
+            target = { $where: doomed.map((it) => idOf(meta, it)) };
+        }
         await this.emitHook(entity, 'beforeDelete', doomed ?? []);
         const changes = await this.internalDeleteMany(entity, target, opts);
         await this.emitHook(entity, 'afterDelete', doomed ?? []);
@@ -218,12 +245,16 @@ export class AbstractQuerier {
         const toInsert = [];
         const toUpdate = [];
         const existingIds = [];
+        // Save reads an id as proof the row exists, and inserts the rest. A composite key is supplied by
+        // the caller on every row, insert included, so that proof does not exist for one: telling the two
+        // apart takes a read, which is `upsertMany`'s job and not this one's.
+        const idKey = soleIdOf(meta, 'saving a row');
         for (const it of payload) {
-            const id = it[meta.id];
+            const id = it[idKey];
             if (!id) {
                 toInsert.push(it);
             }
-            else if (!someKey(it, (key) => key !== meta.id)) {
+            else if (!someKey(it, (key) => key !== idKey)) {
                 existingIds.push(id);
             }
             else {
@@ -233,9 +264,9 @@ export class AbstractQuerier {
         const [insertedIds, updatedIds] = await Promise.all([
             toInsert.length ? this.insertMany(entity, toInsert) : [],
             Promise.all(toUpdate.map(async (it) => {
-                const id = it[meta.id];
+                const id = it[idKey];
                 const data = { ...it };
-                delete data[meta.id];
+                delete data[idKey];
                 await this.updateOneById(entity, id, data);
                 return id;
             })),
@@ -263,11 +294,11 @@ export class AbstractQuerier {
         }
     }
     async fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery) {
-        const localField = parentKeyColumn(relOpts);
+        const joins = parentJoins(relOpts, meta.ids.length);
+        const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
-        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetKeyColumn(relOpts)));
-        const ids = payload.map((it) => it[meta.id]);
+        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetColumn));
         // A relation query names the target's columns, not the join table's, so the projection and the
         // filter belong on the populate below - resolved there against the entity that has them. Spread
         // onto the through query they asked `ItemTag` for `Tag`'s columns: `$where`/`$sort` failed with
@@ -275,53 +306,52 @@ export class AbstractQuerier {
         const { $select: _select, $exclude: _exclude, $where: _where, ...throughQuery } = relationQuery;
         const throughFounds = await this.findMany(throughEntity, {
             ...throughQuery,
-            $select: {
-                [localField]: true,
-            },
+            $select: joinedColumns(joins),
             $populate: {
                 [targetRelKey]: {
                     ...relationQuery,
                     $required: true,
                 },
             },
-            $where: {
-                [localField]: ids,
-            },
+            $where: parentsIn(joins, payload),
         });
+        // The junction's own columns carried onto the target's row, which is where `putChildrenInParents`
+        // reads them back from - a junction row holds the parent's key under `joined`, not under `parent`.
         const founds = throughFounds.map((it) => ({
             ...it[targetRelKey],
-            [localField]: it[localField],
+            ...Object.fromEntries(joins.map(({ joined }) => [joined, it[joined]])),
         }));
-        this.putChildrenInParents(payload, founds, meta.id, localField, relKey);
+        this.putChildrenInParents(payload, founds, joins, relKey);
     }
     async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
-        const foreignField = parentKeyColumn(relOpts);
+        const joins = parentJoins(relOpts, meta.ids.length);
         // The FK is what putChildrenInParents groups on, so it outlives the relation's projection
         // either way: added to a whitelisting `$select` (the raw-array form has nothing to augment),
         // dropped from a subtractive `$exclude`. `relationQuery` is already a clone.
         const select = asSelectMap(relationQuery.$select);
-        if (select && !select[foreignField]) {
-            select[foreignField] = true;
+        const exclude = relationQuery.$exclude;
+        for (const { joined } of joins) {
+            if (select && !select[joined]) {
+                select[joined] = true;
+            }
+            delete exclude?.[joined];
         }
-        delete relationQuery.$exclude?.[foreignField];
-        const ids = payload.map((it) => it[meta.id]);
-        relationQuery.$where = { ...relationQuery.$where, [foreignField]: ids };
+        relationQuery.$where = { ...relationQuery.$where, ...parentsIn(joins, payload) };
         const founds = await this.findMany(relEntity, relationQuery);
-        this.putChildrenInParents(payload, founds, meta.id, foreignField, relKey);
+        this.putChildrenInParents(payload, founds, joins, relKey);
     }
-    putChildrenInParents(parents, children, parentIdKey, referenceKey, relKey) {
+    putChildrenInParents(parents, children, joins, relKey) {
         const childrenByParentId = {};
         for (const child of children) {
-            const parentId = String(child[referenceKey]);
-            if (!childrenByParentId[parentId])
-                childrenByParentId[parentId] = [];
-            childrenByParentId[parentId].push(child);
+            // Every joined column, so two children agreeing on one column of a composite key are not
+            // gathered under the same parent.
+            (childrenByParentId[joinedRowKey(joins, child)] ??= []).push(child);
         }
         for (const parent of parents) {
             // `[]` rather than nothing for a parent with no children: a populated to-many is a list the
             // caller asked for, so it maps and counts without a guard, and its type can say so. An
             // unpopulated one stays absent, which is what tells the two apart.
-            parent[relKey] = (childrenByParentId[String(parent[parentIdKey])] ?? []);
+            parent[relKey] = (childrenByParentId[parentRowKey(joins, parent)] ?? []);
         }
     }
     async insertRelations(entity, payload) {
@@ -334,7 +364,8 @@ export class AbstractQuerier {
         }, []);
         if (!entries.length)
             return;
-        await Promise.all(entries.map(({ it, relKeys }) => Promise.all(relKeys.map((relKey) => this.saveRelation(entity, [it[meta.id]], it[relKey], relKey)))));
+        const idKey = soleIdOf(meta, 'saving a relation');
+        await Promise.all(entries.map(({ it, relKeys }) => Promise.all(relKeys.map((relKey) => this.saveRelation(entity, [it[idKey]], it[relKey], relKey)))));
     }
     async updateRelations(entity, q, payload, opts) {
         const meta = getMeta(entity);
@@ -342,8 +373,9 @@ export class AbstractQuerier {
         if (!relKeys.length) {
             return;
         }
+        const idKey = soleIdOf(meta, 'saving a relation');
         const founds = await this.findMany(entity, idOnlyQuery(meta, q), opts);
-        const ids = founds.map((found) => found[meta.id]);
+        const ids = founds.map((found) => found[idKey]);
         if (!ids.length) {
             return;
         }
@@ -351,6 +383,10 @@ export class AbstractQuerier {
             await this.saveRelation(entity, ids, payload[relKey], relKey, true);
         }
     }
+    /**
+     * `EntityId` because a settled set names composite rows as objects, which is also what the parent's
+     * own delete takes - and what {@link childrenOf} reads each child's foreign key columns out of.
+     */
     async deleteRelations(entity, ids, opts) {
         const meta = getMeta(entity);
         const relKeys = filterPersistableRelationKeys(meta, meta.relations, 'delete');
@@ -360,9 +396,9 @@ export class AbstractQuerier {
             if (!relOpts)
                 continue;
             const relEntity = relOpts.entity();
-            const parentKey = parentKeyColumn(relOpts);
             const target = relOpts.through ? relOpts.through() : relEntity;
-            await this.deleteMany(target, { $where: { [parentKey]: ids } }, opts);
+            const where = childrenOf(parentJoins(relOpts, meta.ids.length), ids);
+            await this.deleteMany(target, { $where: where }, opts);
         }
     }
     /**
@@ -375,6 +411,11 @@ export class AbstractQuerier {
         const relOpts = meta.relations[relKey];
         if (!relOpts)
             return;
+        // Here rather than only in the callers below: writing the parent's key into a child is one column
+        // per key, so a composite takes a statement per parent. `soleParentColumn` and the sole
+        // `targetKeyColumns` under it read the *first* pair, which is a real column of a wrong pairing
+        // unless this has run - and this method is `protected`, so a caller can arrive without them.
+        assertSoleId(meta, 'saving a relation');
         const relEntity = relOpts.entity();
         const relPayload = relValue;
         switch (relOpts.cardinality) {
@@ -391,7 +432,8 @@ export class AbstractQuerier {
     async saveToMany(relOpts, relEntity, ids, relPayload, isUpdate) {
         const { through } = relOpts;
         if (through) {
-            const localField = parentKeyColumn(relOpts);
+            const localField = soleParentColumn(relOpts);
+            const [targetColumn] = targetKeyColumns(relOpts, 1);
             const throughEntity = through();
             if (isUpdate) {
                 await this.deleteMany(throughEntity, { $where: { [localField]: ids } });
@@ -401,12 +443,18 @@ export class AbstractQuerier {
                 // would link every parent to a single shared row instead.
                 for (const id of ids) {
                     const savedIds = await this.saveMany(relEntity, relPayload);
-                    await this.insertMany(throughEntity, savedIds.map((relId) => ({ [localField]: id, [targetKeyColumn(relOpts)]: relId })));
+                    // A link needs the target's id, and a driver that cannot report one (a MySQL batch mixing
+                    // supplied and generated keys) would otherwise write a row pointing at `undefined`.
+                    if (savedIds.some((relId) => relId === undefined)) {
+                        throw new TypeError(`'${relEntity.name}' rows saved through '${throughEntity.name}' reported no id, so they cannot be linked. ` +
+                            'Insert them with their own ids, or save the relation in its own statement.');
+                    }
+                    await this.insertMany(throughEntity, savedIds.map((relId) => ({ [localField]: id, [targetColumn]: relId })));
                 }
             }
             return;
         }
-        const foreignField = parentKeyColumn(relOpts);
+        const foreignField = soleParentColumn(relOpts);
         if (isUpdate) {
             await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
         }
@@ -415,7 +463,7 @@ export class AbstractQuerier {
         }
     }
     async saveOneToOne(relEntity, relOpts, ids, relPayload) {
-        const foreignField = parentKeyColumn(relOpts);
+        const foreignField = soleParentColumn(relOpts);
         if (relPayload === null) {
             await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
             return;
@@ -423,7 +471,7 @@ export class AbstractQuerier {
         await this.saveMany(relEntity, ids.map((id) => ({ ...relPayload, [foreignField]: id })));
     }
     async saveManyToOne(entity, relEntity, relOpts, ids, relPayload) {
-        // Not `parentKeyColumn`: a many-to-one points the other way, so this is the *parent's* own column
+        // Not `soleParentColumn`: a many-to-one points the other way, so this is the *parent's* own column
         // holding the child's id - the one place `references[0].local` does not name a key of the parent.
         const localField = relOpts.references[0].local;
         // Per parent: each gets its own reference row, so each `SET` carries a different value.

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, ExtraOptions, FieldKey, IdValue, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -24,7 +24,7 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     withQuerier<T>(callback: (querier: Q) => Promise<T>, opts?: PoolRunOptions): Promise<T>;
     /** Run `fn` under `context` (an enclosing {@link withContext}) when provided, else run it as-is. */
     private runScoped;
-    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?: QueryOptions): Promise<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?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     findOne<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: QueryOneProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P, C> | undefined>;
     findMany<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): Promise<QueryFindResult<E, S, V, X, P, C>[]>;
     /**
@@ -38,16 +38,16 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
-    saveOne<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>[]>;
-    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    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>;
     /**
      * end the pool.

package/dist/querier/abstractSqlQuerier.d.ts

@@ -105,7 +105,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected internalCount<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
     private settleIds;

package/dist/querier/abstractSqlQuerier.js

@@ -1,6 +1,6 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, idOf, soleIdOf } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
@@ -283,14 +283,19 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         payload = clone(payload);
         const meta = getMeta(entity);
-        const idKey = meta.id;
-        const idField = meta.fields[idKey];
+        // A composite key is supplied whole by the caller, so nothing is generated and nothing comes
+        // back: the rows insert, and their ids are `undefined` for the reason MySQL's are below - there
+        // is no id to report. `idOf` names such a row for the caller that wants one.
+        const [idKey] = meta.ids;
+        const sole = meta.ids.length === 1;
+        const idField = sole ? meta.fields[idKey] : undefined;
         // RETURNING-based IDs are exact per row. Header-derived IDs (LAST_INSERT_ID /
         // lastInsertRowid arithmetic) are only sound when the primary key is database-generated
         // and no record supplies an explicit ID (a mixed batch shifts the positional mapping and
         // MySQL stops guaranteeing consecutive values); otherwise generated IDs stay `undefined`.
-        const idsReliable = this.dialect.insertIdSource === 'returning' ||
-            (!!idField && isAutoIncrement(idField, true) && payload.every((it) => it[idKey] === undefined));
+        const idsReliable = sole &&
+            (this.dialect.insertIdSource === 'returning' ||
+                (!!idField && isAutoIncrement(idField, true) && payload.every((it) => it[idKey] === undefined)));
         // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
         // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
         if (idsReliable && payload.length > 1 && this.dialect.insertIdSource === 'firstId') {
@@ -309,7 +314,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
                 if (idsReliable) {
                     it[idKey] ??= ids[index];
                 }
-                payloadIds.push(it[idKey]);
+                payloadIds.push(sole ? it[idKey] : undefined);
             });
         }
         await this.insertRelations(entity, payload);
@@ -339,7 +344,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, idOnlyQuery(meta, q), opts);
         const founds = await this.all(ctx.sql, ctx.values);
-        return founds.map((it) => it[meta.id]);
+        return founds.map((found) => idOf(meta, found));
     }
     async upsertOne(entity, conflictPaths, payload) {
         return this.upsertMany(entity, conflictPaths, [payload]);