@warlock.js/cascade 4.0.171 → 4.1.1

package/esm/drivers/mongodb/mongodb-query-operations.mjs

@@ -0,0 +1,275 @@
+//#region ../../@warlock.js/cascade/src/drivers/mongodb/mongodb-query-operations.ts
+/**
+* Helper class for constructing MongoDB aggregation pipeline operations.
+*
+* This class encapsulates the logic for creating operation objects that will be
+* converted to MongoDB aggregation stages by the query parser. It provides a
+* clean abstraction over the low-level operation structure, making the query
+* builder code more maintainable and testable.
+*
+* Each operation consists of:
+* - **stage**: The MongoDB aggregation stage name (e.g., "$match", "$project")
+* - **type**: An internal identifier for the operation type
+* - **data**: The data associated with the operation
+* - **mergeable**: Whether this operation can be merged with adjacent similar operations
+*
+* @internal This class is for internal use within the MongoDB driver
+*
+* @example
+* ```typescript
+* const operations: Operation[] = [];
+* const helper = new MongoQueryOperations(operations);
+*
+* // Add a match operation
+* helper.addMatchOperation("whereIn", { field: "status", values: ["active", "pending"] });
+*
+* // Add a project operation
+* helper.addProjectOperation("select", { fields: ["name", "email"] });
+*
+* // Operations array is now populated
+* console.log(operations);
+* // [
+* //   { stage: "$match", mergeable: true, type: "whereIn", data: {...} },
+* //   { stage: "$project", mergeable: true, type: "select", data: {...} }
+* // ]
+* ```
+*/
+var MongoQueryOperations = class {
+	operations;
+	/**
+	* Creates a new operations helper.
+	*
+	* The helper maintains a reference to the operations array and populates it
+	* as methods are called. This allows the query builder to maintain a single
+	* ordered list of operations that will be converted to a MongoDB aggregation
+	* pipeline.
+	*
+	* @param operations - Reference to the operations array to populate
+	*
+	* @example
+	* ```typescript
+	* const operations: Operation[] = [];
+	* const helper = new MongoQueryOperations(operations);
+	* ```
+	*/
+	constructor(operations) {
+		this.operations = operations;
+	}
+	setOperations(operations) {
+		this.operations = operations;
+	}
+	/**
+	* Adds a $match stage operation to the pipeline.
+	*
+	* Match operations filter documents in the aggregation pipeline, similar to
+	* the WHERE clause in SQL. Multiple match operations can be merged together
+	* by the parser for optimization.
+	*
+	* @param type - The operation type identifier (e.g., "where", "whereIn", "whereLike")
+	* @param data - The operation data data containing filter criteria
+	* @param mergeable - Whether this operation can be merged with adjacent match operations (default: true)
+	*
+	* @example
+	* ```typescript
+	* // Simple where operation
+	* helper.addMatchOperation("where", { field: "age", operator: ">", value: 18 });
+	*
+	* // WhereIn operation
+	* helper.addMatchOperation("whereIn", { field: "status", values: ["active", "pending"] });
+	*
+	* // Non-mergeable match (e.g., after a group stage)
+	* helper.addMatchOperation("having", { field: "count", operator: ">", value: 5 }, false);
+	* ```
+	*/
+	addMatchOperation(type, data, mergeable = true) {
+		this.operations.push({
+			stage: "$match",
+			mergeable,
+			type,
+			data
+		});
+	}
+	/**
+	* Adds a $project stage operation to the pipeline.
+	*
+	* Project operations control which fields are included or excluded in the
+	* output documents, similar to the SELECT clause in SQL. They can also be
+	* used to compute new fields or reshape documents.
+	*
+	* @param type - The operation type identifier (e.g., "select", "deselect", "selectRaw")
+	* @param data - The operation data data containing projection specifications
+	* @param mergeable - Whether this operation can be merged with adjacent project operations (default: true)
+	*
+	* @example
+	* ```typescript
+	* // Select specific fields
+	* helper.addProjectOperation("select", { fields: ["name", "email", "age"] });
+	*
+	* // Deselect fields
+	* helper.addProjectOperation("deselect", { fields: ["password", "secret"] });
+	*
+	* // Computed field
+	* helper.addProjectOperation("selectRaw", {
+	*   expression: { fullName: { $concat: ["$firstName", " ", "$lastName"] } }
+	* });
+	* ```
+	*/
+	addProjectOperation(type, data, mergeable = true) {
+		this.operations.push({
+			stage: "$project",
+			mergeable,
+			type,
+			data
+		});
+	}
+	/**
+	* Adds a $sort stage operation to the pipeline.
+	*
+	* Sort operations order the documents in the pipeline, similar to the ORDER BY
+	* clause in SQL. Multiple sort operations can be merged to create compound
+	* sorting.
+	*
+	* @param type - The operation type identifier (e.g., "orderBy", "orderByRandom")
+	* @param data - The operation data data containing sort specifications
+	* @param mergeable - Whether this operation can be merged with adjacent sort operations (default: true)
+	*
+	* @example
+	* ```typescript
+	* // Order by a single field
+	* helper.addSortOperation("orderBy", { field: "createdAt", direction: "desc" });
+	*
+	* // Random ordering (not mergeable)
+	* helper.addSortOperation("orderByRandom", {limit: 1000}, false);
+	*
+	* // Order by raw expression
+	* helper.addSortOperation("orderByRaw", {
+	*   expression: { score: -1, name: 1 }
+	* });
+	* ```
+	*/
+	addSortOperation(type, data, mergeable = true) {
+		this.operations.push({
+			stage: "$sort",
+			mergeable,
+			type,
+			data
+		});
+	}
+	/**
+	* Adds a $group stage operation to the pipeline.
+	*
+	* Group operations aggregate documents by specified fields and compute
+	* aggregate values, similar to the GROUP BY clause in SQL. Group operations
+	* are typically not mergeable as they represent distinct aggregation boundaries.
+	*
+	* @param type - The operation type identifier (e.g., "groupBy", "distinct")
+	* @param data - The operation data data containing grouping specifications
+	* @param mergeable - Whether this operation can be merged with adjacent group operations (default: false)
+	*
+	* @example
+	* ```typescript
+	* // Group by a single field
+	* helper.addGroupOperation("groupBy", { fields: "category" });
+	*
+	* // Group by multiple fields
+	* helper.addGroupOperation("groupBy", {
+	*   fields: { category: "$category", status: "$status" }
+	* });
+	*
+	* // Distinct operation (special case of grouping)
+	* helper.addGroupOperation("distinct", { fields: ["email"] });
+	* ```
+	*/
+	addGroupOperation(type, data, mergeable = false) {
+		this.operations.push({
+			stage: "$group",
+			mergeable,
+			type,
+			data
+		});
+	}
+	/**
+	* Adds a $lookup stage operation to the pipeline.
+	*
+	* Lookup operations perform left outer joins with other collections, similar
+	* to JOIN in SQL. Lookup operations are never mergeable as each represents a
+	* distinct join operation.
+	*
+	* @param type - The operation type identifier (typically "join")
+	* @param data - The operation data data containing join specifications
+	*
+	* @example
+	* ```typescript
+	* // Simple lookup
+	* helper.addLookupOperation("join", {
+	*   table: "orders",
+	*   localField: "id",
+	*   foreignField: "userId",
+	*   alias: "userOrders"
+	* });
+	*
+	* // Lookup with pipeline
+	* helper.addLookupOperation("join", {
+	*   table: "products",
+	*   pipeline: [
+	*     { $match: { inStock: true } },
+	*     { $sort: { price: 1 } }
+	*   ],
+	*   alias: "availableProducts"
+	* });
+	* ```
+	*/
+	addLookupOperation(type, data) {
+		this.operations.push({
+			stage: "$lookup",
+			mergeable: false,
+			type,
+			data
+		});
+	}
+	/**
+	* Adds a generic stage operation to the pipeline.
+	*
+	* This method provides flexibility to add any MongoDB aggregation stage,
+	* including less common stages like $facet, $bucket, $setWindowFields, etc.
+	* Use this for operations that don't fit into the standard categories.
+	*
+	* @param stage - The MongoDB aggregation stage name (e.g., "$limit", "$skip", "$unwind")
+	* @param type - The operation type identifier
+	* @param data - The operation data data
+	* @param mergeable - Whether this operation can be merged with adjacent operations (default: false)
+	*
+	* @example
+	* ```typescript
+	* // Add a limit operation
+	* helper.addOperation("$limit", "limit", { value: 10 });
+	*
+	* // Add a skip operation
+	* helper.addOperation("$skip", "skip", { value: 20 });
+	*
+	* // Add an unwind operation
+	* helper.addOperation("$unwind", "unwind", { path: "$tags" });
+	*
+	* // Add a window function
+	* helper.addOperation("$setWindowFields", "selectWindow", {
+	*   spec: {
+	*     partitionBy: "$category",
+	*     sortBy: { price: 1 },
+	*     output: { rank: { $rank: {} } }
+	*   }
+	* });
+	* ```
+	*/
+	addOperation(stage, type, data, mergeable = false) {
+		this.operations.push({
+			stage,
+			mergeable,
+			type,
+			data
+		});
+	}
+};
+
+//#endregion
+export { MongoQueryOperations };
+//# sourceMappingURL=mongodb-query-operations.mjs.map

package/esm/drivers/mongodb/mongodb-query-operations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb-query-operations.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/mongodb/mongodb-query-operations.ts"],"sourcesContent":["import type { Operation, PipelineStage } from \"./types\";\n\n/**\n * Helper class for constructing MongoDB aggregation pipeline operations.\n *\n * This class encapsulates the logic for creating operation objects that will be\n * converted to MongoDB aggregation stages by the query parser. It provides a\n * clean abstraction over the low-level operation structure, making the query\n * builder code more maintainable and testable.\n *\n * Each operation consists of:\n * - **stage**: The MongoDB aggregation stage name (e.g., \"$match\", \"$project\")\n * - **type**: An internal identifier for the operation type\n * - **data**: The data associated with the operation\n * - **mergeable**: Whether this operation can be merged with adjacent similar operations\n *\n * @internal This class is for internal use within the MongoDB driver\n *\n * @example\n * ```typescript\n * const operations: Operation[] = [];\n * const helper = new MongoQueryOperations(operations);\n *\n * // Add a match operation\n * helper.addMatchOperation(\"whereIn\", { field: \"status\", values: [\"active\", \"pending\"] });\n *\n * // Add a project operation\n * helper.addProjectOperation(\"select\", { fields: [\"name\", \"email\"] });\n *\n * // Operations array is now populated\n * console.log(operations);\n * // [\n * //   { stage: \"$match\", mergeable: true, type: \"whereIn\", data: {...} },\n * //   { stage: \"$project\", mergeable: true, type: \"select\", data: {...} }\n * // ]\n * ```\n */\nexport class MongoQueryOperations {\n  /**\n   * Creates a new operations helper.\n   *\n   * The helper maintains a reference to the operations array and populates it\n   * as methods are called. This allows the query builder to maintain a single\n   * ordered list of operations that will be converted to a MongoDB aggregation\n   * pipeline.\n   *\n   * @param operations - Reference to the operations array to populate\n   *\n   * @example\n   * ```typescript\n   * const operations: Operation[] = [];\n   * const helper = new MongoQueryOperations(operations);\n   * ```\n   */\n  public constructor(private operations: Operation[]) {}\n\n  public setOperations(operations: Operation[]): void {\n    this.operations = operations;\n  }\n\n  /**\n   * Adds a $match stage operation to the pipeline.\n   *\n   * Match operations filter documents in the aggregation pipeline, similar to\n   * the WHERE clause in SQL. Multiple match operations can be merged together\n   * by the parser for optimization.\n   *\n   * @param type - The operation type identifier (e.g., \"where\", \"whereIn\", \"whereLike\")\n   * @param data - The operation data data containing filter criteria\n   * @param mergeable - Whether this operation can be merged with adjacent match operations (default: true)\n   *\n   * @example\n   * ```typescript\n   * // Simple where operation\n   * helper.addMatchOperation(\"where\", { field: \"age\", operator: \">\", value: 18 });\n   *\n   * // WhereIn operation\n   * helper.addMatchOperation(\"whereIn\", { field: \"status\", values: [\"active\", \"pending\"] });\n   *\n   * // Non-mergeable match (e.g., after a group stage)\n   * helper.addMatchOperation(\"having\", { field: \"count\", operator: \">\", value: 5 }, false);\n   * ```\n   */\n  public addMatchOperation(type: string, data: Record<string, unknown>, mergeable = true): void {\n    this.operations.push({\n      stage: \"$match\",\n      mergeable,\n      type,\n      data,\n    });\n  }\n\n  /**\n   * Adds a $project stage operation to the pipeline.\n   *\n   * Project operations control which fields are included or excluded in the\n   * output documents, similar to the SELECT clause in SQL. They can also be\n   * used to compute new fields or reshape documents.\n   *\n   * @param type - The operation type identifier (e.g., \"select\", \"deselect\", \"selectRaw\")\n   * @param data - The operation data data containing projection specifications\n   * @param mergeable - Whether this operation can be merged with adjacent project operations (default: true)\n   *\n   * @example\n   * ```typescript\n   * // Select specific fields\n   * helper.addProjectOperation(\"select\", { fields: [\"name\", \"email\", \"age\"] });\n   *\n   * // Deselect fields\n   * helper.addProjectOperation(\"deselect\", { fields: [\"password\", \"secret\"] });\n   *\n   * // Computed field\n   * helper.addProjectOperation(\"selectRaw\", {\n   *   expression: { fullName: { $concat: [\"$firstName\", \" \", \"$lastName\"] } }\n   * });\n   * ```\n   */\n  public addProjectOperation(\n    type: string,\n    data: Record<string, unknown>,\n    mergeable = true,\n  ): void {\n    this.operations.push({\n      stage: \"$project\",\n      mergeable,\n      type,\n      data,\n    });\n  }\n\n  /**\n   * Adds a $sort stage operation to the pipeline.\n   *\n   * Sort operations order the documents in the pipeline, similar to the ORDER BY\n   * clause in SQL. Multiple sort operations can be merged to create compound\n   * sorting.\n   *\n   * @param type - The operation type identifier (e.g., \"orderBy\", \"orderByRandom\")\n   * @param data - The operation data data containing sort specifications\n   * @param mergeable - Whether this operation can be merged with adjacent sort operations (default: true)\n   *\n   * @example\n   * ```typescript\n   * // Order by a single field\n   * helper.addSortOperation(\"orderBy\", { field: \"createdAt\", direction: \"desc\" });\n   *\n   * // Random ordering (not mergeable)\n   * helper.addSortOperation(\"orderByRandom\", {limit: 1000}, false);\n   *\n   * // Order by raw expression\n   * helper.addSortOperation(\"orderByRaw\", {\n   *   expression: { score: -1, name: 1 }\n   * });\n   * ```\n   */\n  public addSortOperation(type: string, data: Record<string, unknown>, mergeable = true): void {\n    this.operations.push({\n      stage: \"$sort\",\n      mergeable,\n      type,\n      data,\n    });\n  }\n\n  /**\n   * Adds a $group stage operation to the pipeline.\n   *\n   * Group operations aggregate documents by specified fields and compute\n   * aggregate values, similar to the GROUP BY clause in SQL. Group operations\n   * are typically not mergeable as they represent distinct aggregation boundaries.\n   *\n   * @param type - The operation type identifier (e.g., \"groupBy\", \"distinct\")\n   * @param data - The operation data data containing grouping specifications\n   * @param mergeable - Whether this operation can be merged with adjacent group operations (default: false)\n   *\n   * @example\n   * ```typescript\n   * // Group by a single field\n   * helper.addGroupOperation(\"groupBy\", { fields: \"category\" });\n   *\n   * // Group by multiple fields\n   * helper.addGroupOperation(\"groupBy\", {\n   *   fields: { category: \"$category\", status: \"$status\" }\n   * });\n   *\n   * // Distinct operation (special case of grouping)\n   * helper.addGroupOperation(\"distinct\", { fields: [\"email\"] });\n   * ```\n   */\n  public addGroupOperation(\n    type: string,\n    data: Record<string, unknown>,\n    mergeable = false,\n  ): void {\n    this.operations.push({\n      stage: \"$group\",\n      mergeable,\n      type,\n      data,\n    });\n  }\n\n  /**\n   * Adds a $lookup stage operation to the pipeline.\n   *\n   * Lookup operations perform left outer joins with other collections, similar\n   * to JOIN in SQL. Lookup operations are never mergeable as each represents a\n   * distinct join operation.\n   *\n   * @param type - The operation type identifier (typically \"join\")\n   * @param data - The operation data data containing join specifications\n   *\n   * @example\n   * ```typescript\n   * // Simple lookup\n   * helper.addLookupOperation(\"join\", {\n   *   table: \"orders\",\n   *   localField: \"id\",\n   *   foreignField: \"userId\",\n   *   alias: \"userOrders\"\n   * });\n   *\n   * // Lookup with pipeline\n   * helper.addLookupOperation(\"join\", {\n   *   table: \"products\",\n   *   pipeline: [\n   *     { $match: { inStock: true } },\n   *     { $sort: { price: 1 } }\n   *   ],\n   *   alias: \"availableProducts\"\n   * });\n   * ```\n   */\n  public addLookupOperation(type: string, data: Record<string, unknown>): void {\n    this.operations.push({\n      stage: \"$lookup\",\n      mergeable: false,\n      type,\n      data,\n    });\n  }\n\n  /**\n   * Adds a generic stage operation to the pipeline.\n   *\n   * This method provides flexibility to add any MongoDB aggregation stage,\n   * including less common stages like $facet, $bucket, $setWindowFields, etc.\n   * Use this for operations that don't fit into the standard categories.\n   *\n   * @param stage - The MongoDB aggregation stage name (e.g., \"$limit\", \"$skip\", \"$unwind\")\n   * @param type - The operation type identifier\n   * @param data - The operation data data\n   * @param mergeable - Whether this operation can be merged with adjacent operations (default: false)\n   *\n   * @example\n   * ```typescript\n   * // Add a limit operation\n   * helper.addOperation(\"$limit\", \"limit\", { value: 10 });\n   *\n   * // Add a skip operation\n   * helper.addOperation(\"$skip\", \"skip\", { value: 20 });\n   *\n   * // Add an unwind operation\n   * helper.addOperation(\"$unwind\", \"unwind\", { path: \"$tags\" });\n   *\n   * // Add a window function\n   * helper.addOperation(\"$setWindowFields\", \"selectWindow\", {\n   *   spec: {\n   *     partitionBy: \"$category\",\n   *     sortBy: { price: 1 },\n   *     output: { rank: { $rank: {} } }\n   *   }\n   * });\n   * ```\n   */\n  public addOperation(\n    stage: PipelineStage,\n    type: string,\n    data: Record<string, unknown>,\n    mergeable = false,\n  ): void {\n    this.operations.push({\n      stage,\n      mergeable,\n      type,\n      data,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,uBAAb,MAAkC;CAiBL;;;;;;;;;;;;;;;;;CAA3B,AAAO,YAAY,AAAQ,YAAyB;EAAzB;CAA0B;CAErD,AAAO,cAAc,YAA+B;EAClD,KAAK,aAAa;CACpB;;;;;;;;;;;;;;;;;;;;;;;;CAyBA,AAAO,kBAAkB,MAAc,MAA+B,YAAY,MAAY;EAC5F,KAAK,WAAW,KAAK;GACnB,OAAO;GACP;GACA;GACA;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BA,AAAO,oBACL,MACA,MACA,YAAY,MACN;EACN,KAAK,WAAW,KAAK;GACnB,OAAO;GACP;GACA;GACA;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BA,AAAO,iBAAiB,MAAc,MAA+B,YAAY,MAAY;EAC3F,KAAK,WAAW,KAAK;GACnB,OAAO;GACP;GACA;GACA;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BA,AAAO,kBACL,MACA,MACA,YAAY,OACN;EACN,KAAK,WAAW,KAAK;GACnB,OAAO;GACP;GACA;GACA;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCA,AAAO,mBAAmB,MAAc,MAAqC;EAC3E,KAAK,WAAW,KAAK;GACnB,OAAO;GACP,WAAW;GACX;GACA;EACF,CAAC;CACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCA,AAAO,aACL,OACA,MACA,MACA,YAAY,OACN;EACN,KAAK,WAAW,KAAK;GACnB;GACA;GACA;GACA;EACF,CAAC;CACH;AACF"}

package/esm/drivers/mongodb/mongodb-query-parser.d.mts

@@ -0,0 +1,263 @@
+import { Operation } from "./types.mjs";
+import { MongoQueryBuilder } from "./mongodb-query-builder.mjs";
+import { Collection } from "mongodb";
+
+//#region ../../@warlock.js/cascade/src/drivers/mongodb/mongodb-query-parser.d.ts
+/**
+ * Options for configuring the MongoDB query parser.
+ */
+type MongoQueryParserOptions = {
+  /** The MongoDB collection being queried */collection: Collection; /** The ordered list of operations to parse */
+  operations: Operation[]; /** Factory method for creating sub-builders (used for callbacks) */
+  createSubBuilder: () => MongoQueryBuilder;
+};
+/**
+ * Parses query builder operations into MongoDB aggregation pipeline.
+ *
+ * This parser is responsible for converting the abstract operations collected
+ * by the query builder into a concrete MongoDB aggregation pipeline. It handles
+ * intelligent grouping of mergeable operations (like multiple where clauses)
+ * into single pipeline stages for optimal performance.
+ */
+declare class MongoQueryParser {
+  /**
+   * The MongoDB collection being queried.
+   */
+  private readonly collection;
+  /**
+   * The ordered list of operations to parse.
+   */
+  private readonly operations;
+  /**
+   * Factory for creating sub-builders (used when resolving callbacks).
+   */
+  private readonly createSubBuilder;
+  /**
+   * Track group field names for automatic _id renaming.
+   * Maps pipeline index to field names.
+   */
+  private readonly groupFieldNames;
+  /**
+   * Create a new MongoDB query parser.
+   *
+   * @param options - Configuration options for the parser
+   */
+  constructor(options: MongoQueryParserOptions);
+  /**
+   * Parse the operations into a MongoDB aggregation pipeline.
+   *
+   * This method intelligently groups mergeable operations (e.g., multiple where
+   * clauses) into single pipeline stages while maintaining the correct execution
+   * order for non-mergeable operations.
+   *
+   * @returns The MongoDB aggregation pipeline
+   *
+   * @example
+   * ```typescript
+   * const parser = new MongoQueryParser({ collection, operations });
+   * const pipeline = parser.parse();
+   * // [
+   * //   { $match: { status: 'active', age: { $gt: 18 } } },
+   * //   { $sort: { createdAt: -1 } },
+   * //   { $limit: 10 }
+   * // ]
+   * ```
+   */
+  parse(): any[];
+  /**
+   * Track field names for group stages that need _id renaming.
+   */
+  private trackGroupFieldNames;
+  /**
+   * Post-process pipeline to rename _id fields after $group stages.
+   *
+   * This automatically renames MongoDB's `_id` field to the actual field name(s)
+   * used for grouping, making the results more intuitive.
+   *
+   * @param pipeline - The aggregation pipeline
+   * @returns The processed pipeline
+   */
+  private postProcessGroupStages;
+  /**
+   * Convert the parsed pipeline to a pretty-printed string for debugging.
+   *
+   * This method formats the MongoDB aggregation pipeline in a human-readable
+   * way, making it easier to understand and debug complex queries.
+   *
+   * @returns A formatted string representation of the pipeline
+   *
+   * @example
+   * ```typescript
+   * const parser = new MongoQueryParser({ collection, operations });
+   * console.log(parser.toPrettyString());
+   * // Output:
+   * // MongoDB Aggregation Pipeline:
+   * // ════════════════════════════
+   * // Stage 1: $match
+   * //   status: "active"
+   * //   age: { $gt: 18 }
+   * //
+   * // Stage 2: $sort
+   * //   createdAt: -1
+   * ```
+   */
+  toPrettyString(): string;
+  /**
+   * Format stage data with proper indentation.
+   *
+   * @param data - The stage data to format
+   * @param indent - The indentation level
+   * @returns Formatted string
+   */
+  private formatStageData;
+  /**
+   * Build a single pipeline stage from a group of operations.
+   *
+   * @param stage - The pipeline stage type
+   * @param operations - The operations to build the stage from
+   * @returns The built pipeline stage or null if no stage should be added
+   */
+  private buildStage;
+  /**
+   * Build a $match stage from where operations.
+   *
+   * Query building strategy:
+   * - Top-level where() + orWhere() = Pure OR
+   * - Use callbacks for AND + OR grouping
+   *
+   * @param operations - The where operations
+   * @returns The $match stage or null
+   */
+  private buildMatchStage;
+  private isPureOrCondition;
+  /**
+   * Build a condition from a callback-based where clause.
+   * Creates a sub-builder, executes the callback, and extracts the conditions.
+   * If callback has orWhere, all conditions become OR.
+   *
+   * @param callback - The callback function
+   * @returns The built condition or null
+   */
+  private buildCallbackCondition;
+  /**
+   * Build a MongoDB filter condition from a where operation.
+   *
+   * @param op - The operation to build
+   * @returns The MongoDB filter condition
+   */
+  private buildWhereCondition;
+  /**
+   * Build a condition based on the operator.
+   *
+   * @param field - The field name
+   * @param operator - The comparison operator
+   * @param value - The value to compare
+   * @returns The MongoDB filter condition
+   */
+  private buildOperatorCondition;
+  /**
+   * Get MongoDB operator from comparison operator.
+   *
+   * @param operator - The comparison operator
+   * @returns The MongoDB operator
+   */
+  private getMongoOperator;
+  private resolveRawExpression;
+  private bindRawString;
+  private buildColumnComparison;
+  private buildBetweenColumnsCondition;
+  private wrapColumn;
+  private buildDateEqualityCondition;
+  private buildDateBeforeCondition;
+  private buildDateAfterCondition;
+  private buildTimeCondition;
+  private buildDatePartCondition;
+  private buildJsonContainsCondition;
+  private buildJsonDoesntContainCondition;
+  private buildJsonContainsKeyCondition;
+  private buildJsonLengthCondition;
+  private buildJsonTypeCondition;
+  private buildArrayLengthCondition;
+  private normalizeDateInput;
+  private startOfDay;
+  private endOfDay;
+  private normalizePath;
+  private applyProjectionFields;
+  /**
+   * Apply projection object with aliases and inclusion/exclusion.
+   * @param projection - The projection object to modify
+   * @param projectionObj - The projection specification
+   */
+  private applyProjectionObject;
+  private applyRawProjection;
+  private resolveProjectionExpression;
+  private normalizeFieldReference;
+  private buildAggregateProjection;
+  private buildExistsProjection;
+  private buildArraySizeExpression;
+  private buildCaseExpression;
+  private buildCondExpression;
+  /**
+   * Resolve a value as a literal (if it's a plain string) or as an expression.
+   * Used for `then`/`default` values in CASE/WHEN expressions.
+   */
+  private resolveLiteralOrExpression;
+  private inferJsonAlias;
+  private buildConcatExpression;
+  private buildCoalesceExpression;
+  /**
+   * Build a $project stage from select operations.
+   *
+   * @param operations - The select operations
+   * @returns The $project stage or null
+   */
+  private buildProjectStage;
+  /**
+   * Build a $sort stage from order operations.
+   *
+   * @param operations - The order operations
+   * @returns The $sort stage or null
+   */
+  private buildSortStage;
+  /**
+   * Build a $group stage from group operations.
+   *
+   * @param operations - The group operations
+   * @returns The $group stage or null
+   */
+  private buildGroupStage;
+  private buildGroupByStage;
+  /**
+   * Build a $group stage with aggregates from group operations.
+   *
+   * @param fields - Fields to group by
+   * @param aggregates - Aggregate operations (abstract or raw)
+   * @returns The $group stage or null
+   */
+  private buildGroupByWithAggregatesStage;
+  /**
+   * Extract field names from GroupByInput for renaming _id.
+   *
+   * @param fields - The grouping fields
+   * @returns Field name(s) to use for renaming _id
+   */
+  private extractGroupFieldNames;
+  /**
+   * Translate an abstract aggregate expression to MongoDB format.
+   *
+   * @param expr - Abstract aggregate expression
+   * @returns MongoDB aggregation expression
+   */
+  private translateAggregateExpression;
+  private buildGroupId;
+  /**
+   * Build a $lookup stage from join operations.
+   *
+   * @param operations - The join operations
+   * @returns The $lookup stage or null
+   */
+  private buildLookupStage;
+}
+//#endregion
+export { MongoQueryParser };
+//# sourceMappingURL=mongodb-query-parser.d.mts.map

package/esm/drivers/mongodb/mongodb-query-parser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb-query-parser.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/mongodb/mongodb-query-parser.ts"],"mappings":";;;;;;;AAaA;KAAY,uBAAA;6CAEV,UAAA,EAAY,UAAA,EAEA;EAAZ,UAAA,EAAY,SAAA,IAE6B;EAAzC,gBAAA,QAAwB,iBAAA;AAAA;;;;;;;AAAiB;AAW3C;cAAa,gBAAA;;;;mBAIM,UAAA;EAUA;;;EAAA,iBALA,UAAA;EAkBE;;;EAAA,iBAbF,gBAAA;EA+LV;;;;EAAA,iBAzLU,eAAA;EAgfT;;;;;cAzeW,OAAA,EAAS,uBAAuB;EAs0B3C;;;;;;;;;;;;;;;;;;;;EA5yBD,KAAA,CAAA;EAggCC;;;EAAA,QAt8BA,oBAAA;EAkhCA;;;;;;;;;EAAA,QAz/BA,sBAAA;EA8wCA;;;;;;;AAwLgB;;;;;;;;;;;;;;;;EAj4CjB,cAAA,CAAA;;;;;;;;UAgCC,eAAA;;;;;;;;UAoDA,UAAA;;;;;;;;;;;UAmCA,eAAA;EAAA,QA8KA,iBAAA;;;;;;;;;UAkBA,sBAAA;;;;;;;UA8EA,mBAAA;;;;;;;;;UAiNA,sBAAA;;;;;;;UAyBA,gBAAA;EAAA,QAYA,oBAAA;EAAA,QAaA,aAAA;EAAA,QAYA,qBAAA;EAAA,QASA,4BAAA;EAAA,QAWA,UAAA;EAAA,QAIA,0BAAA;EAAA,QAOA,wBAAA;EAAA,QAKA,uBAAA;EAAA,QAKA,kBAAA;EAAA,QAgBA,sBAAA;EAAA,QAiBA,0BAAA;EAAA,QAQA,+BAAA;EAAA,QAMA,6BAAA;EAAA,QAMA,wBAAA;EAAA,QASA,sBAAA;EAAA,QAQA,yBAAA;EAAA,QASA,kBAAA;EAAA,QAWA,UAAA;EAAA,QAMA,QAAA;EAAA,QAMA,aAAA;EAAA,QAIA,qBAAA;;;;;;UAeA,qBAAA;EAAA,QAmCA,kBAAA;EAAA,QAeA,2BAAA;EAAA,QA0BA,uBAAA;EAAA,QAoBA,wBAAA;EAAA,QAwBA,qBAAA;EAAA,QAMA,wBAAA;EAAA,QAMA,mBAAA;EAAA,QAeA,mBAAA;;;;;UAkBA,0BAAA;EAAA,QAaA,cAAA;EAAA,QAMA,qBAAA;EAAA,QAMA,uBAAA;;;;;;;UAsBA,iBAAA;;;;;;;UAqHA,cAAA;;;;;;;UA2BA,eAAA;EAAA,QA+CA,iBAAA;;;;;;;;UAgBA,+BAAA;;;;;;;UAiCA,sBAAA;;;;;;;UA4BA,4BAAA;EAAA,QA2DA,YAAA;;;;;;;UAgDA,gBAAA;AAAA"}