uql-orm 0.47.0 → 0.48.0

package/dist/mongo/mongoDialect.d.ts

@@ -1,4 +1,4 @@
-import { type Document, type Filter, ObjectId, type Sort, type UpdateFilter } from 'mongodb';
+import { type Document, type Filter, type Sort, type UpdateFilter } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { DialectFeatures, EntityData, EntityMeta, FieldValue, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPopulate, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
 import { type CallbackKey } from '../util/index.js';
@@ -43,11 +43,21 @@ export declare class MongoDialect extends AbstractDialect {
     /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
     constrainsRelations<E extends Document>(entity: Type<E>, where: QueryWhere<E> | undefined): boolean;
     /**
-     * Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or`
+     * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
     private renderFilter;
+    /**
+     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
+     * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that
+     * makes a `$nor` list its clauses directly while a `$not` wraps them in one `$and` first.
+     *
+     * Clauses that render to nothing are dropped and an empty operator emits no key at all: MongoDB
+     * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
+     * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
+     */
+    private appendLogicalOperator;
     /**
      * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
      * result: presence of a row for a plain relation filter, a comparison against the row count for
@@ -177,9 +187,20 @@ export declare class MongoDialect extends AbstractDialect {
     private joinKeys;
     /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
     private renamedColumns;
-    normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: E[] | undefined): E[] | undefined;
-    normalizeId<E extends Document>(meta: EntityMeta<E>, doc: E | undefined): E | undefined;
-    getIdValue<T extends IdValue>(value: T): T;
+    private referenceKeys;
+    normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[] | undefined): E[] | undefined;
+    /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
+    normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document | undefined): E | undefined;
+    /**
+     * The seam into the driver: a key, or a reference to one, as MongoDB stores it. A 24-hex string
+     * becomes an `ObjectId`, so a write agrees with the filter that will later look for it; anything
+     * else - a UUID, a number, an `ObjectId` already - is stored as given, which is how those keys keep
+     * their value. Strictly 24-hex: the driver also accepts any 12-byte string, and coercing one of
+     * those turned an ordinary short key into a foreign `ObjectId`. Arrays convert element-wise.
+     */
+    toWireId(value: unknown): unknown;
+    /** The seam out of the driver: an `ObjectId` becomes its hex string, the type the code declares. */
+    fromWireId(value: unknown): unknown;
     getPersistable<E extends Document>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): Partial<E>;
     /** One MongoDB update document's operators, grouped by kind and keyed by dotted path. */
     private groupUpdateOperators;
@@ -201,6 +222,16 @@ export declare class MongoDialect extends AbstractDialect {
      * `$literal` so a string starting with `$` stays data rather than becoming a field reference.
      */
     private getUpdatePipeline;
+    /**
+     * Refuses a key the caller left to MongoDB that MongoDB cannot mint one of.
+     *
+     * The only key a server generates is an `ObjectId`, which {@link fromWireId} hands back as its hex
+     * string - so a key declared `String` is satisfiable and one declared `Number` is not. Answering a
+     * numeric declaration with a string is the lie this exists to refuse: the field says `number`, the
+     * value is not one, and every consumer that indexes or compares by it is quietly wrong. Prisma
+     * refuses the same shape at its schema, and this is the first moment uql can.
+     */
+    private assertMintableKey;
     getPersistables<E extends Document>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): Partial<E>[];
     /**
      * Build MongoDB aggregation pipeline stages from a QueryAggregate.
@@ -253,7 +284,6 @@ type MongoAggregationUnwind = {
     readonly path?: string;
     readonly preserveNullAndEmptyArrays?: boolean;
 };
-type IdValue = string | ObjectId;
 export type ExtractedVectorSort<E> = {
     readonly vectorKey: string;
     readonly vectorSearch: QueryVectorSearch;

package/dist/mongo/mongoDialect.js

@@ -4,7 +4,7 @@ import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '..
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.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, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, columnFamily, 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,
@@ -24,6 +24,12 @@ export const mongoDialectFeatures = {
     supportsTimestamptz: false,
     defaultStringAsText: false,
 };
+/** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
+const HEX_24 = /^[0-9a-f]{24}$/i;
+/** How a declared column type reads in a message: `Number`, `uuid` - not its whole source. */
+function declaredTypeName(type) {
+    return typeof type === 'function' ? type.name : String(type);
+}
 export class MongoDialect extends AbstractDialect {
     featureDefaults = mongoDialectFeatures;
     dialectName = 'mongodb';
@@ -83,12 +89,12 @@ export class MongoDialect extends AbstractDialect {
         }
         const meta = getMeta(entity);
         const whereMap = buildQueryWhereAsMap(meta, where);
-        return someKey(whereMap, (key) => key === '$and' || key === '$or'
-            ? whereMap[key].some((it) => this.constrainsRelations(entity, it))
+        return someKey(whereMap, (key) => MongoDialect.isGroupOp(key)
+            ? (whereMap[key] ?? []).some((it) => this.constrainsRelations(entity, it))
             : Boolean(meta.relations[key]));
     }
     /**
-     * Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or`
+     * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
@@ -99,13 +105,8 @@ export class MongoDialect extends AbstractDialect {
         for (const [rawKey, rawVal] of Object.entries(whereMap)) {
             let key = rawKey;
             let val = rawVal;
-            if (key === '$and' || key === '$or') {
-                filter[key] = val.map((filterIt) => {
-                    // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
-                    // `{ $and: [raw] }`, which lands back on this branch.
-                    this.assertNoRaw(filterIt);
-                    return this.renderFilter(entity, filterIt, opts, lookups);
-                });
+            if (MongoDialect.isGroupOp(key)) {
+                this.appendLogicalOperator(filter, entity, key, val, opts, lookups);
             }
             else if (key === '$text') {
                 // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
@@ -122,9 +123,10 @@ export class MongoDialect extends AbstractDialect {
             else {
                 this.assertNoRaw(val);
                 this.assertKnownPathRoot(meta, key);
+                const isReference = !!meta.fields[key]?.references;
                 key = this.pathOf(meta, key);
-                if (key === MongoDialect.ID_KEY) {
-                    val = this.getIdValue(val);
+                if ((key === MongoDialect.ID_KEY || isReference) && !isOperatorObject(val)) {
+                    val = this.toWireId(val);
                 }
                 if (isOperatorObject(val)) {
                     val = this.transformOperators(val);
@@ -137,6 +139,35 @@ export class MongoDialect extends AbstractDialect {
         }
         return filter;
     }
+    /**
+     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
+     * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that
+     * makes a `$nor` list its clauses directly while a `$not` wraps them in one `$and` first.
+     *
+     * Clauses that render to nothing are dropped and an empty operator emits no key at all: MongoDB
+     * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
+     * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
+     */
+    appendLogicalOperator(filter, entity, key, val, opts, lookups) {
+        const { join, negate } = MongoDialect.GROUP_OPS[key];
+        const parts = MongoDialect.groupClauses(key, val)
+            .map((filterIt) => {
+            // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
+            // `{ $and: [raw] }`, which lands back on this branch.
+            this.assertNoRaw(filterIt);
+            return this.renderFilter(entity, filterIt, opts, lookups);
+        })
+            .filter((part) => Object.keys(part).length > 0);
+        if (!parts.length) {
+            return;
+        }
+        if (!negate) {
+            filter[key] = parts;
+            return;
+        }
+        const negated = join === '$and' && parts.length > 1 ? [{ $and: parts }] : parts;
+        filter['$nor'] = [...(filter['$nor'] ?? []), ...negated];
+    }
     /**
      * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
      * result: presence of a row for a plain relation filter, a comparison against the row count for
@@ -689,20 +720,31 @@ export class MongoDialect extends AbstractDialect {
         }
         return renamed;
     }
+    referenceKeys(meta) {
+        let keys = this.#referenceKeys.get(meta);
+        if (!keys) {
+            keys = getKeys(meta.fields).filter((key) => meta.fields[key]?.references);
+            this.#referenceKeys.set(meta, keys);
+        }
+        return keys;
+    }
     // Keyed by the meta object itself; entity metadata is immutable once defined.
     #renamedColumns = new WeakMap();
+    #referenceKeys = new WeakMap();
     normalizeIds(meta, docs) {
         return docs?.map((doc) => this.normalizeId(meta, doc));
     }
+    /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
     normalizeId(meta, doc) {
         if (!doc) {
             return doc;
         }
         const res = doc;
         const _id = MongoDialect.ID_KEY;
-        if (res[_id]) {
+        // `!== undefined`, not truthiness: `0` is a key MongoDB accepts and a truthy test dropped it.
+        if (res[_id] !== undefined) {
             const idKey = soleIdOf(meta, 'MongoDB');
-            res[idKey] = res[_id];
+            res[idKey] = this.fromWireId(res[_id]);
             if (idKey !== _id) {
                 delete res[_id];
             }
@@ -715,6 +757,12 @@ export class MongoDialect extends AbstractDialect {
                 delete res[column];
             }
         }
+        // After the rename, so a renamed reference is converted under the name the code reads.
+        for (const key of this.referenceKeys(meta)) {
+            if (res[key] !== undefined) {
+                res[key] = this.fromWireId(res[key]);
+            }
+        }
         const relKeys = getKeys(meta.relations).filter((key) => res[key]);
         for (const relKey of relKeys) {
             const relOpts = meta.relations[relKey];
@@ -727,16 +775,22 @@ export class MongoDialect extends AbstractDialect {
         }
         return res;
     }
-    getIdValue(value) {
-        if (value instanceof ObjectId) {
-            return value;
-        }
-        try {
-            return new ObjectId(value);
-        }
-        catch (e) {
-            return value;
+    /**
+     * The seam into the driver: a key, or a reference to one, as MongoDB stores it. A 24-hex string
+     * becomes an `ObjectId`, so a write agrees with the filter that will later look for it; anything
+     * else - a UUID, a number, an `ObjectId` already - is stored as given, which is how those keys keep
+     * their value. Strictly 24-hex: the driver also accepts any 12-byte string, and coercing one of
+     * those turned an ordinary short key into a foreign `ObjectId`. Arrays convert element-wise.
+     */
+    toWireId(value) {
+        if (Array.isArray(value)) {
+            return value.map((it) => this.toWireId(it));
         }
+        return typeof value === 'string' && HEX_24.test(value) ? new ObjectId(value) : value;
+    }
+    /** The seam out of the driver: an `ObjectId` becomes its hex string, the type the code declares. */
+    fromWireId(value) {
+        return value instanceof ObjectId ? value.toHexString() : value;
     }
     getPersistable(meta, payload, callbackKey) {
         return this.getPersistables(meta, payload, callbackKey)[0];
@@ -819,17 +873,48 @@ export class MongoDialect extends AbstractDialect {
         }
         return [{ $set: assignments }, ...(unset.size > 0 ? [{ $unset: [...unset] }] : [])];
     }
+    /**
+     * Refuses a key the caller left to MongoDB that MongoDB cannot mint one of.
+     *
+     * The only key a server generates is an `ObjectId`, which {@link fromWireId} hands back as its hex
+     * string - so a key declared `String` is satisfiable and one declared `Number` is not. Answering a
+     * numeric declaration with a string is the lie this exists to refuse: the field says `number`, the
+     * value is not one, and every consumer that indexes or compares by it is quietly wrong. Prisma
+     * refuses the same shape at its schema, and this is the first moment uql can.
+     */
+    assertMintableKey(meta, field) {
+        if (columnFamily(field.type) === 'string') {
+            return;
+        }
+        throw new TypeError(`'${entityName(meta)}.${meta.ids[0]}' is declared '${declaredTypeName(field.type)}' and left to the ` +
+            'database, which MongoDB cannot do: the only key it generates is an ObjectId, read back as a string. ' +
+            "Declare the key as a string, or give it an 'onInsert' generator.");
+    }
     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.
+        // What `columnOf` refuses, a write has to refuse too.
         assertSoleId(meta, 'MongoDB');
+        const [idKey] = meta.ids;
         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) => {
-            const field = meta.fields[key];
-            acc[this.resolveColumnName(key, field)] = it[key];
-            return acc;
-        }, {}));
+        const inserting = callbackKey === 'onInsert';
+        return payloads.map((it) => {
+            // The key is `_id` on an insert and immutable on an update, so it is left out of one. It used
+            // to land under its own name beside the `_id` the driver minted: a supplied id, or one an
+            // `onInsert` generated, was written and unreachable by the value the caller held.
+            const named = inserting && it[idKey] != null;
+            if (inserting && !named) {
+                // Nothing named the key, so the database is being asked to mint one.
+                this.assertMintableKey(meta, meta.fields[idKey]);
+            }
+            const doc = named ? { [MongoDialect.ID_KEY]: this.toWireId(it[idKey]) } : {};
+            for (const key of filterFieldKeys(meta, it, callbackKey)) {
+                if (key === idKey)
+                    continue;
+                const field = meta.fields[key];
+                doc[this.resolveColumnName(key, field)] = field.references ? this.toWireId(it[key]) : it[key];
+            }
+            return doc;
+        });
     }
     /**
      * Build MongoDB aggregation pipeline stages from a QueryAggregate.

package/dist/mongo/mongodbQuerier.d.ts

@@ -58,13 +58,18 @@ export declare class MongodbQuerier extends AbstractQuerier {
     private settleIds;
     internalInsertMany<E extends Document>(entity: Type<E>, payloads: EntityData<E>[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * `_id` is immutable, so a key the payload names can only be written on the insert branch of an
+     * upsert; in `$set` it would refuse every matched document. Everything else updates either way.
+     */
+    private upsertUpdate;
     private buildConflictFilter;
-    upsertOne<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<{
-        firstId: string;
+    protected internalUpsertOne<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<{
+        firstId: PrimaryKey | undefined;
         changes: number;
         created: boolean;
     }>;
-    upsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<{
+    protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<{
         changes: number;
         ids?: undefined;
         firstId?: undefined;

package/dist/mongo/mongodbQuerier.js

@@ -81,7 +81,11 @@ export class MongodbQuerier extends AbstractQuerier {
      */
     async internalFindManyPerParent(entity, q, { joins, parents }) {
         const queries = parents.map((parent) => queryChildrenOf(q, joins, parent));
-        // A vector sort needs a pipeline of its own shape, which only `internalFindMany` builds.
+        // A vector sort is not a degraded fallback here, it is the only expressible form: `$vectorSearch`
+        // has to be the first stage of a pipeline, so it cannot be one of N `$unionWith` branches. Read a
+        // parent at a time it stays correct, because `buildVectorSearchStage` passes the query's `$where`
+        // - which carries this parent's key - into the search as its filter, so each parent gets its own
+        // nearest rather than a share of the collection's.
         if (this.dialect.extractVectorSort(q.$sort)) {
             return this.readEachInTurn(entity, queries);
         }
@@ -264,7 +268,7 @@ export class MongodbQuerier extends AbstractQuerier {
             const meta = getMeta(entity);
             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 ids = Object.values(insertedIds).map((id) => this.dialect.fromWireId(id));
             const idKey = soleIdOf(meta, 'insert');
             for (const [index, it] of payloads.entries()) {
                 it[idKey] = ids[index];
@@ -282,7 +286,7 @@ export class MongodbQuerier extends AbstractQuerier {
             // relation condition has nowhere to go, and MongoDB takes no page on a write, so a paged one
             // has to name the rows it picked rather than touching every match.
             const where = this.dialect.constrainsRelations(entity, qm.$where) || isPagedQuery(qm)
-                ? { _id: { $in: await this.settleIds(entity, qm, opts) } }
+                ? { _id: { $in: this.dialect.toWireId(await this.settleIds(entity, qm, opts)) } }
                 : this.dialect.where(entity, qm.$where, opts);
             // Maps JSON operators ($set/$unset/$push/$pull) onto their native MongoDB equivalents.
             const update = this.dialect.getUpdateFilter(persistable);
@@ -293,6 +297,21 @@ export class MongodbQuerier extends AbstractQuerier {
             return matchedCount;
         });
     }
+    /**
+     * `_id` is immutable, so a key the payload names can only be written on the insert branch of an
+     * upsert; in `$set` it would refuse every matched document. Everything else updates either way.
+     */
+    upsertUpdate(persistable) {
+        const { _id, ...rest } = persistable;
+        const update = {};
+        if (hasKeys(rest)) {
+            update['$set'] = rest;
+        }
+        if (_id !== undefined) {
+            update['$setOnInsert'] = { _id };
+        }
+        return update;
+    }
     buildConflictFilter(entity, conflictPaths, item) {
         const where = getKeys(conflictPaths).reduce((acc, key) => {
             acc[key] = item[key];
@@ -300,26 +319,26 @@ export class MongodbQuerier extends AbstractQuerier {
         }, {});
         return this.dialect.where(entity, where);
     }
-    async upsertOne(entity, conflictPaths, payload) {
+    async internalUpsertOne(entity, conflictPaths, payload) {
         return this.timed('upsertOne', undefined, async () => {
             payload = clone(payload);
             const meta = getMeta(entity);
             const persistable = this.dialect.getPersistable(meta, payload, 'onInsert');
             const filter = this.buildConflictFilter(entity, conflictPaths, payload);
-            const update = { $set: persistable };
+            const update = this.upsertUpdate(persistable);
             const res = await this.execute((session) => this.collection(entity).findOneAndUpdate(filter, update, {
                 upsert: true,
                 returnDocument: 'after',
                 includeResultMetadata: true,
                 session,
             }));
-            const firstId = res?.value?._id;
+            const firstId = this.dialect.fromWireId(res?.value?._id);
             // `updatedExisting` is false when a new document was inserted (upserted).
             const created = res?.lastErrorObject?.['updatedExisting'] === false;
             return { firstId, changes: firstId ? 1 : 0, created };
         });
     }
-    async upsertMany(entity, conflictPaths, payload) {
+    async internalUpsertMany(entity, conflictPaths, payload) {
         return this.timed('upsertMany', undefined, async () => {
             if (!payload?.length) {
                 return { changes: 0 };
@@ -329,7 +348,7 @@ export class MongodbQuerier extends AbstractQuerier {
             const operations = payload.map((item) => {
                 const persistable = this.dialect.getPersistable(meta, item, 'onInsert');
                 const filter = this.buildConflictFilter(entity, conflictPaths, item);
-                const update = { $set: persistable };
+                const update = this.upsertUpdate(persistable);
                 return {
                     updateOne: {
                         filter,
@@ -344,7 +363,7 @@ export class MongodbQuerier extends AbstractQuerier {
             // updated document's `_id` isn't in the response, so it's simply not represented here - same
             // "exact where knowable, absent otherwise" convention `RETURNING`-based SQL dialects use for
             // rows that hit `DO NOTHING`.
-            const ids = Object.values(res.upsertedIds);
+            const ids = Object.values(res.upsertedIds).map((id) => this.dialect.fromWireId(id));
             return { changes, ids, firstId: ids[0] };
         });
     }
@@ -366,13 +385,13 @@ export class MongodbQuerier extends AbstractQuerier {
                 // Stamp the mapped column: reads filter on it, so a `@Field({ name })` mismatch here would
                 // report a successful delete and leave the row visible.
                 const softDeleteColumn = this.dialect.resolveColumnName(meta.softDelete, field);
-                const updateResult = await this.execute((session) => this.collection(entity).updateMany({ _id: { $in: ids } }, { $set: { [softDeleteColumn]: getSoftDeleteValue(field) } }, {
+                const updateResult = await this.execute((session) => this.collection(entity).updateMany({ _id: { $in: this.dialect.toWireId(ids) } }, { $set: { [softDeleteColumn]: getSoftDeleteValue(field) } }, {
                     session,
                 }));
                 changes = updateResult.matchedCount;
             }
             else {
-                const deleteResult = await this.execute((session) => this.collection(entity).deleteMany({ _id: { $in: ids } }, { session }));
+                const deleteResult = await this.execute((session) => this.collection(entity).deleteMany({ _id: { $in: this.dialect.toWireId(ids) } }, { session }));
                 changes = deleteResult.deletedCount;
             }
             await this.deleteRelations(entity, ids, opts);

package/dist/querier/abstractQuerier.d.ts

@@ -119,8 +119,16 @@ export declare abstract class AbstractQuerier implements Querier {
     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: 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>;
+    /**
+     * `beforeUpsert`/`afterUpsert` rather than the insert's or the update's pair: the database decides
+     * which branch each row takes as the statement runs, so neither of those could be fired honestly -
+     * but the upsert itself is a fact known before and after, and a row written with no hook at all
+     * was how an `@Id({ onInsert })` or an audit trail silently skipped this path.
+     */
+    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>;
+    protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     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
@@ -140,8 +148,24 @@ 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> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
+    /**
+     * Insert or update, as the name has always promised - and now as one statement per kind rather
+     * than a guess.
+     *
+     * Whether a row names its key decides which statement it takes, never whether the row exists: an
+     * id the caller invented is not proof of anything, and a stale one used to issue an `UPDATE` that
+     * matched nothing and reported success. A named row upserts on its own key, so it is written
+     * either way and no read can go stale between deciding and writing. An unnamed one inserts, and
+     * the database assigns the key.
+     *
+     * A composite key is always supplied by the caller, so it always takes the upsert branch - which
+     * is why nothing here special-cases one, and why this is the method that stopped refusing them.
+     *
+     * The hooks follow the statement: a named row fires `beforeUpsert`/`afterUpsert`, never the
+     * update pair, because the database picks the branch as the statement runs.
+     */
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
@@ -196,6 +220,11 @@ export declare abstract class AbstractQuerier implements Querier {
      * Emit a lifecycle hook event for the given entity.
      * Fires global listeners first, then entity-level hooks.
      */
+    /**
+     * Runs `write` between the event's `before`/`after` pair. Every hooked write is this shape, and
+     * each one spelled out was a place the pair could drift - `upsert` had none at all for a release.
+     */
+    private hooked;
     private emitHook;
     /**
      * Runs `task` after everything already queued on this querier, one at a time.