uql-orm 0.41.0 → 0.42.0

package/dist/entity/metadata/definition.js

@@ -1,5 +1,5 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
-import { getKeys, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, normalizeIndexWhere, upperFirst, } from '../../util/index.js';
+import { getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
 // evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). Version-suffixed
@@ -24,12 +24,6 @@ export function defineField(entity, key, opts = {}) {
     return meta;
 }
 export function defineId(entity, key, opts) {
-    const meta = ensureMeta(entity);
-    const id = getIdKey(meta);
-    if (id) {
-        // A subclass narrowing the inherited primary key: drop the old one so exactly one stays marked.
-        delete meta.fields[id];
-    }
     return defineField(entity, key, { ...opts, isId: true });
 }
 // `RelationOptions` is parameterized by the *target* entity, which is independent of the owner `E`, so it
@@ -66,7 +60,7 @@ export function defineIndex(entity, index) {
     meta.indexes.push({
         ...index,
         unique: index.unique ?? false,
-        where: normalizeIndexWhere(index.where),
+        where: ddlText(index.where, 'a partial-index predicate'),
         columns: index.columns.map(normalizeIndexColumn),
     });
     return meta;
@@ -124,6 +118,10 @@ export function defineEntity(entity, opts = {}) {
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
     applyMembers(entity, ownRegistrations(entity));
     applyMembers(entity, opts);
+    // Unnamed checks are named by the generator, as unnamed indexes are.
+    for (const check of opts.checks ?? []) {
+        (meta.checks ??= []).push({ name: check.name, expression: ddlText(check.expression, 'a check constraint') });
+    }
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }
@@ -163,16 +161,51 @@ export function defineEntity(entity, opts = {}) {
             meta.filters = {};
         meta.filters[SOFT_DELETE_FILTER] = { condition: { [meta.softDelete]: null }, default: true };
     }
-    const id = getIdKey(meta);
-    if (!id) {
-        throw TypeError(`'${entity.name}' must have exactly one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
+    const ids = getIdKeys(meta);
+    if (!ids.length) {
+        throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
     }
-    meta.id = id;
+    meta.ids = ids;
     return meta;
 }
+/**
+ * Refuses an entity whose primary key is not one column, naming the path that cannot express it.
+ *
+ * Refusing rather than taking the first of several is the whole guarantee: pairing one column of a
+ * two-column key is how a statement silently addresses rows that merely agree on it.
+ */
+export function assertSoleId(meta, what) {
+    const { ids } = meta;
+    if (ids.length === 1) {
+        return;
+    }
+    throw new TypeError(ids.length
+        ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support yet.`
+        : // An entity registered with `@Field` but no `@Entity` never ran the check in `defineEntity`.
+            `'${meta.entity.name}' has no primary key, which ${what} needs.`);
+}
+/** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
+export function soleIdOf(meta, what) {
+    assertSoleId(meta, what);
+    return meta.ids[0];
+}
+/**
+ * A row's primary key in the shape a `$where` takes: the value itself for a single key, an object
+ * carrying every key for a composite - which is exactly {@link EntityId}.
+ *
+ * What a settled write names its rows by, and what an insert hands back. Naming a composite row by
+ * one of its columns would address every row agreeing on that one.
+ */
+export function idOf(meta, row) {
+    const { ids } = meta;
+    if (ids.length === 1) {
+        return row[ids[0]];
+    }
+    return Object.fromEntries(ids.map((key) => [key, row[key]]));
+}
 export function getEntities() {
     return [...metas.entries()].reduce((acc, [key, val]) => {
-        if (val.id) {
+        if (val.ids.length) {
             acc.push(key);
         }
         return acc;
@@ -183,7 +216,7 @@ function ensureMeta(entity) {
     if (meta) {
         return meta;
     }
-    meta = { entity, id: '', fields: {}, relations: {} };
+    meta = { entity, ids: [], fields: {}, relations: {} };
     metas.set(entity, meta);
     return meta;
 }
@@ -206,7 +239,7 @@ function fillRelations(meta) {
             continue;
         const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
-            fillInverseSide(at, relOpts);
+            fillInverseSide(at, meta, relOpts);
         }
         else if (!relOpts.references) {
             fillOwningSide(at, meta, relKey, relOpts);
@@ -230,13 +263,13 @@ function fillRelations(meta) {
 }
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
-    const relIdKey = relMeta.id;
     if (relOpts.through) {
         // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
-        // `deleteRelations` and every dialect read them as junction columns.
+        // `deleteRelations` and every dialect read them as junction columns. A composite key contributes
+        // one pair per column of it, which is what makes the join address a whole key rather than part.
         relOpts.references = [
-            { local: junctionColumn(meta, meta.id), foreign: meta.id },
-            { local: junctionColumn(relMeta, relIdKey), foreign: relIdKey },
+            ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
+            ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),
         ];
         return;
     }
@@ -244,21 +277,29 @@ function fillOwningSide(at, meta, relKey, relOpts) {
         throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns).");
     }
-    const fkKey = `${relKey}Id`;
-    relOpts.references = [{ local: fkKey, foreign: relIdKey }];
+    // `<rel>Id` for the one-key case it has always been; `<rel><Key>` per column otherwise. Both name a
+    // property, so both are spelled from the referenced *property* - a column name is what the naming
+    // strategy makes of this afterwards.
+    const sole = relMeta.ids.length === 1;
+    relOpts.references = relMeta.ids.map((key) => ({
+        local: sole ? `${relKey}Id` : `${relKey}${upperFirst(key)}`,
+        foreign: key,
+    }));
     // `typeFromReference` so schema generation resolves the referenced primary key's exact type
     // (columnType, length, chained keys) rather than trusting the fallback, as it does for an
     // explicit `@Field({ references })`.
-    if (!meta.fields[fkKey]) {
-        meta.fields[fkKey] = {
-            name: fkKey,
-            type: relMeta.fields[relIdKey]?.type ?? Number,
+    const fields = meta.fields;
+    for (const { local, foreign } of relOpts.references) {
+        fields[local] ??= {
+            name: local,
+            type: relMeta.fields[foreign]?.type ?? Number,
             references: relOpts.entity,
+            referencedKey: foreign,
             typeFromReference: true,
         };
     }
 }
-function fillInverseSide(at, relOpts) {
+function fillInverseSide(at, meta, relOpts) {
     const relEntity = relOpts.entity();
     const relMeta = getMeta(relEntity);
     const mappedBy = getMappedByKey(relOpts);
@@ -266,7 +307,13 @@ function fillInverseSide(at, relOpts) {
     if (relOpts.references)
         return;
     if (relMeta.fields[mappedBy]) {
-        relOpts.references = [{ local: relMeta.id, foreign: mappedBy }];
+        if (meta.ids.length > 1) {
+            throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', one column, but the primary key of ` +
+                `'${meta.entity.name}' is composite (${meta.ids.join(', ')}). Map it by the relation on the other side ` +
+                'instead, which joins every column of the key.');
+        }
+        // `local` is this entity's own key, as in every other pair.
+        relOpts.references = [{ local: meta.ids[0], foreign: mappedBy }];
         return;
     }
     // Authored view again: with each side mapped by the other, the target is still mid-resolution here and
@@ -278,11 +325,12 @@ function fillInverseSide(at, relOpts) {
     if (!owner.references?.length) {
         throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', an inverse side too, so neither owns the foreign key.`);
     }
-    // Two different flips: a junction pair is `[thisSide, otherSide]`, so the array reverses; a plain
-    // foreign key is one pair whose ends swap.
+    // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
+    // swap - `toReversed` would also reverse each group, pairing a composite's columns crosswise. A
+    // plain foreign key is one pair per key whose ends swap.
     relOpts.references =
         relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm'
-            ? owner.references.toReversed()
+            ? [...owner.references.slice(relMeta.ids.length), ...owner.references.slice(0, relMeta.ids.length)]
             : owner.references.map(({ local, foreign }) => ({ local: foreign, foreign: local }));
     relOpts.through = owner.through;
 }
@@ -299,7 +347,16 @@ function fillForeignKeyRelations(meta) {
         const references = meta.fields[fieldKey]?.references;
         if (!references || joined.has(fieldKey))
             continue;
-        const foreign = ensureMeta(references()).id;
+        const target = ensureMeta(references());
+        // Nothing to derive from an entity that has not registered its own fields yet.
+        if (!target.ids.length)
+            continue;
+        if (target.ids.length > 1) {
+            throw new TypeError(`'${meta.entity.name}.${fieldKey}' cannot reference '${target.entity.name}', whose primary key is composite ` +
+                `(${target.ids.join(', ')}): a column points at one. Use ` +
+                `'@ManyToOne({ entity: () => ${target.entity.name} })', which declares one column per key.`);
+        }
+        const [foreign] = target.ids;
         // The relation takes the column's name minus the key it points at (`itemId` -> `item`); a column
         // named anything else has no name to take, so it stays a plain foreign key.
         const suffix = upperFirst(foreign);
@@ -326,16 +383,18 @@ function getMappedByKey(relOpts) {
         ? relOpts.mappedBy(RELATION_KEY_MAP)
         : relOpts.mappedBy;
 }
-function getIdKey(meta) {
-    const id = getKeys(meta.fields).find((key) => meta.fields[key]?.isId);
-    return id;
+/** Every key the entity marks, in declaration order. More than one is a composite primary key. */
+function getIdKeys(meta) {
+    return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);
 }
 function extendMeta(target, source) {
     const sourceFields = { ...source.fields };
-    const sourceId = getIdKey(source);
-    // A subclass that declares its own primary key drops the parent's, so exactly one stays marked.
-    if (sourceId && getIdKey(target)) {
-        delete sourceFields[sourceId];
+    // A subclass declaring its own primary key drops the parent's - every column of it, or a composite
+    // parent would leave its remaining keys marked and silently widen the child's key.
+    if (getIdKeys(target).length) {
+        for (const key of getIdKeys(source)) {
+            delete sourceFields[key];
+        }
     }
     target.fields = { ...sourceFields, ...target.fields };
     target.relations = { ...source.relations, ...target.relations };

package/dist/http/handler.js

@@ -1,5 +1,5 @@
 import { withContext } from '../context/context.js';
-import { getEntities, getMeta } from '../entity/index.js';
+import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
 import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
@@ -142,8 +142,8 @@ export function createRequestHandler(opts) {
                         const founds = await querier.findMany(entity, query);
                         let ids = [];
                         let count = 0;
-                        if (founds.length && meta.id) {
-                            const idKey = meta.id;
+                        if (founds.length) {
+                            const idKey = soleIdOf(meta, 'the HTTP handler');
                             ids = founds.map((found) => found[idKey]);
                             count = await querier.deleteMany(entity, { $where: ids }, { hardDelete });
                         }
@@ -157,7 +157,7 @@ function ok(body) {
     return { status: 200, body };
 }
 function buildIdQuery(meta, id, query) {
-    const idKey = meta.id;
+    const idKey = soleIdOf(meta, 'the HTTP handler');
     const where = query.$where;
     if (Array.isArray(where)) {
         query.$where = { $and: [{ [idKey]: { $in: where } }, { [idKey]: id }] };

package/dist/maria/mariaDialect.d.ts

@@ -1,5 +1,5 @@
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
@@ -10,7 +10,7 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
      */
     protected readonly featureOverrides: Partial<DialectFeatures>;
-    protected upsertReturning<E>(entity: Type<E>): string;
+    protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
      * reads a scalar and `JSON_EXTRACT` the subtree that the array operators need.

package/dist/maria/mariaDialect.js

@@ -18,8 +18,8 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
     };
-    upsertReturning(entity) {
-        return ` ${this.returningId(entity)}`;
+    upsertReturning(meta) {
+        return ` ${this.returningId(meta)}`;
     }
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`

package/dist/migrate/builder/migrationBuilder.js

@@ -5,7 +5,7 @@
  * - OperationRecorder: Record operations only (for code generation)
  * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
  */
-import { normalizeIndexColumn, normalizeIndexWhere } from '../../util/index.js';
+import { ddlText, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
 import { createSchemaGenerator } from '../schemaGenerator.js';
 import { splitSqlStatements } from './splitSqlStatements.js';
@@ -29,7 +29,7 @@ function createIndexOperation(tableName, columns, options = {}) {
             ...index,
             name: name ??
                 derivedIndexName(tableName, entries.map((entry) => entry.column)),
-            where: normalizeIndexWhere(index.where),
+            where: ddlText(index.where, 'a partial-index predicate'),
             entries,
             unique: unique ?? false,
         },

package/dist/migrate/builder/tableBuilder.js

@@ -3,7 +3,7 @@
  *
  * Fluent API for defining tables in migrations.
  */
-import { normalizeIndexColumn, normalizeIndexWhere } from '../../util/index.js';
+import { ddlText, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
 import { ColumnBuilder } from './columnBuilder.js';
 import { expr } from './expressions.js';
@@ -171,7 +171,7 @@ export class TableBuilder {
         this._indexes.push({
             ...rest,
             name: name ?? `${prefix}_${this._name}_${entries.map((entry) => entry.column).join('_')}`,
-            where: normalizeIndexWhere(rest.where),
+            where: ddlText(rest.where, 'a partial-index predicate'),
             entries,
             unique,
         });

package/dist/migrate/schemaGenerator.d.ts

@@ -1,7 +1,7 @@
 import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
 import { type IndexDdl } from './ddl/index.js';
 /**
@@ -82,7 +82,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
      * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
     private defaultClause;
-    getSqlType(field: FieldOptions, fieldType?: unknown): string;
+    getSqlType(field: FieldMeta, fieldType?: unknown): string;
     /**
      * Generate ALTER COLUMN statements (database-specific)
      */

package/dist/migrate/schemaGenerator.js

@@ -1,9 +1,9 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, soleIdOf } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
-import { derivedForeignKeyName } from '../util/sql.util.js';
+import { derivedCheckName, derivedForeignKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
@@ -247,6 +247,10 @@ export class SqlSchemaGenerator {
         if (column.isUnique && !column.isPrimaryKey) {
             def += ' UNIQUE';
         }
+        if (column.enum?.length) {
+            const values = column.enum.map((value) => this.dialect.escape(value)).join(', ');
+            def += ` CHECK (${this.escapeId(column.name)} IN (${values}))`;
+        }
         def += this.defaultClause(column);
         if (column.comment) {
             def += this.generateColumnComment(column.name, column.comment);
@@ -265,7 +269,7 @@ export class SqlSchemaGenerator {
         if (field.references) {
             const refEntity = field.references();
             const refMeta = getMeta(refEntity);
-            const refIdField = refMeta.fields[refMeta.id];
+            const refIdField = refMeta.fields[field.referencedKey ?? soleIdOf(refMeta, 'a foreign key')];
             return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false }, refIdField.type);
         }
         // Get canonical type and convert to SQL
@@ -406,7 +410,7 @@ export class SqlSchemaGenerator {
      * would create for this field, against what it reported for the existing column.
      */
     fieldToColumnSchema(fieldKey, field, meta) {
-        const isPrimaryKey = field.isId === true && meta.id === fieldKey;
+        const isPrimaryKey = field.isId === true;
         return {
             name: this.dialect.resolveColumnName(fieldKey, field),
             type: this.getSqlType(field, field.type),
@@ -493,6 +497,10 @@ export class SqlSchemaGenerator {
             const pkCols = table.primaryKey.map((c) => this.escapeId(c.name)).join(', ');
             constraints.push(`PRIMARY KEY (${pkCols})`);
         }
+        (table.checks ?? []).forEach((check, i) => {
+            const name = check.name ?? derivedCheckName(table.name, i + 1);
+            constraints.push(`CONSTRAINT ${this.escapeId(name)} CHECK (${check.expression})`);
+        });
         for (const rel of table.outgoingRelations) {
             if (rel.from.columns.length > 0) {
                 const fromCols = rel.from.columns.map((c) => this.escapeId(c.name)).join(', ');

package/dist/mongo/mongoDialect.js

@@ -2,7 +2,7 @@ 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';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
@@ -44,7 +44,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);
@@ -250,7 +257,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 +379,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;
@@ -679,8 +686,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 +805,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/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