@warlock.js/cascade 5.12.0 → 5.13.0

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

@@ -71,6 +71,31 @@ declare class MongoQueryParser {
    * ```
    */
   parse(): any[];
+  /**
+   * Apply a raw escape-hatch operation to the pipeline built so far.
+   *
+   * - `joinRaw`: appends the caller-built stages verbatim.
+   * - `raw`: calls the callback with the pipeline array. A returned array
+   *   replaces the pipeline; `undefined` keeps the (possibly mutated) array.
+   *
+   * @throws UnsupportedQueryOperationError when a `raw()` callback leaves
+   *   something other than an array of stage objects
+   */
+  private applyRawOperation;
+  /**
+   * Order a `$sort` against the select `$project` it follows.
+   *
+   * A `$sort` after a `$project` cannot see fields the projection dropped, so
+   * `select(["title"]).orderBy("likes")` would not sort. The sort moves before
+   * the projection, unless it sorts by a field the projection computes
+   * (`selectRaw({ score: ... }).orderBy("score")`), which only exists after it:
+   *
+   * - no computed sort key: `$sort`, `$project`
+   * - only computed or selected sort keys: `$project`, `$sort` (unchanged)
+   * - computed AND unselected sort keys: `$addFields` (the computed keys),
+   *   `$sort`, `$project` (those keys passed through)
+   */
+  private placeSortAroundProjection;
   /**
    * Reorder operations so filters run before projections, mirroring SQL
    * semantics: in `select(...).where(...)`, the WHERE always applies to the
@@ -78,11 +103,13 @@ declare class MongoQueryParser {
    * strips the filter column would run before the `$match` and silently drop
    * every document (`select(["a"]).where("b", x)` → `[]`).
    *
-   * Only *mergeable* `$match` operations are hoisted, and only within a
-   * segment of neighboring mergeable `$match` / `$project` / `$sort`
-   * operations. Any other operation — `$group`, `$lookup`, `$limit`, `$skip`,
-   * `$setWindowFields`, or a non-mergeable op (raw escapes, having-style
-   * post-group matches, `$sample`) — is a barrier: nothing moves across it.
+   * Only *mergeable* operations move, and only within a segment of neighboring
+   * mergeable `$match` / `$project` / `$sort` operations. Inside a segment the
+   * order is `$match`, then `$project`, then `$sort` (each keeping call order),
+   * and {@link placeSortAroundProjection} then decides whether the sort runs
+   * before the projection. Any other operation — `$group`, `$lookup`,
+   * `$limit`, `$skip`, `$setWindowFields`, raw escapes, having-style
+   * post-group matches, `$sample` — is a barrier: nothing moves across it.
    * So `groupBy(...).where(...)` still filters AFTER the group, and
    * `limit(...)` / `random()` keep their call-order meaning.
    */
@@ -98,15 +125,15 @@ declare class MongoQueryParser {
    */
   private trackCountDistinctAliases;
   /**
-   * 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.
+   * Build the `$project` that renames `_id` back to the grouped field name(s)
+   * right after a `$group` stage with tracked field names, so results carry
+   * the grouping columns instead of MongoDB's `_id`.
    *
-   * @param pipeline - The aggregation pipeline
-   * @returns The processed pipeline
+   * @param stage - The stage just emitted
+   * @param stageIndex - Its index in the pipeline
+   * @returns The renaming `$project` stage, or null when none is needed
    */
-  private postProcessGroupStages;
+  private buildGroupRenameStage;
   /**
    * Convert the parsed pipeline to a pretty-printed string for debugging.
    *

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

@@ -1 +1 @@
-{"version":3,"file":"mongodb-query-parser.d.mts","names":[],"sources":["../../../../../../../../cascade/src/drivers/mongodb/mongodb-query-parser.ts"],"mappings":";;;;;;;AAgBA;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;EA0BW;;;EAAA,iBArBX,gBAAA;EAsJT;;;;EAAA,iBAhJS,eAAA;EA8WT;;;;;;EAAA,iBAtWS,oBAAA;EA66BT;;;;;cAt6BW,OAAA,EAAS,uBAAuB;EAmgC3C;;;;;;;;;;;;;;;;;;;;EAz+BD,KAAA;EAutCC;;;;;;;;;;;;;;;EAAA,QAjpCA,WAAA;EAqkDA;;;EAAA,QApiDA,oBAAA;EA+sDgB;AAAA;;;;EAAA,QA7qDhB,yBAAA;;;;;;;;;;UAyBA,sBAAA;;;;;;;;;;;;;;;;;;;;;;;;EA4ED,cAAA;;;;;;;;UAmCC,eAAA;;;;;;;;UAoDA,UAAA;;;;;;;;;;;UAiDA,eAAA;EAAA,QA8KA,iBAAA;;;;;;;;;UAkBA,sBAAA;;;;;;;UA8EA,mBAAA;;;;;;;;;;;;;UA+NA,oBAAA;;;;;;;;;UAgBA,sBAAA;;;;;;;UAyBA,gBAAA;EAAA,QAYA,oBAAA;;;;;;;;UA2BA,4BAAA;EAAA,QAsBA,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,QAYA,qBAAA;EAAA,QAMA,uBAAA;;;;;;;UAsBA,iBAAA;;;;;;;UAqHA,cAAA;;;;;;;UA2BA,eAAA;EAAA,QAgEA,iBAAA;;;;;;;;UAgBA,+BAAA;;;;;;;;;;UAoCA,qBAAA;;;;;;;UA0BA,sBAAA;;;;;;;UA4BA,4BAAA;;;;;;;;;;;;;UAuFA,uBAAA;EAAA,QAoCA,YAAA;;;;;;;UAgDA,gBAAA;AAAA"}
+{"version":3,"file":"mongodb-query-parser.d.mts","names":[],"sources":["../../../../../../../../cascade/src/drivers/mongodb/mongodb-query-parser.ts"],"mappings":";;;;;;;AAkBA;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;EA0BW;;;EAAA,iBArBX,gBAAA;EA4KT;;;;EAAA,iBAtKS,eAAA;EAsXV;;;;;;EAAA,iBA9WU,oBAAA;EAg/BT;;;;;cAz+BW,OAAA,EAAS,uBAAuB;EA2lC3C;;;;;;;;;;;;;;;;;;;;EAjkCD,KAAA;EAqxCC;;;;;;;;;;EAAA,QA3rCA,iBAAA;EAm2CA;;;;;;;;;;;;AA6dgB;EA7dhB,QAh0CA,yBAAA;;;;;;;;;;;;;;;;;;UAuDA,WAAA;;;;UAkCA,oBAAA;;;;;;UAkCA,yBAAA;;;;;;;;;;UAyBA,qBAAA;;;;;;;;;;;;;;;;;;;;;;;;EA4DD,cAAA;;;;;;;;UAmCC,eAAA;;;;;;;;UAoDA,UAAA;;;;;;;;;;;UAyEA,eAAA;EAAA,QA8KA,iBAAA;;;;;;;;;UAkBA,sBAAA;;;;;;;UA8EA,mBAAA;;;;;;;;;;;;;UAoNA,oBAAA;;;;;;;;;UAgBA,sBAAA;;;;;;;UAyBA,gBAAA;EAAA,QAYA,oBAAA;;;;;;;;UA2BA,4BAAA;EAAA,QAsBA,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,QAYA,qBAAA;EAAA,QAMA,uBAAA;;;;;;;UAsBA,iBAAA;;;;;;;UAgHA,cAAA;;;;;;;UA2BA,eAAA;EAAA,QA6DA,iBAAA;;;;;;;;UAgBA,+BAAA;;;;;;;;;;UAoCA,qBAAA;;;;;;;UA0BA,sBAAA;;;;;;;UA4BA,4BAAA;;;;;;;;;;;;;UAuFA,uBAAA;EAAA,QAoCA,YAAA;;;;;;;UAgDA,gBAAA;AAAA"}

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

@@ -1,6 +1,8 @@
 import { UnsafeRawExpressionError } from "../../errors/unsafe-raw-expression.error.mjs";
+import { UnsupportedQueryOperationError } from "../../errors/unsupported-query-operation.error.mjs";
 import { isAggregateExpression } from "../../expressions/aggregate-expressions.mjs";
 import { escapeRegex, resolveLikePattern } from "../../utils/escape-regex.mjs";
+import { isPipelineStageObject } from "./pipeline-stage-object.mjs";
 import { colors } from "@mongez/copper";
 
 //#region ../cascade/src/drivers/mongodb/mongodb-query-parser.ts
@@ -68,42 +70,110 @@ var MongoQueryParser = class {
 	* ```
 	*/
 	parse() {
+		this.groupFieldNames.clear();
+		this.countDistinctAliases.clear();
 		const pipeline = [];
 		let currentStage = null;
 		let currentBuffer = [];
-		for (const op of this.orderStages(this.operations)) if (op.mergeable && op.stage === currentStage) currentBuffer.push(op);
-		else {
+		let trailingProjectIndex = -1;
+		const emit = (stage, operations) => {
+			if (stage === "$raw") {
+				for (const op of operations) this.applyRawOperation(pipeline, op);
+				trailingProjectIndex = -1;
+				return;
+			}
+			const builtStage = this.buildStage(stage, operations);
+			if (!builtStage) return;
+			if (builtStage.$sort && trailingProjectIndex >= 0 && trailingProjectIndex === pipeline.length - 1) {
+				const projectStage = pipeline.pop();
+				pipeline.push(...this.placeSortAroundProjection(projectStage, builtStage));
+				trailingProjectIndex = -1;
+				return;
+			}
+			const stageIndex = pipeline.length;
+			pipeline.push(builtStage);
+			trailingProjectIndex = stage === "$project" ? stageIndex : -1;
+			this.trackGroupFieldNames(stage, operations, stageIndex);
+			const renameStage = this.buildGroupRenameStage(builtStage, stageIndex);
+			if (renameStage) pipeline.push(renameStage);
+		};
+		for (const op of this.orderStages(this.operations)) {
+			if (op.mergeable && op.stage === currentStage) {
+				currentBuffer.push(op);
+				continue;
+			}
 			if (currentBuffer.length > 0) {
-				const builtStage = this.buildStage(currentStage, currentBuffer);
-				if (builtStage) {
-					const stageIndex = pipeline.length;
-					pipeline.push(builtStage);
-					this.trackGroupFieldNames(currentStage, currentBuffer, stageIndex);
-				}
+				emit(currentStage, currentBuffer);
 				currentBuffer = [];
 			}
 			if (op.mergeable) {
 				currentStage = op.stage;
 				currentBuffer.push(op);
 			} else {
-				const builtStage = this.buildStage(op.stage, [op]);
-				if (builtStage) {
-					const stageIndex = pipeline.length;
-					pipeline.push(builtStage);
-					this.trackGroupFieldNames(op.stage, [op], stageIndex);
-				}
+				emit(op.stage, [op]);
 				currentStage = null;
 			}
 		}
-		if (currentBuffer.length > 0) {
-			const builtStage = this.buildStage(currentStage, currentBuffer);
-			if (builtStage) {
-				const stageIndex = pipeline.length;
-				pipeline.push(builtStage);
-				this.trackGroupFieldNames(currentStage, currentBuffer, stageIndex);
-			}
+		if (currentBuffer.length > 0) emit(currentStage, currentBuffer);
+		return pipeline;
+	}
+	/**
+	* Apply a raw escape-hatch operation to the pipeline built so far.
+	*
+	* - `joinRaw`: appends the caller-built stages verbatim.
+	* - `raw`: calls the callback with the pipeline array. A returned array
+	*   replaces the pipeline; `undefined` keeps the (possibly mutated) array.
+	*
+	* @throws UnsupportedQueryOperationError when a `raw()` callback leaves
+	*   something other than an array of stage objects
+	*/
+	applyRawOperation(pipeline, op) {
+		if (op.type === "joinRaw") {
+			pipeline.push(...op.data.stages);
+			return;
 		}
-		return this.postProcessGroupStages(pipeline);
+		const result = op.data.builder(pipeline);
+		const next = result === void 0 ? pipeline : result;
+		if (!Array.isArray(next) || !next.every(isPipelineStageObject)) throw new UnsupportedQueryOperationError("raw", "mongodb", "The raw() callback receives the aggregation pipeline array and must return an array of stage objects, or mutate that array and return nothing.");
+		if (next !== pipeline) pipeline.splice(0, pipeline.length, ...next);
+	}
+	/**
+	* Order a `$sort` against the select `$project` it follows.
+	*
+	* A `$sort` after a `$project` cannot see fields the projection dropped, so
+	* `select(["title"]).orderBy("likes")` would not sort. The sort moves before
+	* the projection, unless it sorts by a field the projection computes
+	* (`selectRaw({ score: ... }).orderBy("score")`), which only exists after it:
+	*
+	* - no computed sort key: `$sort`, `$project`
+	* - only computed or selected sort keys: `$project`, `$sort` (unchanged)
+	* - computed AND unselected sort keys: `$addFields` (the computed keys),
+	*   `$sort`, `$project` (those keys passed through)
+	*/
+	placeSortAroundProjection(projectStage, sortStage) {
+		const projection = projectStage.$project;
+		const sortKeys = Object.keys(sortStage.$sort);
+		const isInclusionFlag = (value) => value === 1 || value === true || value === 0 || value === false;
+		const computedKeys = sortKeys.filter((key) => {
+			const value = projection[key];
+			return value !== void 0 && !isInclusionFlag(value) && value !== `$${key}`;
+		});
+		if (computedKeys.length === 0) return [sortStage, projectStage];
+		if (!sortKeys.some((key) => {
+			const value = projection[key];
+			return value === void 0 || value === 0 || value === false;
+		})) return [projectStage, sortStage];
+		const addFields = {};
+		const passThrough = { ...projection };
+		for (const key of computedKeys) {
+			addFields[key] = projection[key];
+			passThrough[key] = 1;
+		}
+		return [
+			{ $addFields: addFields },
+			sortStage,
+			{ $project: passThrough }
+		];
 	}
 	/**
 	* Reorder operations so filters run before projections, mirroring SQL
@@ -112,11 +182,13 @@ var MongoQueryParser = class {
 	* strips the filter column would run before the `$match` and silently drop
 	* every document (`select(["a"]).where("b", x)` → `[]`).
 	*
-	* Only *mergeable* `$match` operations are hoisted, and only within a
-	* segment of neighboring mergeable `$match` / `$project` / `$sort`
-	* operations. Any other operation — `$group`, `$lookup`, `$limit`, `$skip`,
-	* `$setWindowFields`, or a non-mergeable op (raw escapes, having-style
-	* post-group matches, `$sample`) — is a barrier: nothing moves across it.
+	* Only *mergeable* operations move, and only within a segment of neighboring
+	* mergeable `$match` / `$project` / `$sort` operations. Inside a segment the
+	* order is `$match`, then `$project`, then `$sort` (each keeping call order),
+	* and {@link placeSortAroundProjection} then decides whether the sort runs
+	* before the projection. Any other operation — `$group`, `$lookup`,
+	* `$limit`, `$skip`, `$setWindowFields`, raw escapes, having-style
+	* post-group matches, `$sample` — is a barrier: nothing moves across it.
 	* So `groupBy(...).where(...)` still filters AFTER the group, and
 	* `limit(...)` / `random()` keep their call-order meaning.
 	*/
@@ -126,7 +198,8 @@ var MongoQueryParser = class {
 		const flushSegment = () => {
 			if (segment.length === 0) return;
 			reordered.push(...segment.filter((op) => op.stage === "$match"));
-			reordered.push(...segment.filter((op) => op.stage !== "$match"));
+			reordered.push(...segment.filter((op) => op.stage === "$project"));
+			reordered.push(...segment.filter((op) => op.stage === "$sort"));
 			segment = [];
 		};
 		for (const op of operations) if (op.mergeable && (op.stage === "$match" || op.stage === "$project" || op.stage === "$sort")) segment.push(op);
@@ -165,35 +238,26 @@ var MongoQueryParser = class {
 		if (distinctAliases.size > 0) this.countDistinctAliases.set(stageIndex, distinctAliases);
 	}
 	/**
-	* 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.
+	* Build the `$project` that renames `_id` back to the grouped field name(s)
+	* right after a `$group` stage with tracked field names, so results carry
+	* the grouping columns instead of MongoDB's `_id`.
 	*
-	* @param pipeline - The aggregation pipeline
-	* @returns The processed pipeline
+	* @param stage - The stage just emitted
+	* @param stageIndex - Its index in the pipeline
+	* @returns The renaming `$project` stage, or null when none is needed
 	*/
-	postProcessGroupStages(pipeline) {
-		const processed = [];
-		for (let i = 0; i < pipeline.length; i++) {
-			const stage = pipeline[i];
-			if (stage.$group && this.groupFieldNames.has(i)) {
-				const fieldNames = this.groupFieldNames.get(i);
-				processed.push(stage);
-				const projection = {};
-				if (typeof fieldNames === "string") projection[fieldNames] = "$_id";
-				else if (Array.isArray(fieldNames) && fieldNames.length > 0) for (const fieldName of fieldNames) projection[fieldName] = `$_id.${fieldName}`;
-				const distinctAliases = this.countDistinctAliases.get(i);
-				const aggregateFields = Object.keys(stage.$group).filter((key) => key !== "_id");
-				for (const field of aggregateFields) if (distinctAliases?.has(field)) projection[field] = { $size: `$${field}` };
-				else projection[field] = 1;
-				if (Object.keys(projection).length > 0) {
-					projection._id = 0;
-					processed.push({ $project: projection });
-				}
-			} else processed.push(stage);
-		}
-		return processed;
+	buildGroupRenameStage(stage, stageIndex) {
+		if (!stage.$group || !this.groupFieldNames.has(stageIndex)) return null;
+		const fieldNames = this.groupFieldNames.get(stageIndex);
+		const projection = {};
+		if (typeof fieldNames === "string") projection[fieldNames] = "$_id";
+		else if (Array.isArray(fieldNames) && fieldNames.length > 0) for (const fieldName of fieldNames) projection[fieldName] = `$_id.${fieldName}`;
+		const distinctAliases = this.countDistinctAliases.get(stageIndex);
+		const aggregateFields = Object.keys(stage.$group).filter((key) => key !== "_id");
+		for (const field of aggregateFields) projection[field] = distinctAliases?.has(field) ? { $size: `$${field}` } : 1;
+		if (Object.keys(projection).length === 0) return null;
+		projection._id = 0;
+		return { $project: projection };
 	}
 	/**
 	* Convert the parsed pipeline to a pretty-printed string for debugging.
@@ -293,6 +357,23 @@ var MongoQueryParser = class {
 				const [first] = operations;
 				return first === void 0 ? null : { $setWindowFields: first.data.spec };
 			}
+			case "$unwind": {
+				const [first] = operations;
+				if (first === void 0) return null;
+				const { path, ...options } = first.data;
+				return Object.keys(options).length === 0 ? { $unwind: path } : { $unwind: {
+					path,
+					...options
+				} };
+			}
+			case "$addFields": {
+				const [first] = operations;
+				return first === void 0 ? null : { $addFields: first.data };
+			}
+			case "$vectorSearch": {
+				const [first] = operations;
+				return first === void 0 ? null : { $vectorSearch: first.data };
+			}
 			default: return null;
 		}
 	}
@@ -1109,6 +1190,13 @@ var MongoQueryParser = class {
 		const op = operations[0];
 		if (op === void 0) return null;
 		const options = op.data;
+		if (Array.isArray(options.pipeline)) return { $lookup: {
+			from: options.table,
+			...options.localField !== void 0 ? { localField: options.localField } : {},
+			...options.foreignField !== void 0 ? { foreignField: options.foreignField } : {},
+			as: options.alias || options.table,
+			pipeline: options.pipeline
+		} };
 		return { $lookup: {
 			from: options.table,
 			localField: options.localField,