@warlock.js/cascade 4.0.171 → 4.1.1

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

@@ -1,933 +0,0 @@
-'use strict';var dataSourceRegistry=require('../../data-source/data-source-registry.js'),registerModel=require('../../model/register-model.js'),queryBuilder=require('../../query-builder/query-builder.js'),postgresQueryParser=require('./postgres-query-parser.js');/**
- * PostgreSQL Query Builder
- *
- * Extends the pure QueryBuilder base with PostgreSQL-specific execution,
- * SQL generation, relation hydration, and scope management.
- *
- * @module cascade/drivers/postgres
- */
-// ============================================================================
-// HELPER
-// ============================================================================
-/**
- * Cast an Op[] to PostgresParserOperation[] — the shapes are compatible since
- * both have `type: string` and `data: Record<string, unknown>`.
- */
-function toParserOps(ops) {
-    return ops;
-}
-// ============================================================================
-// POSTGRES QUERY BUILDER
-// ============================================================================
-/**
- * PostgreSQL Query Builder.
- *
- * Collects query operations (via the base class) and delegates SQL generation
- * to `PostgresQueryParser`. Owns execution, hydration, and relation loading.
- *
- * @example
- * ```typescript
- * const users = await User.query()
- *   .select(["id", "name", "email"])
- *   .where("status", "active")
- *   .orderBy("createdAt", "desc")
- *   .limit(10)
- *   .get();
- * ```
- */
-class PostgresQueryBuilder extends queryBuilder.QueryBuilder {
-    table;
-    // ──────────────────────────────────────────────────────────────
-    // POSTGRES-SPECIFIC STATE
-    // ──────────────────────────────────────────────────────────────
-    /** Data source backing this builder. */
-    dataSource;
-    /** Hydration callback for transforming result rows into model instances. */
-    hydrateCallback;
-    /** Invoked before query execution. */
-    fetchingCallback;
-    /** Invoked after fetch but before hydration. */
-    hydratingCallback;
-    /** Invoked after fetch and hydration. */
-    fetchedCallback;
-    /**
-     * Map of relations registered via `joinWith()`.
-     * Keyed by dot-notation path (e.g. "organizationAiModel.aiModel").
-     */
-    joinRelations = new Map();
-    // ──────────────────────────────────────────────────────────────
-    // CONSTRUCTOR
-    // ──────────────────────────────────────────────────────────────
-    /**
-     * @param table - Target table name
-     * @param dataSource - Optional (uses default data source from registry if omitted)
-     */
-    constructor(table, dataSource) {
-        super();
-        this.table = table;
-        this.dataSource = dataSource ?? dataSourceRegistry.dataSourceRegistry.get();
-    }
-    // ──────────────────────────────────────────────────────────────
-    // DRIVER
-    // ──────────────────────────────────────────────────────────────
-    get driver() {
-        return this.dataSource.driver;
-    }
-    // ──────────────────────────────────────────────────────────────
-    // CLONE
-    // ──────────────────────────────────────────────────────────────
-    clone() {
-        const cloned = new PostgresQueryBuilder(this.table, this.dataSource);
-        // Copy base-class state
-        cloned.operations = [...this.operations];
-        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;
-        // Copy PG-specific state
-        cloned.hydrateCallback = this.hydrateCallback;
-        cloned.joinRelations = new Map(this.joinRelations);
-        return cloned;
-    }
-    // ============================================================================
-    // PG-SPECIFIC FLUENT METHODS
-    // ============================================================================
-    /**
-     * Native-query escape hatch. Passes `operations[]` to the callback for
-     * direct manipulation. Use sparingly — only when fluent API is insufficient.
-     *
-     * @example
-     * q.raw(ops => ops.push({ type: "whereRaw", data: { expression: "1=1" } }))
-     */
-    raw(callback) {
-        callback(this.operations);
-        return this;
-    }
-    /**
-     * Record a DISTINCT flag AND auto-select the field(s).
-     * In PostgreSQL, DISTINCT ON (col) requires the col to appear in SELECT.
-     *
-     * @example
-     * q.distinctValues("category")               // SELECT category … DISTINCT ON (category)
-     * q.distinctValues(["category", "status"])   // both fields in DISTINCT ON and SELECT
-     */
-    distinctValues(fields) {
-        // Record the base DISTINCT flag op
-        super.distinctValues(fields);
-        // Also add a select for the field(s) so they appear in the SELECT clause
-        if (fields) {
-            const fieldArr = Array.isArray(fields) ? fields : [fields];
-            this.addOperation("select", { fields: fieldArr });
-        }
-        return this;
-    }
-    /**
-     * Nearest-neighbour vector similarity search via pgvector cosine distance.
-     *
-     * Adds two operations atomically:
-     * 1. `selectRaw` → `1 - (column <=> $n::vector) AS <alias>`
-     *    Makes the similarity score available on every returned row.
-     * 2. `orderByRaw` → `column <=> $n::vector`
-     *    Tells the PostgreSQL query planner to use the IVFFlat/HNSW vector index.
-     *    Using the alias in ORDER BY would bypass the index — the raw expression is required.
-     *
-     * @example
-     * ```typescript
-     * const results = await Vector.query()
-     *   .where({ organization_id: "org-123", content_type: "summary" })
-     *   .similarTo("embedding", queryEmbedding)
-     *   .limit(5)
-     *   .get<VectorRow & { score: number }>();
-     * ```
-     */
-    similarTo(column, embedding, alias = "score") {
-        // pgvector expects the literal format: [n,n,n,...]
-        const literal = `[${embedding.join(",")}]`;
-        const quotedCol = this.driver.dialect.quoteIdentifier(column);
-        const quotedTable = this.driver.dialect.quoteIdentifier(this.table);
-        // 0 — Preserve all table columns.
-        //     Adding a selectRaw suppresses the parser's "SELECT *" fallback,
-        //     so we must explicitly include table.* before the score expression.
-        this.addOperation("selectRaw", {
-            expression: `${quotedTable}.*`,
-            bindings: [],
-        });
-        // 1 — Add similarity score to SELECT
-        this.addOperation("selectRaw", {
-            expression: `1 - (${quotedCol} <=> ?::vector) AS ${alias}`,
-            bindings: [literal],
-        });
-        // 2 — ORDER BY the raw expression so the vector index is used
-        this.addOperation("orderByRaw", {
-            expression: `${quotedCol} <=> ?::vector`,
-            bindings: [literal],
-        });
-        return this;
-    }
-    /** Set a hydration callback that transforms each result row. */
-    hydrate(callback) {
-        this.hydrateCallback = callback;
-        return this;
-    }
-    /** Register a callback invoked before query execution. */
-    onFetching(callback) {
-        this.fetchingCallback = callback;
-        return () => {
-            this.fetchingCallback = undefined;
-        };
-    }
-    /** Register a callback invoked after fetch but before hydration. */
-    onHydrating(callback) {
-        this.hydratingCallback = callback;
-        return () => {
-            this.hydratingCallback = undefined;
-        };
-    }
-    /** Register a callback invoked after fetch and hydration. */
-    onFetched(callback) {
-        this.fetchedCallback = callback;
-        return () => {
-            this.fetchedCallback = undefined;
-        };
-    }
-    // ============================================================================
-    // SCOPES
-    // ============================================================================
-    /** Apply pending global scopes to the operations list. */
-    applyPendingScopes() {
-        if (!this.pendingGlobalScopes || this.scopesApplied)
-            return;
-        const beforeOps = [];
-        const afterOps = [];
-        for (const [name, { callback, timing }] of this.pendingGlobalScopes) {
-            if (this.disabledGlobalScopes.has(name))
-                continue;
-            const temp = new PostgresQueryBuilder(this.table, this.dataSource);
-            callback(temp);
-            if (timing === "before") {
-                beforeOps.push(...temp.operations);
-            }
-            else {
-                afterOps.push(...temp.operations);
-            }
-        }
-        this.operations = [...beforeOps, ...this.operations, ...afterOps];
-        this.scopesApplied = true;
-    }
-    // ============================================================================
-    // WHERE — POSTGRES-SPECIFIC (driver.dialect required)
-    // ============================================================================
-    /** Array field contains a value (or object with key). */
-    whereArrayContains(field, value, key) {
-        const quotedField = this.driver.dialect.quoteIdentifier(field);
-        if (key) {
-            this.addOperation("whereRaw", {
-                expression: `${quotedField} @> ?::jsonb`,
-                bindings: [JSON.stringify([{ [key]: value }])],
-            });
-        }
-        else {
-            this.addOperation("whereRaw", {
-                expression: `? = ANY(${quotedField})`,
-                bindings: [value],
-            });
-        }
-        return this;
-    }
-    /** Array field does NOT contain a value (or object with key). */
-    whereArrayNotContains(field, value, key) {
-        const quotedField = this.driver.dialect.quoteIdentifier(field);
-        if (key) {
-            this.addOperation("whereRaw", {
-                expression: `NOT (${quotedField} @> ?::jsonb)`,
-                bindings: [JSON.stringify([{ [key]: value }])],
-            });
-        }
-        else {
-            this.addOperation("whereRaw", {
-                expression: `NOT (? = ANY(${quotedField}))`,
-                bindings: [value],
-            });
-        }
-        return this;
-    }
-    /** Array field contains value OR is empty. */
-    whereArrayHasOrEmpty(field, value, key) {
-        const quotedField = this.driver.dialect.quoteIdentifier(field);
-        if (key) {
-            this.addOperation("whereRaw", {
-                expression: `(${quotedField} @> ?::jsonb OR ${quotedField} = '[]'::jsonb OR ${quotedField} IS NULL)`,
-                bindings: [JSON.stringify([{ [key]: value }])],
-            });
-        }
-        else {
-            this.addOperation("whereRaw", {
-                expression: `(? = ANY(${quotedField}) OR array_length(${quotedField}, 1) IS NULL)`,
-                bindings: [value],
-            });
-        }
-        return this;
-    }
-    /** Array field does NOT contain value OR is empty. */
-    whereArrayNotHaveOrEmpty(field, value, key) {
-        const quotedField = this.driver.dialect.quoteIdentifier(field);
-        if (key) {
-            this.addOperation("whereRaw", {
-                expression: `(NOT (${quotedField} @> ?::jsonb) OR ${quotedField} = '[]'::jsonb OR ${quotedField} IS NULL)`,
-                bindings: [JSON.stringify([{ [key]: value }])],
-            });
-        }
-        else {
-            this.addOperation("whereRaw", {
-                expression: `(NOT (? = ANY(${quotedField})) OR array_length(${quotedField}, 1) IS NULL)`,
-                bindings: [value],
-            });
-        }
-        return this;
-    }
-    // ============================================================================
-    // joinWith — RESOLVE RELATION DEFINITIONS
-    // ============================================================================
-    /**
-     * Load relations via SQL JOINs (single query) with optional per-relation constraints.
-     *
-     * Supports:
-     * - `joinWith("author")` / `joinWith(["author", "category"])`
-     * - `joinWith({ actions: q => q.where("status", "pending").limit(5) })`
-     * - `joinWith({ organizationAiModel: "id,name", actions: q => q.orderBy("sort_order") })`
-     *
-     * @example
-     * ChatMessage.joinWith({
-     *   actions: q => q.where("status", "pending").orderBy("sort_order", "asc").limit(5),
-     *   organizationAiModel: "id,createdAt",
-     * })
-     */
-    joinWith(...args) {
-        const entries = [];
-        for (const arg of args) {
-            if (typeof arg === "string") {
-                entries.push({ path: arg });
-            }
-            else if (Array.isArray(arg)) {
-                for (const rel of arg) {
-                    entries.push({ path: rel });
-                }
-            }
-            else if (typeof arg === "object" && arg !== null) {
-                for (const [rel, val] of Object.entries(arg)) {
-                    entries.push({ path: rel, constraint: val });
-                }
-            }
-        }
-        for (const { path, constraint } of entries) {
-            // Parse each dot-notation path segment (supports "rel1.rel2" nesting)
-            const segments = path.split(".");
-            let currentModel = this.modelClass;
-            let currentPath = "";
-            for (let i = 0; i < segments.length; i++) {
-                const rawSeg = segments[i];
-                // String shorthand: "relName:col1,col2"
-                const colonIdx = rawSeg.indexOf(":");
-                const segName = colonIdx === -1 ? rawSeg : rawSeg.slice(0, colonIdx);
-                const segColumns = colonIdx === -1
-                    ? undefined
-                    : rawSeg
-                        .slice(colonIdx + 1)
-                        .split(",")
-                        .filter(Boolean);
-                currentPath = currentPath ? `${currentPath}.${segName}` : segName;
-                // If already registered, update if new select columns given; advance model
-                if (this.joinRelations.has(currentPath)) {
-                    const existing = this.joinRelations.get(currentPath);
-                    if (segColumns)
-                        existing.select = segColumns;
-                    // Apply constraint only on the deepest segment
-                    if (i === segments.length - 1 && constraint !== undefined) {
-                        existing.constraintOps = this._resolveConstraintOps(constraint);
-                    }
-                    currentModel =
-                        typeof existing.model === "string"
-                            ? registerModel.getModelFromRegistry(existing.model)
-                            : existing.model;
-                    continue;
-                }
-                if (!this.relationDefinitions)
-                    continue;
-                const def = (i === 0
-                    ? this.relationDefinitions
-                    : currentModel?.relations)?.[segName];
-                if (!def) {
-                    throw new Error(`Relation "${segName}" not found on model ${currentModel?.name ?? "unknown"}`);
-                }
-                // Resolve select columns: colon shorthand > constraint string > def.select
-                let selectColumns = segColumns ?? def.select;
-                let constraintOps;
-                if (i === segments.length - 1 && constraint !== undefined) {
-                    if (typeof constraint === "string") {
-                        selectColumns = constraint.split(",").filter(Boolean);
-                    }
-                    else {
-                        constraintOps = this._resolveConstraintOps(constraint);
-                    }
-                }
-                const alias = currentPath.replace(/\./g, "_");
-                this.joinRelations.set(currentPath, {
-                    alias,
-                    type: def.type,
-                    model: def.model,
-                    localKey: def.localKey,
-                    foreignKey: def.foreignKey,
-                    ownerKey: def.ownerKey,
-                    parentPath: i > 0 ? currentPath.substring(0, currentPath.lastIndexOf(".")) : null,
-                    relationName: segName,
-                    parentModel: currentModel,
-                    select: selectColumns,
-                    constraintOps,
-                });
-                currentModel =
-                    typeof def.model === "string" ? registerModel.getModelFromRegistry(def.model) : def.model;
-                if (!currentModel) {
-                    throw new Error(`Relation model not found for "${segName}" in "${currentPath}"`);
-                }
-            }
-        }
-        return this;
-    }
-    /** Run a joinWith constraint callback against a sub-QB and capture its operations. */
-    _resolveConstraintOps(constraint) {
-        if (typeof constraint === "string")
-            return [];
-        const sub = new PostgresQueryBuilder("__sub__", this.dataSource);
-        constraint(sub);
-        return sub.operations;
-    }
-    // ============================================================================
-    // EXECUTION METHODS
-    // ============================================================================
-    /**
-     * Execute the query and return all matching rows.
-     */
-    async get() {
-        this.applyPendingScopes();
-        this._processJoinWithOps();
-        this.applyJoinRelations();
-        if (this.fetchingCallback) {
-            await this.fetchingCallback(this);
-        }
-        const parser = new postgresQueryParser.PostgresQueryParser({
-            table: this.table,
-            operations: toParserOps(this.operations),
-        });
-        const { query = "", bindings = [] } = parser.parse();
-        try {
-            const result = await this.driver.query(query, bindings);
-            let records = result.rows;
-            const joinedData = this.extractJoinedRelationData(records);
-            if (this.hydratingCallback) {
-                await this.hydratingCallback(records, {});
-            }
-            if (this.hydrateCallback) {
-                records = records.map((row, index) => this.hydrateCallback(row, index));
-            }
-            this.attachJoinedRelations(records, joinedData);
-            if (this.fetchedCallback) {
-                await this.fetchedCallback(records, {});
-            }
-            this.operations = [];
-            return records;
-        }
-        catch (error) {
-            console.log("Error while executing:", query, bindings);
-            console.log("Query Builder Error:", error);
-            throw error;
-        }
-    }
-    /** Get first result. */
-    async first() {
-        const results = await this.limit(1).get();
-        return results[0] ?? null;
-    }
-    /** Get last result (by id desc). */
-    async last() {
-        const results = await this.orderByDesc("id").limit(1).get();
-        return results[0] ?? null;
-    }
-    /** Get random results. */
-    async random(limit) {
-        this.orderByRaw("RANDOM()");
-        if (limit)
-            this.limit(limit);
-        return this.get();
-    }
-    /** Get first or throw. */
-    async firstOrFail() {
-        const result = await this.first();
-        if (!result)
-            throw new Error("No records found");
-        return result;
-    }
-    /** Get first or call callback. */
-    async firstOr(callback) {
-        const result = await this.first();
-        return result ?? (await callback());
-    }
-    /** Get first or return null. */
-    async firstOrNull() {
-        return this.first();
-    }
-    /** Get first or return default. */
-    async firstOrNew(defaults) {
-        const result = await this.first();
-        return result ?? defaults;
-    }
-    /** Find by primary key. */
-    async find(id) {
-        return this.where("id", id).first();
-    }
-    /** Count matching rows. */
-    async count() {
-        this.applyPendingScopes();
-        const countOps = toParserOps([
-            ...this.operations.filter((op) => op.type.includes("where") || op.type.includes("join")),
-            { type: "selectRaw", data: { expression: 'COUNT(*) AS "count"' } },
-        ]);
-        const parser = new postgresQueryParser.PostgresQueryParser({ table: this.table, operations: countOps });
-        const { query = "", bindings = [] } = parser.parse();
-        const result = await this.driver.query(query, bindings);
-        return parseInt(result.rows[0]?.count ?? "0", 10);
-    }
-    /** SUM a numeric field. */
-    async sum(field) {
-        this.applyPendingScopes();
-        const result = await this.selectRaw(`SUM(${field}) as sum`).first();
-        return parseFloat(result?.sum ?? "0");
-    }
-    /** AVG of a numeric field. */
-    async avg(field) {
-        this.applyPendingScopes();
-        const result = await this.selectRaw(`AVG(${field}) as avg`).first();
-        return parseFloat(result?.avg ?? "0");
-    }
-    /** MIN of a numeric field. */
-    async min(field) {
-        this.applyPendingScopes();
-        const result = await this.selectRaw(`MIN(${field}) as min`).first();
-        return parseFloat(result?.min ?? "0");
-    }
-    /** MAX of a numeric field. */
-    async max(field) {
-        this.applyPendingScopes();
-        const result = await this.selectRaw(`MAX(${field}) as max`).first();
-        return parseFloat(result?.max ?? "0");
-    }
-    /** Get distinct values for a field. */
-    async distinct(field) {
-        this.distinctValues(field);
-        const results = await this.get();
-        return results.map((row) => row[field]);
-    }
-    /** Get array of all values for a single field. */
-    async pluck(field) {
-        const results = await this.select([field]).get();
-        return results.map((row) => row[field]);
-    }
-    /** Get a single scalar value. */
-    async value(field) {
-        const result = await this.select([field]).first();
-        return result?.[field] ?? null;
-    }
-    /** Check whether any matching rows exist. */
-    async exists() {
-        const count = await this.limit(1).count();
-        return count > 0;
-    }
-    /** Check whether NO matching rows exist. */
-    async notExists() {
-        return !(await this.exists());
-    }
-    /** COUNT DISTINCT a field. */
-    async countDistinct(field) {
-        const result = await this.selectRaw(`COUNT(DISTINCT ${field}) as count`).first();
-        return parseInt(result?.count ?? "0", 10);
-    }
-    // ─── Aggregation shortcuts via latest/oldest ─────────────────
-    /** Get latest records ordered by a column. */
-    async latest(column = "createdAt") {
-        return this.orderBy(column, "desc").get();
-    }
-    // ─── Increment / Decrement ───────────────────────────────────
-    /** Increment a numeric field. Returns new value. */
-    async increment(field, amount = 1) {
-        this.applyPendingScopes();
-        const { sql: filterSql, params: filterParams } = this.buildFilter();
-        const updateSql = `UPDATE ${this.driver.dialect.quoteIdentifier(this.table)} ` +
-            `SET ${this.driver.dialect.quoteIdentifier(field)} = COALESCE(${this.driver.dialect.quoteIdentifier(field)}, 0) + $1 ` +
-            (filterSql ? `WHERE ${filterSql.replace("WHERE ", "")} ` : "") +
-            `RETURNING ${this.driver.dialect.quoteIdentifier(field)}`;
-        const result = await this.driver.query(updateSql, [
-            amount,
-            ...filterParams,
-        ]);
-        return result.rows[0]?.[field] ?? 0;
-    }
-    /** Decrement a numeric field. Returns new value. */
-    async decrement(field, amount = 1) {
-        return this.increment(field, -amount);
-    }
-    /** Increment a field for all matching rows. Returns affected row count. */
-    async incrementMany(field, amount = 1) {
-        this.applyPendingScopes();
-        const { sql: filterSql, params: filterParams } = this.buildFilter();
-        const updateSql = `UPDATE ${this.driver.dialect.quoteIdentifier(this.table)} ` +
-            `SET ${this.driver.dialect.quoteIdentifier(field)} = COALESCE(${this.driver.dialect.quoteIdentifier(field)}, 0) + $1` +
-            (filterSql ? ` WHERE ${filterSql.replace("WHERE ", "")}` : "");
-        const result = await this.driver.query(updateSql, [amount, ...filterParams]);
-        return result.rowCount ?? 0;
-    }
-    /** Decrement a field for all matching rows. Returns affected row count. */
-    async decrementMany(field, amount = 1) {
-        return this.incrementMany(field, -amount);
-    }
-    // ─── Chunking / Pagination ───────────────────────────────────
-    /**
-     * Process results in memory-efficient chunks.
-     *
-     * @example
-     * await User.query().chunk(100, async (rows, idx) => { ... })
-     */
-    async chunk(size, callback) {
-        let chunkIndex = 0;
-        let hasMore = true;
-        while (hasMore) {
-            const chunk = await this.clone()
-                .skip(chunkIndex * size)
-                .limit(size)
-                .get();
-            if (chunk.length === 0)
-                break;
-            const shouldContinue = await callback(chunk, chunkIndex);
-            if (shouldContinue === false)
-                break;
-            hasMore = chunk.length === size;
-            chunkIndex++;
-        }
-    }
-    /** Page-based pagination. */
-    async paginate(options) {
-        const page = options?.page ?? 1;
-        const limit = options?.limit ?? 10;
-        const skip = (page - 1) * limit;
-        const [data, total] = await Promise.all([
-            this.clone().skip(skip).limit(limit).get(),
-            this.count(),
-        ]);
-        return {
-            data,
-            pagination: {
-                total,
-                page,
-                limit,
-                pages: Math.ceil(total / limit),
-            },
-        };
-    }
-    /**
-     * Set cursor pagination hints fluently.
-     * The recorded values are picked up by `cursorPaginate()` when no explicit
-     * options are passed.
-     *
-     * @example
-     * User.query().cursor(lastId).cursorPaginate({ limit: 20 })
-     */
-    cursor(after, before) {
-        this.addOperation("cursor", { after, before });
-        return this;
-    }
-    /** Cursor-based pagination. */
-    async cursorPaginate(options) {
-        // Fall back to fluently-recorded cursor op if options.cursor not provided
-        const cursorOp = this.getOps("cursor")[0];
-        const recordedCursor = cursorOp?.data.after;
-        const { limit = 10, cursor = recordedCursor, column = "id", direction = "next", } = options ?? {};
-        if (cursor) {
-            this.where(column, direction === "next" ? ">" : "<", cursor);
-        }
-        this.orderBy(column, direction === "next" ? "asc" : "desc");
-        const results = await this.limit(limit + 1).get();
-        const hasMore = results.length > limit;
-        let data = hasMore ? results.slice(0, limit) : results;
-        if (direction === "prev")
-            data = data.reverse();
-        let nextCursor;
-        let prevCursor;
-        let hasPrev = false;
-        if (data.length > 0) {
-            const firstItem = data[0][column];
-            const lastItem = data[data.length - 1][column];
-            if (direction === "next") {
-                nextCursor = hasMore ? lastItem : undefined;
-                if (cursor) {
-                    hasPrev = true;
-                    prevCursor = firstItem;
-                }
-            }
-            else {
-                prevCursor = hasMore ? firstItem : undefined;
-                hasPrev = hasMore;
-                if (cursor)
-                    nextCursor = lastItem;
-            }
-        }
-        return { data, pagination: { hasMore, hasPrev, nextCursor, prevCursor } };
-    }
-    // ─── Mutation methods ────────────────────────────────────────
-    /** Delete matching rows. Returns deleted count. */
-    async delete() {
-        this.applyPendingScopes();
-        const { sql, params } = this.buildFilter();
-        const deleteSql = `DELETE FROM ${this.driver.dialect.quoteIdentifier(this.table)} ${sql}`;
-        const result = await this.driver.query(deleteSql, params);
-        return result.rowCount ?? 0;
-    }
-    /** Delete the first matching row. */
-    async deleteOne() {
-        return this.limit(1).delete();
-    }
-    /** Update matching rows. */
-    async update(fields) {
-        this.applyPendingScopes();
-        const result = await this.driver.updateMany(this.table, {}, { $set: fields });
-        return result.modifiedCount;
-    }
-    /** Unset fields from matching rows. */
-    async unset(...fields) {
-        this.applyPendingScopes();
-        const updateObj = {};
-        for (const field of fields)
-            updateObj[field] = 1;
-        const result = await this.driver.updateMany(this.table, {}, { $unset: updateObj });
-        return result.modifiedCount;
-    }
-    // ─── Inspection / Debugging ───────────────────────────────────
-    /** Return the SQL + bindings without executing. */
-    parse() {
-        this.applyPendingScopes();
-        const parser = new postgresQueryParser.PostgresQueryParser({
-            table: this.table,
-            operations: toParserOps(this.operations),
-        });
-        return parser.parse();
-    }
-    /** Formatted SQL string (for logging/debugging). */
-    pretty() {
-        const { query = "", bindings } = this.parse();
-        return `${query}\n-- Bindings: ${JSON.stringify(bindings ?? [])}`;
-    }
-    /** Run EXPLAIN ANALYZE on the query. */
-    async explain() {
-        const { query = "", bindings = [] } = this.parse();
-        const result = await this.driver.query(`EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ${query}`, bindings);
-        return result.rows;
-    }
-    // ─── Utility ──────────────────────────────────────────────────
-    /** Extend the builder with a driver-specific extension. */
-    extend(extension, ..._args) {
-        throw new Error(`Extension "${extension}" is not supported by PostgresQueryBuilder`);
-    }
-    /** Pluck scalar values for a single field (alias for pluck). */
-    async pluckOne(field) {
-        const results = await this.select([field]).get();
-        return results.map((row) => row[field]);
-    }
-    // ============================================================================
-    // JOIN RELATIONS — INTERNAL PIPELINE
-    // ============================================================================
-    /**
-     * Before `get()` runs the parser, consume any joinWith ops recorded by the base
-     * class and expand them into the joinRelations Map.
-     */
-    _processJoinWithOps() {
-        const joinWithOps = this.operations.filter((op) => op.type === "joinWith");
-        if (joinWithOps.length === 0)
-            return;
-        // Remove joinWith ops from main operations — they are consumed here
-        this.operations = this.operations.filter((op) => op.type !== "joinWith");
-        for (const op of joinWithOps) {
-            const constraints = op.data.constraints;
-            for (const [path, constraint] of Object.entries(constraints)) {
-                // Re-delegate to the extended joinWith implementation
-                if (!constraint || constraint === "") {
-                    this.joinWith(path);
-                }
-                else {
-                    this.joinWith({ [path]: constraint });
-                }
-            }
-        }
-    }
-    /**
-     * Translate each entry in `joinRelations` into actual JOIN + selectRelatedColumns operations.
-     */
-    applyJoinRelations() {
-        if (this.joinRelations.size === 0)
-            return;
-        for (const [path, config] of this.joinRelations) {
-            const RelatedModel = typeof config.model === "string"
-                ? registerModel.getModelFromRegistry(config.model)
-                : config.model;
-            if (!RelatedModel) {
-                throw new Error(`Relation model not found for ${path}`);
-            }
-            const relatedTable = RelatedModel.table;
-            const alias = config.alias;
-            const parentTable = config.parentPath
-                ? this.joinRelations.get(config.parentPath).alias
-                : this.table;
-            const parentDefTable = config.parentModel?.table ?? this.table;
-            let localField;
-            let foreignField;
-            if (config.type === "belongsTo") {
-                localField = config.foreignKey ?? `${config.relationName}Id`;
-                foreignField = config.ownerKey ?? "id";
-            }
-            else {
-                localField = config.localKey ?? "id";
-                foreignField = config.foreignKey ?? `${parentDefTable.slice(0, -1)}Id`;
-            }
-            // hasMany uses a correlated subquery in SELECT (no JOIN) to avoid row explosion
-            if (config.type !== "hasMany") {
-                this.addOperation("leftJoin", {
-                    table: relatedTable,
-                    alias,
-                    localField: `${parentTable}.${localField}`,
-                    foreignField,
-                });
-            }
-            this.addOperation("selectRelatedColumns", {
-                alias,
-                relationName: config.relationName,
-                path,
-                table: relatedTable,
-                select: config.select,
-                type: config.type,
-                foreignKey: foreignField,
-                localKey: localField,
-                parentTable,
-                constraintOps: config.constraintOps, // passed through to parser
-            });
-        }
-    }
-    /**
-     * Extract per-relation data from raw DB rows (before hydration).
-     * Returns a Map of row index → nested relation data tree.
-     */
-    extractJoinedRelationData(records) {
-        const result = new Map();
-        if (this.joinRelations.size === 0)
-            return result;
-        records.forEach((record, index) => {
-            const relationData = {};
-            // Process shallower paths first so parents exist before children
-            const sortedPaths = Array.from(this.joinRelations.keys()).sort((a, b) => a.split(".").length - b.split(".").length);
-            for (const path of sortedPaths) {
-                const config = this.joinRelations.get(path);
-                const columnName = config.alias;
-                const relatedData = record[columnName];
-                delete record[columnName];
-                const parsedData = relatedData !== null &&
-                    !(typeof relatedData === "object" &&
-                        Object.values(relatedData).every((v) => v === null))
-                    ? relatedData
-                    : null;
-                const parts = path.split(".");
-                const lastPart = parts.pop();
-                let current = relationData;
-                for (const part of parts) {
-                    if (!current[part])
-                        current[part] = {};
-                    current = current[part];
-                }
-                current[lastPart] = parsedData;
-            }
-            result.set(index, relationData);
-        });
-        return result;
-    }
-    /**
-     * Attach extracted relation data to hydrated model instances.
-     */
-    attachJoinedRelations(records, joinedData) {
-        if (this.joinRelations.size === 0)
-            return;
-        const attachNested = (model, dataTree, currentPath = "") => {
-            if (!dataTree || typeof dataTree !== "object")
-                return;
-            for (const [key, data] of Object.entries(dataTree)) {
-                const path = currentPath ? `${currentPath}.${key}` : key;
-                const config = this.joinRelations.get(path);
-                if (!config)
-                    continue;
-                const m = model;
-                if (data === null) {
-                    m[key] = null;
-                    m.loadedRelations?.set(key, null);
-                    continue;
-                }
-                const RelatedModel = registerModel.resolveModelClass(config.model);
-                if (!RelatedModel)
-                    continue;
-                const childKeys = Array.from(this.joinRelations.keys())
-                    .filter((p) => p.startsWith(`${path}.`))
-                    .map((p) => p.split(".")[path.split(".").length]);
-                if (config.type === "hasMany") {
-                    const rows = Array.isArray(data) ? data : [];
-                    const instances = rows.map((row) => {
-                        const rowData = { ...row };
-                        for (const childKey of childKeys)
-                            delete rowData[childKey];
-                        return RelatedModel.hydrate(rowData);
-                    });
-                    m[key] = instances;
-                    m.loadedRelations?.set(key, instances);
-                }
-                else {
-                    const modelData = { ...data };
-                    for (const childKey of childKeys)
-                        delete modelData[childKey];
-                    const relatedInstance = RelatedModel.hydrate(modelData);
-                    attachNested(relatedInstance, data, path);
-                    m[key] = relatedInstance;
-                    m.loadedRelations?.set(key, relatedInstance);
-                }
-            }
-        };
-        records.forEach((model, index) => {
-            const relationData = joinedData.get(index);
-            if (relationData)
-                attachNested(model, relationData);
-        });
-    }
-    // ============================================================================
-    // INTERNAL HELPERS
-    // ============================================================================
-    /**
-     * Build a WHERE-only SQL fragment from `where*` operations on the current builder.
-     * Used by DELETE / UPDATE / increment paths.
-     */
-    buildFilter() {
-        const whereOps = this.operations.filter((op) => op.type.includes("where") || op.type.includes("Where"));
-        if (whereOps.length === 0)
-            return { sql: "", params: [] };
-        const parser = new postgresQueryParser.PostgresQueryParser({
-            table: this.table,
-            operations: toParserOps(whereOps),
-        });
-        const { query = "", bindings = [] } = parser.parse();
-        const whereMatch = query.match(/WHERE .+$/);
-        return { sql: whereMatch ? whereMatch[0] : "", params: bindings };
-    }
-}exports.PostgresQueryBuilder=PostgresQueryBuilder;//# sourceMappingURL=postgres-query-builder.js.map