@atscript/db-mongo 0.1.128 → 0.1.130

package/dist/agg.cjs

@@ -37,14 +37,19 @@ function groupIdKey(field, index) {
 	return field.includes(".") ? `k${index}` : field;
 }
 /**
-* Builds the common prefix stages: $match + $group._id from groupBy fields.
-* Shared by both full aggregate and count pipelines.
+* Builds the common prefix stages: [search] + $match + $group._id from groupBy
+* fields. Shared by both full aggregate and count pipelines.
 * `groupKeys` maps each `$groupBy` path to its `_id` sub-key.
+*
+* `searchStage` is the resolved text-search stage (classic `$text` `$match`, or
+* an Atlas `$search`). Both MUST be the pipeline's FIRST stage, hence its
+* position in front of the filter `$match`. Resolving it needs adapter state,
+* so the caller passes it in and this module stays a pure translation.
 */
-function buildPrefix(query) {
+function buildPrefix(query, searchStage) {
 	const controls = query.controls || {};
 	const groupBy = controls.$groupBy ?? [];
-	const pipeline = [{ $match: require_mongo_filter.buildMongoFilter(query.filter) }];
+	const pipeline = searchStage ? [searchStage, { $match: require_mongo_filter.buildMongoFilter(query.filter) }] : [{ $match: require_mongo_filter.buildMongoFilter(query.filter) }];
 	const groupId = {};
 	const groupKeys = [];
 	for (const [index, field] of groupBy.entries()) {
@@ -60,17 +65,30 @@ function buildPrefix(query) {
 	};
 }
 /**
-* Builds a full MongoDB aggregation pipeline for GROUP BY queries.
+* The stages every grouped query shares: `[search →] $match(filter)` →
+* `$group` (dimensions + accumulators) → `$project` (flatten `_id`, keep
+* aliases) → `$match($having)`. The row pipeline appends sort/skip/limit, the
+* count pipeline appends `$count`, so both see exactly the same group set —
+* including the same `$search` narrowing, which is why the stage is threaded
+* through this single seam instead of being appended by each caller.
 *
-* Pipeline: $match → $group → $project → $match(having) → $sort → $skip → $limit
+* With `accumulators: false` only the `$group._id` dimensions are emitted
+* (no accumulators, no `$project`, no `$having`) — the cheapest shape for a
+* plain group count, where no alias has to be resolvable.
 */
-function buildAggregatePipeline(query) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query);
+function buildGroupedStages(query, { accumulators, searchStage }) {
+	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage);
 	const groupStage = { _id: groupId };
+	if (!accumulators) {
+		pipeline.push({ $group: groupStage });
+		return {
+			pipeline,
+			controls
+		};
+	}
 	const project = { _id: 0 };
-	const aggregates = controls.$select?.aggregates;
 	for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
-	if (aggregates) for (const expr of aggregates) {
+	for (const expr of controls.$select?.aggregates ?? []) {
 		const alias = (0, _atscript_db_agg.resolveAlias)(expr);
 		groupStage[alias] = toAccumulator(expr);
 		project[alias] = 1;
@@ -78,25 +96,48 @@ function buildAggregatePipeline(query) {
 	pipeline.push({ $group: groupStage });
 	pipeline.push({ $project: project });
 	if (controls.$having) pipeline.push({ $match: require_mongo_filter.buildMongoFilter(controls.$having) });
+	return {
+		pipeline,
+		controls
+	};
+}
+/**
+* Builds a full MongoDB aggregation pipeline for GROUP BY queries.
+*
+* Pipeline: [search →] $match → $group → $project → $match(having) → $sort →
+* $skip → $limit
+*
+* `searchStage` is the resolved `$search` / `$text` stage (see
+* `buildAggregateSearchStage`); unlike the leaf runner this path adds no
+* relevance `$sort` and no default `$limit`.
+*/
+function buildAggregatePipeline(query, searchStage) {
+	const { pipeline, controls } = buildGroupedStages(query, {
+		accumulators: true,
+		searchStage
+	});
 	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
 	if (controls.$limit) pipeline.push({ $limit: controls.$limit });
 	return pipeline;
 }
 /**
-* Builds a count-only pipeline: returns the number of distinct groups.
+* Builds a count-only pipeline: the number of groups that survive `$having`
+* (all groups when there is none). With `$having` it runs the same grouped
+* stages as the row pipeline — the accumulators must run so an alias
+* `$having` has a value to match; without it only the `$group._id`
+* dimensions are needed.
+*
+* Pipeline: [search →] $match → $group → [$project → $match(having)] → $count
 *
-* Pipeline: $match → $group (just _id) → $project → $match(having) → $count
+* `searchStage` must be the SAME stage handed to `buildAggregatePipeline` for
+* the same query — the counted groups are exactly the rows the search matched.
 */
-function buildCountPipeline(query) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query);
-	pipeline.push({ $group: { _id: groupId } });
-	if (controls.$having) {
-		const project = { _id: 0 };
-		for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
-		pipeline.push({ $project: project });
-		pipeline.push({ $match: require_mongo_filter.buildMongoFilter(controls.$having) });
-	}
+function buildCountPipeline(query, searchStage) {
+	const { pipeline } = buildGroupedStages(query, {
+		accumulators: Boolean(query.controls?.$having),
+		searchStage
+	});
 	pipeline.push({ $count: "count" });
 	return pipeline;
 }

package/dist/agg.d.cts

@@ -5,14 +5,26 @@ import { Document } from "mongodb";
 /**
  * Builds a full MongoDB aggregation pipeline for GROUP BY queries.
  *
- * Pipeline: $match → $group → $project → $match(having) → $sort → $skip → $limit
+ * Pipeline: [search →] $match → $group → $project → $match(having) → $sort →
+ * $skip → $limit
+ *
+ * `searchStage` is the resolved `$search` / `$text` stage (see
+ * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
+ * relevance `$sort` and no default `$limit`.
  */
-declare function buildAggregatePipeline(query: DbQuery): Document[];
+declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document): Document[];
 /**
- * Builds a count-only pipeline: returns the number of distinct groups.
+ * Builds a count-only pipeline: the number of groups that survive `$having`
+ * (all groups when there is none). With `$having` it runs the same grouped
+ * stages as the row pipeline — the accumulators must run so an alias
+ * `$having` has a value to match; without it only the `$group._id`
+ * dimensions are needed.
+ *
+ * Pipeline: [search →] $match → $group → [$project → $match(having)] → $count
  *
- * Pipeline: $match → $group (just _id) → $project → $match(having) → $count
+ * `searchStage` must be the SAME stage handed to `buildAggregatePipeline` for
+ * the same query — the counted groups are exactly the rows the search matched.
  */
-declare function buildCountPipeline(query: DbQuery): Document[];
+declare function buildCountPipeline(query: DbQuery, searchStage?: Document): Document[];
 //#endregion
 export { buildAggregatePipeline, buildCountPipeline };

package/dist/agg.d.mts

@@ -5,14 +5,26 @@ import { Document } from "mongodb";
 /**
  * Builds a full MongoDB aggregation pipeline for GROUP BY queries.
  *
- * Pipeline: $match → $group → $project → $match(having) → $sort → $skip → $limit
+ * Pipeline: [search →] $match → $group → $project → $match(having) → $sort →
+ * $skip → $limit
+ *
+ * `searchStage` is the resolved `$search` / `$text` stage (see
+ * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
+ * relevance `$sort` and no default `$limit`.
  */
-declare function buildAggregatePipeline(query: DbQuery): Document[];
+declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document): Document[];
 /**
- * Builds a count-only pipeline: returns the number of distinct groups.
+ * Builds a count-only pipeline: the number of groups that survive `$having`
+ * (all groups when there is none). With `$having` it runs the same grouped
+ * stages as the row pipeline — the accumulators must run so an alias
+ * `$having` has a value to match; without it only the `$group._id`
+ * dimensions are needed.
+ *
+ * Pipeline: [search →] $match → $group → [$project → $match(having)] → $count
  *
- * Pipeline: $match → $group (just _id) → $project → $match(having) → $count
+ * `searchStage` must be the SAME stage handed to `buildAggregatePipeline` for
+ * the same query — the counted groups are exactly the rows the search matched.
  */
-declare function buildCountPipeline(query: DbQuery): Document[];
+declare function buildCountPipeline(query: DbQuery, searchStage?: Document): Document[];
 //#endregion
 export { buildAggregatePipeline, buildCountPipeline };

package/dist/agg.mjs

@@ -36,14 +36,19 @@ function groupIdKey(field, index) {
 	return field.includes(".") ? `k${index}` : field;
 }
 /**
-* Builds the common prefix stages: $match + $group._id from groupBy fields.
-* Shared by both full aggregate and count pipelines.
+* Builds the common prefix stages: [search] + $match + $group._id from groupBy
+* fields. Shared by both full aggregate and count pipelines.
 * `groupKeys` maps each `$groupBy` path to its `_id` sub-key.
+*
+* `searchStage` is the resolved text-search stage (classic `$text` `$match`, or
+* an Atlas `$search`). Both MUST be the pipeline's FIRST stage, hence its
+* position in front of the filter `$match`. Resolving it needs adapter state,
+* so the caller passes it in and this module stays a pure translation.
 */
-function buildPrefix(query) {
+function buildPrefix(query, searchStage) {
 	const controls = query.controls || {};
 	const groupBy = controls.$groupBy ?? [];
-	const pipeline = [{ $match: buildMongoFilter(query.filter) }];
+	const pipeline = searchStage ? [searchStage, { $match: buildMongoFilter(query.filter) }] : [{ $match: buildMongoFilter(query.filter) }];
 	const groupId = {};
 	const groupKeys = [];
 	for (const [index, field] of groupBy.entries()) {
@@ -59,17 +64,30 @@ function buildPrefix(query) {
 	};
 }
 /**
-* Builds a full MongoDB aggregation pipeline for GROUP BY queries.
+* The stages every grouped query shares: `[search →] $match(filter)` →
+* `$group` (dimensions + accumulators) → `$project` (flatten `_id`, keep
+* aliases) → `$match($having)`. The row pipeline appends sort/skip/limit, the
+* count pipeline appends `$count`, so both see exactly the same group set —
+* including the same `$search` narrowing, which is why the stage is threaded
+* through this single seam instead of being appended by each caller.
 *
-* Pipeline: $match → $group → $project → $match(having) → $sort → $skip → $limit
+* With `accumulators: false` only the `$group._id` dimensions are emitted
+* (no accumulators, no `$project`, no `$having`) — the cheapest shape for a
+* plain group count, where no alias has to be resolvable.
 */
-function buildAggregatePipeline(query) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query);
+function buildGroupedStages(query, { accumulators, searchStage }) {
+	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage);
 	const groupStage = { _id: groupId };
+	if (!accumulators) {
+		pipeline.push({ $group: groupStage });
+		return {
+			pipeline,
+			controls
+		};
+	}
 	const project = { _id: 0 };
-	const aggregates = controls.$select?.aggregates;
 	for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
-	if (aggregates) for (const expr of aggregates) {
+	for (const expr of controls.$select?.aggregates ?? []) {
 		const alias = resolveAlias(expr);
 		groupStage[alias] = toAccumulator(expr);
 		project[alias] = 1;
@@ -77,25 +95,48 @@ function buildAggregatePipeline(query) {
 	pipeline.push({ $group: groupStage });
 	pipeline.push({ $project: project });
 	if (controls.$having) pipeline.push({ $match: buildMongoFilter(controls.$having) });
+	return {
+		pipeline,
+		controls
+	};
+}
+/**
+* Builds a full MongoDB aggregation pipeline for GROUP BY queries.
+*
+* Pipeline: [search →] $match → $group → $project → $match(having) → $sort →
+* $skip → $limit
+*
+* `searchStage` is the resolved `$search` / `$text` stage (see
+* `buildAggregateSearchStage`); unlike the leaf runner this path adds no
+* relevance `$sort` and no default `$limit`.
+*/
+function buildAggregatePipeline(query, searchStage) {
+	const { pipeline, controls } = buildGroupedStages(query, {
+		accumulators: true,
+		searchStage
+	});
 	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
 	if (controls.$limit) pipeline.push({ $limit: controls.$limit });
 	return pipeline;
 }
 /**
-* Builds a count-only pipeline: returns the number of distinct groups.
+* Builds a count-only pipeline: the number of groups that survive `$having`
+* (all groups when there is none). With `$having` it runs the same grouped
+* stages as the row pipeline — the accumulators must run so an alias
+* `$having` has a value to match; without it only the `$group._id`
+* dimensions are needed.
+*
+* Pipeline: [search →] $match → $group → [$project → $match(having)] → $count
 *
-* Pipeline: $match → $group (just _id) → $project → $match(having) → $count
+* `searchStage` must be the SAME stage handed to `buildAggregatePipeline` for
+* the same query — the counted groups are exactly the rows the search matched.
 */
-function buildCountPipeline(query) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query);
-	pipeline.push({ $group: { _id: groupId } });
-	if (controls.$having) {
-		const project = { _id: 0 };
-		for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
-		pipeline.push({ $project: project });
-		pipeline.push({ $match: buildMongoFilter(controls.$having) });
-	}
+function buildCountPipeline(query, searchStage) {
+	const { pipeline } = buildGroupedStages(query, {
+		accumulators: Boolean(query.controls?.$having),
+		searchStage
+	});
 	pipeline.push({ $count: "count" });
 	return pipeline;
 }

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_mongo_filter = require("./mongo-filter-z_hLPMyv.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
+let _atscript_db_agg = require("@atscript/db/agg");
 //#region src/lib/path-utils.ts
 function joinPath(prefix, segment) {
 	return prefix ? `${prefix}.${segment}` : segment;
@@ -648,16 +649,39 @@ function isVectorSearchableImpl(host) {
 	for (const index of host.getMongoSearchIndexes().values()) if (index.type === "vector") return true;
 	return false;
 }
+/**
+* Resolves the leading stage for a text search, or throws when no index
+* answers to `indexName` (the default index when it is omitted).
+*/
+function requireSearchStage(host, text, indexName, controls) {
+	const plan = buildSearchStage(host, text, indexName, controls);
+	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	return plan;
+}
+/**
+* Resolves the leading search stage for a GROUPED aggregate query, or
+* `undefined` when the query carries no `$search` term (the plain grouped
+* path). `$index` picks the search index by the same rules as `search()`, and
+* an unresolvable one throws exactly as the leaf path does.
+*
+* `classicText` is deliberately dropped: it only drives the leaf runner's
+* `_score` projection and relevance `$sort`, and no per-document score
+* survives `$group`. See `resolveAggregateSearch` in `@atscript/db/agg` for
+* the normative cross-adapter contract.
+*/
+function buildAggregateSearchStage(host, controls) {
+	const search = (0, _atscript_db_agg.resolveAggregateSearch)(controls);
+	if (!search) return;
+	return requireSearchStage(host, search.text, search.indexName, controls).stage;
+}
 /** Text search via $search aggregation stage. */
 async function searchImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName, query.controls);
-	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	const plan = requireSearchStage(host, text, indexName, query.controls);
 	return runSearchPipeline(host, plan.stage, query, "search", void 0, plan.classicText);
 }
 /** Text search with faceted count. */
 async function searchWithCountImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName, query.controls);
-	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	const plan = requireSearchStage(host, text, indexName, query.controls);
 	return runSearchWithCountPipeline(host, plan.stage, query, "searchWithCount", void 0, plan.classicText);
 }
 /** Vector search via $vectorSearch aggregation stage. */
@@ -1681,13 +1705,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	}
 	async aggregate(query) {
 		const { buildAggregatePipeline, buildCountPipeline } = await Promise.resolve().then(() => require("./agg.cjs"));
+		const searchStage = buildAggregateSearchStage(this, query.controls);
 		if (query.controls?.$count) {
-			const pipeline = buildCountPipeline(query);
+			const pipeline = buildCountPipeline(query, searchStage);
 			this._log("aggregate (count)", pipeline);
 			const result = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
 			return result.length > 0 ? result : [{ count: 0 }];
 		}
-		const pipeline = buildAggregatePipeline(query);
+		const pipeline = buildAggregatePipeline(query, searchStage);
 		this._log("aggregate", pipeline);
 		return wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
 	}

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { t as buildMongoFilter } from "./mongo-filter-DceAGI-S.mjs";
 import { BaseDbAdapter, DbError, DbSpace, computeInsights, createFailureCollector, getDbFieldOp, getKeyProps, isAtscriptDbView, resolveDesignType } from "@atscript/db";
 import { MongoClient, MongoServerError, ObjectId } from "mongodb";
+import { resolveAggregateSearch } from "@atscript/db/agg";
 //#region src/lib/path-utils.ts
 function joinPath(prefix, segment) {
 	return prefix ? `${prefix}.${segment}` : segment;
@@ -647,16 +648,39 @@ function isVectorSearchableImpl(host) {
 	for (const index of host.getMongoSearchIndexes().values()) if (index.type === "vector") return true;
 	return false;
 }
+/**
+* Resolves the leading stage for a text search, or throws when no index
+* answers to `indexName` (the default index when it is omitted).
+*/
+function requireSearchStage(host, text, indexName, controls) {
+	const plan = buildSearchStage(host, text, indexName, controls);
+	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	return plan;
+}
+/**
+* Resolves the leading search stage for a GROUPED aggregate query, or
+* `undefined` when the query carries no `$search` term (the plain grouped
+* path). `$index` picks the search index by the same rules as `search()`, and
+* an unresolvable one throws exactly as the leaf path does.
+*
+* `classicText` is deliberately dropped: it only drives the leaf runner's
+* `_score` projection and relevance `$sort`, and no per-document score
+* survives `$group`. See `resolveAggregateSearch` in `@atscript/db/agg` for
+* the normative cross-adapter contract.
+*/
+function buildAggregateSearchStage(host, controls) {
+	const search = resolveAggregateSearch(controls);
+	if (!search) return;
+	return requireSearchStage(host, search.text, search.indexName, controls).stage;
+}
 /** Text search via $search aggregation stage. */
 async function searchImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName, query.controls);
-	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	const plan = requireSearchStage(host, text, indexName, query.controls);
 	return runSearchPipeline(host, plan.stage, query, "search", void 0, plan.classicText);
 }
 /** Text search with faceted count. */
 async function searchWithCountImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName, query.controls);
-	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
+	const plan = requireSearchStage(host, text, indexName, query.controls);
 	return runSearchWithCountPipeline(host, plan.stage, query, "searchWithCount", void 0, plan.classicText);
 }
 /** Vector search via $vectorSearch aggregation stage. */
@@ -1680,13 +1704,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	}
 	async aggregate(query) {
 		const { buildAggregatePipeline, buildCountPipeline } = await import("./agg.mjs");
+		const searchStage = buildAggregateSearchStage(this, query.controls);
 		if (query.controls?.$count) {
-			const pipeline = buildCountPipeline(query);
+			const pipeline = buildCountPipeline(query, searchStage);
 			this._log("aggregate (count)", pipeline);
 			const result = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
 			return result.length > 0 ? result : [{ count: 0 }];
 		}
-		const pipeline = buildAggregatePipeline(query);
+		const pipeline = buildAggregatePipeline(query, searchStage);
 		this._log("aggregate", pipeline);
 		return wrapInvalidQuery(() => this.aggregatePipeline(pipeline).toArray());
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.128",
+  "version": "0.1.130",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -56,7 +56,7 @@
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.128"
+    "@atscript/db": "^0.1.130"
   },
   "scripts": {
     "postinstall": "asc -f dts",