@warlock.js/cascade 4.0.48 → 4.0.59

package/cjs/drivers/mongo/mongo-query-builder.d.ts

@@ -0,0 +1,922 @@
+import { GenericObject } from "@mongez/reinforcements";
+import type { Collection } from "mongodb";
+import type { CursorPaginationOptions, CursorPaginationResult, GroupByInput, HavingInput, JoinOptions, OrderDirection, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression, WhereCallback, WhereObject, WhereOperator } from "../../contracts";
+import { type DataSource } from "../../data-source/data-source";
+import { MongoQueryOperations } from "./mongo-query-operations";
+import { MongoQueryParser } from "./mongo-query-parser";
+import type { Operation } from "./types";
+/**
+ * MongoDB-specific query builder implementation using aggregation pipeline.
+ */
+export declare class MongoQueryBuilder<T = unknown> implements QueryBuilderContract<T> {
+    readonly table: string;
+    /**
+     * Ordered list of operations to be converted to MongoDB aggregation pipeline.
+     * Public to allow parser access.
+     */
+    operations: Operation[];
+    /**
+     * Data source instance
+     */
+    readonly dataSource: DataSource;
+    /**
+     * Lazy-loaded operations helper for constructing pipeline operations.
+     */
+    protected _operationsHelper?: MongoQueryOperations;
+    hydrateCallback?: (data: any, index: number) => any;
+    private fetchingCallback?;
+    private hydratingCallback?;
+    private fetchedCallback?;
+    pendingGlobalScopes?: Map<string, any>;
+    availableLocalScopes?: Map<string, any>;
+    disabledGlobalScopes: Set<string>;
+    scopesApplied: boolean;
+    /**
+     * Create a new query builder for the given collection.
+     * @param collection - The MongoDB collection to query
+     */
+    constructor(table: string, dataSource?: DataSource);
+    /**
+     * Gets the operations helper instance, creating it if needed.
+     * @returns The operations helper instance
+     */
+    protected get operationsHelper(): MongoQueryOperations;
+    /**
+     * Get collection instance
+     */
+    get collection(): Collection;
+    /**
+     * Add hydrate callback function
+     */
+    hydrate(callback: (data: any, index: number) => any): this;
+    /**
+     * Register a callback to be invoked before query execution
+     * @returns Unsubscribe function to remove the callback
+     */
+    onFetching(callback: (query: this) => void | Promise<void>): () => void;
+    /**
+     * Register a callback to be invoked after records are fetched but before hydration
+     * @returns Unsubscribe function to remove the callback
+     */
+    onHydrating(callback: (records: any[], context: any) => void | Promise<void>): () => void;
+    /**
+     * Register a callback to be invoked after records are fetched and hydrated
+     * @returns Unsubscribe function to remove the callback
+     */
+    onFetched(callback: (records: any[], context: any) => void | Promise<void>): () => void;
+    /**
+     * Disable one or more global scopes for this query
+     */
+    withoutGlobalScope(...scopeNames: string[]): this;
+    /**
+     * Disable all global scopes for this query
+     */
+    withoutGlobalScopes(): this;
+    /**
+     * Apply a local scope to this query
+     */
+    scope(scopeName: string): this;
+    /**
+     * Apply pending global scopes before query execution
+     */
+    private applyPendingScopes;
+    /**
+     * Adds a WHERE clause to filter documents. Supports equality, operators, objects, or callbacks.
+     * @param field - Field name, or conditions object, or callback
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     */
+    where(field: string, value: unknown): this;
+    where(field: string, operator: WhereOperator, value: unknown): this;
+    where(conditions: WhereObject): this;
+    where(callback: WhereCallback<T>): this;
+    /**
+     * Adds an OR WHERE clause. Works like where() but uses OR logic.
+     * @param field - Field name, or conditions object, or callback
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     */
+    orWhere(field: string, value: unknown): this;
+    orWhere(field: string, operator: WhereOperator, value: unknown): this;
+    orWhere(conditions: WhereObject): this;
+    orWhere(callback: WhereCallback<T>): 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: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Adds a raw OR WHERE clause using MongoDB's native query syntax.
+     * @param expression - Raw MongoDB expression
+     * @param bindings - Optional parameter bindings
+     */
+    orWhereRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * 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: string, operator: WhereOperator, second: string): 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: string, operator: WhereOperator, second: string): this;
+    /**
+     * Adds multiple column comparison clauses at once.
+     * @param comparisons - Array of tuples [leftField, operator, rightField]
+     */
+    whereColumns(comparisons: Array<[left: string, operator: WhereOperator, right: string]>): 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: string, lowerColumn: string, upperColumn: string): this;
+    /**
+     * 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: string, value: Date | string): 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: string, value: Date | string): 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: string, value: Date | string): 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: string, value: Date | string): 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: string, value: string): 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: string, value: number): 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: string, value: number): this;
+    /**
+     * Filters documents where the year matches the given value.
+     * @param field - The date field name
+     * @param value - The year
+     */
+    whereYear(field: string, value: number): this;
+    /**
+     * 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: string, value: unknown): 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: string, value: unknown): this;
+    /**
+     * Filters documents where a JSON field contains a specific key.
+     * @param path - The JSON path to check for key existence
+     */
+    whereJsonContainsKey(path: string): 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: string, operator: WhereOperator, value: number): this;
+    /**
+     * Filters documents where a JSON field is an array.
+     * @param path - The JSON path to check
+     */
+    whereJsonIsArray(path: string): this;
+    /**
+     * Filters documents where a JSON field is an object.
+     * @param path - The JSON path to check
+     */
+    whereJsonIsObject(path: string): 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: string, operator: WhereOperator, value: number): this;
+    /**
+     * Filters documents by ID (convenience method for `where("id", value)`).
+     * @param value - The ID value to match
+     */
+    whereId(value: string | number): this;
+    /**
+     * Filters documents by multiple IDs (convenience method for `whereIn("id", values)`).
+     * @param values - Array of ID values to match
+     */
+    whereIds(values: Array<string | number>): this;
+    /**
+     * Filters documents by UUID (convenience method for `where("uuid", value)`).
+     * @param value - The UUID string to match
+     */
+    whereUuid(value: string): this;
+    /**
+     * Filters documents by ULID (convenience method for `where("ulid", value)`).
+     * @param value - The ULID string to match
+     */
+    whereUlid(value: string): this;
+    /**
+     * 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: string | string[], query: string): 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: string | string[], query: string): this;
+    /**
+     * Alias for `whereFullText()` with a single field.
+     * @param field - The field name to search
+     * @param query - The search query string
+     */
+    whereSearch(field: string, query: string): this;
+    /**
+     * Negates a set of conditions using a callback.
+     * @param callback - Callback function defining conditions to negate
+     */
+    whereNot(callback: WhereCallback<T>): this;
+    /**
+     * Negates a set of conditions with OR logic.
+     * @param callback - Callback function defining conditions to negate
+     */
+    orWhereNot(callback: WhereCallback<T>): this;
+    /**
+     * 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: string, values: unknown[]): 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: string, values: unknown[]): this;
+    /**
+     * Filters documents where a field's value is null or undefined.
+     * @param field - The field name to check
+     */
+    whereNull(field: string): this;
+    /**
+     * Filters documents where a field's value is NOT null or undefined.
+     * @param field - The field name to check
+     */
+    whereNotNull(field: string): 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: string, range: [unknown, unknown]): 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: string, range: [unknown, unknown]): this;
+    /**
+     * 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: string, pattern: RegExp | string): 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: string, pattern: RegExp | string): 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: string, value: string | number): 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: string, value: string | number): 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: string, value: string | number): 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: string, value: string | number): 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: string, range: [Date, Date]): 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: string, range: [Date, Date]): this;
+    /**
+     * Filters documents where a field exists (has any value including null).
+     * @param field - The field name to check for existence
+     * @param callback - Optional callback for subquery existence
+     */
+    whereExists(field: string): this;
+    whereExists(callback: WhereCallback<T>): this;
+    /**
+     * Filters documents where a field does NOT exist in the document.
+     * @param field - The field name to check for absence
+     * @param callback - Optional callback for subquery non-existence
+     */
+    whereNotExists(field: string): this;
+    whereNotExists(callback: WhereCallback<T>): this;
+    /**
+     * Filters documents where an array field has a specific size.
+     * @param field - The array field name
+     * @param size - The exact size to match
+     * @param operator - Optional comparison operator
+     */
+    whereSize(field: string, size: number): this;
+    whereSize(field: string, operator: ">" | ">=" | "=" | "<" | "<=", size: number): this;
+    /**
+     * Performs a full-text search on the specified fields.
+     * @param query - The search query string
+     * @param filters - Optional additional filter conditions
+     */
+    textSearch(query: string, filters?: WhereObject): this;
+    /**
+     * 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: string, value: unknown, key?: string): 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: string, value: unknown, key?: string): 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: string, value: unknown, key?: string): 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: string, value: unknown, key?: string): this;
+    /**
+     * Internal helper for processing where clause arguments.
+     * @param prefix - The operation prefix
+     * @param args - The arguments passed to where/orWhere
+     */
+    protected addWhereClause(prefix: "where" | "orWhere", args: any[]): void;
+    /**
+     * 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
+     */
+    protected addRawWhere(type: "whereRaw" | "orWhereRaw", expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Normalizes select field arguments into a structured format.
+     * @param args - The arguments to normalize
+     * @returns Normalized selection object with fields and aliases
+     */
+    protected normalizeSelectFields(args: any[]): {
+        fields?: string[];
+        projection?: Record<string, unknown>;
+    };
+    /**
+     * Specifies which fields to include in the query results.
+     * Supports arrays, multiple args, or object with aliases/inclusion/exclusion.
+     * @param fields - Field names, array, or projection object
+     */
+    select(fields: string[]): this;
+    select(fields: Record<string, 0 | 1 | boolean | string>): this;
+    select(...fields: string[]): 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: string, alias: string): this;
+    /**
+     * 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: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Adds multiple computed fields using raw MongoDB expressions.
+     * @param definitions - Array of field definitions with alias, expression, and optional bindings
+     */
+    selectRawMany(definitions: Array<{
+        alias: string;
+        expression: RawExpression;
+        bindings?: unknown[];
+    }>): this;
+    /**
+     * Adds a subquery as a computed field.
+     * @param expression - The subquery expression
+     * @param alias - The alias for the computed field
+     */
+    selectSub(expression: RawExpression, alias: string): this;
+    /**
+     * Adds an additional subquery field to existing selections.
+     * @param expression - The subquery expression
+     * @param alias - The alias for the computed field
+     */
+    addSelectSub(expression: RawExpression, alias: string): 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: string, aggregate: "sum" | "avg" | "min" | "max" | "count" | "first" | "last", alias: string): 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: string, alias: string): 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: string, alias: string): 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: Array<{
+        when: RawExpression;
+        then: RawExpression | unknown;
+    }>, otherwise: RawExpression | unknown, alias: string): 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: RawExpression, thenValue: RawExpression | unknown, elseValue: RawExpression | unknown, alias: string): this;
+    /**
+     * Allows direct manipulation of the MongoDB projection object.
+     * @param callback - Function that receives and modifies the projection object
+     */
+    selectDriverProjection(callback: (projection: Record<string, unknown>) => void): 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: string, alias?: string): 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: string, expression: RawExpression, alias: string): this;
+    /**
+     * Excludes a JSON path from the results.
+     * @param path - The JSON path to exclude
+     */
+    deselectJson(path: string): 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: Array<string | RawExpression>, alias: string): 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: Array<string | RawExpression>, alias: string): this;
+    /**
+     * Adds window function operations to the query.
+     * @param spec - The window function specification
+     */
+    selectWindow(spec: RawExpression): this;
+    /**
+     * Excludes specific fields from the query results.
+     * @param fields - Field names to exclude
+     */
+    deselect(fields: string[]): this;
+    deselect(...fields: Array<string | string[]>): this;
+    /**
+     * Returns only distinct values for the specified fields.
+     * @param fields - Optional field names to use for distinctness
+     */
+    distinctValues(fields?: string | string[]): this;
+    /**
+     * Adds additional fields to an existing selection.
+     * @param fields - Additional field names to include
+     */
+    addSelect(fields: string[]): this;
+    addSelect(...fields: Array<string | string[]>): this;
+    /**
+     * Removes all field selection restrictions.
+     */
+    clearSelect(): this;
+    /**
+     * Alias for `clearSelect()`. Removes all field restrictions.
+     */
+    selectAll(): this;
+    /**
+     * Alias for `clearSelect()`. Resets to default field selection.
+     */
+    selectDefault(): this;
+    /**
+     * Orders the query results by a specific field or multiple fields.
+     *
+     * @param field - The field name to sort by, or an object with multiple fields
+     * @param direction - The sort direction (only used when field is a string)
+     *
+     * @example
+     * ```typescript
+     * // Single field
+     * query.orderBy("createdAt", "desc");
+     *
+     * // Multiple fields
+     * query.orderBy({ id: "asc", age: "desc", createdAt: "desc" });
+     * ```
+     */
+    orderBy(field: string, direction?: OrderDirection): this;
+    orderBy(fields: Record<string, OrderDirection>): this;
+    /**
+     * Orders the query results by a field in descending order.
+     * @param field - The field name to sort by
+     */
+    orderByDesc(field: string): this;
+    /**
+     * Orders the query results using a raw MongoDB sort expression.
+     * @param expression - The raw MongoDB sort expression
+     * @param bindings - Optional parameter bindings
+     */
+    orderByRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Orders the query results randomly.
+     */
+    orderByRandom(limit?: number): this;
+    /**
+     * Orders results by a date field in descending order (newest first).
+     * @param column - The date column to sort by
+     */
+    latest(column?: string): Promise<T[]>;
+    /**
+     * Orders results by a date field in ascending order (oldest first).
+     * @param column - The date column to sort by
+     */
+    oldest(column?: string): this;
+    /**
+     * Limits the number of documents returned by the query.
+     * @param value - The maximum number of documents to return
+     */
+    limit(value: number): this;
+    /**
+     * Skips a specified number of documents in the query results.
+     * @param value - The number of documents to skip
+     */
+    skip(value: number): this;
+    /**
+     * Alias for `skip()`. Skips a specified number of documents.
+     * @param value - The number of documents to skip
+     */
+    offset(value: number): this;
+    /**
+     * Alias for `limit()`. Limits the number of documents returned.
+     * @param value - The maximum number of documents to return
+     */
+    take(value: number): this;
+    /**
+     * Applies cursor-based filtering for pagination.
+     * @param after - Cursor value for forward pagination
+     * @param before - Cursor value for backward pagination
+     */
+    cursor(after?: unknown, before?: unknown): this;
+    /**
+     * Groups documents by one or more fields.
+     *
+     * @param fields - Field(s) to group by
+     * @param aggregates - Optional aggregate operations to perform
+     *
+     * @example
+     * ```typescript
+     * import { $agg } from '@warlock.js/cascade';
+     *
+     * // Simple grouping
+     * query.groupBy("type");
+     *
+     * // Grouping with aggregates
+     * query.groupBy("type", {
+     *   count: $agg.count(),
+     *   total: $agg.sum("duration")
+     * });
+     * ```
+     */
+    groupBy(fields: GroupByInput): this;
+    groupBy(fields: GroupByInput, aggregates: Record<string, RawExpression>): this;
+    /**
+     * Groups documents using a raw MongoDB expression.
+     * @param expression - The raw grouping expression
+     * @param bindings - Optional parameter bindings
+     */
+    groupByRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Filters grouped results based on aggregate conditions.
+     * @param field - The aggregate field to filter on
+     * @param value - The value to compare against
+     * @param operator - The comparison operator
+     * @param condition - A condition object for complex filters
+     */
+    having(field: string, value: unknown): this;
+    having(field: string, operator: WhereOperator, value: unknown): this;
+    having(condition: HavingInput): this;
+    /**
+     * Filters grouped results using a raw MongoDB expression.
+     * @param expression - The raw having expression
+     * @param bindings - Optional parameter bindings
+     */
+    havingRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Performs a left outer join with another collection.
+     * @param options - Join configuration including table, fields, and optional pipeline
+     */
+    join(options: JoinOptions): this;
+    /**
+     * Allows direct manipulation of the native MongoDB query.
+     * @param builder - Function that receives and modifies the native query
+     */
+    raw(builder: (native: unknown) => unknown): 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<R>(extension: string, ..._args: unknown[]): R;
+    /**
+     * Creates a deep copy of the query builder.
+     * @returns A new query builder instance with copied operations
+     */
+    clone(): this;
+    /**
+     * Executes a callback with the query builder without breaking the chain.
+     * @param callback - Function to execute with the builder
+     */
+    tap(callback: (builder: this) => void): 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<V>(condition: V | boolean, callback: (builder: this, value: V) => void, otherwise?: (builder: this) => void): this;
+    /**
+     * Executes the query and returns all matching documents.
+     * @returns an array of matching documents
+     */
+    get<Output = T>(): Promise<Output[]>;
+    /**
+     * Execute the query and get first result
+     * This is different than `first` as first adds a `limit = 1` to the pipeline
+     */
+    getFirst<Output = T>(): Promise<Output | null>;
+    /**
+     * Executes the query and returns the first matching document.
+     * @returns the first document or null
+     */
+    first<Output = T>(): Promise<Output | null>;
+    /**
+     * Executes the query and returns the first matching document, throwing if none found.
+     * @returns the first document
+     */
+    firstOrFail<Output = T>(): Promise<Output>;
+    /**
+     * Configures the query to retrieve the last matching document.
+     */
+    last<Output = T>(field?: string): Promise<Output | null>;
+    /**
+     * Counts the number of documents matching the query.
+     * @returns the count of matching documents
+     */
+    count(): Promise<number>;
+    /**
+     * Calculates the sum of a numeric field across matching documents.
+     * @param field - The numeric field to sum
+     * @returns the sum value
+     */
+    sum(field: string): Promise<number>;
+    /**
+     * Calculates the average value of a numeric field across matching documents.
+     * @param field - The numeric field to average
+     * @returns the average value
+     */
+    avg(field: string): Promise<number>;
+    /**
+     * Finds the minimum value of a field across matching documents.
+     * @param field - The field to find the minimum of
+     * @returns the minimum value
+     */
+    min(field: string): Promise<number>;
+    /**
+     * Finds the maximum value of a field across matching documents.
+     * @param field - The field to find the maximum of
+     * @returns the maximum value
+     */
+    max(field: string): Promise<number>;
+    /**
+     * 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
+     */
+    distinct<T = unknown>(field: string, ignoreNull?: boolean): Promise<T[]>;
+    /**
+     * Count distinct values for a field, respecting query filters.
+     * @param field - The field to count distinct values for
+     * @returns the count of distinct values
+     */
+    countDistinct(field: string, ignoreNull?: boolean): Promise<number>;
+    /**
+     * Extracts a single field value from each matching document.
+     * @param field - The field to extract
+     * @returns an array of field values
+     */
+    pluck<T = unknown>(field: string): Promise<T[]>;
+    /**
+     * Gets the value of a single field from the first matching document.
+     * @param field - The field to extract
+     * @returns the field value or null
+     */
+    value<T = unknown>(field: string): Promise<T | null>;
+    /**
+     * Checks if any documents match the query.
+     * @param filter - Optional filter to apply to the query
+     * @returns true if documents exist, false otherwise
+     */
+    exists(filter?: GenericObject): Promise<boolean>;
+    /**
+     * Checks if no documents match the query.
+     * @param filter - Optional filter to apply to the query
+     * @returns true if no documents exist, false otherwise
+     */
+    notExists(filter?: GenericObject): Promise<boolean>;
+    /**
+     * 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
+     */
+    increment(field: string, amount?: number): Promise<number>;
+    /**
+     * 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
+     */
+    decrement(field: string, amount?: number): Promise<number>;
+    /**
+     * 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
+     */
+    incrementMany(field: string, amount?: number): Promise<number>;
+    /**
+     * 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
+     */
+    decrementMany(field: string, amount?: number): Promise<number>;
+    /**
+     * Delete all documents matching the query.
+     */
+    delete(): Promise<number>;
+    /**
+     * Delete a single document matching the query.
+     */
+    deleteOne(): Promise<number>;
+    /**
+     * Update the given fields for all documents matching the query.
+     */
+    update(fields: Record<string, unknown>): Promise<number>;
+    /**
+     * Unset the given fields from all documents matching the query.
+     */
+    unset(...fields: string[]): Promise<number>;
+    /**
+     * 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
+     */
+    chunk(size: number, callback: (rows: T[], chunkIndex: number) => Promise<boolean | void> | boolean | void): Promise<void>;
+    /**
+     * Executes the query with traditional page-based pagination.
+     * @param options - Pagination options
+     * @returns pagination result with data and metadata
+     */
+    paginate(options: PaginationOptions): Promise<PaginationResult<T>>;
+    /**
+     * Executes the query with cursor-based pagination supporting both directions.
+     * @param options - Cursor pagination options
+     * @returns cursor pagination result with data and cursor info
+     */
+    cursorPaginate(options: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
+    /**
+     * Returns the MongoDB aggregation pipeline that will be executed.
+     * @returns The MongoDB aggregation pipeline array
+     */
+    parse(): any[];
+    /**
+     * Returns a formatted string representation of the query pipeline.
+     * @returns A formatted string representation of the pipeline
+     */
+    pretty(): string;
+    /**
+     * Returns the MongoDB query execution plan.
+     * @returns MongoDB's explain output
+     */
+    explain(): Promise<unknown>;
+    /**
+     * Get query parser instance
+     */
+    protected getParser(): MongoQueryParser;
+    /**
+     * Build the MongoDB aggregation pipeline from the operations list.
+     * @returns The MongoDB aggregation pipeline
+     */
+    protected buildPipeline(): any[];
+    /**
+     * Build a MongoDB filter object from the query's where clauses.
+     * Used for update operations like increment/decrement.
+     * @returns The MongoDB filter object
+     */
+    protected buildFilter(): Record<string, unknown>;
+    /**
+     * Execute the aggregate command
+     */
+    protected execute<T extends any = any>(pipeline?: any[]): Promise<T[]>;
+}
+//# sourceMappingURL=mongo-query-builder.d.ts.map