@warlock.js/cascade 4.0.157 → 4.0.161

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

@@ -1,1988 +0,0 @@
-'use strict';var reinforcements=require('@mongez/reinforcements'),databaseTransactionContext=require('../../context/database-transaction-context.js'),dataSourceRegistry=require('../../data-source/data-source-registry.js'),queryBuilder=require('../../query-builder/query-builder.js'),mongodbQueryOperations=require('./mongodb-query-operations.js'),mongodbQueryParser=require('./mongodb-query-parser.js');/* eslint-disable no-case-declarations */
-/**
- * MongoDB-specific query builder implementation using aggregation pipeline.
- */
-class MongoQueryBuilder extends queryBuilder.QueryBuilder {
-    table;
-    /**
-     * Ordered list of operations to be converted to MongoDB aggregation pipeline.
-     * Public to allow parser access. Uses MongoDB's own Operation type.
-     *
-     * NOTE: This shadows the base `operations: Op[]` field intentionally — the Mongo
-     * Operation type carries an extra `stage` discriminator used by the pipeline assembler.
-     */
-    operations = [];
-    /**
-     * Data source instance
-     */
-    dataSource;
-    /**
-     * Lazy-loaded operations helper for constructing pipeline operations.
-     */
-    _operationsHelper;
-    hydrateCallback;
-    fetchingCallback;
-    hydratingCallback;
-    fetchedCallback;
-    // scopesApplied, pendingGlobalScopes, availableLocalScopes, disabledGlobalScopes
-    // are inherited from QueryBuilder base class.
-    /**
-     * Create a new query builder for the given collection.
-     * @param collection - The MongoDB collection to query
-     */
-    constructor(table, dataSource) {
-        super();
-        this.table = table;
-        this.dataSource = dataSource || dataSourceRegistry.dataSourceRegistry.get();
-        // TODO: Trigger the fetching event
-    }
-    /**
-     * Gets the operations helper instance, creating it if needed.
-     * @returns The operations helper instance
-     */
-    get operationsHelper() {
-        if (!this._operationsHelper) {
-            this._operationsHelper = new mongodbQueryOperations.MongoQueryOperations(this.operations);
-        }
-        return this._operationsHelper;
-    }
-    /**
-     * Get collection instance
-     */
-    get collection() {
-        const driver = this.dataSource.driver;
-        return driver.database.collection(this.table);
-    }
-    /**
-     * Add hydrate callback function
-     */
-    hydrate(callback) {
-        this.hydrateCallback = callback;
-        return this;
-    }
-    /**
-     * Register a callback to be invoked before query execution
-     * @returns Unsubscribe function to remove the callback
-     */
-    onFetching(callback) {
-        this.fetchingCallback = callback;
-        return () => {
-            this.fetchingCallback = undefined;
-        };
-    }
-    /**
-     * Register a callback to be invoked after records are fetched but before hydration
-     * @returns Unsubscribe function to remove the callback
-     */
-    onHydrating(callback) {
-        this.hydratingCallback = callback;
-        return () => {
-            this.hydratingCallback = undefined;
-        };
-    }
-    /**
-     * Register a callback to be invoked after records are fetched and hydrated
-     * @returns Unsubscribe function to remove the callback
-     */
-    onFetched(callback) {
-        this.fetchedCallback = callback;
-        return () => {
-            this.fetchedCallback = undefined;
-        };
-    }
-    /**
-     * Disable one or more global scopes for this query
-     */
-    withoutGlobalScope(...scopeNames) {
-        scopeNames.forEach((name) => this.disabledGlobalScopes.add(name));
-        return this;
-    }
-    /**
-     * Disable all global scopes for this query
-     */
-    withoutGlobalScopes() {
-        if (this.pendingGlobalScopes) {
-            this.pendingGlobalScopes.forEach((_, name) => {
-                this.disabledGlobalScopes.add(name);
-            });
-        }
-        return this;
-    }
-    /**
-     * Apply a local scope to this query
-     */
-    scope(scopeName, ...args) {
-        if (!this.availableLocalScopes) {
-            throw new Error(`No local scopes available`);
-        }
-        const scopeCallback = this.availableLocalScopes.get(scopeName);
-        if (!scopeCallback) {
-            throw new Error(`Local scope "${scopeName}" not found`);
-        }
-        // Apply scope immediately (not deferred)
-        scopeCallback(this, ...args);
-        return this;
-    }
-    /**
-     * Apply pending global scopes before query execution
-     */
-    applyPendingScopes() {
-        if (!this.pendingGlobalScopes || this.scopesApplied) {
-            return;
-        }
-        const beforeOps = [];
-        const afterOps = [];
-        for (const [name, { callback, timing }] of this.pendingGlobalScopes) {
-            // Skip disabled scopes
-            if (this.disabledGlobalScopes.has(name)) {
-                continue;
-            }
-            // Create temporary query builder to capture operations
-            const tempBuilder = new MongoQueryBuilder(this.table, this.dataSource);
-            callback(tempBuilder);
-            // Collect operations based on timing
-            if (timing === "before") {
-                beforeOps.push(...tempBuilder.operations);
-            }
-            else {
-                afterOps.push(...tempBuilder.operations);
-            }
-        }
-        // Apply: before scopes + user operations + after scopes
-        this.operations = [...beforeOps, ...this.operations, ...afterOps];
-        this.scopesApplied = true;
-    }
-    where(...args) {
-        this.addWhereClause("where", args);
-        return this;
-    }
-    orWhere(...args) {
-        this.addWhereClause("orWhere", args);
-        return this;
-    }
-    /**
-     * Adds a raw WHERE clause using MongoDB's native query syntax.
-     * @param expression - Raw MongoDB expression
-     * @param bindings - Optional parameter bindings for string expressions
-     */
-    whereRaw(expression, bindings) {
-        return this.addRawWhere("whereRaw", expression, bindings);
-    }
-    /**
-     * Adds a raw OR WHERE clause using MongoDB's native query syntax.
-     * @param expression - Raw MongoDB expression
-     * @param bindings - Optional parameter bindings
-     */
-    orWhereRaw(expression, bindings) {
-        return this.addRawWhere("orWhereRaw", expression, bindings);
-    }
-    // ============================================================================
-    // WHERE CLAUSES - COLUMN COMPARISONS
-    // ============================================================================
-    /**
-     * Adds a WHERE clause comparing two columns/fields directly.
-     * @param first - The first field name
-     * @param operator - The comparison operator
-     * @param second - The second field name
-     */
-    whereColumn(first, operator, second) {
-        this.operationsHelper.addMatchOperation("whereColumn", {
-            first,
-            operator,
-            second,
-        });
-        return this;
-    }
-    /**
-     * Adds an OR WHERE clause comparing two columns/fields directly.
-     * @param first - The first field name
-     * @param operator - The comparison operator
-     * @param second - The second field name
-     */
-    orWhereColumn(first, operator, second) {
-        this.operationsHelper.addMatchOperation("orWhereColumn", {
-            first,
-            operator,
-            second,
-        });
-        return this;
-    }
-    /**
-     * Adds multiple column comparison clauses at once.
-     * @param comparisons - Array of tuples [leftField, operator, rightField]
-     */
-    whereColumns(comparisons) {
-        for (const [left, operator, right] of comparisons) {
-            this.whereColumn(left, operator, right);
-        }
-        return this;
-    }
-    /**
-     * Filters documents where a field's value falls between two other fields.
-     * @param field - The field to check
-     * @param lowerColumn - The field defining the lower bound
-     * @param upperColumn - The field defining the upper bound
-     */
-    whereBetweenColumns(field, lowerColumn, upperColumn) {
-        this.operationsHelper.addMatchOperation("whereBetweenColumns", {
-            field,
-            lowerColumn,
-            upperColumn,
-        });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - DATE OPERATIONS
-    // ============================================================================
-    /**
-     * Filters documents where a date field matches the given date (ignoring time).
-     * @param field - The date field name
-     * @param value - The date to match
-     */
-    whereDate(field, value) {
-        this.operationsHelper.addMatchOperation("whereDate", { field, value });
-        return this;
-    }
-    /**
-     * Alias for `whereDate()`. Filters by exact date match (ignoring time).
-     * @param field - The date field name
-     * @param value - The date to match
-     */
-    whereDateEquals(field, value) {
-        this.operationsHelper.addMatchOperation("whereDateEquals", {
-            field,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a date field is before the given date.
-     * @param field - The date field name
-     * @param value - The cutoff date
-     */
-    whereDateBefore(field, value) {
-        this.operationsHelper.addMatchOperation("whereDateBefore", {
-            field,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a date field is after the given date.
-     * @param field - The date field name
-     * @param value - The cutoff date
-     */
-    whereDateAfter(field, value) {
-        this.operationsHelper.addMatchOperation("whereDateAfter", { field, value });
-        return this;
-    }
-    /**
-     * Filters documents where a time field matches the given time (HH:MM:SS format).
-     * @param field - The time/datetime field name
-     * @param value - The time string in HH:MM:SS format
-     */
-    whereTime(field, value) {
-        this.operationsHelper.addMatchOperation("whereTime", { field, value });
-        return this;
-    }
-    /**
-     * Filters documents where the day of the month matches the given value (1-31).
-     * @param field - The date field name
-     * @param value - The day of the month
-     */
-    whereDay(field, value) {
-        this.operationsHelper.addMatchOperation("whereDay", { field, value });
-        return this;
-    }
-    /**
-     * Filters documents where the month matches the given value (1-12).
-     * @param field - The date field name
-     * @param value - The month number
-     */
-    whereMonth(field, value) {
-        this.operationsHelper.addMatchOperation("whereMonth", { field, value });
-        return this;
-    }
-    /**
-     * Filters documents where the year matches the given value.
-     * @param field - The date field name
-     * @param value - The year
-     */
-    whereYear(field, value) {
-        this.operationsHelper.addMatchOperation("whereYear", { field, value });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - JSON OPERATIONS
-    // ============================================================================
-    /**
-     * Filters documents where a JSON field contains the specified value.
-     * @param path - The JSON path to check
-     * @param value - The value to search for
-     */
-    whereJsonContains(path, value) {
-        this.operationsHelper.addMatchOperation("whereJsonContains", {
-            path,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a JSON field does NOT contain the specified value.
-     * @param path - The JSON path to check
-     * @param value - The value to exclude
-     */
-    whereJsonDoesntContain(path, value) {
-        this.operationsHelper.addMatchOperation("whereJsonDoesntContain", {
-            path,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a JSON field contains a specific key.
-     * @param path - The JSON path to check for key existence
-     */
-    whereJsonContainsKey(path) {
-        this.operationsHelper.addMatchOperation("whereJsonContainsKey", { path });
-        return this;
-    }
-    /**
-     * Filters documents where a JSON array or string has a specific length.
-     * @param path - The JSON path to check
-     * @param operator - The comparison operator
-     * @param value - The length value to compare against
-     */
-    whereJsonLength(path, operator, value) {
-        this.operationsHelper.addMatchOperation("whereJsonLength", {
-            path,
-            operator,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a JSON field is an array.
-     * @param path - The JSON path to check
-     */
-    whereJsonIsArray(path) {
-        this.operationsHelper.addMatchOperation("whereJsonIsArray", { path });
-        return this;
-    }
-    /**
-     * Filters documents where a JSON field is an object.
-     * @param path - The JSON path to check
-     */
-    whereJsonIsObject(path) {
-        this.operationsHelper.addMatchOperation("whereJsonIsObject", { path });
-        return this;
-    }
-    /**
-     * Filters documents where an array field has a specific length.
-     * @param field - The array field name
-     * @param operator - The comparison operator
-     * @param value - The length value to compare against
-     */
-    whereArrayLength(field, operator, value) {
-        this.operationsHelper.addMatchOperation("whereArrayLength", {
-            field,
-            operator,
-            value,
-        });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - CONVENIENCE METHODS
-    // ============================================================================
-    /**
-     * Filters documents by ID (convenience method for `where("id", value)`).
-     * @param value - The ID value to match
-     */
-    whereId(value) {
-        return this.where("id", value);
-    }
-    /**
-     * Filters documents by multiple IDs (convenience method for `whereIn("id", values)`).
-     * @param values - Array of ID values to match
-     */
-    whereIds(values) {
-        return this.whereIn("id", values);
-    }
-    /**
-     * Filters documents by UUID (convenience method for `where("uuid", value)`).
-     * @param value - The UUID string to match
-     */
-    whereUuid(value) {
-        return this.where("uuid", value);
-    }
-    /**
-     * Filters documents by ULID (convenience method for `where("ulid", value)`).
-     * @param value - The ULID string to match
-     */
-    whereUlid(value) {
-        return this.where("ulid", value);
-    }
-    /**
-     * Performs full-text search on one or more fields.
-     * @param fields - Field name or array of field names to search
-     * @param query - The search query string
-     */
-    whereFullText(fields, query) {
-        const filters = typeof fields === "string" ? { fields: [fields] } : { fields: fields ?? [] };
-        this.operationsHelper.addMatchOperation("whereFullText", {
-            fields: filters.fields,
-            query,
-        });
-        return this;
-    }
-    /**
-     * Performs full-text search with OR logic.
-     * @param fields - Field name or array of field names to search
-     * @param query - The search query string
-     */
-    orWhereFullText(fields, query) {
-        const filters = typeof fields === "string" ? { fields: [fields] } : { fields: fields ?? [] };
-        this.operationsHelper.addMatchOperation("orWhereFullText", {
-            fields: filters.fields,
-            query,
-        });
-        return this;
-    }
-    /**
-     * Alias for `whereFullText()` with a single field.
-     * @param field - The field name to search
-     * @param query - The search query string
-     */
-    whereSearch(field, query) {
-        return this.whereFullText(field, query);
-    }
-    /**
-     * Negates a set of conditions using a callback.
-     * @param callback - Callback function defining conditions to negate
-     */
-    whereNot(callback) {
-        this.operationsHelper.addMatchOperation("where:not", { callback });
-        return this;
-    }
-    /**
-     * Negates a set of conditions with OR logic.
-     * @param callback - Callback function defining conditions to negate
-     */
-    orWhereNot(callback) {
-        this.operationsHelper.addMatchOperation("orWhere:not", { callback });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - COMPARISON OPERATORS
-    // ============================================================================
-    /**
-     * Filters documents where a field's value matches any value in the given array.
-     * @param field - The field name to check
-     * @param values - Array of values to match against
-     */
-    whereIn(field, values) {
-        this.operationsHelper.addMatchOperation("whereIn", { field, values });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value does NOT match any value in the array.
-     * @param field - The field name to check
-     * @param values - Array of values to exclude
-     */
-    whereNotIn(field, values) {
-        this.operationsHelper.addMatchOperation("whereNotIn", { field, values });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value is null or undefined.
-     * @param field - The field name to check
-     */
-    whereNull(field) {
-        this.operationsHelper.addMatchOperation("whereNull", { field });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value is NOT null or undefined.
-     * @param field - The field name to check
-     */
-    whereNotNull(field) {
-        this.operationsHelper.addMatchOperation("whereNotNull", { field });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value falls within the given range (inclusive).
-     * @param field - The field name to check
-     * @param range - Tuple of [min, max] values
-     */
-    whereBetween(field, range) {
-        this.operationsHelper.addMatchOperation("whereBetween", { field, range });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value is NOT within the given range.
-     * @param field - The field name to check
-     * @param range - Tuple of [min, max] values to exclude
-     */
-    whereNotBetween(field, range) {
-        this.operationsHelper.addMatchOperation("whereNotBetween", {
-            field,
-            range,
-        });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - PATTERN MATCHING
-    // ============================================================================
-    /**
-     * Filters documents where a field matches the given pattern (case-insensitive).
-     * @param field - The field name to search
-     * @param pattern - The pattern to match
-     */
-    whereLike(field, pattern) {
-        this.operationsHelper.addMatchOperation("whereLike", { field, pattern });
-        return this;
-    }
-    /**
-     * Filters documents where a field does NOT match the given pattern.
-     * @param field - The field name to search
-     * @param pattern - The pattern to exclude
-     */
-    whereNotLike(field, pattern) {
-        this.operationsHelper.addMatchOperation("whereNotLike", { field, pattern });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value starts with the given prefix.
-     * @param field - The field name to check
-     * @param value - The prefix to match
-     */
-    whereStartsWith(field, value) {
-        this.operationsHelper.addMatchOperation("whereStartsWith", {
-            field,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value does NOT start with the given prefix.
-     * @param field - The field name to check
-     * @param value - The prefix to exclude
-     */
-    whereNotStartsWith(field, value) {
-        this.operationsHelper.addMatchOperation("whereNotStartsWith", {
-            field,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value ends with the given suffix.
-     * @param field - The field name to check
-     * @param value - The suffix to match
-     */
-    whereEndsWith(field, value) {
-        this.operationsHelper.addMatchOperation("whereEndsWith", { field, value });
-        return this;
-    }
-    /**
-     * Filters documents where a field's value does NOT end with the given suffix.
-     * @param field - The field name to check
-     * @param value - The suffix to exclude
-     */
-    whereNotEndsWith(field, value) {
-        this.operationsHelper.addMatchOperation("whereNotEndsWith", {
-            field,
-            value,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a date field falls within the given date range.
-     * @param field - The date field name
-     * @param range - Tuple of [startDate, endDate]
-     */
-    whereDateBetween(field, range) {
-        this.operationsHelper.addMatchOperation("whereDateBetween", {
-            field,
-            range,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where a date field is NOT within the given date range.
-     * @param field - The date field name
-     * @param range - Tuple of [startDate, endDate] to exclude
-     */
-    whereDateNotBetween(field, range) {
-        this.operationsHelper.addMatchOperation("whereDateNotBetween", {
-            field,
-            range,
-        });
-        return this;
-    }
-    whereExists(param) {
-        if (typeof param === "function") {
-            this.operationsHelper.addMatchOperation("where:exists", {
-                callback: param,
-            });
-            return this;
-        }
-        this.operationsHelper.addMatchOperation("whereExists", { field: param });
-        return this;
-    }
-    whereNotExists(param) {
-        if (typeof param === "function") {
-            this.operationsHelper.addMatchOperation("where:notExists", {
-                callback: param,
-            });
-            return this;
-        }
-        this.operationsHelper.addMatchOperation("whereNotExists", {
-            field: param,
-        });
-        return this;
-    }
-    whereSize(field, ...args) {
-        if (args.length === 1) {
-            this.operationsHelper.addMatchOperation("whereSize", {
-                field,
-                operator: "=",
-                size: args[0],
-            });
-        }
-        else {
-            this.operationsHelper.addMatchOperation("whereSize", {
-                field,
-                operator: args[0],
-                size: args[1],
-            });
-        }
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - FULL-TEXT SEARCH
-    // ============================================================================
-    /**
-     * Performs a full-text search on the specified fields.
-     * @param query - The search query string
-     * @param filters - Optional additional filter conditions
-     */
-    textSearch(query, filters) {
-        this.operationsHelper.addMatchOperation("textSearch", { query, filters });
-        return this;
-    }
-    // ============================================================================
-    // WHERE CLAUSES - ARRAY OPERATIONS
-    // ============================================================================
-    /**
-     * Filters documents where an array field contains the given value.
-     * @param field - The array field name
-     * @param value - The value to search for in the array
-     * @param key - Optional key to check within array objects
-     */
-    whereArrayContains(field, value, key) {
-        this.operationsHelper.addMatchOperation("whereArrayContains", {
-            field,
-            value,
-            key,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where an array field does NOT contain the given value.
-     * @param field - The array field name
-     * @param value - The value to exclude from the array
-     * @param key - Optional key to check within array objects
-     */
-    whereArrayNotContains(field, value, key) {
-        this.operationsHelper.addMatchOperation("whereArrayNotContains", {
-            field,
-            value,
-            key,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where an array field contains the value OR is empty.
-     * @param field - The array field name
-     * @param value - The value to search for
-     * @param key - Optional key to check within array objects
-     */
-    whereArrayHasOrEmpty(field, value, key) {
-        this.operationsHelper.addMatchOperation("whereArrayHasOrEmpty", {
-            field,
-            value,
-            key,
-        });
-        return this;
-    }
-    /**
-     * Filters documents where an array field does NOT contain the value AND is not empty.
-     * @param field - The array field name
-     * @param value - The value to exclude
-     * @param key - Optional key to check within array objects
-     */
-    whereArrayNotHaveOrEmpty(field, value, key) {
-        this.operationsHelper.addMatchOperation("whereArrayNotHaveOrEmpty", {
-            field,
-            value,
-            key,
-        });
-        return this;
-    }
-    /**
-     * Internal helper for processing where clause arguments.
-     * @param prefix - The operation prefix
-     * @param args - The arguments passed to where/orWhere
-     */
-    addWhereClause(prefix, args) {
-        if (args.length === 1) {
-            if (typeof args[0] === "function") {
-                // Callback-based where
-                this.operationsHelper.addMatchOperation(`${prefix}:callback`, args[0]);
-            }
-            else {
-                // Object-based where
-                this.operationsHelper.addMatchOperation(`${prefix}:object`, args[0]);
-            }
-        }
-        else if (args.length === 2) {
-            // Simple equality: where(field, value)
-            this.operationsHelper.addMatchOperation(prefix, {
-                field: args[0],
-                operator: "=",
-                value: args[1],
-            });
-        }
-        else if (args.length === 3) {
-            // With operator: where(field, operator, value)
-            this.operationsHelper.addMatchOperation(prefix, {
-                field: args[0],
-                operator: args[1],
-                value: args[2],
-            });
-        }
-    }
-    /**
-     * Internal helper for adding raw where clauses.
-     * @param type - The operation type
-     * @param expression - The raw expression in MongoDB query language
-     * @param bindings - Optional bindings for the expression
-     */
-    addRawWhere(type, expression, bindings) {
-        this.operationsHelper.addMatchOperation(type, { expression, bindings });
-        return this;
-    }
-    /**
-     * Normalizes select field arguments into a structured format.
-     * @param args - The arguments to normalize
-     * @returns Normalized selection object with fields and aliases
-     */
-    normalizeSelectFields(args) {
-        // Single argument cases
-        if (args.length === 1) {
-            const arg = args[0];
-            // Object format: { field: 1, field2: 0, field3: "alias", field4: true }
-            if (typeof arg === "object" && !Array.isArray(arg)) {
-                return { projection: arg };
-            }
-            // Array format: ["field1", "field2"]
-            if (Array.isArray(arg)) {
-                return { fields: arg };
-            }
-            // Single string: "field"
-            if (typeof arg === "string") {
-                return { fields: [arg] };
-            }
-        }
-        // Multiple string arguments: select("field1", "field2", "field3")
-        return { fields: args.filter((arg) => typeof arg === "string") };
-    }
-    select(...args) {
-        const normalized = this.normalizeSelectFields(args);
-        this.operationsHelper.addProjectOperation("select", normalized);
-        return this;
-    }
-    /**
-     * Selects a field with an alias.
-     * @param field - The field to select
-     * @param alias - The alias name for the field
-     * @returns The query builder instance
-     */
-    selectAs(field, alias) {
-        return this.select({ [field]: alias });
-    }
-    /**
-     * Adds a computed field using a raw MongoDB expression.
-     * @param expression - The raw MongoDB expression
-     * @param bindings - Optional parameter bindings for string expressions
-     */
-    selectRaw(expression, bindings) {
-        this.operationsHelper.addProjectOperation("selectRaw", {
-            expression,
-            bindings,
-        });
-        return this;
-    }
-    /**
-     * Adds multiple computed fields using raw MongoDB expressions.
-     * @param definitions - Array of field definitions with alias, expression, and optional bindings
-     */
-    selectRawMany(definitions) {
-        for (const definition of definitions) {
-            this.selectRaw({ [definition.alias]: definition.expression }, definition.bindings);
-        }
-        return this;
-    }
-    /**
-     * Adds a subquery as a computed field.
-     * @param expression - The subquery expression
-     * @param alias - The alias for the computed field
-     */
-    selectSub(expression, alias) {
-        this.operationsHelper.addProjectOperation("selectSub", {
-            expression,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds an additional subquery field to existing selections.
-     * @param expression - The subquery expression
-     * @param alias - The alias for the computed field
-     */
-    addSelectSub(expression, alias) {
-        this.operationsHelper.addProjectOperation("addSelectSub", {
-            expression,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds an aggregate value as a computed field.
-     * @param field - The field to aggregate
-     * @param aggregate - The aggregate function to apply
-     * @param alias - The alias for the computed field
-     */
-    selectAggregate(field, aggregate, alias) {
-        this.operationsHelper.addProjectOperation("selectAggregate", {
-            field,
-            aggregate,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds a boolean field indicating whether a related document exists.
-     * @param field - The field to check for existence
-     * @param alias - The alias for the boolean field
-     */
-    selectExists(field, alias) {
-        this.operationsHelper.addProjectOperation("selectExists", {
-            field,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds a count field for a related collection.
-     * @param field - The field to count
-     * @param alias - The alias for the count field
-     */
-    selectCount(field, alias) {
-        this.operationsHelper.addProjectOperation("selectCount", { field, alias });
-        return this;
-    }
-    /**
-     * Adds a CASE-like conditional field using multiple conditions.
-     * @param cases - Array of when/then pairs
-     * @param otherwise - Default value if no conditions match
-     * @param alias - The alias for the computed field
-     */
-    selectCase(cases, otherwise, alias) {
-        this.operationsHelper.addProjectOperation("selectCase", {
-            cases,
-            otherwise,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds a simple conditional field (if/else).
-     * @param condition - The condition to evaluate
-     * @param thenValue - Value if condition is true
-     * @param elseValue - Value if condition is false
-     * @param alias - The alias for the computed field
-     */
-    selectWhen(condition, thenValue, elseValue, alias) {
-        this.operationsHelper.addProjectOperation("selectWhen", {
-            condition,
-            thenValue,
-            elseValue,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Allows direct manipulation of the MongoDB projection object.
-     * @param callback - Function that receives and modifies the projection object
-     */
-    selectDriverProjection(callback) {
-        this.operationsHelper.addProjectOperation("selectDriverProjection", {
-            callback,
-        });
-        return this;
-    }
-    /**
-     * Extracts a JSON field from a document.
-     * @param path - The JSON path to extract
-     * @param alias - Optional alias for the extracted field
-     */
-    selectJson(path, alias) {
-        this.operationsHelper.addProjectOperation("selectJson", { path, alias });
-        return this;
-    }
-    /**
-     * Extracts a JSON field using a raw MongoDB expression.
-     * @param path - The JSON path
-     * @param expression - The raw expression for extraction
-     * @param alias - The alias for the extracted field
-     */
-    selectJsonRaw(path, expression, alias) {
-        this.operationsHelper.addProjectOperation("selectJsonRaw", {
-            path,
-            expression,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Excludes a JSON path from the results.
-     * @param path - The JSON path to exclude
-     */
-    deselectJson(path) {
-        this.operationsHelper.addProjectOperation("deselectJson", { path });
-        return this;
-    }
-    /**
-     * Concatenates multiple fields into a single string field.
-     * @param fields - Array of fields or expressions to concatenate
-     * @param alias - The alias for the concatenated field
-     */
-    selectConcat(fields, alias) {
-        this.operationsHelper.addProjectOperation("selectConcat", {
-            fields,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Returns the first non-null value from a list of fields.
-     * @param fields - Array of fields to check
-     * @param alias - The alias for the coalesced field
-     */
-    selectCoalesce(fields, alias) {
-        this.operationsHelper.addProjectOperation("selectCoalesce", {
-            fields,
-            alias,
-        });
-        return this;
-    }
-    /**
-     * Adds window function operations to the query.
-     * @param spec - The window function specification
-     */
-    selectWindow(spec) {
-        this.operationsHelper.addOperation("$setWindowFields", "selectWindow", { spec }, false);
-        return this;
-    }
-    deselect(...args) {
-        const fields = this.normalizeSelectFields(args);
-        this.operationsHelper.addProjectOperation("deselect", { fields });
-        return this;
-    }
-    /**
-     * Returns only distinct values for the specified fields.
-     * @param fields - Optional field names to use for distinctness
-     */
-    distinctValues(fields) {
-        this.operationsHelper.addGroupOperation("distinct", { fields }, false);
-        return this;
-    }
-    addSelect(...args) {
-        const fields = this.normalizeSelectFields(args);
-        this.operationsHelper.addProjectOperation("addSelect", { fields });
-        return this;
-    }
-    /**
-     * Removes all field selection restrictions.
-     */
-    clearSelect() {
-        this.operations = this.operations.filter((op) => op.stage !== "$project");
-        return this;
-    }
-    /**
-     * Alias for `clearSelect()`. Removes all field restrictions.
-     */
-    selectAll() {
-        return this.clearSelect();
-    }
-    /**
-     * Alias for `clearSelect()`. Resets to default field selection.
-     */
-    selectDefault() {
-        return this.clearSelect();
-    }
-    orderBy(fieldOrFields, direction = "asc") {
-        if (typeof fieldOrFields === "string") {
-            // Single field
-            this.operationsHelper.addSortOperation("orderBy", {
-                field: fieldOrFields,
-                direction,
-            });
-        }
-        else {
-            // Multiple fields - add each as a separate operation (they'll be merged)
-            for (const [field, dir] of Object.entries(fieldOrFields)) {
-                this.operationsHelper.addSortOperation("orderBy", {
-                    field,
-                    direction: dir,
-                });
-            }
-        }
-        return this;
-    }
-    /**
-     * Orders the query results by a field in descending order.
-     * @param field - The field name to sort by
-     */
-    orderByDesc(field) {
-        return this.orderBy(field, "desc");
-    }
-    /**
-     * Orders the query results using a raw MongoDB sort expression.
-     * @param expression - The raw MongoDB sort expression
-     * @param bindings - Optional parameter bindings
-     */
-    orderByRaw(expression, bindings) {
-        this.operationsHelper.addSortOperation("orderByRaw", {
-            expression,
-            bindings,
-        });
-        return this;
-    }
-    /**
-     * Orders the query results randomly.
-     */
-    orderByRandom(limit = 1000) {
-        this.operationsHelper.addSortOperation("orderByRandom", { limit }, false);
-        return this;
-    }
-    /**
-     * Orders results by a date field in descending order (newest first).
-     * @param column - The date column to sort by
-     */
-    latest(column = "createdAt") {
-        return this.orderBy(column, "desc").get();
-    }
-    /**
-     * Orders results by a date field in ascending order (oldest first).
-     * @param column - The date column to sort by
-     */
-    oldest(column = "createdAt") {
-        return this.orderBy(column, "asc");
-    }
-    // ============================================================================
-    // LIMITING / PAGINATION
-    // ============================================================================
-    /**
-     * Limits the number of documents returned by the query.
-     * @param value - The maximum number of documents to return
-     */
-    limit(value) {
-        this.operationsHelper.addOperation("$limit", "limit", { value }, false);
-        return this;
-    }
-    /**
-     * Skips a specified number of documents in the query results.
-     * @param value - The number of documents to skip
-     */
-    skip(value) {
-        this.operationsHelper.addOperation("$skip", "skip", { value }, false);
-        return this;
-    }
-    /**
-     * Alias for `skip()`. Skips a specified number of documents.
-     * @param value - The number of documents to skip
-     */
-    offset(value) {
-        return this.skip(value);
-    }
-    /**
-     * Alias for `limit()`. Limits the number of documents returned.
-     * @param value - The maximum number of documents to return
-     */
-    take(value) {
-        return this.limit(value);
-    }
-    /**
-     * Applies cursor-based filtering for pagination.
-     * @param after - Cursor value for forward pagination
-     * @param before - Cursor value for backward pagination
-     */
-    cursor(after, before) {
-        this.operationsHelper.addMatchOperation("cursor", { after, before });
-        return this;
-    }
-    groupBy(fields, aggregates) {
-        if (aggregates) {
-            this.operationsHelper.addGroupOperation("groupByWithAggregates", { fields, aggregates }, false);
-        }
-        else {
-            this.operationsHelper.addGroupOperation("groupBy", { fields }, false);
-        }
-        return this;
-    }
-    /**
-     * Groups documents using a raw MongoDB expression.
-     * @param expression - The raw grouping expression
-     * @param bindings - Optional parameter bindings
-     */
-    groupByRaw(expression, bindings) {
-        this.operationsHelper.addGroupOperation("groupByRaw", { expression, bindings }, false);
-        return this;
-    }
-    having(...args) {
-        if (args.length === 1) {
-            this.operationsHelper.addMatchOperation("having:condition", args[0], false);
-        }
-        else if (args.length === 2) {
-            this.operationsHelper.addMatchOperation("having", { field: args[0], operator: "=", value: args[1] }, false);
-        }
-        else {
-            this.operationsHelper.addMatchOperation("having", { field: args[0], operator: args[1], value: args[2] }, false);
-        }
-        return this;
-    }
-    /**
-     * Filters grouped results using a raw MongoDB expression.
-     * @param expression - The raw having expression
-     * @param bindings - Optional parameter bindings
-     */
-    havingRaw(expression, bindings) {
-        this.operationsHelper.addMatchOperation("havingRaw", { expression, bindings }, false);
-        return this;
-    }
-    join(tableOrOptions, localField, foreignField) {
-        const options = typeof tableOrOptions === "string"
-            ? {
-                table: tableOrOptions,
-                localField: localField,
-                foreignField: foreignField,
-                type: "left", // MongoDB $lookup is inherently a left outer join
-            }
-            : tableOrOptions;
-        this.operationsHelper.addLookupOperation("join", options);
-        return this;
-    }
-    leftJoin(tableOrOptions, localField, foreignField) {
-        const options = typeof tableOrOptions === "string"
-            ? {
-                table: tableOrOptions,
-                localField: localField,
-                foreignField: foreignField,
-                type: "left",
-            }
-            : { ...tableOrOptions, type: "left" };
-        this.operationsHelper.addLookupOperation("join", options);
-        return this;
-    }
-    rightJoin(tableOrOptions, localField, foreignField) {
-        // MongoDB $lookup is always a left join from the perspective of the input collection
-        // Right join semantics would require reversing the query direction
-        const options = typeof tableOrOptions === "string"
-            ? {
-                table: tableOrOptions,
-                localField: localField,
-                foreignField: foreignField,
-                type: "right",
-            }
-            : { ...tableOrOptions, type: "right" };
-        this.operationsHelper.addLookupOperation("join", options);
-        return this;
-    }
-    innerJoin(tableOrOptions, localField, foreignField) {
-        const options = typeof tableOrOptions === "string"
-            ? {
-                table: tableOrOptions,
-                localField: localField,
-                foreignField: foreignField,
-                type: "inner",
-            }
-            : { ...tableOrOptions, type: "inner" };
-        this.operationsHelper.addLookupOperation("join", options);
-        return this;
-    }
-    fullJoin(tableOrOptions, localField, foreignField) {
-        const options = typeof tableOrOptions === "string"
-            ? {
-                table: tableOrOptions,
-                localField: localField,
-                foreignField: foreignField,
-                type: "full",
-            }
-            : { ...tableOrOptions, type: "full" };
-        this.operationsHelper.addLookupOperation("join", options);
-        return this;
-    }
-    /**
-     * Performs a cross join with another collection.
-     *
-     * This creates a cartesian product by using $lookup with empty matching criteria.
-     *
-     * @param table - Target collection name
-     */
-    crossJoin(table) {
-        // Cross join: match every document in the foreign collection
-        this.operationsHelper.addLookupOperation("join", {
-            table,
-            localField: "_crossJoinDummy",
-            foreignField: "_crossJoinDummy",
-            type: "cross",
-            pipeline: [{ $match: {} }], // Match all documents
-        });
-        return this;
-    }
-    /**
-     * Performs a raw join using a custom aggregation pipeline.
-     *
-     * This allows full control over the $lookup stage for complex join scenarios.
-     *
-     * @param expression - Raw expression (typically a $lookup stage or pipeline)
-     * @param _bindings - Optional bindings (not used in MongoDB but kept for API consistency)
-     */
-    joinRaw(expression, _bindings) {
-        // For MongoDB, expression should be a $lookup stage object or a simple string
-        // describing the join. We add it as a raw operation.
-        this.operationsHelper.addMatchOperation("raw", { builder: () => expression }, false);
-        return this;
-    }
-    /**
-     * Allows direct manipulation of the native MongoDB query.
-     * @param builder - Function that receives and modifies the native query
-     */
-    raw(builder) {
-        this.operationsHelper.addMatchOperation("raw", { builder }, false);
-        return this;
-    }
-    /**
-     * Extends the query builder with driver-specific functionality.
-     * @param extension - The extension name
-     * @param _args - Extension-specific arguments
-     * @returns The extension's return value
-     */
-    extend(extension, ..._args) {
-        // Driver-specific extensions can be added here
-        throw new Error(`Extension '${extension}' is not supported by MongoQueryBuilder`);
-    }
-    /**
-     * Creates a deep copy of the query builder.
-     * @returns A new query builder instance with copied operations
-     */
-    clone() {
-        const cloned = new MongoQueryBuilder(this.table, this.dataSource);
-        cloned.operations = [...this.operations];
-        cloned.hydrateCallback = this.hydrateCallback?.bind(cloned);
-        cloned.fetchingCallback = this.fetchingCallback?.bind(cloned);
-        cloned.hydratingCallback = this.hydratingCallback?.bind(cloned);
-        cloned.fetchedCallback = this.fetchedCallback?.bind(cloned);
-        // Copy scope state
-        cloned.pendingGlobalScopes = this.pendingGlobalScopes;
-        cloned.availableLocalScopes = this.availableLocalScopes;
-        cloned.disabledGlobalScopes = new Set(this.disabledGlobalScopes);
-        cloned.scopesApplied = this.scopesApplied;
-        cloned.__operationsHelper = this.__operationsHelper;
-        return cloned;
-    }
-    /**
-     * Executes a callback with the query builder without breaking the chain.
-     * @param callback - Function to execute with the builder
-     */
-    tap(callback) {
-        callback(this);
-        return this;
-    }
-    /**
-     * Conditionally applies query modifications based on a condition.
-     * @param condition - The condition to evaluate
-     * @param callback - Function to execute if condition is true
-     * @param otherwise - Optional function to execute if condition is false
-     *
-     * @example
-     * query.when(searchTerm, (q, term) => q.whereLike('name', term))
-     */
-    when(condition, callback, otherwise) {
-        if (condition) {
-            callback(this, condition);
-        }
-        else if (otherwise) {
-            otherwise(this);
-        }
-        return this;
-    }
-    // ============================================================================
-    // EXECUTION METHODS
-    // ============================================================================
-    /**
-     * Executes the query and returns all matching documents.
-     * @returns an array of matching documents
-     */
-    async get() {
-        const startTime = Date.now();
-        // Emit onFetching event
-        if (this.fetchingCallback) {
-            await this.fetchingCallback(this);
-        }
-        // Execute query and get raw records
-        const rawRecords = await this.execute();
-        // Emit onHydrating event
-        if (this.hydratingCallback) {
-            await this.hydratingCallback(rawRecords, {
-                query: this,
-                hydrateCallback: this.hydrateCallback,
-            });
-        }
-        // Hydrate records
-        const hydratedRecords = this.hydrateCallback
-            ? rawRecords.map(this.hydrateCallback)
-            : rawRecords;
-        // Emit onFetched event
-        if (this.fetchedCallback) {
-            await this.fetchedCallback(hydratedRecords, {
-                query: this,
-                rawRecords,
-                duration: Date.now() - startTime,
-            });
-        }
-        return hydratedRecords;
-    }
-    /**
-     * Execute the query and get first result
-     * This is different than `first` as first adds a `limit = 1` to the pipeline
-     */
-    async getFirst() {
-        return (await this.get())?.[0] ?? null;
-    }
-    /**
-     * Executes the query and returns the first matching document.
-     * @returns the first document or null
-     */
-    async first() {
-        const results = await this.limit(1).get();
-        return results.length > 0 ? results[0] : null;
-    }
-    /**
-     * Executes the query and returns the first matching document, throwing if none found.
-     * @returns the first document
-     */
-    async firstOrFail() {
-        const result = await this.first();
-        if (!result) {
-            throw new Error("No records found matching the query");
-        }
-        return result;
-    }
-    /**
-     * Find a document by its primary key (id field).
-     */
-    async find(id) {
-        return this.where("id", id).first();
-    }
-    /**
-     * Configures the query to retrieve the last matching document.
-     */
-    last(field = "createdAt") {
-        this.orderBy(field, "desc");
-        return this.first();
-    }
-    /**
-     * Counts the number of documents matching the query.
-     * @returns the count of matching documents
-     */
-    async count() {
-        const pipeline = this.buildPipeline();
-        pipeline.push({ $count: "total" });
-        const results = await this.execute(pipeline);
-        return results.length > 0 ? results[0].total : 0;
-    }
-    /**
-     * Calculates the sum of a numeric field across matching documents.
-     * @param field - The numeric field to sum
-     * @returns the sum value
-     */
-    async sum(field) {
-        this.groupByRaw({
-            _id: null,
-            total: { $sum: `$${field}` },
-        });
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        const result = await this.getFirst();
-        return result?.total ?? 0;
-    }
-    /**
-     * Calculates the average value of a numeric field across matching documents.
-     * @param field - The numeric field to average
-     * @returns the average value
-     */
-    async avg(field) {
-        this.groupByRaw({
-            _id: null,
-            average: { $avg: `$${field}` },
-        });
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        return (await this.getFirst())?.average ?? 0;
-    }
-    /**
-     * Finds the minimum value of a field across matching documents.
-     * @param field - The field to find the minimum of
-     * @returns the minimum value
-     */
-    async min(field) {
-        this.groupByRaw({
-            _id: null,
-            minimum: { $min: `$${field}` },
-        });
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        return (await this.getFirst())?.minimum ?? 0;
-    }
-    /**
-     * Finds the maximum value of a field across matching documents.
-     * @param field - The field to find the maximum of
-     * @returns the maximum value
-     */
-    async max(field) {
-        this.groupByRaw({
-            _id: null,
-            maximum: { $max: `$${field}` },
-        });
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        return (await this.getFirst())?.maximum ?? 0;
-    }
-    /**
-     * Returns an array of distinct values for a field, respecting query filters.
-     * @param field - The field to get distinct values from
-     * @returns an array of distinct values
-     */
-    async distinct(field, ignoreNull = true) {
-        if (ignoreNull) {
-            this.whereNotNull(field);
-        }
-        this.groupBy(field);
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        const results = await this.get();
-        return results.map((doc) => doc._id);
-    }
-    /**
-     * Count distinct values for a field, respecting query filters.
-     * @param field - The field to count distinct values for
-     * @returns the count of distinct values
-     */
-    async countDistinct(field, ignoreNull = true) {
-        if (ignoreNull) {
-            this.whereNotNull(field);
-        }
-        return await this.groupBy(field).count();
-    }
-    /**
-     * Extracts a single field value from each matching document.
-     * @param field - The field to extract
-     * @returns an array of field values
-     */
-    async pluck(field) {
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        // Use object aliasing: { [field]: "value" } to project field as "value"
-        const results = await this.selectAs(field, "value").get();
-        return results.map((doc) => doc.value).filter((value) => value !== undefined);
-    }
-    /**
-     * Gets the value of a single field from the first matching document.
-     * @param field - The field to extract
-     * @returns the field value or null
-     */
-    async value(field) {
-        // make sure to clear the data map callback
-        this.hydrateCallback = undefined;
-        const result = await this.selectAs(field, "value").first();
-        return result?.value ?? null;
-    }
-    /**
-     * Checks if any documents match the query.
-     * @param filter - Optional filter to apply to the query
-     * @returns true if documents exist, false otherwise
-     */
-    async exists(filter) {
-        if (filter) {
-            this.where(filter);
-        }
-        const count = await this.limit(1).count();
-        return count > 0;
-    }
-    /**
-     * Checks if no documents match the query.
-     * @param filter - Optional filter to apply to the query
-     * @returns true if no documents exist, false otherwise
-     */
-    async notExists(filter) {
-        return !(await this.exists(filter));
-    }
-    /**
-     * Increments a numeric field by the specified amount for first matching document.
-     * @param field - The field to increment
-     * @param amount - The amount to increment by (default: 1)
-     * @returns the new value
-     */
-    async increment(field, amount = 1) {
-        const filter = this.buildFilter();
-        const result = await this.collection.findOneAndUpdate(filter, {
-            $inc: { [field]: amount },
-        }, {
-            returnDocument: "after",
-        });
-        return reinforcements.get(result, field, 0);
-    }
-    /**
-     * Decrements a numeric field by the specified amount.
-     * @param field - The field to decrement
-     * @param amount - The amount to decrement by
-     * @returns the new value
-     */
-    async decrement(field, amount = 1) {
-        return this.increment(field, -amount);
-    }
-    /**
-     * Increments a numeric field by the specified amount for all matching documents.
-     * @param field - The field to increment
-     * @param amount - The amount to increment by (default: 1)
-     * @returns the number of documents modified
-     */
-    async incrementMany(field, amount = 1) {
-        const filter = this.buildFilter();
-        const result = await this.dataSource.driver.updateMany(this.table, filter, {
-            $inc: { [field]: amount },
-        });
-        return result.modifiedCount;
-    }
-    /**
-     * Decrements a numeric field by the specified amount for all matching documents.
-     * @param field - The field to decrement
-     * @param amount - The amount to decrement by (default: 1)
-     * @returns the number of documents modified
-     */
-    async decrementMany(field, amount = 1) {
-        return this.incrementMany(field, -amount);
-    }
-    /**
-     * Delete all documents matching the query.
-     */
-    async delete() {
-        const filter = this.buildFilter();
-        return await this.dataSource.driver.deleteMany(this.table, filter);
-    }
-    /**
-     * Delete a single document matching the query.
-     */
-    async deleteOne() {
-        const filter = this.buildFilter();
-        return await this.dataSource.driver.delete(this.table, filter);
-    }
-    /**
-     * Update the given fields for all documents matching the query.
-     */
-    async update(fields) {
-        const filter = this.buildFilter();
-        const result = await this.dataSource.driver.updateMany(this.table, filter, {
-            $set: fields,
-        });
-        return result.modifiedCount;
-    }
-    /**
-     * Unset the given fields from all documents matching the query.
-     */
-    async unset(...fields) {
-        const filter = this.buildFilter();
-        const result = await this.dataSource.driver.updateMany(this.table, filter, {
-            $unset: fields.reduce((acc, field) => {
-                acc[field] = 1;
-                return acc;
-            }, {}),
-        });
-        return result.modifiedCount;
-    }
-    // ============================================================================
-    // CHUNKING / PAGINATION
-    // ============================================================================
-    /**
-     * Processes query results in chunks, executing a callback for each chunk.
-     * @param size - The number of documents per chunk
-     * @param callback - Function to execute for each chunk
-     * @returns void
-     */
-    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++;
-        }
-    }
-    /**
-     * Executes the query with traditional page-based pagination.
-     * @param options - Pagination options
-     * @returns pagination result with data and metadata
-     */
-    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),
-            },
-        };
-    }
-    /**
-     * Executes the query with cursor-based pagination supporting both directions.
-     * @param options - Cursor pagination options
-     * @returns cursor pagination result with data and cursor info
-     */
-    async cursorPaginate(options) {
-        const limit = options?.limit ?? 10;
-        const cursor = options?.cursor;
-        const column = options?.column ?? "id";
-        const direction = options?.direction ?? "next";
-        // Apply cursor filter
-        if (cursor) {
-            const operator = direction === "next" ? ">" : "<";
-            this.where(column, operator, cursor);
-        }
-        // Apply sorting
-        const sortOrder = direction === "next" ? "asc" : "desc";
-        this.orderBy(column, sortOrder);
-        this.orderBy("_id", sortOrder); // Always sort by _id to ensure consistent order
-        // Fetch one extra to detect if there are more results
-        const results = await this.limit(limit + 1).get();
-        const hasMore = results.length > limit;
-        let data = hasMore ? results.slice(0, limit) : results;
-        // Reverse results if fetching previous page to keep natural order
-        if (direction === "prev") {
-            data = data.reverse();
-        }
-        // Determine cursors based on actual data
-        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") {
-                // Forward pagination
-                nextCursor = hasMore ? lastItem : undefined;
-                // Check if there's a previous page
-                if (cursor) {
-                    hasPrev = true;
-                    prevCursor = firstItem;
-                }
-            }
-            else {
-                // Backward pagination
-                prevCursor = hasMore ? firstItem : undefined;
-                hasPrev = hasMore;
-                // Check if there's a next page
-                if (cursor) {
-                    nextCursor = lastItem;
-                }
-            }
-        }
-        return {
-            data,
-            pagination: {
-                hasMore,
-                hasPrev,
-                nextCursor,
-                prevCursor,
-            },
-        };
-    }
-    // ============================================================================
-    // INSPECTION / DEBUGGING
-    // ============================================================================
-    /**
-     * Returns the MongoDB aggregation pipeline that will be executed.
-     */
-    parse() {
-        return { pipeline: this.buildPipeline() };
-    }
-    /**
-     * Returns a formatted string representation of the query pipeline.
-     * @returns A formatted string representation of the pipeline
-     */
-    pretty() {
-        return this.getParser().toPrettyString();
-    }
-    /**
-     * Returns the MongoDB query execution plan.
-     * @returns MongoDB's explain output
-     */
-    async explain() {
-        // TODO: Trigger the explaining event
-        const pipeline = this.buildPipeline();
-        const session = databaseTransactionContext.databaseTransactionContext.getSession();
-        const options = session ? { session, explain: true } : { explain: true };
-        return this.collection.aggregate(pipeline, options).toArray();
-    }
-    // ============================================================================
-    // INTERNAL PIPELINE BUILDING
-    // ============================================================================
-    /**
-     * Get query parser instance
-     */
-    getParser() {
-        this.applyPendingScopes();
-        return new mongodbQueryParser.MongoQueryParser({
-            collection: this.collection,
-            operations: this.operations,
-            createSubBuilder: () => new MongoQueryBuilder(this.table, this.dataSource),
-        });
-    }
-    /**
-     * Build the MongoDB aggregation pipeline from the operations list.
-     * @returns The MongoDB aggregation pipeline
-     */
-    buildPipeline() {
-        const parser = this.getParser();
-        return parser.parse();
-    }
-    /**
-     * Build a MongoDB filter object from the query's where clauses.
-     * Used for update operations like increment/decrement.
-     * @returns The MongoDB filter object
-     */
-    buildFilter() {
-        // Get all match operations
-        const matchOperations = this.operations.filter((op) => op.stage === "$match");
-        if (matchOperations.length === 0) {
-            return {}; // No filters, match all documents
-        }
-        // Build the pipeline and extract the first $match stage
-        const pipeline = this.buildPipeline();
-        const matchStage = pipeline.find((stage) => stage.$match);
-        if (matchStage && matchStage.$match) {
-            return matchStage.$match;
-        }
-        return {};
-    }
-    /**
-     * Execute the aggregate command
-     */
-    async execute(pipeline) {
-        const aggregationPipeline = pipeline || this.buildPipeline();
-        const session = databaseTransactionContext.databaseTransactionContext.getSession();
-        const options = { session };
-        // TODO: Trigger the executing event
-        const results = (await this.collection
-            .aggregate(aggregationPipeline, options)
-            .toArray());
-        // TODO: Trigger the fetched event
-        // we need to cleanup the operations list
-        this.operations = [];
-        this.operationsHelper.setOperations(this.operations);
-        return results;
-    }
-    // ============================================================================
-    // RELATIONS / EAGER LOADING (Stubs)
-    // ============================================================================
-    /**
-     * Relations to eagerly load.
-     */
-    eagerLoadRelations = new Map();
-    /**
-     * Relations to count.
-     */
-    countRelations = [];
-    /**
-     * Relations to load via $lookup (single query).
-     */
-    joinRelations = new Map();
-    /**
-     * Load relations using MongoDB $lookup in a single aggregation query.
-     *
-     * Unlike `with()` which uses separate queries, `joinWith()` uses
-     * $lookup to fetch related data in a single aggregation pipeline.
-     *
-     * @param relations - Relation names to load via $lookup
-     * @returns This builder for chaining
-     */
-    joinWith(...relations) {
-        for (const relation of relations) {
-            const def = this.relationDefinitions?.[relation];
-            if (def) {
-                this.joinRelations.set(relation, {
-                    alias: `_rel_${relation}`,
-                    type: def.type,
-                });
-            }
-        }
-        return this;
-    }
-    /**
-     * Eagerly load one or more relations.
-     *
-     * Supported patterns:
-     * - `with("posts")` - Load relation
-     * - `with("posts", "comments")` - Load multiple relations
-     * - `with("posts", callback)` - Load relation with constraint
-     * - `with({ posts: true, comments: callback })` - Object configuration
-     *
-     * @param args - Relation name(s), callbacks, or configuration object
-     */
-    with(...args) {
-        for (let i = 0; i < args.length; i++) {
-            const arg = args[i];
-            if (typeof arg === "string") {
-                // Check if next argument is a callback for this relation
-                const nextArg = args[i + 1];
-                if (typeof nextArg === "function") {
-                    this.eagerLoadRelations.set(arg, nextArg);
-                    i++; // Skip the callback in next iteration
-                }
-                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);
-                }
-            }
-            // Functions not preceded by a string are ignored (invalid usage)
-        }
-        return this;
-    }
-    /**
-     * Add a count of related models as a virtual field.
-     * @param relations - Relation name(s) to count
-     */
-    withCount(...relations) {
-        this.countRelations.push(...relations);
-        return this;
-    }
-    /**
-     * Filter results to only those that have related models.
-     * @param relation - Relation name
-     * @param operator - Optional comparison operator
-     * @param count - Optional count to compare against
-     */
-    has(relation, operator, count) {
-        // TODO: Implement has() using $lookup and $match
-        this.operationsHelper.addMatchOperation("has", { relation, operator, count });
-        return this;
-    }
-    /**
-     * Filter results that have related models matching specific conditions.
-     * @param relation - Relation name
-     * @param callback - Callback to define conditions
-     */
-    whereHas(relation, callback) {
-        // TODO: Implement whereHas() using $lookup with pipeline
-        this.operationsHelper.addMatchOperation("whereHas", { relation, callback });
-        return this;
-    }
-    /**
-     * Filter results that don't have any related models.
-     * @param relation - Relation name
-     */
-    doesntHave(relation) {
-        // TODO: Implement doesntHave() using $lookup and $match
-        this.operationsHelper.addMatchOperation("doesntHave", { relation });
-        return this;
-    }
-    /**
-     * Filter results that don't have related models matching specific conditions.
-     * @param relation - Relation name
-     * @param callback - Callback to define conditions
-     */
-    whereDoesntHave(relation, callback) {
-        // TODO: Implement whereDoesntHave() using $lookup with pipeline
-        this.operationsHelper.addMatchOperation("whereDoesntHave", { relation, callback });
-        return this;
-    }
-    /**
-     * Nearest-neighbour vector similarity search via MongoDB Atlas $vectorSearch.
-     *
-     * Adds two pipeline stages:
-     * 1. `$vectorSearch` — runs the ANN search using the Atlas vector index.
-     *    Must be the first stage in the pipeline. Limit is embedded here.
-     * 2. `$addFields` — exposes `{ $meta: "vectorSearchScore" }` under `alias`
-     *    so callers can filter by minimum score after `.get()`.
-     *
-     * **Prerequisites:**
-     * - MongoDB Atlas cluster (local/Community MongoDB does NOT support $vectorSearch)
-     * - A vector search index on the collection, e.g.:
-     *   `{ "fields": [{ "type": "vector", "path": "embedding", "numDimensions": 1536, "similarity": "cosine" }] }`
-     * - The index name convention used here is `"${column}_index"` (override via `alias` if needed).
-     *
-     * @param column    - Vector column name (e.g. `"embedding"`)
-     * @param embedding - Query embedding as a plain number array
-     * @param alias     - Score alias added to each result row (default: `"score"`)
-     *
-     * @example
-     * ```typescript
-     * const results = await Vector.query()
-     *   .where({ organization_id: "org-123" })
-     *   .nearestTo("embedding", queryEmbedding)
-     *   .limit(5)
-     *   .get<VectorRow & { score: number }>();
-     * ```
-     */
-    nearestTo(column, embedding, alias = "score") {
-        // Grab the limit op recorded so far (default to 10 if not set yet)
-        const limitOp = this.operations.find((op) => op.type === "limit");
-        const limit = limitOp?.data?.value ?? 10;
-        // Stage 1: $vectorSearch — ANN search via Atlas vector index
-        this.operationsHelper.addOperation("$vectorSearch", "vectorSearch", {
-            index: `${column}_index`,
-            path: column,
-            queryVector: embedding,
-            numCandidates: limit * 10,
-            limit,
-        }, false);
-        // Stage 2: $addFields — expose vectorSearchScore as the score alias
-        this.operationsHelper.addOperation("$addFields", "vectorSearchScore", { [alias]: { $meta: "vectorSearchScore" } }, false);
-        return this;
-    }
-}exports.MongoQueryBuilder=MongoQueryBuilder;//# sourceMappingURL=mongodb-query-builder.js.map