@spinajs/orm 2.0.481 → 2.0.484

package/lib/mjs/builders.js

@@ -10,7 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var RawQuery_1, WhereBuilder_1, SelectQueryBuilder_1;
 /* eslint-disable prettier/prettier */
 import { Container, Inject, NewInstance, DI, Injectable, isConstructor } from '@spinajs/di';
-import { InvalidArgument, MethodNotImplemented, InvalidOperation } from '@spinajs/exceptions';
+import { InvalidArgument, MethodNotImplemented, InvalidOperation, NotSupported } from '@spinajs/exceptions';
 import { OrmException, OrmNotFoundException } from './exceptions.js';
 import _ from 'lodash';
 import { use } from 'typescript-mix';
@@ -18,9 +18,10 @@ import { ColumnMethods, ColumnType, QueryMethod, SortOrder, WhereBoolean, SqlOpe
 import { DeleteQueryCompiler, InsertQueryCompiler, SelectQueryCompiler, TruncateTableQueryCompiler, TableQueryCompiler, AlterTableQueryCompiler, UpdateQueryCompiler, QueryContext, IndexQueryCompiler, RelationType, ReferentialAction, DefaultValueBuilder, ColumnAlterationType, TableExistsCompiler, DropViewCompiler, DropTableCompiler, TableCloneQueryCompiler, QueryMiddleware, DropEventQueryCompiler, EventQueryCompiler, RawSchemaQueryCompiler } from './interfaces.js';
 import { BetweenStatement, ColumnMethodStatement, ColumnStatement, ExistsQueryStatement, InSetStatement, InStatement, RawQueryStatement, WhereQueryStatement, WhereStatement, ColumnRawStatement, JoinStatement, WithRecursiveStatement, GroupByStatement, Wrap, LazyQueryStatement } from './statements.js';
 import { BelongsToRelation, OneToManyRelation, ManyToManyRelation, BelongsToRecursiveRelation, QueryRelation, VirtualRelation } from './relations.js';
-import { Lazy } from '@spinajs/util';
+import { Lazy, isNullOrWhitespace, _check_arg, _positive } from '@spinajs/util';
 import { DiscriminationMapMiddleware } from './discrimination-middleware.js';
 import { extractModelDescriptor } from './descriptor.js';
+import { ExistsRelationHandler } from './existsRelationHandlers.js';
 function isWhereOperator(val) {
     return _.isString(val) && Object.values(SqlOperator).includes(val.toLowerCase());
 }
@@ -37,6 +38,12 @@ let Builder = class Builder {
     constructor(container, driver, model) {
         this._middlewares = [];
         this._queryMiddlewares = [];
+        /**
+         * Memoized result of {@link execute}. A builder executes at most once; awaiting
+         * it again resolves with the same value instead of re-running the query.
+         * Call `clone()` first if you genuinely need a second round-trip.
+         */
+        this._executionPromise = null;
         this._driver = driver;
         this._container = container;
         this._model = model;
@@ -44,82 +51,104 @@ let Builder = class Builder {
         this._asRaw = false;
         this._queryMiddlewares = DI.resolve(Array.ofType(QueryMiddleware));
     }
-    then(onfulfilled, onrejected) {
-        return this._driver
-            .execute(this)
-            .then((result) => {
-            try {
-                if (this._asRaw) {
-                    onfulfilled?.(result);
-                    return;
-                }
-                let transformedResult = result;
-                // if we have something to transform ...
-                if (transformedResult) {
-                    this._middlewares.forEach((m) => {
-                        Object.assign(transformedResult, m.afterQuery(transformedResult));
-                    });
-                }
-                if (this._model && !this._nonSelect) {
-                    // TODO: rething this casting
-                    const models = transformedResult.map((r) => {
-                        let model = null;
-                        for (const middleware of this._middlewares.reverse()) {
-                            model = middleware.modelCreation(r);
-                            if (model !== null) {
-                                break;
-                            }
-                        }
-                        if (model === null) {
-                            model = DI.resolve('__orm_model_factory__', [this._model]);
-                        }
-                        model.hydrate(r);
-                        model.IsDirty = false;
-                        return model;
-                    });
-                    const afterMiddlewarePromises = this._middlewares.reduce((prev, current) => {
-                        return prev.concat([current.afterHydration(models)]);
-                    }, []);
-                    if (this._middlewares.length > 0) {
-                        Promise.all(afterMiddlewarePromises).then(() => {
-                            try {
-                                onfulfilled?.(models);
-                            }
-                            catch (err) {
-                                if (onrejected) {
-                                    onrejected(err);
-                                }
-                                else {
-                                    throw err;
-                                }
-                            }
-                        }, onrejected);
-                    }
-                    else {
-                        onfulfilled?.(models);
+    /**
+     * The execution engine. Sends the compiled query to the driver, applies the
+     * result middlewares, hydrates models and awaits the post-hydration middlewares.
+     *
+     * Always *returns* its value — the caller's promise chain is what propagates it.
+     * Subclasses override this (not `execute()`) so that their extra work also lands
+     * inside the memo.
+     */
+    async _run() {
+        // Fires for EVERY builder type, not just SELECT. This used to live on
+        // `SelectQueryBuilder._run`, so an INSERT/UPDATE/DELETE never reached a
+        // `beforeQueryExecution` hook at all — which silently disabled any middleware that
+        // needs the finished query (rbac's insert-ownership check is exactly that: the payload
+        // does not exist until `values()` has been called, long after construction).
+        //
+        // Awaited in sequence, not `forEach`ed: a hook that needs a database round-trip to
+        // decide — an rbac rule whose ownership lives in another table — could otherwise only
+        // return a promise into the void, and the query would execute anyway. For a security
+        // check that is the difference between enforcing and pretending to.
+        for (const middleware of this._queryMiddlewares) {
+            await middleware.beforeQueryExecution(this);
+        }
+        const result = (await this._driver.execute(this));
+        // Snapshot the pipeline once, *after* the driver call: compiling the query is what
+        // registers the relation middlewares (the driver calls `toDB()`), so this is the first
+        // point at which the list is complete. Everything below runs against this immutable copy,
+        // so a middleware registered later cannot change the pipeline mid-flight, and — crucially —
+        // we never call `Array.prototype.reverse()` on `this._middlewares`, which mutates in place
+        // and used to flip `modelCreation` resolution order on every execution ( B8 ).
+        const middlewares = [...this._middlewares];
+        const creationOrder = [...middlewares].reverse();
+        if (this._asRaw) {
+            return result;
+        }
+        const transformedResult = result;
+        // if we have something to transform ...
+        if (transformedResult) {
+            middlewares.forEach((m) => {
+                Object.assign(transformedResult, m.afterQuery(transformedResult));
+            });
+        }
+        if (this._model && !this._nonSelect) {
+            // TODO: rething this casting
+            const models = transformedResult.map((r) => {
+                let model = null;
+                for (const middleware of creationOrder) {
+                    model = middleware.modelCreation(r);
+                    if (model !== null) {
+                        break;
                     }
                 }
-                else {
-                    onfulfilled?.(transformedResult);
+                if (model === null) {
+                    model = DI.resolve('__orm_model_factory__', [this._model]);
                 }
-            }
-            catch (err) {
-                if (onrejected) {
-                    onrejected(err);
-                }
-                else {
-                    throw err;
+                model.hydrate(r);
+                model.IsDirty = false;
+                // This is the one point at which the instance's columns hold exactly what the
+                // database returned, so it is the diff baseline for `save()`. Relation members
+                // are attached later by the afterHydration middlewares below, which record their
+                // own member keys into this same snapshot.
+                model.takeSnapshot();
+                // Nested relation data that arrived on the row itself ( belongsTo LEFT JOIN,
+                // and hasMany arrays passed straight to hydrate ) was attached by the hydrators
+                // inside `hydrate()` above — i.e. before the snapshot existed, so their own
+                // `snapshotRelation` calls no-opped. Record those relations now.
+                for (const name of (model.ModelDescriptor?.Relations ?? new Map()).keys()) {
+                    if (model[name]?.Populated) {
+                        model.snapshotRelation(name);
+                    }
                 }
+                return model;
+            });
+            if (middlewares.length > 0) {
+                await Promise.all(middlewares.map((m) => m.afterHydration(models)));
             }
-        })
-            .catch((err) => {
-            if (onrejected) {
-                onrejected(err);
-            }
-            else {
-                throw err;
-            }
-        });
+            return models;
+        }
+        return transformedResult;
+    }
+    /**
+     * Executes the query. The single entry point for execution — `then()` delegates here.
+     * The underlying work runs exactly once per builder instance; subsequent calls resolve
+     * with the memoized result.
+     */
+    execute() {
+        if (!this._executionPromise) {
+            this._executionPromise = this._run();
+        }
+        return this._executionPromise;
+    }
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.execute().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.execute().finally(onfinally);
     }
     middleware(middleware) {
         this._middlewares.push(middleware);
@@ -191,7 +220,7 @@ let QueryBuilder = class QueryBuilder extends Builder {
      *
      */
     setTable(table, alias) {
-        if (!table.trim()) {
+        if (isNullOrWhitespace(table)) {
             throw new InvalidArgument('table name is empty');
         }
         this._table = table;
@@ -228,9 +257,7 @@ let LimitBuilder = class LimitBuilder {
         };
     }
     take(count) {
-        if (count <= 0) {
-            throw new InvalidArgument(`take count cannot be negative number`);
-        }
+        _check_arg(_positive())(count, 'take count');
         this._limit.limit = count;
         return this;
     }
@@ -256,7 +283,7 @@ let LimitBuilder = class LimitBuilder {
         const result = (await this);
         if (result === undefined || (Array.isArray(result) && result.length === 0)) {
             if (typeof error === 'function') {
-                error = error(this.toDB());
+                throw error(this.toDB());
             }
             else
                 throw error;
@@ -285,10 +312,7 @@ LimitBuilder = __decorate([
 export { LimitBuilder };
 let OrderByBuilder = class OrderByBuilder {
     constructor() {
-        this._sort = {
-            column: '',
-            order: SortOrder.ASC,
-        };
+        this._sorts = [];
     }
     order(column, direction) {
         if (!column) {
@@ -301,10 +325,10 @@ let OrderByBuilder = class OrderByBuilder {
             });
             return this;
         }
-        this._sort = {
+        this._sorts.push({
             column,
             order: direction,
-        };
+        });
         return this;
     }
     orderBy(column) {
@@ -315,10 +339,10 @@ let OrderByBuilder = class OrderByBuilder {
             });
             return this;
         }
-        this._sort = {
+        this._sorts.push({
             column,
             order: SortOrder.ASC,
-        };
+        });
         return this;
     }
     orderByDescending(column) {
@@ -329,14 +353,25 @@ let OrderByBuilder = class OrderByBuilder {
             });
             return this;
         }
-        this._sort = {
+        this._sorts.push({
             column,
             order: SortOrder.DESC,
-        };
+        });
         return this;
     }
+    /**
+     * Returns the FIRST sort entry (or null) for backward compat with dialect
+     * packages that emit a single ORDER BY column. Use getSorts() for all entries.
+     */
     getSort() {
-        return this._sort.column.trim() !== '' ? this._sort : null;
+        const sort = this._sorts.find((s) => s.column.trim() !== '');
+        return sort ?? null;
+    }
+    /**
+     * Returns all sort entries (multi-column ORDER BY), skipping empty columns.
+     */
+    getSorts() {
+        return this._sorts.filter((s) => s.column.trim() !== '');
     }
 };
 OrderByBuilder = __decorate([
@@ -548,6 +583,23 @@ let WithRecursiveBuilder = class WithRecursiveBuilder {
         this._cteStatement = this._container.resolve(WithRecursiveStatement, ['cte', this, rcKeyName, pkName]);
         return this;
     }
+    /**
+     * Drops the recursive CTE from this builder.
+     *
+     * `WithRecursiveStatement.build()` compiles two CLONES of the owning query — the anchor
+     * member and the recursive member of the CTE. `clone()` copies `_cteStatement`, so each
+     * clone was still marked recursive and compiling it re-entered `build()`, which cloned
+     * again: an unbounded mutual recursion between `toDB()` and the recursive compiler that
+     * ended in a stack overflow rather than a query. The two member queries are by definition
+     * not themselves recursive, so the statement clears the flag on its clones.
+     *
+     * Named alongside `clearJoins()` / `clearWhere()`, which `build()` already uses to strip the
+     * parts of the parent query each member must not inherit.
+     */
+    clearRecursive() {
+        this._cteStatement = undefined;
+        return this;
+    }
 };
 WithRecursiveBuilder = __decorate([
     NewInstance()
@@ -582,12 +634,31 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
     clone(_parent) {
         // TODO: fix this cast
         const builder = new WhereBuilder_1(_parent);
-        builder._statements = this._statements.map((s) => s.clone(builder));
+        builder._statements = this._statements.map((s) => {
+            const cloned = s.clone(builder);
+            // preserve the per-statement boolean connector (clone() rebuilds the
+            // statement from scratch and would otherwise reset it to the AND default)
+            cloned.Boolean = s.Boolean;
+            return cloned;
+        });
         builder._boolean = this._boolean;
         builder._model = this._model;
         builder._tableAlias = this.TableAlias;
         return builder;
     }
+    /**
+     * Pushes a statement onto this builder, stamping it with the currently pending
+     * boolean connector (set by {@link orWhere}/{@link andWhere}). The pending
+     * connector applies to the NEXT pushed statement only and resets to AND
+     * afterwards, so `where(a).where(b).orWhere(c).where(d)` compiles to
+     * `a AND b OR c AND d` rather than rewriting the whole clause.
+     */
+    pushStatement(statement) {
+        statement.Boolean = this._boolean;
+        this._statements.push(statement);
+        this._boolean = WhereBoolean.AND;
+        return this;
+    }
     when(condition, callback, callbackElse) {
         if (condition) {
             if (callback)
@@ -632,18 +703,18 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
             return this.where(RawQuery.create(column ? 'TRUE' : 'FALSE'));
         }
         if (column instanceof RawQuery) {
-            this.Statements.push(this._container.resolve(RawQueryStatement, [column.Query, column.Bindings, self.TableAlias]));
+            this.pushStatement(this._container.resolve(RawQueryStatement, [column.Query, column.Bindings, self.TableAlias]));
             return this;
         }
         // handle nested where's
         if (_.isFunction(column)) {
             const builder = new WhereBuilder_1(this);
             column.call(builder);
-            self.Statements.push(this._container.resolve(WhereQueryStatement, [builder, self.TableAlias]));
+            self.pushStatement(this._container.resolve(WhereQueryStatement, [builder, self.TableAlias]));
             return this;
         }
         if (column instanceof Lazy) {
-            this.Statements.push(this._container.resolve(LazyQueryStatement, [column, this]));
+            this.pushStatement(this._container.resolve(LazyQueryStatement, [column, this]));
             return this;
         }
         // handle simple key = object[key] AND ....
@@ -672,7 +743,7 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
             if (sVal === null) {
                 return this.whereNull(c);
             }
-            self._statements.push(self._container.resolve(WhereStatement, [c, SqlOperator.EQ, sVal, this]));
+            self.pushStatement(self._container.resolve(WhereStatement, [c, SqlOperator.EQ, sVal, this]));
             return self;
         }
         /**
@@ -691,12 +762,17 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
                 throw new InvalidArgument(`value cannot be NaN`);
             }
             if (sVal === null) {
-                return this.whereNull(c);
-            }
-            if (sVal === null) {
-                return o === SqlOperator.NOT_NULL ? this.whereNotNull(c) : this.whereNull(c);
+                const op = String(o).toLowerCase();
+                // where(col, '=', null) => IS NULL ; where(col, '!=' / '<>', null) => IS NOT NULL
+                if (op === SqlOperator.EQ) {
+                    return this.whereNull(c);
+                }
+                if (op === SqlOperator.NOT || op === SqlOperator.NOT_2) {
+                    return this.whereNotNull(c);
+                }
+                throw new InvalidArgument(`operator ${o} cannot be used with null value ( only =, !=, <> are allowed )`);
             }
-            self._statements.push(self._container.resolve(WhereStatement, [c, o, sVal, self]));
+            self.pushStatement(self._container.resolve(WhereStatement, [c, o, sVal, self]));
             return this;
         }
     }
@@ -713,9 +789,9 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
         for (const key of Object.keys(obj).filter((x) => obj[x] !== undefined)) {
             const val = obj[key];
             if (Array.isArray(val)) {
-                if (val.length !== 0) {
-                    this.whereIn(key, val);
-                }
+                // empty array => SQL `IN ()` semantics => match nothing (FALSE),
+                // never "no condition" (which would match everything)
+                this.whereIn(key, val);
             }
             else if (val === null) {
                 this.whereNull(key);
@@ -726,165 +802,82 @@ let WhereBuilder = WhereBuilder_1 = class WhereBuilder {
         return this;
     }
     whereNotNull(column) {
-        this._statements.push(this._container.resolve(WhereStatement, [column, SqlOperator.NOT_NULL, null, this]));
+        this.pushStatement(this._container.resolve(WhereStatement, [column, SqlOperator.NOT_NULL, null, this]));
         return this;
     }
     whereNull(column) {
-        this._statements.push(this._container.resolve(WhereStatement, [column, SqlOperator.NULL, null, this]));
+        this.pushStatement(this._container.resolve(WhereStatement, [column, SqlOperator.NULL, null, this]));
         return this;
     }
     whereNot(column, val) {
         return this.where(column, SqlOperator.NOT, val);
     }
     whereIn(column, val) {
-        this._statements.push(this._container.resolve(InStatement, [column, val, false, this]));
+        // `IN ()` matches nothing in SQL; compile an empty set to FALSE rather than
+        // emitting no condition (which would silently match every row).
+        if (Array.isArray(val) && val.length === 0) {
+            this.where(false);
+            return this;
+        }
+        this.pushStatement(this._container.resolve(InStatement, [column, val, false, this]));
         return this;
     }
     whereNotIn(column, val) {
-        this._statements.push(this._container.resolve(InStatement, [column, val, true, this]));
+        this.pushStatement(this._container.resolve(InStatement, [column, val, true, this]));
         return this;
     }
     whereExist(query, callback) {
-        // TODO: refactor and remove code duplication with whereNotExists
-        // TODO: move relation handling to separate DI service for every exists relation type
-        let relQuery;
-        let sourcePKey = '';
-        const self = this;
-        let tableName = '';
-        let tDesc;
-        if (typeof query === 'string') {
-            const rel = this._model.getRelationDescriptor(query);
-            if (!rel) {
-                throw new OrmException(`relation ${query} not found in model ${this.constructor.name}`);
-            }
-            switch (rel.Type) {
-                case RelationType.One:
-                    this.whereNotNull(rel.ForeignKey);
-                    // simply use right join for condition check
-                    if (callback) {
-                        // TODO: cast fix
-                        this.rightJoin(rel.TargetModel, callback.bind(query));
-                    }
-                    break;
-                case RelationType.Many:
-                    tableName = rel.TargetModel.getModelDescriptor().TableName;
-                    tDesc = self._model.getModelDescriptor();
-                    // set alias to avoid conflicts in case of multiple relations to same model and to make sure that relation query is correct even if source query has alias
-                    relQuery = rel.TargetModel.query().setAlias(`${tableName}_exists`);
-                    relQuery.where(Lazy.oF(function () {
-                        const sourceAlias = self._tableAlias ?? (self._parent ? self._parent.TableAlias : tDesc.TableName);
-                        sourcePKey = `\`${sourceAlias}\`.\`${self._model.getModelDescriptor().PrimaryKey}\``;
-                        // relQuery is guaranteed assigned above before this lazy callback executes
-                        relQuery.where(new RawQuery(`${rel.ForeignKey} = ${sourcePKey}`));
-                    }));
-                    if (callback) {
-                        callback.apply(relQuery);
-                    }
-                    this.whereExist(relQuery);
-                    break;
-                case RelationType.ManyToMany:
-                    relQuery = rel.JunctionModel.query();
-                    tableName = rel.TargetModel.getModelDescriptor().TableName;
-                    tDesc = self._model.getModelDescriptor();
-                    relQuery = rel.TargetModel.query().setAlias(`${tableName}_exists`);
-                    relQuery.where(Lazy.oF(function () {
-                        const sourceAlias = self._tableAlias ?? (self._parent ? self._parent.TableAlias : tDesc.TableName);
-                        sourcePKey = `\`${sourceAlias}\`.\`${self._model.getModelDescriptor().PrimaryKey}\``;
-                        // relQuery is guaranteed assigned above before this lazy callback executes
-                        relQuery.where(new RawQuery(`${rel.JunctionModelSourceModelFKey_Name} = ${sourcePKey}`));
-                    }));
-                    this.setAlias();
-                    relQuery.rightJoin({
-                        joinModel: rel.TargetModel,
-                        joinTableForeignKey: rel.ForeignKey,
-                        sourceTablePrimaryKey: rel.JunctionModelTargetModelFKey_Name,
-                        callback: callback,
-                    });
-                    this.whereExist(relQuery);
-                    break;
-            }
-        }
-        else {
-            this._statements.push(this._container.resolve(ExistsQueryStatement, [query, false]));
-        }
-        return this;
+        return this.buildExistsClause(query, false, callback);
     }
     whereNotExists(query, callback) {
-        let relQuery;
-        let sourcePKey = '';
-        const self = this;
-        let tableName = '';
-        let tDesc;
-        if (typeof query === 'string') {
-            const rel = this._model.getRelationDescriptor(query);
-            if (!rel) {
-                throw new OrmException(`relation ${query} not found in model ${this.constructor.name}`);
-            }
-            switch (rel.Type) {
-                case RelationType.One:
-                    this.whereNotNull(rel.ForeignKey);
-                    // simply use right join for condition check
-                    if (callback) {
-                        // TODO: cast fix
-                        this.rightJoin(rel.TargetModel, callback.bind(query));
-                    }
-                    break;
-                case RelationType.Many:
-                    tableName = rel.TargetModel.getModelDescriptor().TableName;
-                    tDesc = self._model.getModelDescriptor();
-                    // set alias to avoid conflicts in case of multiple relations to same model and to make sure that relation query is correct even if source query has alias
-                    relQuery = rel.TargetModel.query().setAlias(`${tableName}_exists`);
-                    relQuery.where(Lazy.oF(function () {
-                        const sourceAlias = self._tableAlias || (self._parent ? self._parent.TableAlias : tDesc.TableName);
-                        sourcePKey = `\`${sourceAlias}\`.\`${self._model.getModelDescriptor().PrimaryKey}\``;
-                        // relQuery is guaranteed assigned above before this lazy callback executes
-                        relQuery.where(new RawQuery(`${rel.ForeignKey} = ${sourcePKey}`));
-                    }));
-                    if (callback) {
-                        callback.apply(relQuery);
-                    }
-                    this.whereNotExists(relQuery);
-                    break;
-                case RelationType.ManyToMany:
-                    relQuery = rel.JunctionModel.query();
-                    tableName = rel.TargetModel.getModelDescriptor().TableName;
-                    tDesc = self._model.getModelDescriptor();
-                    relQuery = rel.TargetModel.query().setAlias(`${tableName}_exists`);
-                    relQuery.where(Lazy.oF(function () {
-                        const sourceAlias = self._tableAlias || (self._parent ? self._parent.TableAlias : tDesc.TableName);
-                        sourcePKey = `\`${sourceAlias}\`.\`${self._model.getModelDescriptor().PrimaryKey}\``;
-                        // relQuery is guaranteed assigned above before this lazy callback executes
-                        relQuery.where(new RawQuery(`${rel.JunctionModelSourceModelFKey_Name} = ${sourcePKey}`));
-                    }));
-                    relQuery.rightJoin({
-                        joinModel: rel.TargetModel,
-                        joinTableForeignKey: rel.PrimaryKey,
-                        sourceTablePrimaryKey: rel.ForeignKey,
-                        callback: callback,
-                    });
-                    this.whereNotExists(relQuery);
-                    break;
-            }
+        return this.buildExistsClause(query, true, callback);
+    }
+    /**
+     * Shared implementation for {@link whereExist} / {@link whereNotExists}.
+     *
+     * For a ready sub-query it pushes an {@link ExistsQueryStatement} directly. For a relation
+     * name it resolves the matching {@link ExistsRelationHandler} from the container (one per
+     * {@link RelationType}) and lets it either mutate this builder or return a correlated
+     * sub-query that we then wrap in EXISTS / NOT EXISTS.
+     *
+     * @param query relation name or a ready sub-query
+     * @param negated `true` for NOT EXISTS, `false` for EXISTS
+     * @param callback optional where-callback applied to the relation sub-query
+     */
+    buildExistsClause(query, negated, callback) {
+        if (typeof query !== 'string') {
+            this.pushStatement(this._container.resolve(ExistsQueryStatement, [query, negated]));
+            return this;
         }
-        else {
-            this._statements.push(this._container.resolve(ExistsQueryStatement, [query, true]));
+        const rel = this._model.getRelationDescriptor(query);
+        if (!rel) {
+            throw new OrmException(`relation ${query} not found in model ${this.constructor.name}`);
+        }
+        const handlers = this._container.resolve(Array.ofType(ExistsRelationHandler));
+        const handler = handlers.find((h) => h.Type === rel.Type);
+        if (!handler) {
+            throw new OrmException(`no ExistsRelationHandler registered for relation type ${rel.Type} (relation ${query} on ${this.constructor.name})`);
+        }
+        const subquery = handler.apply(this, rel, query, callback);
+        if (subquery) {
+            this.pushStatement(this._container.resolve(ExistsQueryStatement, [subquery, negated]));
         }
         return this;
     }
     whereBetween(column, val) {
-        this._statements.push(this._container.resolve(BetweenStatement, [column, val, false, this.TableAlias]));
+        this.pushStatement(this._container.resolve(BetweenStatement, [column, val, false, this.TableAlias]));
         return this;
     }
     whereNotBetween(column, val) {
-        this._statements.push(this._container.resolve(BetweenStatement, [column, val, true, this.TableAlias]));
+        this.pushStatement(this._container.resolve(BetweenStatement, [column, val, true, this.TableAlias]));
         return this;
     }
     whereInSet(column, val) {
-        this._statements.push(this._container.resolve(InSetStatement, [column, val, false, this.TableAlias]));
+        this.pushStatement(this._container.resolve(InSetStatement, [column, val, false, this.TableAlias]));
         return this;
     }
     whereNotInSet(column, val) {
-        this._statements.push(this._container.resolve(InSetStatement, [column, val, true, this.TableAlias]));
+        this.pushStatement(this._container.resolve(InSetStatement, [column, val, true, this.TableAlias]));
         return this;
     }
     clearWhere() {
@@ -924,10 +917,7 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         this._distinct = false;
         this._method = QueryMethod.SELECT;
         this._boolean = WhereBoolean.AND;
-        this._sort = {
-            column: '',
-            order: SortOrder.NONE,
-        };
+        this._sorts = [];
         this._first = false;
         this._limit = {
             limit: -1,
@@ -942,13 +932,12 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         return (await this);
     }
     setAlias(alias) {
-        if (!alias || alias.trim() === '') {
-            alias = `${this._driver.Options.AliasSeparator}${this._table}${this._driver.Options.AliasSeparator}`;
-        }
-        this._tableAlias = alias;
-        this._columns.forEach((c) => (c.TableAlias = alias));
-        this._joinStatements.forEach((c) => (c.TableAlias = alias));
-        this._statements.forEach((c) => (c.TableAlias = alias));
+        // isNullOrWhitespace is not a type predicate; a false result guarantees a non-blank string
+        const resolvedAlias = isNullOrWhitespace(alias) ? `${this._driver.Options.AliasSeparator}${this._table}${this._driver.Options.AliasSeparator}` : alias;
+        this._tableAlias = resolvedAlias;
+        this._columns.forEach((c) => (c.TableAlias = resolvedAlias));
+        this._joinStatements.forEach((c) => (c.TableAlias = resolvedAlias));
+        this._statements.forEach((c) => (c.TableAlias = resolvedAlias));
         return this;
     }
     clone() {
@@ -959,11 +948,18 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         builder._joinStatements = this._joinStatements.map(c => c.clone(builder));
         // Clone statements with mapped WhereBuilder references
         builder._statements = this._statements.map(c => c.clone(builder));
+        // Clone group-by statements (previously dropped, silently losing GROUP BY
+        // on a cloned query — eg. orm-api count-pagination clones the builder).
+        builder._groupStatements = this._groupStatements.map(c => c.clone(builder));
+        // Carry relations and result middlewares over. These hold live objects and
+        // are shared the same way mergeRelations()/mergeBuilder() already share them.
+        builder._relations = [...this._relations];
+        builder._middlewares = [...this._middlewares];
         /**
          * ------------------------------------------------------------------
          */
         builder._limit = { ...this._limit };
-        builder._sort = { ...this._sort };
+        builder._sorts = this._sorts.map((s) => ({ ...s }));
         builder._boolean = this._boolean;
         builder._distinct = this._distinct;
         builder._table = this._table;
@@ -1062,15 +1058,21 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         this._getRelationInstance(relation).execute(callback);
         return this;
     }
-    mergeBuilder(builder) {
+    mergeBuilder(builder, includeStatements = true) {
         this._columns = this._columns.concat(builder._columns);
         this._cteStatement = builder._cteStatement;
         this._distinct = builder._distinct;
-        this._sort = {
-            column: builder._sort.column !== '' ? builder._sort.column : this._sort.column,
-            order: builder._sort.order !== '' ? builder._sort.order : this._sort.order,
-        };
-        this.mergeStatements(builder);
+        // Fold the merged builder's sorts into this query's sorts (multi-column
+        // ORDER BY). If the merged builder has no sorts, this keeps our own.
+        this._sorts = this._sorts.concat(builder._sorts.map((s) => ({ ...s })));
+        // `includeStatements: false` is used by JoinStatement so that a join
+        // callback's WHERE conditions are NOT folded into the main query's WHERE
+        // (which silently turns a LEFT JOIN into an inner filter). The join emits
+        // those conditions in its own ON clause instead. Columns/sort are still
+        // merged so join-callback selects (e.g. extra joined columns) keep working.
+        if (includeStatements) {
+            this.mergeStatements(builder);
+        }
     }
     mergeRelations(builder) {
         this._relations = this._relations.concat(builder._relations);
@@ -1081,6 +1083,21 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         this._joinStatements = this._joinStatements.concat(builder._joinStatements);
         this._statements = this._statements.concat(stms);
     }
+    /**
+     * Includes soft-deleted rows in the result set by removing the default
+     * `DeletedAt IS NULL` filter added by createQuery for @SoftDelete models.
+     */
+    withDeleted() {
+        const descriptor = extractModelDescriptor(this._model);
+        const deletedAt = descriptor?.SoftDelete?.DeletedAt;
+        if (!deletedAt) {
+            return this;
+        }
+        this._statements = this._statements.filter((s) => {
+            return !(s instanceof WhereStatement && s.Column === deletedAt && s.Operator === SqlOperator.NULL);
+        });
+        return this;
+    }
     min(column, as) {
         this._columns.push(this._container.resolve(ColumnMethodStatement, [column, ColumnMethods.MIN, as, this._tableAlias]));
         return this;
@@ -1122,44 +1139,26 @@ let SelectQueryBuilder = SelectQueryBuilder_1 = class SelectQueryBuilder extends
         return compiler.compile();
     }
     async all() {
-        return await this;
+        return await this.execute();
     }
     async resultExists() {
-        return this.then((res) => {
-            if (Array.isArray(res)) {
-                return res.length > 0;
-            }
-            return res !== undefined && res !== null;
-        });
-    }
-    then(onfulfilled, onrejected) {
-        this._queryMiddlewares.forEach((x) => x.beforeQueryExecution(this));
-        return super.then((result) => {
-            if (this._first) {
-                if (Array.isArray(result)) {
-                    if (result.length !== 0) {
-                        return onfulfilled?.(result[0]);
-                    }
-                    else {
-                        try {
-                            return onfulfilled?.(undefined);
-                        }
-                        catch (err) {
-                            onrejected?.(err);
-                        }
-                    }
-                }
-                else {
-                    return onfulfilled?.(result);
-                }
-            }
-            else {
-                return onfulfilled?.(result);
-            }
-        }, onrejected);
+        const res = await this.execute();
+        if (Array.isArray(res)) {
+            return res.length > 0;
+        }
+        return res !== undefined && res !== null;
     }
-    async execute() {
-        return (await this);
+    /**
+     * Overrides the engine rather than `execute()` so that the `takeFirst()` unwrapping
+     * happens *inside* the memo. `beforeQueryExecution` is dispatched by `Builder._run()`
+     * for every builder type, so it still fires once per builder rather than once per await.
+     */
+    async _run() {
+        const result = await super._run();
+        if (this._first && Array.isArray(result)) {
+            return (result.length !== 0 ? result[0] : undefined);
+        }
+        return result;
     }
 };
 __decorate([
@@ -1184,6 +1183,10 @@ let DeleteQueryBuilder = class DeleteQueryBuilder extends QueryBuilder {
             offset: -1,
         };
         this.QueryContext = QueryContext.Delete;
+        // Query middlewares (e.g. rbac ownership enforcement) must run for deletes
+        // too, not only selects — otherwise :own permission constraints are never
+        // applied and any row can be deleted.
+        this._queryMiddlewares.forEach((x) => x.afterQueryCreation(this));
     }
     toDB() {
         return this._container.resolve(DeleteQueryCompiler, [this]).compile();
@@ -1223,6 +1226,9 @@ let OnDuplicateQueryBuilder = class OnDuplicateQueryBuilder {
         this._columnsToUpdate = columns;
         return this;
     }
+    execute() {
+        return this._parent.execute();
+    }
     then(onfulfilled, onrejected) {
         return this._parent.then(onfulfilled, onrejected);
     }
@@ -1246,6 +1252,10 @@ let UpdateQueryBuilder = class UpdateQueryBuilder extends QueryBuilder {
         this._boolean = WhereBoolean.AND;
         this._statements = [];
         this.QueryContext = QueryContext.Update;
+        // Query middlewares (e.g. rbac ownership enforcement) must run for updates
+        // too, not only selects — otherwise :own permission constraints are never
+        // applied and any row can be updated.
+        this._queryMiddlewares.forEach((x) => x.afterQueryCreation(this));
     }
     in(name) {
         this.setTable(name);
@@ -1281,6 +1291,10 @@ let InsertQueryBuilder = class InsertQueryBuilder extends QueryBuilder {
     get Replace() {
         return this._replace;
     }
+    /** Columns requested via {@link returning}. Empty when no RETURNING clause was asked for. */
+    get Returning() {
+        return this._returning ?? [];
+    }
     constructor(container, driver, model) {
         super(container, driver, model);
         this._update = false;
@@ -1289,6 +1303,52 @@ let InsertQueryBuilder = class InsertQueryBuilder extends QueryBuilder {
         this._columns = [];
         this._values = [];
         this.QueryContext = QueryContext.Insert;
+        // Inserts get the same middleware pass as the other three builders. Note that a
+        // middleware which needs to see or amend the row payload must use
+        // `beforeQueryExecution` instead — at construction time `values()` has not been called.
+        this._queryMiddlewares.forEach((x) => x.afterQueryCreation(this));
+    }
+    /**
+     * The value of `column` on every row about to be inserted, in row order. Empty when the
+     * payload does not carry that column at all.
+     *
+     * The read counterpart of {@link forceColumn}, and the only sane way for a
+     * `beforeQueryExecution` hook to inspect what is being written: the payload lives in two
+     * parallel structures ( `_columns` and one array per row ), so every caller would
+     * otherwise repeat the same index lookup.
+     *
+     * @param column - column to read off each row
+     */
+    getColumnValues(column) {
+        const index = this._columns.findIndex((c) => !(c.Column instanceof RawQuery) && c.Column === column);
+        if (index === -1) {
+            return [];
+        }
+        // eslint-disable-next-line security/detect-object-injection
+        return this._values.map((row) => row[index]);
+    }
+    /**
+     * Forces `column` to `value` on every row of the payload, overwriting whatever the caller
+     * supplied.
+     *
+     * This is the write path for a policy that must not be negotiable — rbac's `createOwn`
+     * ownership stamp. `values()` cannot serve: it appends rows and takes the column list from
+     * its own argument, so calling it a second time adds a row rather than amending the
+     * existing ones.
+     *
+     * @param column - column to overwrite on every row
+     * @param value - value to force
+     */
+    forceColumn(column, value) {
+        const existing = this._columns.findIndex((c) => !(c.Column instanceof RawQuery) && c.Column === column);
+        if (existing === -1) {
+            this.columns([...this._columns.filter((c) => !(c.Column instanceof RawQuery)).map((c) => c.Column), column]);
+            this._values.forEach((row) => row.push(value));
+            return this;
+        }
+        // eslint-disable-next-line security/detect-object-injection
+        this._values.forEach((row) => (row[existing] = value));
+        return this;
     }
     /**
      * Sets insert to ignore on duplicate
@@ -1301,8 +1361,21 @@ let InsertQueryBuilder = class InsertQueryBuilder extends QueryBuilder {
         this._replace = true;
         return this;
     }
+    /**
+     * Asks the dialect to echo the given columns of every inserted row back.
+     *
+     * @throws NotSupported on drivers whose `supportedFeatures().insertReturning` is false —
+     *         silently doing nothing is how this API was a no-op on MySQL and MSSQL for years.
+     */
     returning(columns) {
+        if (!this.Driver.supportedFeatures().insertReturning) {
+            throw new NotSupported(`driver ${this.Driver.Options.Driver} does not support RETURNING on INSERT`);
+        }
         this._returning = columns;
+        // onDuplicate() sets Upsert unconditionally and wins if it runs afterwards.
+        if (this.QueryContext === QueryContext.Insert) {
+            this.QueryContext = QueryContext.InsertReturning;
+        }
         return this;
     }
     values(data) {
@@ -1464,6 +1537,7 @@ let ColumnQueryBuilder = class ColumnQueryBuilder {
         this.Comment = '';
         this.Unique = false;
         this.Unsigned = false;
+        this.InlinePrimaryKey = true;
         this.Args.push(...args);
     }
     notNull() {
@@ -1634,10 +1708,11 @@ AlterTableQueryBuilder = __decorate([
 export { AlterTableQueryBuilder };
 let TableQueryBuilder = class TableQueryBuilder extends QueryBuilder {
     /**
-     * Alias for string(name, 36 )
+     * Alias for binary(name, 16 ) - uuids are stored as 16-byte BINARY to match
+     * the UuidConverter ( which writes a dashed uuid as a 16-byte buffer ).
      */
     uuid(name) {
-        return this.string(name, 36);
+        return this.binary(name, 16);
     }
     ifExists() {
         this._checkExists = true;
@@ -2043,6 +2118,16 @@ export function createQuery(model, query, injectModel = true) {
     }
     qr.middleware(new DiscriminationMapMiddleware(dsc));
     qr.setTable(dsc.TableName);
+    // Soft-delete read filtering: by default exclude rows that have been soft
+    // deleted (DeletedAt IS NOT NULL). SelectQueryBuilder.withDeleted() removes
+    // this default statement to include soft-deleted rows again.
+    // Guarded on the DeletedAt column actually being present in the model's
+    // reflected columns — a filter on a column the schema does not expose is
+    // impossible anyway, and the guard keeps queries working when table info
+    // has not (yet) surfaced the column.
+    if (qr instanceof SelectQueryBuilder && dsc.SoftDelete?.DeletedAt && dsc.Columns?.some((c) => c.Name === dsc.SoftDelete.DeletedAt)) {
+        qr.whereNull(dsc.SoftDelete.DeletedAt);
+    }
     if (driver.Options.Database) {
         qr.database(driver.Options.Database);
     }