@warlock.js/cascade 4.0.162 → 4.0.164

package/cjs/query-builder/query-builder.js

@@ -0,0 +1,1070 @@
+'use strict';/**
+ * Pure Query Builder Base Class
+ *
+ * Driver-agnostic operation recorder. All fluent methods push typed entries into
+ * `operations[]`. No SQL, no driver references, no table property, no execution.
+ *
+ * ┌─────────────────────────────────────────────────┐
+ * │  Usage contexts                                 │
+ * │  (a) Subclassed — PG / Mongo / MySQL / …       │
+ * │  (b) Instantiated directly (new QueryBuilder()) │
+ * │      inside callbacks for:                      │
+ * │      • nested where groups                      │
+ * │      • joinWith constraints                     │
+ * │      • whereExists / whereHas subqueries        │
+ * └─────────────────────────────────────────────────┘
+ *
+ * Design rules:
+ *  - `table` / alias are NOT here — the parser gets them from the executor.
+ *  - `opIndex` is protected so subclasses can rebuild after direct mutation.
+ *  - Op type names are stable — parsers switch on them; no renaming without
+ *    a parser update.
+ *  - OR-variants keep distinct op types (orWhere, orWhereColumn, …) so existing
+ *    parsers that switch on type need no changes.
+ *  - `joinWith` eagerly resolves callbacks → subOps at record time so the
+ *    driver executor receives a plain data structure, not a live function.
+ *
+ * @module cascade/query-builder
+ */
+// ============================================================================
+// QUERY BUILDER — CONCRETE, DIRECTLY INSTANTIABLE
+// ============================================================================
+/**
+ * Pure, driver-agnostic query builder.
+ *
+ * Records operations in `operations[]`. Subclasses own execution, parsing, and
+ * driver-specific clause generation. Safe to instantiate directly inside
+ * callbacks where only operation recording is needed.
+ *
+ * @example
+ * ```ts
+ * // Driver subclass usage:
+ * const users = await User.query()
+ *   .select(["id", "name"])
+ *   .where("status", "active")
+ *   .where(q => q.where("role", "admin").orWhere("role", "mod"))
+ *   .orderBy("createdAt", "desc")
+ *   .limit(10)
+ *   .get();
+ *
+ * // Direct instantiation (callback context — no driver needed):
+ * joinWith({ actions: q => q.where("status", "pending").limit(5) });
+ * // The sub-QB's operations[] are captured and stored in the joinWith op data.
+ * ```
+ */
+class QueryBuilder {
+    // ════════════════════════════════════════════════════════
+    // OPERATION STORE
+    // ════════════════════════════════════════════════════════
+    /** Flat, ordered list of recorded operations. Public for parser access. */
+    operations = [];
+    /**
+     * type → ordered list of indices into `operations[]`.
+     *
+     * Protected (not private) so:
+     *  - `rebuildIndex()` can reset it after direct `operations[]` mutation.
+     *  - Subclasses can inspect it without unsafe casts.
+     *
+     * External consumers should use `getOps(type)` instead.
+     */
+    opIndex = new Map();
+    // ════════════════════════════════════════════════════════
+    // SCOPE STATE  (injected by Model.query(), consumed before execution)
+    // ════════════════════════════════════════════════════════
+    /** Global scope definitions injected by Model.query(). Keyed by scope name. */
+    pendingGlobalScopes;
+    /** Local scope callbacks injected by Model.query(). Applied on demand via scope(). */
+    availableLocalScopes;
+    /** Names of global scopes that have been intentionally disabled. */
+    disabledGlobalScopes = new Set();
+    /** True once the driver subclass has applied pending scopes. */
+    scopesApplied = false;
+    // ════════════════════════════════════════════════════════
+    // RELATION STATE  (consumed by driver subclass at execute time)
+    // ════════════════════════════════════════════════════════
+    /** Relations to eager-load via separate queries. */
+    eagerLoadRelations = new Map();
+    /** Relation names to count alongside results. */
+    countRelations = [];
+    /** Relation definition map injected from the owning Model. */
+    relationDefinitions;
+    /** The Model class reference, required for relation resolution. */
+    modelClass;
+    // ════════════════════════════════════════════════════════
+    // CORE INTERNALS
+    // ════════════════════════════════════════════════════════
+    /**
+     * Append an operation to `operations[]` and update `opIndex`.
+     * Every fluent method calls this.
+     */
+    addOperation(type, data) {
+        const idx = this.operations.length;
+        this.operations.push({ type, data });
+        const list = this.opIndex.get(type);
+        if (list) {
+            list.push(idx);
+        }
+        else {
+            this.opIndex.set(type, [idx]);
+        }
+    }
+    /**
+     * Return all recorded operations of the specified types in original
+     * insertion order.
+     *
+     * @example
+     * builder.getOps("where", "orWhere", "whereIn")
+     */
+    getOps(...types) {
+        if (types.length === 1) {
+            return (this.opIndex.get(types[0]) ?? []).map((i) => this.operations[i]);
+        }
+        const result = [];
+        for (const type of types) {
+            for (const idx of this.opIndex.get(type) ?? []) {
+                result.push({ idx, op: this.operations[idx] });
+            }
+        }
+        return result.sort((a, b) => a.idx - b.idx).map((r) => r.op);
+    }
+    /**
+     * Rebuild `opIndex` from scratch.
+     *
+     * Call this after any direct mutation of `this.operations[]` (e.g. scope
+     * injection, joinWith consumption in the executor, clone post-processing).
+     */
+    rebuildIndex() {
+        this.opIndex = new Map();
+        for (let i = 0; i < this.operations.length; i++) {
+            const type = this.operations[i].type;
+            const list = this.opIndex.get(type);
+            if (list) {
+                list.push(i);
+            }
+            else {
+                this.opIndex.set(type, [i]);
+            }
+        }
+    }
+    /**
+     * Factory for sub-QueryBuilders used inside callbacks.
+     *
+     * Override in driver subclasses to return a driver-typed instance, so that
+     * driver-specific methods (e.g. `whereArrayContains`) are available inside
+     * nested `where(q => ...)` / `whereHas` / `joinWith` callbacks.
+     *
+     * @example
+     * // In PostgresQueryBuilder:
+     * protected override subQuery(): QueryBuilder {
+     *   return new PostgresQueryBuilder("__sub__", this.dataSource);
+     * }
+     */
+    subQuery() {
+        return new QueryBuilder();
+    }
+    /**
+     * Shallow-clone this builder — copies operations, opIndex, and all shared state.
+     *
+     * Subclasses MUST call `super.clone()` and then copy their own fields
+     * (dataSource, joinRelations, …).
+     */
+    clone() {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        cloned.operations = [...this.operations];
+        cloned.opIndex = new Map(Array.from(this.opIndex.entries()).map(([k, v]) => [k, [...v]]));
+        cloned.pendingGlobalScopes = this.pendingGlobalScopes;
+        cloned.availableLocalScopes = this.availableLocalScopes;
+        cloned.disabledGlobalScopes = new Set(this.disabledGlobalScopes);
+        cloned.scopesApplied = this.scopesApplied;
+        cloned.eagerLoadRelations = new Map(this.eagerLoadRelations);
+        cloned.countRelations = [...this.countRelations];
+        cloned.relationDefinitions = this.relationDefinitions;
+        cloned.modelClass = this.modelClass;
+        return cloned;
+    }
+    // ════════════════════════════════════════════════════════
+    // SCOPES
+    // ════════════════════════════════════════════════════════
+    /** Disable one or more named global scopes for this query. */
+    withoutGlobalScope(...scopeNames) {
+        scopeNames.forEach((name) => this.disabledGlobalScopes.add(name));
+        return this;
+    }
+    /** Disable ALL pending global scopes for this query. */
+    withoutGlobalScopes() {
+        this.pendingGlobalScopes?.forEach((_, name) => this.disabledGlobalScopes.add(name));
+        return this;
+    }
+    /**
+     * Apply a registered local scope by name.
+     * @throws if no local scopes are available or the named scope is not found
+     */
+    scope(scopeName, ...args) {
+        if (!this.availableLocalScopes) {
+            throw new Error("No local scopes available on this query builder.");
+        }
+        const cb = this.availableLocalScopes.get(scopeName);
+        if (!cb)
+            throw new Error(`Local scope "${scopeName}" not found.`);
+        cb(this, ...args);
+        return this;
+    }
+    where(...args) {
+        if (args.length === 1 && typeof args[0] === "function") {
+            const sub = this.subQuery();
+            args[0](sub);
+            this.addOperation("where", { nested: sub.operations });
+        }
+        else if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+            for (const [key, value] of Object.entries(args[0])) {
+                this.addOperation("where", { field: key, operator: "=", value });
+            }
+        }
+        else if (args.length === 2) {
+            this.addOperation("where", { field: args[0], operator: "=", value: args[1] });
+        }
+        else {
+            this.addOperation("where", { field: args[0], operator: args[1], value: args[2] });
+        }
+        return this;
+    }
+    orWhere(...args) {
+        if (args.length === 1 && typeof args[0] === "function") {
+            const sub = this.subQuery();
+            args[0](sub);
+            this.addOperation("orWhere", { nested: sub.operations });
+        }
+        else if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+            for (const [key, value] of Object.entries(args[0])) {
+                this.addOperation("orWhere", { field: key, operator: "=", value });
+            }
+        }
+        else if (args.length === 2) {
+            this.addOperation("orWhere", { field: args[0], operator: "=", value: args[1] });
+        }
+        else {
+            this.addOperation("orWhere", { field: args[0], operator: args[1], value: args[2] });
+        }
+        return this;
+    }
+    /**
+     * Raw WHERE expression in the target dialect (AND).
+     *
+     * @example
+     * q.whereRaw("age > ? AND role = ?", [18, "admin"])           // SQL
+     * q.whereRaw({ $expr: { $gt: ["$stock", "$reserved"] } })     // MongoDB
+     */
+    whereRaw(expression, bindings) {
+        this.addOperation("whereRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    /** Raw OR WHERE expression. */
+    orWhereRaw(expression, bindings) {
+        this.addOperation("orWhereRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — COLUMN COMPARISONS
+    // ════════════════════════════════════════════════════════
+    /**
+     * Compare two columns directly (AND).
+     * @example q.whereColumn("stock", ">", "reserved")
+     */
+    whereColumn(first, operator, second) {
+        this.addOperation("whereColumn", { first, operator, second });
+        return this;
+    }
+    /** Compare two columns directly (OR). */
+    orWhereColumn(first, operator, second) {
+        this.addOperation("orWhereColumn", { first, operator, second });
+        return this;
+    }
+    /** Compare multiple column pairs in one call. */
+    whereColumns(comparisons) {
+        for (const [left, operator, right] of comparisons) {
+            this.whereColumn(left, operator, right);
+        }
+        return this;
+    }
+    /**
+     * Field value must fall between two other column values.
+     * Stored as a `whereBetween` op with `useColumns: true` so the SQL parser
+     * knows to quote the values as identifiers rather than bind them.
+     */
+    whereBetweenColumns(field, lowerColumn, upperColumn) {
+        this.addOperation("whereBetween", { field, lowerColumn, upperColumn, useColumns: true });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — STANDARD COMPARISON OPERATORS
+    // ════════════════════════════════════════════════════════
+    /** WHERE field IN values. */
+    whereIn(field, values) {
+        this.addOperation("whereIn", { field, values });
+        return this;
+    }
+    /** WHERE field NOT IN values. */
+    whereNotIn(field, values) {
+        this.addOperation("whereNotIn", { field, values });
+        return this;
+    }
+    /** WHERE field IS NULL. */
+    whereNull(field) {
+        this.addOperation("whereNull", { field });
+        return this;
+    }
+    /** WHERE field IS NOT NULL. */
+    whereNotNull(field) {
+        this.addOperation("whereNotNull", { field });
+        return this;
+    }
+    /** WHERE field BETWEEN low AND high. */
+    whereBetween(field, range) {
+        this.addOperation("whereBetween", { field, range });
+        return this;
+    }
+    /** WHERE field NOT BETWEEN low AND high. */
+    whereNotBetween(field, range) {
+        this.addOperation("whereNotBetween", { field, range });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — PATTERN MATCHING
+    // ════════════════════════════════════════════════════════
+    /**
+     * LIKE pattern match (AND).
+     * @example q.whereLike("email", "%@gmail.com")
+     */
+    whereLike(field, pattern) {
+        const patternStr = pattern instanceof RegExp ? pattern.source : pattern;
+        this.addOperation("whereLike", { field, pattern: patternStr });
+        return this;
+    }
+    /** NOT LIKE pattern match. */
+    whereNotLike(field, pattern) {
+        const patternStr = pattern instanceof RegExp ? pattern.source : pattern;
+        this.addOperation("whereNotLike", { field, pattern: patternStr });
+        return this;
+    }
+    /** Starts with a prefix. */
+    whereStartsWith(field, value) {
+        return this.whereLike(field, `${value}%`);
+    }
+    /** Does NOT start with a prefix. */
+    whereNotStartsWith(field, value) {
+        return this.whereNotLike(field, `${value}%`);
+    }
+    /** Ends with a suffix. */
+    whereEndsWith(field, value) {
+        return this.whereLike(field, `%${value}`);
+    }
+    /** Does NOT end with a suffix. */
+    whereNotEndsWith(field, value) {
+        return this.whereNotLike(field, `%${value}`);
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — DATE/TIME PARTIALS
+    // ════════════════════════════════════════════════════════
+    /**
+     * Match on date portion only (time ignored).
+     * @example q.whereDate("createdAt", "2024-05-01")
+     */
+    whereDate(field, value) {
+        this.addOperation("whereDate", { field, value });
+        return this;
+    }
+    /** Alias for whereDate. */
+    whereDateEquals(field, value) {
+        return this.whereDate(field, value);
+    }
+    /** Field date is before value. */
+    whereDateBefore(field, value) {
+        this.addOperation("whereDateBefore", { field, value });
+        return this;
+    }
+    /** Field date is after value. */
+    whereDateAfter(field, value) {
+        this.addOperation("whereDateAfter", { field, value });
+        return this;
+    }
+    /** Field date is within a range [from, to]. */
+    whereDateBetween(field, range) {
+        this.addOperation("whereDateBetween", { field, range });
+        return this;
+    }
+    /** Field date is NOT within a range. */
+    whereDateNotBetween(field, range) {
+        this.addOperation("whereNotBetween", { field, range });
+        return this;
+    }
+    /**
+     * Match on the time portion of a datetime field.
+     * Emits a `whereRaw` op with a driver-agnostic marker; the driver parser
+     * rewrites it to the appropriate SQL (`TIME(field) = ?`) or Mongo expression.
+     */
+    whereTime(field, value) {
+        this.addOperation("whereRaw", {
+            expression: `TIME(${field}) = ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    /**
+     * Day-of-month from a date field (1–31).
+     * Uses a `whereRaw` op so SQL parsers get the `EXTRACT` expression directly.
+     * MongoDB drivers override to emit `$dayOfMonth`.
+     */
+    whereDay(field, value) {
+        this.addOperation("whereRaw", {
+            expression: `EXTRACT(DAY FROM ${field}) = ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    /** Month extracted from a date field (1–12). */
+    whereMonth(field, value) {
+        this.addOperation("whereRaw", {
+            expression: `EXTRACT(MONTH FROM ${field}) = ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    /** Year extracted from a date field. */
+    whereYear(field, value) {
+        this.addOperation("whereRaw", {
+            expression: `EXTRACT(YEAR FROM ${field}) = ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — JSON / STRUCTURED DATA
+    // ════════════════════════════════════════════════════════
+    /**
+     * JSON/array path contains the given value.
+     * @example q.whereJsonContains("tags", "typescript")
+     */
+    whereJsonContains(path, value) {
+        this.addOperation("whereJsonContains", { path, value });
+        return this;
+    }
+    /** JSON/array path does NOT contain the value. */
+    whereJsonDoesntContain(path, value) {
+        this.addOperation("whereJsonDoesntContain", { path, value });
+        return this;
+    }
+    /**
+     * JSON path key exists.
+     * Uses a `whereRaw` so existing SQL parsers get `IS NOT NULL` immediately.
+     */
+    whereJsonContainsKey(path) {
+        this.addOperation("whereRaw", { expression: `${path} IS NOT NULL`, bindings: [] });
+        return this;
+    }
+    /**
+     * Constrain the length of a JSON array at a path.
+     * @example q.whereJsonLength("tags", ">", 3)
+     */
+    whereJsonLength(path, operator, value) {
+        this.addOperation("whereRaw", {
+            expression: `jsonb_array_length(${path}) ${operator} ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    /** JSON path must resolve to an array. */
+    whereJsonIsArray(path) {
+        this.addOperation("whereRaw", {
+            expression: `jsonb_typeof(${path}) = 'array'`,
+            bindings: [],
+        });
+        return this;
+    }
+    /** JSON path must resolve to an object. */
+    whereJsonIsObject(path) {
+        this.addOperation("whereRaw", {
+            expression: `jsonb_typeof(${path}) = 'object'`,
+            bindings: [],
+        });
+        return this;
+    }
+    /**
+     * Constrain the number of elements in an array field.
+     * @example q.whereArrayLength("roles", ">=", 2)
+     */
+    whereArrayLength(field, operator, value) {
+        this.addOperation("whereRaw", {
+            expression: `array_length(${field}, 1) ${operator} ?`,
+            bindings: [value],
+        });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // WHERE CLAUSES — CONVENIENCE SHORTCUTS
+    // ════════════════════════════════════════════════════════
+    /** WHERE id = value. */
+    whereId(value) {
+        return this.where("id", value);
+    }
+    /** WHERE id IN values. */
+    whereIds(values) {
+        return this.whereIn("id", values);
+    }
+    /** WHERE uuid = value. */
+    whereUuid(value) {
+        return this.where("uuid", value);
+    }
+    /** WHERE ulid = value. */
+    whereUlid(value) {
+        return this.where("ulid", value);
+    }
+    /**
+     * Full-text search across one or more fields.
+     * @example q.whereFullText(["title", "body"], "typescript")
+     */
+    whereFullText(fields, query) {
+        this.addOperation("whereFullText", {
+            fields: Array.isArray(fields) ? fields : [fields],
+            query,
+        });
+        return this;
+    }
+    /** Full-text search (OR). */
+    orWhereFullText(fields, query) {
+        return this.whereFullText(fields, query);
+    }
+    /** Alias for whereFullText with a single field. */
+    whereSearch(field, query) {
+        return this.whereFullText([field], query);
+    }
+    /**
+     * Text search with optional extra equality filters.
+     * MongoDB-style convenience shorthand.
+     */
+    textSearch(query, filters) {
+        if (filters) {
+            for (const [key, value] of Object.entries(filters))
+                this.where(key, value);
+        }
+        return this;
+    }
+    whereExists(param) {
+        if (typeof param === "function") {
+            const sub = this.subQuery();
+            param(sub);
+            this.addOperation("whereExists", { subquery: sub.operations });
+        }
+        else {
+            this.addOperation("whereNotNull", { field: param });
+        }
+        return this;
+    }
+    whereNotExists(param) {
+        if (typeof param === "function") {
+            const sub = this.subQuery();
+            param(sub);
+            this.addOperation("whereNotExists", { subquery: sub.operations });
+        }
+        else {
+            this.addOperation("whereNull", { field: param });
+        }
+        return this;
+    }
+    whereSize(field, ...args) {
+        const operator = args.length === 2 ? args[0] : "=";
+        const size = (args.length === 2 ? args[1] : args[0]);
+        return this.whereArrayLength(field, operator, size);
+    }
+    /**
+     * AND NOT wrapper — negate a nested group.
+     * @example q.whereNot(q => q.where("status", "banned").where("role", "user"))
+     */
+    whereNot(callback) {
+        const sub = this.subQuery();
+        callback(sub);
+        this.addOperation("whereNot", { nested: sub.operations });
+        return this;
+    }
+    /** OR NOT wrapper. */
+    orWhereNot(callback) {
+        const sub = this.subQuery();
+        callback(sub);
+        this.addOperation("orWhereNot", { nested: sub.operations });
+        return this;
+    }
+    join(...args) {
+        if (args.length === 3) {
+            this.addOperation("join", { table: args[0], localField: args[1], foreignField: args[2] });
+        }
+        else {
+            this.addOperation("join", args[0]);
+        }
+        return this;
+    }
+    leftJoin(...args) {
+        if (args.length === 3) {
+            this.addOperation("leftJoin", { table: args[0], localField: args[1], foreignField: args[2] });
+        }
+        else {
+            this.addOperation("leftJoin", args[0]);
+        }
+        return this;
+    }
+    rightJoin(...args) {
+        if (args.length === 3) {
+            this.addOperation("rightJoin", {
+                table: args[0],
+                localField: args[1],
+                foreignField: args[2],
+            });
+        }
+        else {
+            this.addOperation("rightJoin", args[0]);
+        }
+        return this;
+    }
+    innerJoin(...args) {
+        if (args.length === 3) {
+            this.addOperation("innerJoin", {
+                table: args[0],
+                localField: args[1],
+                foreignField: args[2],
+            });
+        }
+        else {
+            this.addOperation("innerJoin", args[0]);
+        }
+        return this;
+    }
+    fullJoin(...args) {
+        if (args.length === 3) {
+            this.addOperation("fullJoin", { table: args[0], localField: args[1], foreignField: args[2] });
+        }
+        else {
+            this.addOperation("fullJoin", args[0]);
+        }
+        return this;
+    }
+    /** CROSS JOIN. */
+    crossJoin(table) {
+        this.addOperation("crossJoin", { table });
+        return this;
+    }
+    /** Raw JOIN expression. Driver responsible for handling. */
+    joinRaw(expression, bindings) {
+        this.addOperation("joinRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // RELATION EAGER LOADING — JOIN-BASED (joinWith)
+    // ════════════════════════════════════════════════════════
+    /**
+     * Eager-load named relations via a single JOIN / $lookup query.
+     *
+     * Constraints are eagerly resolved at call time:
+     *  - Callbacks are invoked immediately → `subOps` stored in op data.
+     *  - Column shorthands are parsed into a `columns[]` array.
+     *
+     * The driver executor reads the `joinWith` op and uses the resolved data
+     * alongside its own relation definition map to emit the appropriate SQL JOIN
+     * or MongoDB $lookup stage.
+     *
+     * Supported arg forms (may be mixed):
+     *   - `"author"` / `["author", "category"]` — no constraint
+     *   - `{ author: "id,name" }` — column shorthand
+     *   - `{ actions: q => q.where("status","pending").limit(5) }` — callback
+     *
+     * @example
+     * Post.joinWith("author", "category")
+     * ChatMessage.joinWith({ actions: q => q.where("status", "pending").limit(5) })
+     * ChatMessage.joinWith({ org: "id,name", actions: q => q.orderBy("sort_order") })
+     */
+    joinWith(...args) {
+        const resolved = {};
+        for (const arg of args) {
+            if (typeof arg === "string") {
+                resolved[arg] = {};
+            }
+            else if (Array.isArray(arg)) {
+                for (const rel of arg)
+                    resolved[rel] = {};
+            }
+            else if (typeof arg === "object" && arg !== null) {
+                for (const [rel, constraint] of Object.entries(arg)) {
+                    if (typeof constraint === "function") {
+                        const sub = this.subQuery();
+                        constraint(sub);
+                        resolved[rel] = { subOps: sub.operations };
+                    }
+                    else if (typeof constraint === "string" && constraint !== "") {
+                        resolved[rel] = {
+                            columns: constraint
+                                .split(",")
+                                .map((s) => s.trim())
+                                .filter(Boolean),
+                        };
+                    }
+                    else {
+                        resolved[rel] = {};
+                    }
+                }
+            }
+        }
+        this.addOperation("joinWith", { resolved });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // RELATION EAGER LOADING — SEPARATE QUERIES (with)
+    // ════════════════════════════════════════════════════════
+    /**
+     * Eager-load relations via separate queries (N+1 avoided by batching).
+     *
+     * @example
+     * q.with("posts")
+     * q.with("posts", q => q.where("published", true))
+     * q.with({ posts: true, comments: q => q.limit(5) })
+     */
+    with(...args) {
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (typeof arg === "string") {
+                const next = args[i + 1];
+                if (typeof next === "function") {
+                    this.eagerLoadRelations.set(arg, next);
+                    i++;
+                }
+                else {
+                    this.eagerLoadRelations.set(arg, true);
+                }
+            }
+            else if (typeof arg === "object" && arg !== null) {
+                for (const [key, value] of Object.entries(arg)) {
+                    this.eagerLoadRelations.set(key, value);
+                }
+            }
+        }
+        return this;
+    }
+    /** Count related models alongside results. */
+    withCount(...relations) {
+        this.countRelations.push(...relations);
+        return this;
+    }
+    /**
+     * Filter to rows that have at least one related record.
+     * @example q.has("comments")
+     * @example q.has("comments", ">=", 3)
+     */
+    has(relation, operator, count) {
+        this.addOperation("has", { relation, operator: operator ?? ">=", count: count ?? 1 });
+        return this;
+    }
+    /**
+     * Filter to rows with related records matching a sub-query (AND).
+     * @example q.whereHas("comments", q => q.where("approved", true))
+     */
+    whereHas(relation, callback) {
+        const sub = this.subQuery();
+        callback(sub);
+        this.addOperation("whereHas", { relation, subquery: sub.operations });
+        return this;
+    }
+    /** Same as whereHas but OR-joined. */
+    orWhereHas(relation, callback) {
+        const sub = this.subQuery();
+        callback(sub);
+        this.addOperation("orWhereHas", { relation, subquery: sub.operations });
+        return this;
+    }
+    /** Filter to rows with NO related records. */
+    doesntHave(relation) {
+        this.addOperation("doesntHave", { relation });
+        return this;
+    }
+    /** Filter to rows with NO related records matching conditions. */
+    whereDoesntHave(relation, callback) {
+        const sub = this.subQuery();
+        callback(sub);
+        this.addOperation("whereDoesntHave", { relation, subquery: sub.operations });
+        return this;
+    }
+    select(...args) {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            this.addOperation("select", { fields: args[0] });
+        }
+        else if (args.length === 1 && typeof args[0] === "object" && !Array.isArray(args[0])) {
+            this.addOperation("select", { fields: args[0] });
+        }
+        else {
+            this.addOperation("select", { fields: args.flat() });
+        }
+        return this;
+    }
+    /** Select a field under an alias. @example q.selectAs("fullName", "name") */
+    selectAs(field, alias) {
+        this.addOperation("select", { fields: { [field]: alias } });
+        return this;
+    }
+    /**
+     * Raw SELECT expression.
+     * @example q.selectRaw("COUNT(*) AS total")
+     */
+    selectRaw(expression, bindings) {
+        this.addOperation("selectRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    /** Multiple raw SELECT expressions in one call. */
+    selectRawMany(definitions) {
+        for (const def of definitions) {
+            this.selectRaw({ [def.alias]: def.expression }, def.bindings);
+        }
+        return this;
+    }
+    /** Subquery as a named projected field. */
+    selectSub(expression, alias) {
+        this.addOperation("selectRaw", { expression: { [alias]: expression } });
+        return this;
+    }
+    /** Alias for selectSub. */
+    addSelectSub(expression, alias) {
+        return this.selectSub(expression, alias);
+    }
+    /**
+     * Aggregate function as a projected field.
+     * @example q.selectAggregate("price", "sum", "totalRevenue")
+     */
+    selectAggregate(field, aggregate, alias) {
+        return this.selectRaw({ [alias]: `${aggregate.toUpperCase()}(${field})` });
+    }
+    /** Existence check as a projected boolean field. */
+    selectExists(field, alias) {
+        return this.selectRaw({ [alias]: `${field} IS NOT NULL` });
+    }
+    /** COUNT as a projected field. */
+    selectCount(field, alias) {
+        return this.selectAggregate(field, "count", alias);
+    }
+    /**
+     * CASE / switch expression.
+     * @example q.selectCase([{ when: "status = 1", then: "'active'" }], "'inactive'", "statusLabel")
+     */
+    selectCase(cases, otherwise, alias) {
+        const caseExpr = cases.map((c) => `WHEN ${c.when} THEN ${c.then}`).join(" ");
+        return this.selectRaw({ [alias]: `CASE ${caseExpr} ELSE ${otherwise} END` });
+    }
+    /** IF/ELSE conditional field. */
+    selectWhen(condition, thenValue, elseValue, alias) {
+        return this.selectRaw({
+            [alias]: `CASE WHEN ${condition} THEN ${thenValue} ELSE ${elseValue} END`,
+        });
+    }
+    /**
+     * Driver-native projection manipulation.
+     * No-op in base — override in driver subclasses.
+     */
+    selectDriverProjection(_callback) {
+        return this;
+    }
+    /** JSON path extraction as a projected field. */
+    selectJson(path, alias) {
+        const parts = path.split("->");
+        const column = parts[0];
+        const jsonPath = parts.slice(1).join("->");
+        const expr = jsonPath ? `${column}->>'${jsonPath}'` : column;
+        return alias ? this.selectAs(expr, alias) : this.selectRaw(expr);
+    }
+    /** JSON extraction via raw expression. */
+    selectJsonRaw(_path, expression, alias) {
+        return this.selectRaw({ [alias]: expression });
+    }
+    /** Exclude a JSON path from projection. */
+    deselectJson(path) {
+        return this.deselect([path]);
+    }
+    /** String concatenation as a projected field. */
+    selectConcat(fields, alias) {
+        return this.selectRaw({ [alias]: fields.join(" || ") });
+    }
+    /** COALESCE (first non-null) as a projected field. */
+    selectCoalesce(fields, alias) {
+        return this.selectRaw({ [alias]: `COALESCE(${fields.join(", ")})` });
+    }
+    /** Window function expression. */
+    selectWindow(spec) {
+        this.addOperation("selectRaw", { expression: spec });
+        return this;
+    }
+    /** Exclude specific columns from results. */
+    deselect(fields) {
+        this.addOperation("deselect", { fields });
+        return this;
+    }
+    /**
+     * Remove all select operations (resets to wildcard).
+     * Uses `rebuildIndex()` — no unsafe casts.
+     */
+    clearSelect() {
+        this.operations = this.operations.filter((op) => !op.type.startsWith("select") && op.type !== "deselect");
+        this.rebuildIndex();
+        return this;
+    }
+    /** Alias for clearSelect. */
+    selectAll() {
+        return this.clearSelect();
+    }
+    /** Alias for clearSelect. */
+    selectDefault() {
+        return this.clearSelect();
+    }
+    /** Append additional fields to existing selection. */
+    addSelect(fields) {
+        this.addOperation("select", { fields, add: true });
+        return this;
+    }
+    /**
+     * Record a DISTINCT flag (fluent — does not execute).
+     * Subclasses expose a separate async `distinct(field)` execution method.
+     */
+    distinctValues(fields) {
+        const fieldList = fields ? (Array.isArray(fields) ? fields : [fields]) : [];
+        this.addOperation("distinct", { fields: fieldList });
+        return this;
+    }
+    orderBy(...args) {
+        if (typeof args[0] === "string") {
+            this.addOperation("orderBy", {
+                field: args[0],
+                direction: args[1] ?? "asc",
+            });
+        }
+        else {
+            for (const [field, direction] of Object.entries(args[0])) {
+                this.addOperation("orderBy", { field, direction });
+            }
+        }
+        return this;
+    }
+    /** ORDER BY descending shorthand. */
+    orderByDesc(field) {
+        return this.orderBy(field, "desc");
+    }
+    /**
+     * Raw ORDER BY expression.
+     * @example q.orderByRaw("RANDOM()")
+     * @example q.orderByRaw({ $meta: "textScore" })
+     */
+    orderByRaw(expression, bindings) {
+        this.addOperation("orderByRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    /**
+     * Random order. Maps to `RANDOM()` in SQL or `$sample` in MongoDB.
+     * @param limit - Optional limit (required for MongoDB $sample)
+     */
+    orderByRandom(limit) {
+        this.addOperation("orderByRaw", { expression: "RANDOM()" });
+        if (limit !== undefined)
+            this.limit(limit);
+        return this;
+    }
+    /** Order ascending by a date column (oldest first). */
+    oldest(column = "createdAt") {
+        return this.orderBy(column, "asc");
+    }
+    // ════════════════════════════════════════════════════════
+    // LIMIT / OFFSET
+    // ════════════════════════════════════════════════════════
+    /** Limit number of results. */
+    limit(value) {
+        this.addOperation("limit", { value });
+        return this;
+    }
+    /** Skip N results (OFFSET). */
+    skip(value) {
+        this.addOperation("offset", { value });
+        return this;
+    }
+    /** Alias for skip. */
+    offset(value) {
+        return this.skip(value);
+    }
+    /** Alias for limit. */
+    take(value) {
+        return this.limit(value);
+    }
+    // ════════════════════════════════════════════════════════
+    // GROUPING / AGGREGATION
+    // ════════════════════════════════════════════════════════
+    /**
+     * GROUP BY clause.
+     * @example q.groupBy("status")
+     * @example q.groupBy(["year", "month"])
+     */
+    groupBy(input) {
+        const fields = Array.isArray(input) ? input : [input];
+        this.addOperation("groupBy", { fields });
+        return this;
+    }
+    /** Raw GROUP BY expression. */
+    groupByRaw(expression, bindings) {
+        this.addOperation("groupBy", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    having(...args) {
+        if (args.length === 1) {
+            const input = args[0];
+            if (Array.isArray(input)) {
+                if (input.length === 2) {
+                    this.addOperation("having", { field: input[0], operator: "=", value: input[1] });
+                }
+                else {
+                    this.addOperation("having", { field: input[0], operator: input[1], value: input[2] });
+                }
+            }
+            else {
+                for (const [key, value] of Object.entries(input)) {
+                    this.addOperation("having", { field: key, operator: "=", value });
+                }
+            }
+        }
+        else if (args.length === 2) {
+            this.addOperation("having", { field: args[0], operator: "=", value: args[1] });
+        }
+        else {
+            this.addOperation("having", { field: args[0], operator: args[1], value: args[2] });
+        }
+        return this;
+    }
+    /** Raw HAVING expression. */
+    havingRaw(expression, bindings) {
+        this.addOperation("havingRaw", { expression, bindings: bindings ?? [] });
+        return this;
+    }
+    // ════════════════════════════════════════════════════════
+    // UTILITY / CONTROL FLOW
+    // ════════════════════════════════════════════════════════
+    /**
+     * Side-effect tap — executes callback synchronously and returns `this`.
+     * @example q.where(...).tap(q => console.log(q.operations.length)).limit(10)
+     */
+    tap(callback) {
+        callback(this);
+        return this;
+    }
+    /**
+     * Conditionally apply query modifications.
+     *
+     * @example
+     * q.when(userId, (q, id) => q.where("userId", id))
+     * q.when(isAdmin, q => q.withoutGlobalScopes(), q => q.scope("active"))
+     */
+    when(condition, callback, otherwise) {
+        if (condition) {
+            callback(this, condition);
+        }
+        else if (otherwise) {
+            otherwise(this);
+        }
+        return this;
+    }
+}exports.QueryBuilder=QueryBuilder;//# sourceMappingURL=query-builder.js.map