@veap/database 0.0.0-stage → 0.1.1

package/dist/query-builder.js

@@ -0,0 +1,749 @@
+import { serializeForStorage } from "./casts.js";
+import { getKnex } from "./connection.js";
+import { DatabaseError } from "./errors.js";
+import { eagerLoadRelations } from "./relations/eager-loader.js";
+import { BelongsTo, BelongsToMany, MorphedByMany, MorphMany, MorphOne, MorphToMany, } from "./relations/index.js";
+import { toCamelCase, toSnakeCase } from "./utils.js";
+export class ModelQueryBuilder {
+    modelClass;
+    knexBuilder;
+    eagerRelations = [];
+    _withTrashed = false;
+    _onlyTrashed = false;
+    _softDeleteScopeApplied = false;
+    _scopesApplied = false;
+    _ignoredGlobalScopes = new Set();
+    _ignoreAllGlobalScopes = false;
+    constructor(modelClass, // typeof Model
+    customKnexBuilder) {
+        this.modelClass = modelClass;
+        const knex = getKnex();
+        this.knexBuilder = customKnexBuilder || knex(modelClass.table);
+        // Return Proxy to enable dynamic local scope dispatching (e.g. query.active(), query.popular(10))
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                if (typeof prop === "string") {
+                    // 1. Direct property or method on ModelQueryBuilder
+                    if (prop in target) {
+                        const val = Reflect.get(target, prop, receiver);
+                        if (typeof val === "function") {
+                            return (...args) => {
+                                const res = val.apply(target, args);
+                                return res === target ? receiver : res;
+                            };
+                        }
+                        return val;
+                    }
+                    // 2. Check for local scope method on modelClass (prototype or static)
+                    // e.g. "active" -> "scopeActive", "popular" -> "scopePopular"
+                    const scopeName = `scope${prop.charAt(0).toUpperCase()}${prop.slice(1)}`;
+                    const proto = target.modelClass?.prototype;
+                    const fn = proto?.[scopeName] || target.modelClass?.[scopeName];
+                    if (typeof fn === "function") {
+                        return (...args) => {
+                            const result = fn.call(proto || target.modelClass, receiver, ...args);
+                            return result === target || result === undefined
+                                ? receiver
+                                : result;
+                        };
+                    }
+                    // 3. Delegate to Knex query builder if method exists (e.g. groupBy, having, distinct, joinRaw)
+                    if (target.knexBuilder &&
+                        typeof target.knexBuilder[prop] === "function") {
+                        return (...args) => {
+                            const result = target.knexBuilder[prop](...args);
+                            return result === target.knexBuilder ? receiver : result;
+                        };
+                    }
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+    }
+    /**
+     * Explicitly applies a local scope method by name.
+     */
+    scope(name, ...args) {
+        const scopeName = name.startsWith("scope")
+            ? name
+            : `scope${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+        const proto = this.modelClass?.prototype;
+        const fn = proto?.[scopeName] || this.modelClass?.[scopeName];
+        if (typeof fn !== "function") {
+            throw DatabaseError.Internal(`[veap:ORM] Scope "${name}" (${scopeName}) not found on model ${this.modelClass?.name || this.modelClass?.table}.`);
+        }
+        const result = fn.call(proto || this.modelClass, this, ...args);
+        return result !== undefined ? result : this;
+    }
+    /**
+     * Excludes a specific global scope from this query.
+     */
+    withoutGlobalScope(scope) {
+        this._ignoredGlobalScopes.add(scope);
+        if (scope === "softDeletes" || scope === "softDelete") {
+            this.withTrashed();
+        }
+        return this;
+    }
+    /**
+     * Excludes multiple or all global scopes from this query.
+     */
+    withoutGlobalScopes(scopes) {
+        if (!scopes || scopes.length === 0) {
+            this._ignoreAllGlobalScopes = true;
+            this.withTrashed();
+        }
+        else {
+            for (const s of scopes) {
+                this.withoutGlobalScope(s);
+            }
+        }
+        return this;
+    }
+    /**
+     * Includes soft-deleted models in query results.
+     */
+    withTrashed() {
+        this._withTrashed = true;
+        this._onlyTrashed = false;
+        return this;
+    }
+    /**
+     * Restricts query to only soft-deleted models.
+     */
+    onlyTrashed() {
+        this._onlyTrashed = true;
+        this._withTrashed = false;
+        return this;
+    }
+    /**
+     * Applies both user-defined global scopes and soft-delete scope.
+     */
+    applyGlobalScopes() {
+        if (this._scopesApplied) {
+            return;
+        }
+        this._scopesApplied = true;
+        // 1. User-defined global scopes from modelClass
+        if (!this._ignoreAllGlobalScopes && this.modelClass) {
+            const globalScopes = typeof this.modelClass.getGlobalScopes === "function"
+                ? this.modelClass.getGlobalScopes()
+                : this.modelClass.globalScopes || {};
+            for (const [name, scope] of Object.entries(globalScopes)) {
+                if (!this._ignoredGlobalScopes.has(name)) {
+                    if (typeof scope === "function") {
+                        scope(this, this.modelClass);
+                    }
+                    else if (scope && typeof scope.apply === "function") {
+                        scope.apply(this, this.modelClass);
+                    }
+                }
+            }
+        }
+        // 2. Soft deletes
+        this.applySoftDeleteScope();
+    }
+    /**
+     * Applies the soft delete filter to the underlying query if enabled.
+     */
+    applySoftDeleteScope() {
+        if (this._softDeleteScopeApplied || !this.modelClass?.softDeletes) {
+            return;
+        }
+        const colName = toSnakeCase(this.modelClass.deletedAtColumn || "deleted_at");
+        const column = this.modelClass?.table
+            ? `${this.modelClass.table}.${colName}`
+            : colName;
+        if (this._onlyTrashed) {
+            this.knexBuilder.whereNotNull(column);
+        }
+        else if (!this._withTrashed) {
+            this.knexBuilder.whereNull(column);
+        }
+        this._softDeleteScopeApplied = true;
+    }
+    /**
+     * Returns the underlying Knex query builder.
+     */
+    toKnex() {
+        return this.knexBuilder;
+    }
+    /**
+     * Basic WHERE clause. Automatically maps camelCase to snake_case columns.
+     */
+    where(column, operator, value) {
+        if (typeof column === "function") {
+            this.knexBuilder.where(column);
+        }
+        else if (typeof column === "object" && column !== null) {
+            const converted = {};
+            for (const [k, v] of Object.entries(column)) {
+                converted[toSnakeCase(k)] = v;
+            }
+            this.knexBuilder.where(converted);
+        }
+        else if (typeof column === "string") {
+            const col = toSnakeCase(column);
+            if (value === undefined) {
+                this.knexBuilder.where(col, operator);
+            }
+            else {
+                this.knexBuilder.where(col, operator, value);
+            }
+        }
+        else {
+            this.knexBuilder.where(column, operator, value);
+        }
+        return this;
+    }
+    orWhere(column, operator, value) {
+        if (typeof column === "function") {
+            this.knexBuilder.orWhere(column);
+        }
+        else if (typeof column === "object" && column !== null) {
+            const converted = {};
+            for (const [k, v] of Object.entries(column)) {
+                converted[toSnakeCase(k)] = v;
+            }
+            this.knexBuilder.orWhere(converted);
+        }
+        else if (typeof column === "string") {
+            const col = toSnakeCase(column);
+            if (value === undefined) {
+                this.knexBuilder.orWhere(col, operator);
+            }
+            else {
+                this.knexBuilder.orWhere(col, operator, value);
+            }
+        }
+        else {
+            this.knexBuilder.orWhere(column, operator, value);
+        }
+        return this;
+    }
+    whereIn(column, values) {
+        this.knexBuilder.whereIn(toSnakeCase(column), values);
+        return this;
+    }
+    whereNotIn(column, values) {
+        this.knexBuilder.whereNotIn(toSnakeCase(column), values);
+        return this;
+    }
+    whereNull(column) {
+        this.knexBuilder.whereNull(toSnakeCase(column));
+        return this;
+    }
+    whereNotNull(column) {
+        this.knexBuilder.whereNotNull(toSnakeCase(column));
+        return this;
+    }
+    whereBetween(column, range) {
+        this.knexBuilder.whereBetween(toSnakeCase(column), range);
+        return this;
+    }
+    whereLike(column, pattern) {
+        this.knexBuilder.whereLike(toSnakeCase(column), pattern);
+        return this;
+    }
+    whereILike(column, pattern) {
+        this.knexBuilder.whereILike(toSnakeCase(column), pattern);
+        return this;
+    }
+    select(...columns) {
+        const converted = columns.map((col) => typeof col === "string" ? toSnakeCase(col) : col);
+        this.knexBuilder.select(...converted);
+        return this;
+    }
+    orderBy(column, direction = "asc") {
+        this.knexBuilder.orderBy(toSnakeCase(column), direction);
+        return this;
+    }
+    latest(column = "created_at") {
+        return this.orderBy(column, "desc");
+    }
+    oldest(column = "created_at") {
+        return this.orderBy(column, "asc");
+    }
+    limit(count) {
+        this.knexBuilder.limit(count);
+        return this;
+    }
+    take(count) {
+        return this.limit(count);
+    }
+    offset(count) {
+        this.knexBuilder.offset(count);
+        return this;
+    }
+    skip(count) {
+        return this.offset(count);
+    }
+    groupBy(...columns) {
+        const converted = columns.map((col) => typeof col === "string" ? toSnakeCase(col) : col);
+        this.knexBuilder.groupBy(...converted);
+        return this;
+    }
+    having(column, operatorOrValue, value) {
+        if (value === undefined) {
+            if (operatorOrValue === undefined) {
+                this.knexBuilder.having(column);
+            }
+            else {
+                this.knexBuilder.having(column, "=", operatorOrValue);
+            }
+        }
+        else {
+            this.knexBuilder.having(column, operatorOrValue, value);
+        }
+        return this;
+    }
+    distinct(...columns) {
+        const converted = columns.map((col) => typeof col === "string" ? toSnakeCase(col) : col);
+        this.knexBuilder.distinct(...converted);
+        return this;
+    }
+    join(table, first, operatorOrSecond, second) {
+        if (second === undefined) {
+            this.knexBuilder.join(table, first, operatorOrSecond);
+        }
+        else {
+            this.knexBuilder.join(table, first, operatorOrSecond, second);
+        }
+        return this;
+    }
+    leftJoin(table, first, operatorOrSecond, second) {
+        if (second === undefined) {
+            this.knexBuilder.leftJoin(table, first, operatorOrSecond);
+        }
+        else {
+            this.knexBuilder.leftJoin(table, first, operatorOrSecond, second);
+        }
+        return this;
+    }
+    /**
+     * Eager load relations (e.g. .with('author', 'posts.comments'))
+     */
+    with(...relations) {
+        const flattened = relations.flat();
+        this.eagerRelations.push(...flattened);
+        return this;
+    }
+    /**
+     * Helper to retrieve a relation instance from a temporary model instance.
+     */
+    getRelationInstance(relationName) {
+        const dummy = new this.modelClass({}, false);
+        if (typeof dummy[relationName] !== "function") {
+            throw DatabaseError.Internal(`[veap:ORM] Relation "${relationName}" is not defined on model ${this.modelClass.name || this.modelClass.table}.`);
+        }
+        const rel = dummy[relationName]();
+        if (!rel) {
+            throw DatabaseError.Internal(`[veap:ORM] Method "${relationName}" on model ${this.modelClass.name || this.modelClass.table} did not return a valid Relation instance.`);
+        }
+        return rel;
+    }
+    /**
+     * Builds an EXISTS or COUNT subquery for a relation.
+     */
+    buildRelationSubquery(sub, relationName, callback, isCount = false) {
+        const rel = this.getRelationInstance(relationName);
+        const parentTable = this.modelClass.table;
+        const relatedTable = rel.related.table;
+        const knex = getKnex();
+        if (isCount) {
+            sub.from(relatedTable).count("* as count");
+        }
+        else {
+            sub.from(relatedTable).select(knex.raw(1));
+        }
+        if (rel instanceof MorphToMany) {
+            const pivotTable = rel.pivotTable;
+            const foreignPivotKey = toSnakeCase(rel.foreignPivotKey);
+            const relatedPivotKey = toSnakeCase(rel.relatedPivotKey);
+            const relatedKey = toSnakeCase(rel.relatedKey || "id");
+            const localKey = toSnakeCase(rel.localKey || "id");
+            const typeColumn = toSnakeCase(rel.morphTypeColumn);
+            sub.join(pivotTable, `${relatedTable}.${relatedKey}`, `${pivotTable}.${relatedPivotKey}`);
+            sub.where(`${pivotTable}.${typeColumn}`, rel.morphType);
+            sub.whereRaw("CAST(?? AS TEXT) = CAST(?? AS TEXT)", [
+                `${pivotTable}.${foreignPivotKey}`,
+                `${parentTable}.${localKey}`,
+            ]);
+        }
+        else if (rel instanceof MorphedByMany) {
+            const pivotTable = rel.pivotTable;
+            const foreignPivotKey = toSnakeCase(rel.foreignPivotKey);
+            const relatedPivotKey = toSnakeCase(rel.relatedPivotKey);
+            const relatedKey = toSnakeCase(rel.relatedKey || "id");
+            const localKey = toSnakeCase(rel.localKey || "id");
+            const typeColumn = toSnakeCase(rel.morphTypeColumn);
+            sub.join(pivotTable, function () {
+                this.on(knex.raw("CAST(?? AS TEXT) = CAST(?? AS TEXT)", [
+                    `${relatedTable}.${relatedKey}`,
+                    `${pivotTable}.${foreignPivotKey}`,
+                ]));
+            });
+            sub.where(`${pivotTable}.${typeColumn}`, rel.morphType);
+            sub.whereRaw("?? = ??", [
+                `${pivotTable}.${relatedPivotKey}`,
+                `${parentTable}.${localKey}`,
+            ]);
+        }
+        else if (rel instanceof BelongsToMany || rel.pivotTable) {
+            const pivotTable = rel.pivotTable;
+            const foreignPivotKey = toSnakeCase(rel.foreignPivotKey);
+            const relatedPivotKey = toSnakeCase(rel.relatedPivotKey);
+            const relatedKey = toSnakeCase(rel.relatedKey || "id");
+            const localKey = toSnakeCase(rel.localKey || "id");
+            sub.join(pivotTable, `${relatedTable}.${relatedKey}`, `${pivotTable}.${relatedPivotKey}`);
+            sub.whereRaw("?? = ??", [
+                `${pivotTable}.${foreignPivotKey}`,
+                `${parentTable}.${localKey}`,
+            ]);
+        }
+        else if (rel instanceof BelongsTo) {
+            const foreignKey = toSnakeCase(rel.foreignKey);
+            const localKey = toSnakeCase(rel.localKey || "id");
+            sub.whereRaw("?? = ??", [
+                `${relatedTable}.${localKey}`,
+                `${parentTable}.${foreignKey}`,
+            ]);
+        }
+        else if (rel instanceof MorphMany || rel instanceof MorphOne) {
+            const foreignKey = toSnakeCase(rel.idColumn || rel.foreignKey);
+            const localKey = toSnakeCase(rel.localKey || "id");
+            const typeColumn = toSnakeCase(rel.typeColumn);
+            sub.where(`${relatedTable}.${typeColumn}`, rel.morphType);
+            sub.whereRaw("CAST(?? AS TEXT) = CAST(?? AS TEXT)", [
+                `${relatedTable}.${foreignKey}`,
+                `${parentTable}.${localKey}`,
+            ]);
+        }
+        else {
+            // HasOne or HasMany
+            const foreignKey = toSnakeCase(rel.foreignKey);
+            const localKey = toSnakeCase(rel.localKey || "id");
+            sub.whereRaw("?? = ??", [
+                `${relatedTable}.${foreignKey}`,
+                `${parentTable}.${localKey}`,
+            ]);
+        }
+        if (rel.related.softDeletes) {
+            const delCol = toSnakeCase(rel.related.deletedAtColumn || "deleted_at");
+            sub.whereNull(`${relatedTable}.${delCol}`);
+        }
+        if (callback) {
+            const relatedQuery = new ModelQueryBuilder(rel.related, sub);
+            callback(relatedQuery);
+        }
+    }
+    /**
+     * Adds a relationship count condition to the query with where clause.
+     */
+    has(relation, operator = ">=", count = 1, boolean = "and", callback) {
+        if (operator === ">=" && count === 1 && !callback) {
+            return boolean === "or"
+                ? this.orWhereHas(relation)
+                : this.whereHas(relation);
+        }
+        if (((operator === "<" && count === 1) ||
+            (operator === "=" && count === 0)) &&
+            !callback) {
+            return boolean === "or"
+                ? this.orWhereDoesntHave(relation)
+                : this.whereDoesntHave(relation);
+        }
+        const knex = getKnex();
+        const sub = knex.queryBuilder();
+        this.buildRelationSubquery(sub, relation, callback, true);
+        const rawClause = `(${sub.toQuery()}) ${operator} ?`;
+        if (boolean === "or") {
+            this.knexBuilder.orWhereRaw(rawClause, [count]);
+        }
+        else {
+            this.knexBuilder.whereRaw(rawClause, [count]);
+        }
+        return this;
+    }
+    /**
+     * Adds an OR relationship count condition to the query.
+     */
+    orHas(relation, operator = ">=", count = 1, callback) {
+        return this.has(relation, operator, count, "or", callback);
+    }
+    /**
+     * Adds a relationship existence condition with an optional callback constraint.
+     */
+    whereHas(relation, callback) {
+        this.knexBuilder.whereExists((sub) => {
+            this.buildRelationSubquery(sub, relation, callback, false);
+        });
+        return this;
+    }
+    /**
+     * Adds an OR relationship existence condition with an optional callback constraint.
+     */
+    orWhereHas(relation, callback) {
+        this.knexBuilder.orWhereExists((sub) => {
+            this.buildRelationSubquery(sub, relation, callback, false);
+        });
+        return this;
+    }
+    /**
+     * Adds a relationship absence condition with an optional callback constraint.
+     */
+    whereDoesntHave(relation, callback) {
+        this.knexBuilder.whereNotExists((sub) => {
+            this.buildRelationSubquery(sub, relation, callback, false);
+        });
+        return this;
+    }
+    /**
+     * Adds an OR relationship absence condition with an optional callback constraint.
+     */
+    orWhereDoesntHave(relation, callback) {
+        this.knexBuilder.orWhereNotExists((sub) => {
+            this.buildRelationSubquery(sub, relation, callback, false);
+        });
+        return this;
+    }
+    /**
+     * Alias for whereDoesntHave.
+     */
+    doesntHave(relation) {
+        return this.whereDoesntHave(relation);
+    }
+    /**
+     * Alias for orWhereDoesntHave.
+     */
+    orDoesntHave(relation) {
+        return this.orWhereDoesntHave(relation);
+    }
+    /**
+     * Adds subquery counts for related models as `{relation}_count`.
+     */
+    withCount(...relations) {
+        const normalized = {};
+        for (const item of relations) {
+            if (typeof item === "string") {
+                normalized[item] = undefined;
+            }
+            else if (Array.isArray(item)) {
+                for (const subItem of item) {
+                    normalized[subItem] = undefined;
+                }
+            }
+            else if (typeof item === "object" && item !== null) {
+                for (const [key, callback] of Object.entries(item)) {
+                    normalized[key] = callback;
+                }
+            }
+        }
+        // Ensure main table columns are selected if no columns have been explicitly selected yet
+        const statements = this.knexBuilder._statements || [];
+        const hasColumns = statements.some((s) => s.grouping === "columns");
+        if (!hasColumns) {
+            this.knexBuilder.select(`${this.modelClass.table}.*`);
+        }
+        const knex = getKnex();
+        for (const [relName, callback] of Object.entries(normalized)) {
+            const sub = knex.queryBuilder();
+            this.buildRelationSubquery(sub, relName, callback, true);
+            const colAlias = `${toSnakeCase(relName)}_count`;
+            this.knexBuilder.select(knex.raw(`(${sub.toQuery()}) as ??`, [colAlias]));
+        }
+        return this;
+    }
+    /**
+     * Executes query and returns hydrated Model instances.
+     */
+    async get() {
+        this.applyGlobalScopes();
+        const rows = await this.knexBuilder;
+        const models = rows.map((row) => {
+            return new this.modelClass(row, false);
+        });
+        if (this.eagerRelations.length > 0 && models.length > 0) {
+            await eagerLoadRelations(models, this.eagerRelations);
+        }
+        return models;
+    }
+    /**
+     * Returns the first matched Model instance or null.
+     */
+    async first() {
+        const models = await this.limit(1).get();
+        return models[0] || null;
+    }
+    /**
+     * Returns the first matched Model or throws an error.
+     */
+    async firstOrFail() {
+        const model = await this.first();
+        if (!model) {
+            throw DatabaseError.Internal(`[veap:ORM] Model ${this.modelClass.name} not found matching query.`);
+        }
+        return model;
+    }
+    /**
+     * Get the first record matching the attributes or instantiate it.
+     */
+    async firstOrNew(attributes, values = {}) {
+        const existing = await this.where(attributes).first();
+        if (existing) {
+            return existing;
+        }
+        return new this.modelClass({ ...attributes, ...values }, true);
+    }
+    /**
+     * Get the first record matching the attributes or create it.
+     */
+    async firstOrCreate(attributes, values = {}) {
+        const existing = await this.where(attributes).first();
+        if (existing) {
+            return existing;
+        }
+        const instance = new this.modelClass({ ...attributes, ...values }, true);
+        await instance.save();
+        return instance;
+    }
+    /**
+     * Create or update a record matching the attributes, and fill it with values.
+     */
+    async updateOrCreate(attributes, values = {}) {
+        const existing = await this.where(attributes).first();
+        if (existing) {
+            existing.fill(values);
+            await existing.save();
+            return existing;
+        }
+        const instance = new this.modelClass({ ...attributes, ...values }, true);
+        await instance.save();
+        return instance;
+    }
+    /**
+     * Finds a record by its primary key.
+     */
+    async find(id) {
+        const pk = this.modelClass.primaryKey || "id";
+        return await this.where(pk, id).first();
+    }
+    /**
+     * Finds a record by primary key or throws an error.
+     */
+    async findOrFail(id) {
+        const model = await this.find(id);
+        if (!model) {
+            throw DatabaseError.Internal(`[veap:ORM] Record not found in ${this.modelClass.name} with ID: ${id}`);
+        }
+        return model;
+    }
+    /**
+     * Counts rows matching criteria.
+     */
+    async count(column = "*") {
+        this.applyGlobalScopes();
+        const col = column === "*" ? "*" : toSnakeCase(column);
+        const [result] = await this.knexBuilder.count({ count: col });
+        const countVal = result?.count;
+        return Number(countVal || 0);
+    }
+    /**
+     * Checks if any records exist matching criteria.
+     */
+    async exists() {
+        return (await this.count()) > 0;
+    }
+    /**
+     * Plucks a single column's values into an array.
+     */
+    async pluck(column) {
+        this.applyGlobalScopes();
+        const col = toSnakeCase(column);
+        const rows = await this.knexBuilder.select(col);
+        return rows.map((row) => row[col] !== undefined ? row[col] : row[column]);
+    }
+    /**
+     * Paginates results.
+     */
+    async paginate(page = 1, perPage = 15) {
+        this.applyGlobalScopes();
+        const countBuilder = this.knexBuilder.clone().clearSelect().clearOrder();
+        const [countResult] = await countBuilder.count({ total: "*" });
+        const total = Number(countResult?.total || 0);
+        const offset = Math.max(0, (page - 1) * perPage);
+        const data = await this.offset(offset).limit(perPage).get();
+        const lastPage = Math.max(1, Math.ceil(total / perPage));
+        return {
+            data,
+            total,
+            page,
+            currentPage: page,
+            perPage,
+            lastPage,
+        };
+    }
+    /**
+     * Bulk updates matching records.
+     */
+    async update(attributes) {
+        this.applyGlobalScopes();
+        const converted = {};
+        const casts = this.modelClass?.casts || {};
+        const knex = getKnex();
+        const clientType = knex.client?.config?.client;
+        for (const [k, v] of Object.entries(attributes)) {
+            const col = toSnakeCase(k);
+            const castType = casts[k] || casts[col] || casts[toCamelCase(k)];
+            converted[col] = serializeForStorage(v, castType, clientType);
+        }
+        return await this.knexBuilder.update(converted);
+    }
+    /**
+     * Bulk deletes matching records (soft-deletes if softDeletes is enabled).
+     */
+    async delete() {
+        if (this.modelClass?.softDeletes) {
+            this.applyGlobalScopes();
+            const col = toSnakeCase(this.modelClass.deletedAtColumn || "deleted_at");
+            return await this.update({ [col]: new Date() });
+        }
+        this.applyGlobalScopes();
+        return await this.knexBuilder.delete();
+    }
+    /**
+     * Bulk force-deletes matching records (hard delete regardless of softDeletes setting).
+     */
+    async forceDelete() {
+        return await this.knexBuilder.delete();
+    }
+    /**
+     * Bulk restores soft-deleted matching records.
+     */
+    async restore() {
+        if (this.modelClass?.softDeletes) {
+            if (this._onlyTrashed) {
+                this.applyGlobalScopes();
+            }
+            const col = toSnakeCase(this.modelClass.deletedAtColumn || "deleted_at");
+            return await this.update({ [col]: null });
+        }
+        return 0;
+    }
+    /**
+     * Increments column value.
+     */
+    async increment(column, amount = 1) {
+        return await this.knexBuilder.increment(toSnakeCase(column), amount);
+    }
+    /**
+     * Decrements column value.
+     */
+    async decrement(column, amount = 1) {
+        return await this.knexBuilder.decrement(toSnakeCase(column), amount);
+    }
+    toSQL() {
+        this.applyGlobalScopes();
+        return this.knexBuilder.toSQL();
+    }
+}