uql-orm 0.41.0 → 0.42.0

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 { getMeta, idOf, soleIdOf } from '../entity/index.js';
+import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, LoggerWrapper, parentJoins, parentsIn, parseRelationAtKey, parseRelationQueryValue, rowKey, 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: Object.fromEntries(joins.map(({ joined }) => [joined, true])),
             $populate: {
                 [targetRelKey]: {
                     ...relationQuery,
                     $required: true,
                 },
             },
-            $where: {
-                [localField]: ids,
-            },
+            $where: parentsIn(joins, payload),
         });
         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.
+            const parentId = rowKey(joins.map(({ joined }) => child[joined]));
+            (childrenByParentId[parentId] ??= []).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])] ?? []);
+            const key = rowKey(joins.map(({ parent: parentKey }) => parent[parentKey]));
+            parent[relKey] = (childrenByParentId[key] ?? []);
         }
     }
     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);
         }
     }
     /**
@@ -391,7 +427,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 +438,12 @@ 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 })));
+                    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 +452,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 +460,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]);

package/dist/querier/relationCount.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } from '../util/index.js';
+import { asSelectMap, getKeys, parentJoins, parentsIn, rowKey, targetKeyColumns, } from '../util/index.js';
 /**
  * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
  * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
@@ -9,27 +9,33 @@ import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } from '../util/
  */
 export function withIdForCounts(entity, q) {
     const meta = getMeta(entity);
-    if (!q.$count || !meta.id) {
+    if (!q.$count) {
         return q;
     }
+    const { ids } = meta;
+    const named = ids.join(', ');
     if (q.$distinct) {
-        // The id would have to join the projection for the tallies to group by, and that is the set
-        // `$distinct` collapses on: adding it silently stops the grouping collapsing anything at all.
-        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${String(meta.id)}', which the grouping does not keep.`);
+        // The keys would have to join the projection for the tallies to group by, and that is the set
+        // `$distinct` collapses on: adding them silently stops the grouping collapsing anything at all.
+        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${named}', which the grouping does not keep.`);
     }
     if (Array.isArray(q.$select)) {
-        // Nothing to add the id to, and without it every tally would be looked up by `undefined` and
+        // Nothing to add the keys to, and without them every tally would be looked up by `undefined` and
         // come back zero. Refused rather than answered wrong, the way an unorderable clause is.
-        throw new TypeError(`$count needs the '${String(meta.id)}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
+        throw new TypeError(`$count needs the '${named}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
     }
     const next = { ...q };
     const select = asSelectMap(q.$select);
-    if (select && !select[meta.id]) {
-        next.$select = { ...select, [meta.id]: true };
+    const missing = select ? ids.filter((key) => !select[key]) : [];
+    if (missing.length) {
+        next.$select = { ...select, ...Object.fromEntries(missing.map((key) => [key, true])) };
     }
-    if (q.$exclude?.[meta.id]) {
+    const excluded = ids.filter((key) => q.$exclude?.[key]);
+    if (excluded.length) {
         const kept = { ...q.$exclude };
-        delete kept[meta.id];
+        for (const key of excluded) {
+            delete kept[key];
+        }
         next.$exclude = kept;
     }
     return next;
@@ -44,9 +50,6 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         return;
     }
     const meta = getMeta(entity);
-    // The ids cross the same boundary the entity does: past here every column is named by metadata,
-    // so they are read as {@link CountedRow}'s values rather than as this entity's own id type.
-    const ids = payload.map((it) => it[meta.id]);
     const counted = new Map();
     for (const relKey of getKeys(count)) {
         const value = count[relKey];
@@ -55,10 +58,11 @@ export async function fillRelationCounts(querier, entity, payload, count) {
             continue;
         }
         const where = typeof value === 'object' ? value.$where : undefined;
-        counted.set(relKey, await countPerParent(querier, relOpts, ids, where));
+        const joins = parentJoins(relOpts, meta.ids.length);
+        counted.set(relKey, await countPerParent(querier, relOpts, joins, payload, where));
     }
     for (const parent of payload) {
-        const id = String(parent[meta.id]);
+        const id = rowKey(meta.ids.map((key) => parent[key]));
         const row = {};
         for (const [relKey, byParent] of counted) {
             // A parent the grouped result has no row for matched nothing, which is a zero rather than a
@@ -68,37 +72,42 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         parent[COUNT_RESULT_KEY] = row;
     }
 }
-async function countPerParent(querier, relOpts, ids, where) {
+async function countPerParent(querier, relOpts, joins, parents, where) {
     const through = relOpts.through;
     if (through) {
-        return countThroughPerParent(querier, relOpts, through(), ids, where);
+        return countThroughPerParent(querier, relOpts, through(), joins, parents, where);
     }
-    const foreign = parentKeyColumn(relOpts);
-    return groupedCount(querier, relOpts.entity(), foreign, { ...where, [foreign]: ids });
+    return groupedCount(querier, relOpts.entity(), joins, {
+        ...where,
+        ...parentsIn(joins, parents),
+    });
 }
 /**
  * A many-to-many counts its junction rows, one per pairing. A filter names the target's columns,
  * which the junction does not have, so the matching targets are resolved first and the junction
  * counted against them - the one shape here that costs a second statement, and only when filtered.
  */
-async function countThroughPerParent(querier, relOpts, throughEntity, ids, where) {
-    const local = parentKeyColumn(relOpts);
-    const throughWhere = { [local]: ids };
+async function countThroughPerParent(querier, relOpts, throughEntity, joins, parents, where) {
+    const throughWhere = parentsIn(joins, parents);
     if (where) {
         const target = relOpts.entity();
-        const targetId = getMeta(target).id;
+        const targetId = soleIdOf(getMeta(target), 'a many-to-many target');
         const targets = await querier.findMany(target, { $select: { [targetId]: true }, $where: where });
-        throughWhere[targetKeyColumn(relOpts)] = targets.map((it) => it[targetId]);
+        const [targetColumn] = targetKeyColumns(relOpts, joins.length);
+        throughWhere[targetColumn] = targets.map((it) => it[targetId]);
     }
-    return groupedCount(querier, throughEntity, local, throughWhere);
+    return groupedCount(querier, throughEntity, joins, throughWhere);
 }
-/** `SELECT <key>, COUNT(*) ... GROUP BY <key>`, as a lookup from parent key to tally. */
-async function groupedCount(querier, entity, groupKey, where) {
+/** `SELECT <keys>, COUNT(*) ... GROUP BY <keys>`, as a lookup from parent key to tally. */
+async function groupedCount(querier, entity, joins, where) {
     const $agg = { [COUNT_ALIAS]: { $count: '*' } };
-    const rows = await querier.aggregate(entity, { $group: { [groupKey]: true }, $agg, $where: where });
+    const $group = Object.fromEntries(joins.map(({ joined }) => [joined, true]));
+    const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
     const byParent = {};
     for (const row of rows) {
-        byParent[String(row[groupKey])] = Number(row[COUNT_ALIAS]);
+        // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
+        // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
+        byParent[rowKey(joins.map(({ joined }) => row[joined]))] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

package/dist/schema/schemaAST.js

@@ -19,6 +19,7 @@ export function createTableNode(name, schema, comment) {
         columns: new Map(),
         primaryKey: [],
         indexes: [],
+        checks: [],
         incomingRelations: [],
         outgoingRelations: [],
     };

package/dist/schema/schemaASTBuilder.js

@@ -5,7 +5,7 @@
  * - Entity metadata (decorator-based entities)
  * - Database introspection results (TableSchema[])
  */
-import { getMeta } from '../entity/metadata/definition.js';
+import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
 import { fieldOptionsToCanonical } from './canonicalType.js';
 import { createTableNode, SchemaAST } from './schemaAST.js';
@@ -57,7 +57,9 @@ function resolveColumnCanonicalType(field, seen = new Set()) {
     if (!hasExplicitType && field.references && !seen.has(field.references)) {
         seen.add(field.references);
         const referencedMeta = getMeta(field.references());
-        const referencedIdField = referencedMeta.fields[referencedMeta.id];
+        // The column names which key it points at when the target has several; otherwise there is one.
+        const referencedKey = field.referencedKey ?? soleIdOf(referencedMeta, 'a foreign key');
+        const referencedIdField = referencedMeta.fields[referencedKey];
         if (referencedIdField) {
             return resolveColumnCanonicalType(referencedIdField, seen);
         }
@@ -71,6 +73,7 @@ function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
     const table = createTableNode(tableName, ctx.resolveSchema(meta));
     const { columns, primaryKey } = table;
+    table.checks?.push(...(meta.checks ?? []));
     // Add columns from fields
     const fields = meta.fields;
     for (const key of Object.keys(fields)) {
@@ -82,7 +85,8 @@ function addTableFromEntity(ctx, meta) {
             continue;
         const columnName = ctx.resolveColumnName(key, field);
         const type = resolveColumnCanonicalType(field);
-        const isPrimaryKey = key === meta.id;
+        const isPrimaryKey = field.isId === true;
+        const isSoleKey = isPrimaryKey && meta.ids.length === 1;
         const column = {
             name: columnName,
             type,
@@ -91,15 +95,18 @@ function addTableFromEntity(ctx, meta) {
             nullable: isPrimaryKey ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
-            isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && type.category === 'integer'),
+            // Only a sole integer key defaults to auto-increment: a composite's columns are values the
+            // caller supplies, and the serial type carries an inline `PRIMARY KEY` the table already states.
+            isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && isSoleKey && type.category === 'integer'),
             isUnique: field.unique ?? false,
             comment: field.comment,
+            enum: field.enum,
             table,
             referencedBy: [],
             references: undefined,
         };
         columns.set(columnName, column);
-        if (key === meta.id) {
+        if (field.isId) {
             primaryKey.push(column);
         }
     }
@@ -131,27 +138,35 @@ function addRelationshipsFromEntity(ctx, meta) {
         // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
         const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
         if (ownsForeignKey) {
-            const localPropName = relation.references[0].local;
-            const foreignPropName = relation.references[0].foreign;
-            const localField = meta.fields[localPropName];
-            if (!localField)
-                continue;
-            const localColName = ctx.resolveColumnName(localPropName, localField);
-            const foreignField = relatedMeta.fields[foreignPropName];
-            if (!foreignField)
-                continue;
-            const foreignColName = ctx.resolveColumnName(foreignPropName, foreignField);
-            const localColumn = table.columns.get(localColName);
-            const foreignColumn = relatedTable.columns.get(foreignColName);
-            if (localColumn && foreignColumn) {
+            // Every pair, not just the first: a composite key is one constraint over all its columns, and
+            // the engine requires the referenced columns to match a unique constraint as a whole.
+            const localColumns = [];
+            const foreignColumns = [];
+            let firstLocalField;
+            for (const { local: localPropName, foreign: foreignPropName } of relation.references) {
+                const localField = meta.fields[localPropName];
+                const foreignField = relatedMeta.fields[foreignPropName];
+                if (!localField || !foreignField) {
+                    continue;
+                }
+                const localColumn = table.columns.get(ctx.resolveColumnName(localPropName, localField));
+                const foreignColumn = relatedTable.columns.get(ctx.resolveColumnName(foreignPropName, foreignField));
+                if (!localColumn || !foreignColumn) {
+                    continue;
+                }
+                firstLocalField ??= localField;
+                localColumns.push(localColumn);
+                foreignColumns.push(foreignColumn);
+            }
+            if (localColumns.length === relation.references.length && firstLocalField) {
                 const relNode = {
-                    name: derivedForeignKeyName(table.name, [localColName]),
+                    name: derivedForeignKeyName(table.name, localColumns.map((column) => column.name)),
                     type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
-                    from: { table, columns: [localColumn] },
-                    to: { table: relatedTable, columns: [foreignColumn] },
+                    from: { table, columns: localColumns },
+                    to: { table: relatedTable, columns: foreignColumns },
                     // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
                     // references, onDelete })` work with no relation declared at all.
-                    onDelete: relation.onDelete ?? localField.onDelete ?? ctx.defaultForeignKeyAction,
+                    onDelete: relation.onDelete ?? firstLocalField.onDelete ?? ctx.defaultForeignKeyAction,
                     onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
                     confidence: 1.0,
                     inferredFrom: 'entity_decorator',