@spinajs/orm 2.0.481 → 2.0.484

package/lib/mjs/model.js

@@ -6,11 +6,14 @@ import { ModelHydrator } from './hydrators.js';
 import { OrmException } from './exceptions.js';
 import { StandardModelDehydrator, StandardModelWithRelationsDehydrator } from './dehydrators.js';
 import { SingleRelation } from './relation-objects.js';
-import { DI, isConstructor, isClass } from '@spinajs/di';
+import { createSnapshot, snapshotEquals, snapshotValue } from './snapshot.js';
+import { UnitOfWork } from './unit-of-work.js';
+import { DI, isConstructor, isClass, getInheritedDescriptor } from '@spinajs/di';
 import { DateTime } from 'luxon';
 import _ from 'lodash';
 import { v4 as uuidv4 } from 'uuid';
-import { extractModelDescriptor } from './descriptor.js';
+import { extractModelDescriptor, createDefaultModelDescriptor } from './descriptor.js';
+import { assertAssignedKeys, generateClientSideKeys, hasPk, isCompositePk, orderByPk, pkColumns, pkGeneration, pkValueOf, setPkValue, whereAnyPk, wherePk } from './primary-keys.js';
 const MODEL_PROXY_HANDLER = {
     set: (target, p, value) => {
         if (target[p] !== value) {
@@ -37,8 +40,16 @@ export function updateModelDescriptor(targetOrForward, callback) {
     if (!target) {
         return;
     }
-    const metadata = Reflect.getMetadata(MODEL_DESCTRIPTION_SYMBOL, target);
-    callback(metadata[target.name]);
+    // Must go through getInheritedDescriptor like every other write of this
+    // symbol - it hands back the class's OWN descriptor, so mutating it here
+    // cannot leak into the base class ( eg. assigning the driver to a subclass )
+    const descriptor = getInheritedDescriptor(target, MODEL_DESCTRIPTION_SYMBOL, createDefaultModelDescriptor);
+    // Name is this class's own, never inherited from the base. Matters when this
+    // is the FIRST access for the class: the descriptor is created by collapsing
+    // the chain, and the merger keeps the ancestor's non-empty Name over the
+    // default '' ( eg. a subclass would be stored under its parent's name )
+    descriptor.Name = target.name;
+    callback(descriptor);
 }
 export class ModelBase {
     /**
@@ -73,24 +84,41 @@ export class ModelBase {
         }
         return this._container;
     }
+    /**
+     * Primary key column names of this model. One element for the common single-column case.
+     */
     get PrimaryKeyName() {
         return this.ModelDescriptor.PrimaryKey;
     }
+    /**
+     * Primary key value: a scalar for a single-column key, a tuple in key order for a composite key.
+     */
     get PrimaryKeyValue() {
-        return this[this.PrimaryKeyName];
+        return pkValueOf(this, this.ModelDescriptor);
     }
+    /**
+     * Accepts a scalar for a single-column key, and an array in key order or an object keyed by
+     * column name for a composite key. Cascades the new value into loaded relations exactly as
+     * before, using the single-column relation key ( relations join on one column pair ).
+     */
     set PrimaryKeyValue(newVal) {
-        this[this.PrimaryKeyName] = newVal;
+        setPkValue(this, this.ModelDescriptor, newVal);
         this.ModelDescriptor.Relations.forEach((r) => {
             const rel = this[r.Name];
             if (!rel)
                 return;
+            // A relation's ForeignKey names ONE column, so it can only carry a single-column key.
+            // Cascading a composite parent key into children is not expressible and is skipped.
+            if (isCompositePk(this.ModelDescriptor)) {
+                return;
+            }
+            const scalar = pkValueOf(this, this.ModelDescriptor);
             switch (r.Type) {
                 case RelationType.One:
-                    rel[r.ForeignKey] = newVal;
+                    rel[r.ForeignKey] = scalar;
                     break;
                 case RelationType.Many:
-                    rel.forEach((rVal) => (rVal[r.ForeignKey] = newVal));
+                    rel.forEach((rVal) => (rVal[r.ForeignKey] = scalar));
                     break;
                 case RelationType.ManyToMany:
                     // TODO: rethink this
@@ -98,6 +126,122 @@ export class ModelBase {
             }
         });
     }
+    /**
+     * The diff baseline for this instance, or `null` when it has never been hydrated from
+     * the database. Read-only from the outside: mutate it only through `takeSnapshot()`,
+     * `snapshotRelation()` and `clearSnapshot()`.
+     */
+    get Snapshot() {
+        return this.__snapshot__;
+    }
+    /**
+     * Captures the current value of every column as the diff baseline, discarding any
+     * previous baseline and any relation keys recorded against it.
+     *
+     * Values are copied, never aliased — see `snapshotValue`. An aliased snapshot makes
+     * every diff empty and `save()` a silent no-op.
+     */
+    takeSnapshot() {
+        const snapshot = createSnapshot();
+        for (const c of this.ModelDescriptor?.Columns ?? []) {
+            snapshot.Columns.set(c.Name, snapshotValue(this[c.Name], c.Converter));
+        }
+        this.__snapshot__ = snapshot;
+    }
+    /**
+     * Records the primary keys of the members currently in relation `name` as that
+     * relation's baseline. A no-op when the model has no snapshot — an unhydrated model
+     * has nothing to diff against and its relations are all "new".
+     *
+     * @param name - relation property name, as declared on the model descriptor
+     */
+    snapshotRelation(name) {
+        if (!this.__snapshot__) {
+            return;
+        }
+        const relation = this[name];
+        if (relation === null || relation === undefined) {
+            return;
+        }
+        if (relation instanceof SingleRelation) {
+            const value = relation.Value;
+            this.__snapshot__.Relations.set(name, value ? [value.PrimaryKeyValue] : []);
+            return;
+        }
+        if (typeof relation[Symbol.iterator] === 'function') {
+            this.__snapshot__.Relations.set(name, [...relation].map((m) => m.PrimaryKeyValue));
+        }
+    }
+    /**
+     * Discards the diff baseline. After this the model is treated as brand new by `save()`.
+     */
+    clearSnapshot() {
+        this.__snapshot__ = null;
+    }
+    /**
+     * Names of the columns whose current value differs from the snapshot.
+     *
+     * With no snapshot every column is reported as changed, which is the right answer for a
+     * model that is about to be inserted.
+     *
+     * This is deliberately independent of `__dirty_props__`: the proxy records a property as
+     * dirty on any write, including one that puts the original value back, so the snapshot
+     * diff is the more precise answer and the one the UPDATE payload is built from.
+     */
+    changedColumns() {
+        const columns = this.ModelDescriptor?.Columns ?? [];
+        if (!this.__snapshot__) {
+            return columns.map((c) => c.Name);
+        }
+        const snapshot = this.__snapshot__;
+        return columns.filter((c) => !snapshotEquals(snapshot.Columns.get(c.Name), this[c.Name], c.Converter)).map((c) => c.Name);
+    }
+    /**
+     * Foreign-key columns a relation object reported as rewritten, via {@link markDirty}.
+     *
+     * These are the only columns the snapshot diff cannot see. `SingleRelation.attach()` stores
+     * the new target on the relation wrapper and marks the foreign key dirty, but never writes
+     * the column on the model — the value is materialised from the relation later, by
+     * `StandardModelToSqlConverter`. So `changedColumns()` compares the column against its
+     * snapshot, finds it untouched, and reports no change even though the relation was
+     * re-pointed. Detaching a relation and calling `update()` would then emit nothing at all.
+     *
+     * Restricted to declared relation foreign keys on purpose. `__dirty_props__` also collects
+     * ordinary property writes, and folding those in wholesale would undo the precision the
+     * diff exists for: a column written A -> B -> A is in `__dirty_props__` but has no net
+     * change, and must not be written back.
+     */
+    relationDirtyColumns() {
+        const descriptor = this.ModelDescriptor;
+        if (!descriptor) {
+            return [];
+        }
+        const relationKeys = new Set();
+        for (const [, relation] of descriptor.Relations) {
+            if (relation.ForeignKey) {
+                relationKeys.add(relation.ForeignKey);
+            }
+        }
+        return this.__dirty_props__.filter((p) => relationKeys.has(p));
+    }
+    /**
+     * Records `prop` as changed and marks the model dirty.
+     *
+     * This is the supported way for relation objects to report that they rewrote one of the
+     * owner's foreign keys. It replaces the `(owner as any).__dirty_props__.push(...)` casts
+     * that reached into a private field from outside the class ( A6 ).
+     *
+     * The push comes before `IsDirty = true` so the method stays correct even if the
+     * `IsDirty` setter ever starts clearing `__dirty_props__` on a truthy assignment too.
+     *
+     * @param prop - column name
+     */
+    markDirty(prop) {
+        if (!this.__dirty_props__.includes(prop)) {
+            this.__dirty_props__.push(prop);
+        }
+        this.IsDirty = true;
+    }
     valueOf() {
         return this.PrimaryKeyValue;
     }
@@ -274,6 +418,11 @@ export class ModelBase {
     static whereNotExists(_qOrR, _func) {
         throw new Error('Not implemented');
     }
+    /**
+     * Runs `_callback` inside a transaction on this model's connection. The transaction commits
+     * when the callback resolves and rolls back when it throws — see `OrmDriver.transaction`.
+     * Resolves with whatever the callback returned.
+     */
     static transaction(_callback) {
         throw new Error('Not implemented');
     }
@@ -283,6 +432,13 @@ export class ModelBase {
          * prop to track model props that changeded since last update
          */
         this.__dirty_props__ = [];
+        /**
+         * Diff baseline, captured when this instance was hydrated from a database row.
+         * `null` means "this model has never been in the database", which is what `save()`
+         * uses to classify it as an INSERT — not the presence of a primary key, because
+         * `setDefaults()` pre-fills @Uuid keys on construction.
+         */
+        this.__snapshot__ = null;
         /**
          * List of hidden properties from JSON / dehydrations
          * eg. password field of user
@@ -311,26 +467,36 @@ export class ModelBase {
     attach(data) {
         // TODO: refactor this, to not check every time for relation
         // do this as map or smth
-        for (const [_, v] of this.ModelDescriptor.Relations.entries()) {
-            if (v.TargetModel.name === data.constructor.name) {
-                // TODO: refactor this, so we dont update foreign key
-                // instead we must use belongsTo relation on data model to update
-                //(data as any)[v.ForeignKey] = this.PrimaryKeyValue;
-                switch (v.Type) {
-                    case RelationType.One:
-                        this[v.Name].attach(data);
-                        this.__dirty_props__.push(v.ForeignKey);
-                        break;
-                    case RelationType.Many:
-                        // attach to related model too
-                        const rel = [...data.ModelDescriptor.Relations.entries()].find((e) => e[1].ForeignKey === v.ForeignKey);
-                        if (rel) {
-                            data[rel[0]].Value = this;
-                        }
-                    case RelationType.ManyToMany:
-                        this[v.Name].push(data);
-                        break;
+        for (const [, v] of this.ModelDescriptor.Relations.entries()) {
+            // Constructor identity, not class name. Name matching pushed the row into *every*
+            // relation whose target happened to share a name, so a model with two relations to
+            // the same target received it twice ( B26 ), and it breaks under minification ( A9 ).
+            if (v.TargetModel !== data.constructor) {
+                continue;
+            }
+            switch (v.Type) {
+                case RelationType.One:
+                    this[v.Name].attach(data);
+                    this.markDirty(v.ForeignKey);
+                    break;
+                case RelationType.Many: {
+                    // Set the child's back-reference to this owner, when the child declares one.
+                    const rel = [...data.ModelDescriptor.Relations.entries()].find((e) => e[1].ForeignKey === v.ForeignKey);
+                    if (rel) {
+                        data[rel[0]].Value = this;
+                    }
+                    this[v.Name].push(data);
+                    break;
                 }
+                case RelationType.ManyToMany:
+                    // No back-reference: the link lives in the junction table, not on the target row.
+                    // The `push` is written out again rather than shared with the Many case above —
+                    // the two are only coincidentally similar, and the missing `break` that used to
+                    // join them was one reordering away from silently breaking.
+                    this[v.Name].push(data);
+                    break;
+                default:
+                    break;
             }
         }
         this.IsDirty = true;
@@ -367,10 +533,14 @@ export class ModelBase {
      * deletes enitt from db. If model have SoftDelete decorator, model is marked as deleted
      */
     async destroy() {
-        if (!this.PrimaryKeyValue) {
+        // A composite key is a tuple, and a tuple is ALWAYS truthy - so the old `!pk` guard
+        // would happily issue a DELETE for a model whose key columns are still unset.
+        const pk = this.PrimaryKeyValue;
+        const missing = Array.isArray(pk) ? pk.some((v) => v === null || v === undefined) : !pk;
+        if (missing) {
             return;
         }
-        const result = await this.constructor.destroy(this.PrimaryKeyValue);
+        const result = await this.constructor.destroy(pk);
         this.IsDirty = false;
         return result;
     }
@@ -385,33 +555,64 @@ export class ModelBase {
             throw new OrmException('archived at column not exists in model');
         }
         const { query } = this.createUpdateQuery();
-        return await query.update(this.toSql()).where(this.PrimaryKeyName, this.PrimaryKeyValue);
+        query.update(this.toSql());
+        wherePk(query, this.ModelDescriptor, this.PrimaryKeyValue);
+        return await query;
     }
+    /**
+     * Writes the columns that differ from the snapshot.
+     *
+     * The change set comes from `changedColumns()` — the snapshot diff — and not from the
+     * proxy's `__dirty_props__`, which records a property as dirty on ANY write including one
+     * that puts the original value straight back. `save()` has always used the diff, and
+     * `changedColumns()` documents it as the more precise answer; this path used the imprecise
+     * one, so the same edit produced a different UPDATE depending on which method you called.
+     *
+     * A model with no snapshot ( never hydrated ) reports every column as changed, which is the
+     * right answer: there is no baseline to be more precise than.
+     *
+     * @param data - optional patch hydrated onto the model first
+     */
     async update(data) {
-        const { query } = this.createUpdateQuery();
-        let result = {
+        const result = {
             RowsAffected: 0,
             LastInsertId: 0,
         };
         if (data) {
             this.hydrate(data);
         }
-        // if no changes, return without update
-        if (this.IsDirty === false) {
+        const keyColumns = this.ModelDescriptor.PrimaryKey ?? [];
+        const changed = _.union(this.changedColumns(), this.relationDirtyColumns()).filter((c) => !keyColumns.includes(c));
+        // Nothing to write. Checked against the diff, so re-assigning a column its current value
+        // no longer produces an UPDATE that sets it to what it already was.
+        if (changed.length === 0) {
+            this.IsDirty = false;
             return result;
         }
-        if (this.ModelDescriptor.Timestamps.UpdatedAt) {
-            this[this.ModelDescriptor.Timestamps.UpdatedAt] = DateTime.now();
+        const updatedAt = this.ModelDescriptor.Timestamps.UpdatedAt;
+        if (updatedAt) {
+            this[updatedAt] = DateTime.now();
+            if (!changed.includes(updatedAt)) {
+                changed.push(updatedAt);
+            }
         }
-        result = await query.update(this.toSql(true)).where(this.PrimaryKeyName, this.PrimaryKeyValue);
+        const { query } = this.createUpdateQuery();
+        query.update(_.pick(this.toSql(), changed));
+        wherePk(query, this.ModelDescriptor, this.PrimaryKeyValue);
+        const updateResult = await query;
         this.IsDirty = false;
-        return result;
+        this.takeSnapshot();
+        return updateResult;
     }
     /**
      * Save all changes to db. It creates new entry id db or updates existing one if
      * primary key exists
      */
     async insert(insertBehaviour = InsertBehaviour.None) {
+        // Both run BEFORE the query is built, so an `assigned` key that was never supplied fails
+        // without touching the database.
+        generateClientSideKeys(this, this.ModelDescriptor);
+        assertAssignedKeys(this, this.ModelDescriptor);
         const { query, description } = this.createInsertQuery();
         const sResponseMapper = query.Container.resolve(ServerResponseMapper);
         switch (insertBehaviour) {
@@ -425,14 +626,27 @@ export class ModelBase {
                 query.orReplace();
                 break;
         }
+        // Only an `auto` key needs the database to tell us what it became. Asking for RETURNING
+        // where the dialect supports it beats reading an identity counter, and is the shape
+        // orm-uow needs to backfill cascaded children.
+        const needsKeyBack = pkColumns(description).some((c) => pkGeneration(description, c) === 'auto');
+        if (needsKeyBack && insertBehaviour !== InsertBehaviour.InsertOrUpdate && query.Driver.supportedFeatures().insertReturning) {
+            query.returning(pkColumns(description));
+        }
         query.middleware({
             afterQuery: (data) => {
-                const response = sResponseMapper.read(data, this.PrimaryKeyName);
-                // if already exists do not overwrite
-                // sometimes we have models with primary key as string etc
-                // and not autoincrement
-                if (!this.PrimaryKeyValue) {
-                    this.PrimaryKeyValue = response.LastInsertId;
+                const response = sResponseMapper.read(data, pkColumns(description));
+                if ((response.Returning ?? []).length !== 0) {
+                    setPkValue(this, description, pkValueOf(response.Returning[0], description));
+                }
+                else if (needsKeyBack) {
+                    // Do not overwrite a key the caller already supplied ( uuid / assigned strategies ).
+                    // Same tuple-truthiness trap as destroy().
+                    const current = this.PrimaryKeyValue;
+                    const missing = Array.isArray(current) ? current.some((v) => v === null || v === undefined) : !current;
+                    if (missing) {
+                        this.PrimaryKeyValue = response.LastInsertId;
+                    }
                 }
                 return data;
             },
@@ -456,6 +670,26 @@ export class ModelBase {
         }
         return await this.insert();
     }
+    /**
+     * Persists this model and everything reachable from it in one transaction.
+     *
+     * The graph is diffed against the snapshots taken when it was loaded, sorted so that a
+     * parent is inserted before any child that references it, and executed as inserts, then
+     * updates restricted to the columns that actually changed, then junction rows, then the
+     * orphan policy of every relation that lost a member.
+     *
+     * A relation that was never populated is invisible: `Items: OrderItem[] = []` on a freshly
+     * constructed model deletes nothing. That is the deliberate divergence from TypeORM.
+     *
+     * @param options - `{ reload: true }` to diff against current database state instead of the
+     *                  hydration snapshot; `{ chunk: n }` to bound batched statement size.
+     */
+    async save(options) {
+        // `UnitOfWork` is referenced only inside this body, never at module-evaluation time, so
+        // the model.ts -> unit-of-work.ts -> ... -> model.ts cycle stays safe under ESM. Do not
+        // move this into a field initializer or an extends clause.
+        return await UnitOfWork.save(this, options);
+    }
     /**
      * Gets model data from database and returns as fresh instance.
      *
@@ -482,6 +716,7 @@ export class ModelBase {
         for (const c of this.ModelDescriptor.Columns) {
             this[c.Name] = model[c.Name];
         }
+        this.IsDirty = false;
     }
     toJSON() {
         return this.dehydrate();
@@ -498,6 +733,9 @@ export class ModelBase {
                 this[c.Name] = c.DefaultValue;
             }
         });
+        // `uuid` primary keys are generated at construction so the value is available to callers
+        // and to cascaded children before the row ever reaches the database.
+        generateClientSideKeys(this, this.ModelDescriptor);
         if (this.ModelDescriptor.Timestamps.CreatedAt) {
             this[this.ModelDescriptor.Timestamps.CreatedAt] = DateTime.now();
         }
@@ -531,9 +769,60 @@ export class ModelBase {
         return createQuery(this.constructor, InsertQueryBuilder);
     }
 }
+/**
+ * Decides whether a multi-row insert's generated keys can be read off `LastInsertId + index` on a
+ * dialect that has no RETURNING.
+ *
+ * The premise is a documented MySQL guarantee, not a guess. InnoDB splits inserts into *simple*
+ * ones — row count known before execution, which is exactly what `INSERT INTO t (…) VALUES (…),
+ * (…)` is, and the only shape {@link InsertQueryBuilder} can build — and *bulk* ones
+ * (`INSERT … SELECT`), where it is not. For a simple insert InnoDB reserves one contiguous block
+ * of N auto-increment values under a short mutex it releases immediately, so the k-th row of the
+ * statement gets `LAST_INSERT_ID() + k`. This holds under `innodb_autoinc_lock_mode = 2`, the
+ * MySQL 8 default, and was verified against a live server. The "values may not be contiguous"
+ * caveat in the MySQL manual is about bulk inserts and about mixed-mode inserts.
+ *
+ * The guards below rule out every case where the mapping stops being positional.
+ */
+function _canBackfillContiguousKeys(description, rows, response, features, insertBehaviour) {
+    // Only a dialect whose reported id is the FIRST of the block can be walked forwards. MSSQL's
+    // SCOPE_IDENTITY() and SQLite's last_insert_rowid() report the LAST one.
+    if (!features.insertIdIsFirstOfBatch) {
+        return false;
+    }
+    // One database-generated identity column, or there is no counter to walk. A composite key has
+    // no single identity column, and uuid / assigned keys are already set by this point.
+    const keys = pkColumns(description);
+    if (keys.length !== 1 || pkGeneration(description, keys[0]) !== 'auto') {
+        return false;
+    }
+    // INSERT IGNORE / REPLACE / ON DUPLICATE KEY UPDATE are mixed-mode: rows can be skipped,
+    // replaced or updated rather than inserted, so the k-th allocated id stops belonging to the
+    // k-th input row. ( The array path rejects these outright today; this keeps the invariant
+    // local to the decision rather than depending on a check three hundred lines away. )
+    if (insertBehaviour !== InsertBehaviour.None) {
+        return false;
+    }
+    // No identity value reported at all.
+    if (typeof response.LastInsertId !== 'number' || !Number.isFinite(response.LastInsertId) || response.LastInsertId <= 0) {
+        return false;
+    }
+    // The server must confirm it inserted exactly one row per row we sent. Anything else means
+    // rows were skipped or the statement did something other than a plain multi-row insert.
+    if (response.RowsAffected !== rows.length) {
+        return false;
+    }
+    // A batch where SOME rows carry an explicit key is a mixed-mode insert: InnoDB allocates
+    // auto-increment values only for the rows that omitted one, so index arithmetic would both
+    // mis-key the generated rows and overwrite the supplied ones.
+    return rows.every((v) => v instanceof ModelBase && (v.PrimaryKeyValue === null || v.PrimaryKeyValue === undefined));
+}
 function _preparePkWhere(description, query, model) {
-    if (description.PrimaryKey) {
-        query.where(description.PrimaryKey, model.PrimaryKeyValue);
+    // NOTE: `if (description.PrimaryKey)` used to be false for the '' default. An empty ARRAY is
+    // truthy, so this must be an explicit length check or no-primary-key models would stop
+    // falling back to their unique columns.
+    if (hasPk(description)) {
+        wherePk(query, description, model.PrimaryKeyValue);
     }
     else {
         const unique = description.Columns.filter((x) => x.Unique);
@@ -548,20 +837,20 @@ function _preparePkWhere(description, query, model) {
     }
 }
 function _prepareOrderBy(description, query, order) {
-    if (description.PrimaryKey) {
-        query.order(description.PrimaryKey, order ?? SortOrder.DESC);
+    // orderByPk emits one ORDER BY term per key column and reports whether the model has a
+    // primary key at all - see the note in _preparePkWhere on why a length check is required.
+    if (orderByPk(query, description, order ?? SortOrder.DESC)) {
+        return;
     }
-    else {
-        const unique = description.Columns.filter((c) => c.Unique);
-        if (unique.length !== 0) {
-            unique.forEach((c) => query.order(c.Name, order ?? SortOrder.DESC));
-        }
-        else if (description.Timestamps?.CreatedAt) {
-            query.order(description.Timestamps.CreatedAt, order ?? SortOrder.DESC);
-        }
-        else if (description.Timestamps?.UpdatedAt) {
-            query.order(description.Timestamps.UpdatedAt, order ?? SortOrder.DESC);
-        }
+    const unique = description.Columns.filter((c) => c.Unique);
+    if (unique.length !== 0) {
+        unique.forEach((c) => query.order(c.Name, order ?? SortOrder.DESC));
+    }
+    else if (description.Timestamps?.CreatedAt) {
+        query.order(description.Timestamps.CreatedAt, order ?? SortOrder.DESC);
+    }
+    else if (description.Timestamps?.UpdatedAt) {
+        query.order(description.Timestamps.UpdatedAt, order ?? SortOrder.DESC);
     }
 }
 export class HistoricalModel {
@@ -601,6 +890,8 @@ export const MODEL_STATIC_MIXINS = {
         }
         return driver;
     },
+    // Every branch now returns a builder or throws, so the `| undefined` is gone — it only ever
+    // described the unimplemented ManyToMany case. This matches ModelBase.populate's static stub.
     populate(relation, owner) {
         //TODO: fix cast
         const modelDescriptor = this.getModelDescriptor();
@@ -621,7 +912,7 @@ export const MODEL_STATIC_MIXINS = {
             async afterHydration(_relationData) { },
         };
         switch (relationDescriptor.Type) {
-            case RelationType.One:
+            case RelationType.One: {
                 const { query: JoinQuery } = createQuery(relationDescriptor.SourceModel, SelectQueryBuilder);
                 // NOTE: we could use simple right join, but we use LEFT JOIN
                 // becouse sqlite does not support right join
@@ -631,19 +922,52 @@ export const MODEL_STATIC_MIXINS = {
                     joinModel: relationDescriptor.TargetModel,
                     queryCallback: function () {
                         this.select(new RawQuery(`\`${this.TableAlias}\`.*`));
-                    }
+                    },
+                    // Both were omitted, so the join compiled to `$source$.undefined`. A belongsTo
+                    // joins the owner's ForeignKey to the target's PrimaryKey — the same derivation
+                    // SelectQueryBuilder uses for RelationType.One.
+                    sourceTablePrimaryKey: relationDescriptor.ForeignKey,
+                    joinTableForeignKey: relationDescriptor.PrimaryKey,
                 });
-                JoinQuery.where(relationDescriptor.SourceModel.getModelDescriptor().PrimaryKey, owner);
+                // `wherePk`, not `where(descriptor.PrimaryKey, ...)`: PrimaryKey is a string[] since
+                // composite keys landed, and passing the array as a column name compiled to
+                // `column 0 not exists in model ...`.
+                wherePk(JoinQuery, relationDescriptor.SourceModel.getModelDescriptor(), owner instanceof ModelBase ? owner.PrimaryKeyValue : owner);
                 JoinQuery.middleware(hydrateMiddleware);
                 return JoinQuery;
-            case RelationType.ManyToMany:
-                break;
+            }
+            case RelationType.ManyToMany: {
+                // Was a bare `break`, so this returned undefined and every caller crashed on the
+                // result. Read the junction table, join the target, and project the target's columns
+                // — the same shape ManyToManyRelation.compile() builds. A sub-query would be more
+                // direct but `whereIn` takes value arrays only.
+                if (!relationDescriptor.JunctionModel) {
+                    throw new OrmException(`relation ${relation} on ${modelDescriptor.Name} has no junction model`);
+                }
+                const { query: junctionQuery } = createQuery(relationDescriptor.JunctionModel, SelectQueryBuilder);
+                junctionQuery.clearColumns();
+                junctionQuery.leftJoin({
+                    joinModel: relationDescriptor.TargetModel,
+                    queryCallback: function () {
+                        this.select(new RawQuery(`\`${this.TableAlias}\`.*`));
+                    },
+                    sourceTablePrimaryKey: relationDescriptor.JunctionModelTargetModelFKey_Name,
+                    joinTableForeignKey: relationDescriptor.ForeignKey,
+                });
+                junctionQuery.where(relationDescriptor.JunctionModelSourceModelFKey_Name, owner instanceof ModelBase ? owner.PrimaryKeyValue : owner);
+                junctionQuery.middleware(hydrateMiddleware);
+                return junctionQuery;
+            }
+            case RelationType.Virtual:
             case RelationType.Query:
                 throw new OrmException(`Query population for relation type ${RelationType[relationDescriptor.Type]} is not supported yet`);
-            case RelationType.Many:
+            case RelationType.Many: {
                 const { query } = createQuery(relationDescriptor.TargetModel, SelectQueryBuilder);
                 query.where(relationDescriptor.ForeignKey, owner instanceof ModelBase ? owner.PrimaryKeyValue : owner);
                 return query;
+            }
+            default:
+                throw new OrmException(`unknown relation type ${relationDescriptor.Type} for relation ${relation} on ${modelDescriptor.Name}`);
         }
     },
     query() {
@@ -689,6 +1013,12 @@ export const MODEL_STATIC_MIXINS = {
             if (insertBehaviour !== InsertBehaviour.None) {
                 throw new OrmException(`insert behaviour is not supported with arrays`);
             }
+            // Run the key strategies over every element BEFORE any SQL is built, so a missing
+            // `assigned` key fails with a clear message instead of a NOT NULL violation.
+            data.forEach((d) => {
+                generateClientSideKeys(d, description);
+                assertAssignedKeys(d, description);
+            });
             query.values(data.map((d) => {
                 if (d instanceof ModelBase) {
                     return d.toSql();
@@ -708,6 +1038,8 @@ export const MODEL_STATIC_MIXINS = {
                     query.orReplace();
                     break;
             }
+            generateClientSideKeys(data, description);
+            assertAssignedKeys(data, description);
             if (data instanceof ModelBase) {
                 query.values(data.toSql());
             }
@@ -715,19 +1047,40 @@ export const MODEL_STATIC_MIXINS = {
                 query.values(converter.toSql(data, description));
             }
         }
+        const autoKey = pkColumns(description).some((c) => pkGeneration(description, c) === 'auto');
+        if (autoKey && query.Driver.supportedFeatures().insertReturning) {
+            query.returning(pkColumns(description));
+        }
         const iMidleware = {
             afterQuery: (result) => {
-                const response = sResponseMapper.read(result);
-                if (Array.isArray(data)) {
-                    data.forEach((v, idx) => {
+                const response = sResponseMapper.read(result, pkColumns(description));
+                const rows = Array.isArray(data) ? data : [data];
+                if ((response.Returning ?? []).length === rows.length) {
+                    // Authoritative: the database told us every key it assigned, in insert order.
+                    rows.forEach((v, idx) => {
                         if (v instanceof ModelBase) {
-                            v.PrimaryKeyValue = v.PrimaryKeyValue ?? response.LastInsertId + idx;
+                            setPkValue(v, description, pkValueOf(response.Returning[idx], description));
                         }
                     });
                 }
-                else if (data instanceof ModelBase) {
-                    data.PrimaryKeyValue = data.PrimaryKeyValue ?? response.LastInsertId;
+                else if (autoKey && rows.length === 1) {
+                    // One row, one identity value - safe.
+                    const v = rows[0];
+                    if (v instanceof ModelBase && !v.PrimaryKeyValue) {
+                        v.PrimaryKeyValue = response.LastInsertId;
+                    }
+                }
+                else if (_canBackfillContiguousKeys(description, rows, response, query.Driver.supportedFeatures(), insertBehaviour)) {
+                    // Multi-row `INSERT ... VALUES` on a dialect with no RETURNING whose identity value is
+                    // the first of the statement's contiguous block. See _canBackfillContiguousKeys.
+                    rows.forEach((v, idx) => {
+                        v.PrimaryKeyValue = response.LastInsertId + idx;
+                    });
                 }
+                // Anything else — a dialect whose insert id names the last row, a batch that mixed
+                // supplied and generated keys, a statement the server did not insert one row per input
+                // row for — cannot be mapped positionally, so nothing is assigned. Callers needing the
+                // keys there must re-select or insert the models one at a time.
                 return result;
             },
             modelCreation: () => null,
@@ -738,16 +1091,14 @@ export const MODEL_STATIC_MIXINS = {
     },
     async find(pks) {
         const { query, description } = createQuery(this, SelectQueryBuilder);
-        const pkey = description.PrimaryKey;
         query.select('*');
-        query.whereIn(pkey, pks);
+        whereAnyPk(query, description, pks);
         return await query;
     },
     async findOrFail(pks) {
         const { query, description, model } = createQuery(this, SelectQueryBuilder);
-        const pkey = description.PrimaryKey;
         query.select('*');
-        query.whereIn(pkey, pks);
+        whereAnyPk(query, description, pks);
         const result = await query;
         if (result.length !== pks.length) {
             throw new Error(`could not find all results for model ${model.name}`);
@@ -756,22 +1107,23 @@ export const MODEL_STATIC_MIXINS = {
     },
     async get(pk) {
         const { query, description } = createQuery(this, SelectQueryBuilder);
-        const pkey = description.PrimaryKey;
         query.select('*');
-        query.where(pkey, pk);
+        wherePk(query, description, pk);
         _prepareOrderBy(description, query);
         return (await query.first());
     },
     async getOrFail(pk) {
         const { query, description } = createQuery(this, SelectQueryBuilder);
-        const pkey = description.PrimaryKey;
         query.select('*');
-        query.where(pkey, pk);
+        wherePk(query, description, pk);
         _prepareOrderBy(description, query);
         return (await query.firstOrFail());
     },
     destroy(pks) {
         const description = _descriptor(this);
+        if (pks === undefined || pks === null) {
+            throw new OrmException('Cannot destroy without primary keys ( unbounded DELETE/UPDATE ). Use truncate() to clear the whole table.');
+        }
         const data = Array.isArray(pks) ? pks : [pks];
         if (data.length === 0) {
             throw new OrmException('Cannot delete empty array of primary keys');
@@ -783,7 +1135,7 @@ export const MODEL_STATIC_MIXINS = {
             });
         }
         if (pks) {
-            query.whereIn(description.PrimaryKey, data);
+            whereAnyPk(query, description, data);
         }
         return query;
     },
@@ -795,8 +1147,8 @@ export const MODEL_STATIC_MIXINS = {
     async getOrCreate(pk, data) {
         const { query, description } = createQuery(this, SelectQueryBuilder);
         // pk constrain
-        if (description.PrimaryKey && pk !== null) {
-            query.where(description.PrimaryKey, pk);
+        if (hasPk(description) && pk !== null) {
+            wherePk(query, description, pk);
         }
         // check for all unique columns ( unique constrain )
         description.Columns.filter((c) => c.Unique).forEach((c) => {
@@ -825,13 +1177,15 @@ export const MODEL_STATIC_MIXINS = {
         let entity = (await query.first());
         if (!entity) {
             const toHydrate = data ?? {};
-            const primaryKey = description.Columns.find((c) => c.PrimaryKey);
-            // remove primary key from data to hydrate
-            // we dont want to set primary key on new model if not exists
-            // and autoincrement is set
-            if (primaryKey?.AutoIncrement) {
-                delete toHydrate[description.PrimaryKey];
-            }
+            // Do not carry an auto-increment key into a brand new model; the engine assigns it.
+            // Every key column is checked, not just the first, so a composite key with an
+            // auto-increment member is stripped correctly.
+            pkColumns(description).forEach((name) => {
+                const col = description.Columns.find((c) => c.Name === name);
+                if (col?.AutoIncrement) {
+                    delete toHydrate[name];
+                }
+            });
             entity = new (Function.prototype.bind.apply(this))(toHydrate);
             return entity;
         }
@@ -840,10 +1194,12 @@ export const MODEL_STATIC_MIXINS = {
     async exists(pk) {
         const { query, description } = createQuery(this, SelectQueryBuilder);
         // pk constrain
-        if (description.PrimaryKey && pk !== null) {
-            query.where(description.PrimaryKey, pk);
+        if (hasPk(description) && pk !== null) {
+            wherePk(query, description, pk);
         }
-        const result = await query.clearColumns().select(description.PrimaryKey).first();
+        const q = query.clearColumns();
+        pkColumns(description).forEach((c) => q.select(c));
+        const result = await q.first();
         if (result) {
             return true;
         }
@@ -907,7 +1263,8 @@ export const MODEL_STATIC_MIXINS = {
         if (callback) {
             callback(query);
         }
-        return await (await query.asRaw()).count;
+        const row = await query.takeFirst().asRaw();
+        return row?.count ?? 0;
     },
     async transaction(callback) {
         const driver = this.getModelDescriptor();
@@ -915,8 +1272,7 @@ export const MODEL_STATIC_MIXINS = {
     }
 };
 export const _modelProxyFactory = (_c, model) => {
-    const mInstance = new model();
-    return new Proxy(mInstance, MODEL_PROXY_HANDLER);
+    return new model();
 };
 DI.register(_modelProxyFactory).as('__orm_model_factory__');
 //# sourceMappingURL=model.js.map