@atscript/db-mongo 0.1.146 → 0.1.148

package/dist/agg.cjs

@@ -1,19 +1,29 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_accumulator = require("./mongo-accumulator-BalE9LkU.cjs");
+const require_mongo_accumulator = require("./mongo-accumulator-BKMdRf3s.cjs");
+let _atscript_db = require("@atscript/db");
 let _atscript_db_agg = require("@atscript/db/agg");
 let _uniqu_core = require("@uniqu/core");
 //#region src/agg.ts
+/**
+* MongoDB aggregation pipeline builder.
+* Dynamically imported by MongoAdapter.aggregate() on first call.
+*
+* Constructs MongoDB aggregation pipelines from translated DbQuery objects
+* containing $groupBy, $select (with AggregateExpr), $having, $sort, etc.
+*/
 /** Maps an AggregateExpr to its MongoDB `$group` accumulator (see `buildAccumulator`). */
 function toAccumulator(expr) {
 	return require_mongo_accumulator.buildAccumulator(expr.$fn, expr.$field === "*" ? "*" : `$${expr.$field}`);
 }
+/** An operand of query-time arithmetic: the field as a double (IEEE, like the SQL adapters). */
+const asDouble = (path) => ({ $toDouble: `$${path}` });
+/** Prefix of the hidden `$group` field counting a sum's non-null values. */
+const NON_NULL_PREFIX = "__as_n_";
 const DAY_MS = 864e5;
 const ISO_DATE = "%Y-%m-%d";
-/**
-* Units whose first day `$dateToString` renders straight from the instant in
-* the zone: the local day, then the literal `01` for day-of-month / month.
-*/
-const LOCAL_DATE_FORMATS = {
+/** Units `$dateToString` labels straight from the instant in the zone (literal `01` for day / month). */
+const LOCAL_LABEL_FORMATS = {
+	hour: "%Y-%m-%dT%H:00",
 	day: ISO_DATE,
 	month: "%Y-%m-01",
 	year: "%Y-01-01"
@@ -41,7 +51,8 @@ function naiveFirstDay(b) {
 }
 /**
 * The `$group._id` expression of a calendar bucket: the ISO local date
-* `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+* `YYYY-MM-DD` of the bucket's first day in `b.tz` (for `hour`, the local
+* `YYYY-MM-DDTHH:00`), or `null`.
 *
 * The only zone-aware step is instant → local date (`timezone` on
 * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
@@ -58,7 +69,7 @@ function naiveFirstDay(b) {
 function bucketExpression(b) {
 	const source = `$${b.field}`;
 	const date = { $toDate: { $toLong: source } };
-	const format = LOCAL_DATE_FORMATS[b.unit];
+	const format = LOCAL_LABEL_FORMATS[b.unit];
 	const label = format ? { $dateToString: {
 		date,
 		format,
@@ -101,10 +112,11 @@ function bucketExpression(b) {
 * 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, searchStage) {
+function buildPrefix(query, searchStage, filterOptions) {
 	const controls = query.controls || {};
 	const groupBy = controls.$groupBy ?? [];
-	const pipeline = searchStage ? [searchStage, { $match: require_mongo_accumulator.buildMongoFilter(query.filter) }] : [{ $match: require_mongo_accumulator.buildMongoFilter(query.filter) }];
+	const filterStages = require_mongo_accumulator.mongoFilterStages(query.filter, filterOptions);
+	const pipeline = searchStage ? [searchStage, ...filterStages] : filterStages;
 	const groupId = {};
 	const groupKeys = [];
 	for (const [index, key] of groupBy.entries()) {
@@ -132,8 +144,8 @@ function buildPrefix(query, searchStage) {
 * (no accumulators, no `$project`, no `$having`) — the cheapest shape for a
 * plain group count, where no alias has to be resolvable.
 */
-function buildGroupedStages(query, { accumulators, searchStage }) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage);
+function buildGroupedStages(query, { accumulators, searchStage, filterOptions }) {
+	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage, filterOptions);
 	const groupStage = { _id: groupId };
 	if (!accumulators) {
 		pipeline.push({ $group: groupStage });
@@ -142,15 +154,41 @@ function buildGroupedStages(query, { accumulators, searchStage }) {
 			controls
 		};
 	}
+	const firstLast = controls.$select?.firstLast ?? [];
+	const rowOrder = controls.$select?.rowOrder ?? [];
+	if (firstLast.length > 0 && rowOrder.length > 0) pipeline.push({ $sort: Object.fromEntries(rowOrder.map((k) => [k.column, k.desc ? -1 : 1])) });
 	const project = { _id: 0 };
 	for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
+	const nullWhenEmpty = (alias, nonNull) => {
+		const count = `${NON_NULL_PREFIX}${alias}`;
+		groupStage[count] = { $sum: { $cond: [
+			nonNull,
+			1,
+			0
+		] } };
+		return { $cond: [
+			{ $eq: [`$${count}`, 0] },
+			null,
+			`$${alias}`
+		] };
+	};
 	for (const expr of controls.$select?.aggregates ?? []) {
 		const alias = (0, _atscript_db_agg.resolveAlias)(expr);
 		groupStage[alias] = toAccumulator(expr);
-		project[alias] = expr.$fn === "countDistinct" ? require_mongo_accumulator.distinctCountExpr(`$${alias}`) : 1;
+		project[alias] = expr.$fn === "countDistinct" ? require_mongo_accumulator.distinctCountExpr(`$${alias}`) : expr.$fn === "sum" ? nullWhenEmpty(alias, require_mongo_accumulator.notNullExpr(`$${expr.$field}`)) : 1;
+	}
+	for (const e of controls.$select?.exprAggregates ?? []) {
+		const value = require_mongo_accumulator.exprToMongo(e.expr, asDouble);
+		groupStage[e.alias] = { [`$${e.fn}`]: value };
+		project[e.alias] = e.fn === "sum" ? nullWhenEmpty(e.alias, require_mongo_accumulator.notNullExpr(value)) : 1;
+	}
+	for (const fl of firstLast) {
+		groupStage[fl.alias] = { [`$${fl.fn}`]: require_mongo_accumulator.orNull(`$${fl.column}`) };
+		project[fl.alias] = 1;
 	}
 	pipeline.push({ $group: groupStage });
 	pipeline.push({ $project: project });
+	for (const e of controls.$select?.exprs ?? []) pipeline.push({ $addFields: { [e.alias]: require_mongo_accumulator.exprToMongo(e.expr, asDouble) } });
 	if (controls.$having) pipeline.push({ $match: require_mongo_accumulator.buildMongoFilter(controls.$having) });
 	return {
 		pipeline,
@@ -165,12 +203,14 @@ function buildGroupedStages(query, { accumulators, searchStage }) {
 *
 * `searchStage` is the resolved `$search` / `$text` stage (see
 * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
-* relevance `$sort` and no default `$limit`.
+* relevance `$sort` and no default `$limit`. `filterOptions` renders a
+* filter with relational predicates (`mongoFilterStages`).
 */
-function buildAggregatePipeline(query, searchStage) {
+function buildAggregatePipeline(query, searchStage, filterOptions) {
 	const { pipeline, controls } = buildGroupedStages(query, {
 		accumulators: true,
-		searchStage
+		searchStage,
+		filterOptions
 	});
 	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
@@ -178,6 +218,69 @@ function buildAggregatePipeline(query, searchStage) {
 	return pipeline;
 }
 /**
+* The row an UNGROUPED aggregate yields over no input rows: a pipeline's
+* `$group` emits nothing there, while SQL (and the memory adapter) always
+* yield the one group — counts 0, every other aggregate, `first` / `last` and
+* the expressions over them `null`. `undefined` when the query is grouped or
+* computes nothing. The row is BEFORE `$having` / `$skip` — see
+* {@link emptyGroupStages}.
+*/
+function emptyGroupRow(query) {
+	const controls = query.controls;
+	const select = controls?.$select;
+	if (!controls || controls.$groupBy?.length) return void 0;
+	if (!select?.computedAliases.length) return void 0;
+	const row = {};
+	for (const expr of select.aggregates ?? []) row[(0, _atscript_db_agg.resolveAlias)(expr)] = expr.$fn === "count" || expr.$fn === "countDistinct" ? 0 : null;
+	for (const e of select.exprAggregates ?? []) row[e.alias] = null;
+	for (const fl of select.firstLast ?? []) row[fl.alias] = null;
+	for (const e of select.exprs ?? []) row[e.alias] = (0, _atscript_db.evaluateExpr)(e.expr, (name) => row[name]);
+	return row;
+}
+/**
+* A pipeline yielding at most one document iff ANY input row matches the
+* query's filter (and search) — the probe that tells "no rows matched" (the
+* one empty group exists) from "the real group was removed by `$having`".
+*/
+function buildMatchedProbe(query, searchStage, filterOptions) {
+	const { pipeline } = buildPrefix(query, searchStage, filterOptions);
+	pipeline.push({ $limit: 1 }, { $project: { _id: 1 } });
+	return pipeline;
+}
+/**
+* The pipeline that applies the query's `$having` (and, for the row query, `$skip`
+* and `$limit`) to the {@link emptyGroupRow} — over a single synthetic document
+* (a `$facet` emits exactly one document, even from an empty input), so the
+* server evaluates `$having` exactly as it does for a real group. `undefined`
+* when there is nothing to apply (the row stands). Its result is empty when the
+* row is filtered out.
+*/
+function emptyGroupStages(query, row, forCount) {
+	const controls = query.controls;
+	const having = controls?.$having;
+	const skip = forCount ? 0 : controls?.$skip ?? 0;
+	const limit = forCount ? 0 : controls?.$limit ?? 0;
+	if (!having && !skip && !limit) return void 0;
+	const stages = [
+		{ $match: { _id: { $in: [] } } },
+		{ $facet: { one: [] } },
+		{ $replaceRoot: { newRoot: { $literal: row } } }
+	];
+	if (having) stages.push({ $match: require_mongo_accumulator.buildMongoFilter(having) });
+	if (skip) stages.push({ $skip: skip });
+	if (limit) stages.push({ $limit: limit });
+	return stages;
+}
+/**
+* `allowDiskUse` for a pipeline that sorts before it groups (`first` / `last`
+* order every matching row by `$rowOrder` first, which may exceed the
+* in-memory sort limit); `undefined` otherwise.
+*/
+function aggregateOptions(pipeline) {
+	const group = pipeline.findIndex((stage) => "$group" in stage);
+	return pipeline.slice(0, group < 0 ? 0 : group).some((stage) => "$sort" in stage) ? { allowDiskUse: true } : void 0;
+}
+/**
 * 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
@@ -189,15 +292,20 @@ function buildAggregatePipeline(query, searchStage) {
 * `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, searchStage) {
+function buildCountPipeline(query, searchStage, filterOptions) {
 	const { pipeline } = buildGroupedStages(query, {
 		accumulators: Boolean(query.controls?.$having),
-		searchStage
+		searchStage,
+		filterOptions
 	});
 	pipeline.push({ $count: "count" });
 	return pipeline;
 }
 //#endregion
+exports.aggregateOptions = aggregateOptions;
 exports.bucketExpression = bucketExpression;
 exports.buildAggregatePipeline = buildAggregatePipeline;
 exports.buildCountPipeline = buildCountPipeline;
+exports.buildMatchedProbe = buildMatchedProbe;
+exports.emptyGroupRow = emptyGroupRow;
+exports.emptyGroupStages = emptyGroupStages;

package/dist/agg.d.cts

@@ -1,10 +1,12 @@
+import { r as TMongoFilterOptions } from "./mongo-filter-CGd9ryOD.cjs";
 import { DbQuery, TResolvedBucket } from "@atscript/db";
 import { Document } from "mongodb";
 
 //#region src/agg.d.ts
 /**
  * The `$group._id` expression of a calendar bucket: the ISO local date
- * `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+ * `YYYY-MM-DD` of the bucket's first day in `b.tz` (for `hour`, the local
+ * `YYYY-MM-DDTHH:00`), or `null`.
  *
  * The only zone-aware step is instant → local date (`timezone` on
  * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
@@ -27,9 +29,42 @@ declare function bucketExpression(b: TResolvedBucket): Document;
  *
  * `searchStage` is the resolved `$search` / `$text` stage (see
  * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
- * relevance `$sort` and no default `$limit`.
+ * relevance `$sort` and no default `$limit`. `filterOptions` renders a
+ * filter with relational predicates (`mongoFilterStages`).
  */
-declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document): Document[];
+declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
+/**
+ * The row an UNGROUPED aggregate yields over no input rows: a pipeline's
+ * `$group` emits nothing there, while SQL (and the memory adapter) always
+ * yield the one group — counts 0, every other aggregate, `first` / `last` and
+ * the expressions over them `null`. `undefined` when the query is grouped or
+ * computes nothing. The row is BEFORE `$having` / `$skip` — see
+ * {@link emptyGroupStages}.
+ */
+declare function emptyGroupRow(query: DbQuery): Document | undefined;
+/**
+ * A pipeline yielding at most one document iff ANY input row matches the
+ * query's filter (and search) — the probe that tells "no rows matched" (the
+ * one empty group exists) from "the real group was removed by `$having`".
+ */
+declare function buildMatchedProbe(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
+/**
+ * The pipeline that applies the query's `$having` (and, for the row query, `$skip`
+ * and `$limit`) to the {@link emptyGroupRow} — over a single synthetic document
+ * (a `$facet` emits exactly one document, even from an empty input), so the
+ * server evaluates `$having` exactly as it does for a real group. `undefined`
+ * when there is nothing to apply (the row stands). Its result is empty when the
+ * row is filtered out.
+ */
+declare function emptyGroupStages(query: DbQuery, row: Document, forCount: boolean): Document[] | undefined;
+/**
+ * `allowDiskUse` for a pipeline that sorts before it groups (`first` / `last`
+ * order every matching row by `$rowOrder` first, which may exceed the
+ * in-memory sort limit); `undefined` otherwise.
+ */
+declare function aggregateOptions(pipeline: Document[]): {
+  allowDiskUse: true;
+} | undefined;
 /**
  * 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
@@ -42,6 +77,6 @@ declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document):
  * `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, searchStage?: Document): Document[];
+declare function buildCountPipeline(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
 //#endregion
-export { bucketExpression, buildAggregatePipeline, buildCountPipeline };
+export { aggregateOptions, bucketExpression, buildAggregatePipeline, buildCountPipeline, buildMatchedProbe, emptyGroupRow, emptyGroupStages };

package/dist/agg.d.mts

@@ -1,10 +1,12 @@
+import { r as TMongoFilterOptions } from "./mongo-filter-CGd9ryOD.mjs";
 import { DbQuery, TResolvedBucket } from "@atscript/db";
 import { Document } from "mongodb";
 
 //#region src/agg.d.ts
 /**
  * The `$group._id` expression of a calendar bucket: the ISO local date
- * `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+ * `YYYY-MM-DD` of the bucket's first day in `b.tz` (for `hour`, the local
+ * `YYYY-MM-DDTHH:00`), or `null`.
  *
  * The only zone-aware step is instant → local date (`timezone` on
  * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
@@ -27,9 +29,42 @@ declare function bucketExpression(b: TResolvedBucket): Document;
  *
  * `searchStage` is the resolved `$search` / `$text` stage (see
  * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
- * relevance `$sort` and no default `$limit`.
+ * relevance `$sort` and no default `$limit`. `filterOptions` renders a
+ * filter with relational predicates (`mongoFilterStages`).
  */
-declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document): Document[];
+declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
+/**
+ * The row an UNGROUPED aggregate yields over no input rows: a pipeline's
+ * `$group` emits nothing there, while SQL (and the memory adapter) always
+ * yield the one group — counts 0, every other aggregate, `first` / `last` and
+ * the expressions over them `null`. `undefined` when the query is grouped or
+ * computes nothing. The row is BEFORE `$having` / `$skip` — see
+ * {@link emptyGroupStages}.
+ */
+declare function emptyGroupRow(query: DbQuery): Document | undefined;
+/**
+ * A pipeline yielding at most one document iff ANY input row matches the
+ * query's filter (and search) — the probe that tells "no rows matched" (the
+ * one empty group exists) from "the real group was removed by `$having`".
+ */
+declare function buildMatchedProbe(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
+/**
+ * The pipeline that applies the query's `$having` (and, for the row query, `$skip`
+ * and `$limit`) to the {@link emptyGroupRow} — over a single synthetic document
+ * (a `$facet` emits exactly one document, even from an empty input), so the
+ * server evaluates `$having` exactly as it does for a real group. `undefined`
+ * when there is nothing to apply (the row stands). Its result is empty when the
+ * row is filtered out.
+ */
+declare function emptyGroupStages(query: DbQuery, row: Document, forCount: boolean): Document[] | undefined;
+/**
+ * `allowDiskUse` for a pipeline that sorts before it groups (`first` / `last`
+ * order every matching row by `$rowOrder` first, which may exceed the
+ * in-memory sort limit); `undefined` otherwise.
+ */
+declare function aggregateOptions(pipeline: Document[]): {
+  allowDiskUse: true;
+} | undefined;
 /**
  * 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
@@ -42,6 +77,6 @@ declare function buildAggregatePipeline(query: DbQuery, searchStage?: Document):
  * `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, searchStage?: Document): Document[];
+declare function buildCountPipeline(query: DbQuery, searchStage?: Document, filterOptions?: TMongoFilterOptions): Document[];
 //#endregion
-export { bucketExpression, buildAggregatePipeline, buildCountPipeline };
+export { aggregateOptions, bucketExpression, buildAggregatePipeline, buildCountPipeline, buildMatchedProbe, emptyGroupRow, emptyGroupStages };

package/dist/agg.mjs

@@ -1,18 +1,28 @@
-import { i as orNull, n as distinctCountExpr, r as buildMongoFilter, t as buildAccumulator } from "./mongo-accumulator-Dc0w4t0l.mjs";
+import { d as orNull, i as buildMongoFilter, l as exprToMongo, n as distinctCountExpr, s as mongoFilterStages, t as buildAccumulator, u as notNullExpr } from "./mongo-accumulator-BvJNCVoc.mjs";
+import { evaluateExpr } from "@atscript/db";
 import { resolveAlias } from "@atscript/db/agg";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/agg.ts
+/**
+* MongoDB aggregation pipeline builder.
+* Dynamically imported by MongoAdapter.aggregate() on first call.
+*
+* Constructs MongoDB aggregation pipelines from translated DbQuery objects
+* containing $groupBy, $select (with AggregateExpr), $having, $sort, etc.
+*/
 /** Maps an AggregateExpr to its MongoDB `$group` accumulator (see `buildAccumulator`). */
 function toAccumulator(expr) {
 	return buildAccumulator(expr.$fn, expr.$field === "*" ? "*" : `$${expr.$field}`);
 }
+/** An operand of query-time arithmetic: the field as a double (IEEE, like the SQL adapters). */
+const asDouble = (path) => ({ $toDouble: `$${path}` });
+/** Prefix of the hidden `$group` field counting a sum's non-null values. */
+const NON_NULL_PREFIX = "__as_n_";
 const DAY_MS = 864e5;
 const ISO_DATE = "%Y-%m-%d";
-/**
-* Units whose first day `$dateToString` renders straight from the instant in
-* the zone: the local day, then the literal `01` for day-of-month / month.
-*/
-const LOCAL_DATE_FORMATS = {
+/** Units `$dateToString` labels straight from the instant in the zone (literal `01` for day / month). */
+const LOCAL_LABEL_FORMATS = {
+	hour: "%Y-%m-%dT%H:00",
 	day: ISO_DATE,
 	month: "%Y-%m-01",
 	year: "%Y-01-01"
@@ -40,7 +50,8 @@ function naiveFirstDay(b) {
 }
 /**
 * The `$group._id` expression of a calendar bucket: the ISO local date
-* `YYYY-MM-DD` of the bucket's first day in `b.tz`, or `null`.
+* `YYYY-MM-DD` of the bucket's first day in `b.tz` (for `hour`, the local
+* `YYYY-MM-DDTHH:00`), or `null`.
 *
 * The only zone-aware step is instant → local date (`timezone` on
 * `$dateToString` / `$dateToParts`, never ambiguous). `$dateTrunc` is
@@ -57,7 +68,7 @@ function naiveFirstDay(b) {
 function bucketExpression(b) {
 	const source = `$${b.field}`;
 	const date = { $toDate: { $toLong: source } };
-	const format = LOCAL_DATE_FORMATS[b.unit];
+	const format = LOCAL_LABEL_FORMATS[b.unit];
 	const label = format ? { $dateToString: {
 		date,
 		format,
@@ -100,10 +111,11 @@ function bucketExpression(b) {
 * 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, searchStage) {
+function buildPrefix(query, searchStage, filterOptions) {
 	const controls = query.controls || {};
 	const groupBy = controls.$groupBy ?? [];
-	const pipeline = searchStage ? [searchStage, { $match: buildMongoFilter(query.filter) }] : [{ $match: buildMongoFilter(query.filter) }];
+	const filterStages = mongoFilterStages(query.filter, filterOptions);
+	const pipeline = searchStage ? [searchStage, ...filterStages] : filterStages;
 	const groupId = {};
 	const groupKeys = [];
 	for (const [index, key] of groupBy.entries()) {
@@ -131,8 +143,8 @@ function buildPrefix(query, searchStage) {
 * (no accumulators, no `$project`, no `$having`) — the cheapest shape for a
 * plain group count, where no alias has to be resolvable.
 */
-function buildGroupedStages(query, { accumulators, searchStage }) {
-	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage);
+function buildGroupedStages(query, { accumulators, searchStage, filterOptions }) {
+	const { pipeline, groupId, groupKeys, controls } = buildPrefix(query, searchStage, filterOptions);
 	const groupStage = { _id: groupId };
 	if (!accumulators) {
 		pipeline.push({ $group: groupStage });
@@ -141,15 +153,41 @@ function buildGroupedStages(query, { accumulators, searchStage }) {
 			controls
 		};
 	}
+	const firstLast = controls.$select?.firstLast ?? [];
+	const rowOrder = controls.$select?.rowOrder ?? [];
+	if (firstLast.length > 0 && rowOrder.length > 0) pipeline.push({ $sort: Object.fromEntries(rowOrder.map((k) => [k.column, k.desc ? -1 : 1])) });
 	const project = { _id: 0 };
 	for (const [field, idKey] of groupKeys) project[field] = `$_id.${idKey}`;
+	const nullWhenEmpty = (alias, nonNull) => {
+		const count = `${NON_NULL_PREFIX}${alias}`;
+		groupStage[count] = { $sum: { $cond: [
+			nonNull,
+			1,
+			0
+		] } };
+		return { $cond: [
+			{ $eq: [`$${count}`, 0] },
+			null,
+			`$${alias}`
+		] };
+	};
 	for (const expr of controls.$select?.aggregates ?? []) {
 		const alias = resolveAlias(expr);
 		groupStage[alias] = toAccumulator(expr);
-		project[alias] = expr.$fn === "countDistinct" ? distinctCountExpr(`$${alias}`) : 1;
+		project[alias] = expr.$fn === "countDistinct" ? distinctCountExpr(`$${alias}`) : expr.$fn === "sum" ? nullWhenEmpty(alias, notNullExpr(`$${expr.$field}`)) : 1;
+	}
+	for (const e of controls.$select?.exprAggregates ?? []) {
+		const value = exprToMongo(e.expr, asDouble);
+		groupStage[e.alias] = { [`$${e.fn}`]: value };
+		project[e.alias] = e.fn === "sum" ? nullWhenEmpty(e.alias, notNullExpr(value)) : 1;
+	}
+	for (const fl of firstLast) {
+		groupStage[fl.alias] = { [`$${fl.fn}`]: orNull(`$${fl.column}`) };
+		project[fl.alias] = 1;
 	}
 	pipeline.push({ $group: groupStage });
 	pipeline.push({ $project: project });
+	for (const e of controls.$select?.exprs ?? []) pipeline.push({ $addFields: { [e.alias]: exprToMongo(e.expr, asDouble) } });
 	if (controls.$having) pipeline.push({ $match: buildMongoFilter(controls.$having) });
 	return {
 		pipeline,
@@ -164,12 +202,14 @@ function buildGroupedStages(query, { accumulators, searchStage }) {
 *
 * `searchStage` is the resolved `$search` / `$text` stage (see
 * `buildAggregateSearchStage`); unlike the leaf runner this path adds no
-* relevance `$sort` and no default `$limit`.
+* relevance `$sort` and no default `$limit`. `filterOptions` renders a
+* filter with relational predicates (`mongoFilterStages`).
 */
-function buildAggregatePipeline(query, searchStage) {
+function buildAggregatePipeline(query, searchStage, filterOptions) {
 	const { pipeline, controls } = buildGroupedStages(query, {
 		accumulators: true,
-		searchStage
+		searchStage,
+		filterOptions
 	});
 	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
@@ -177,6 +217,69 @@ function buildAggregatePipeline(query, searchStage) {
 	return pipeline;
 }
 /**
+* The row an UNGROUPED aggregate yields over no input rows: a pipeline's
+* `$group` emits nothing there, while SQL (and the memory adapter) always
+* yield the one group — counts 0, every other aggregate, `first` / `last` and
+* the expressions over them `null`. `undefined` when the query is grouped or
+* computes nothing. The row is BEFORE `$having` / `$skip` — see
+* {@link emptyGroupStages}.
+*/
+function emptyGroupRow(query) {
+	const controls = query.controls;
+	const select = controls?.$select;
+	if (!controls || controls.$groupBy?.length) return void 0;
+	if (!select?.computedAliases.length) return void 0;
+	const row = {};
+	for (const expr of select.aggregates ?? []) row[resolveAlias(expr)] = expr.$fn === "count" || expr.$fn === "countDistinct" ? 0 : null;
+	for (const e of select.exprAggregates ?? []) row[e.alias] = null;
+	for (const fl of select.firstLast ?? []) row[fl.alias] = null;
+	for (const e of select.exprs ?? []) row[e.alias] = evaluateExpr(e.expr, (name) => row[name]);
+	return row;
+}
+/**
+* A pipeline yielding at most one document iff ANY input row matches the
+* query's filter (and search) — the probe that tells "no rows matched" (the
+* one empty group exists) from "the real group was removed by `$having`".
+*/
+function buildMatchedProbe(query, searchStage, filterOptions) {
+	const { pipeline } = buildPrefix(query, searchStage, filterOptions);
+	pipeline.push({ $limit: 1 }, { $project: { _id: 1 } });
+	return pipeline;
+}
+/**
+* The pipeline that applies the query's `$having` (and, for the row query, `$skip`
+* and `$limit`) to the {@link emptyGroupRow} — over a single synthetic document
+* (a `$facet` emits exactly one document, even from an empty input), so the
+* server evaluates `$having` exactly as it does for a real group. `undefined`
+* when there is nothing to apply (the row stands). Its result is empty when the
+* row is filtered out.
+*/
+function emptyGroupStages(query, row, forCount) {
+	const controls = query.controls;
+	const having = controls?.$having;
+	const skip = forCount ? 0 : controls?.$skip ?? 0;
+	const limit = forCount ? 0 : controls?.$limit ?? 0;
+	if (!having && !skip && !limit) return void 0;
+	const stages = [
+		{ $match: { _id: { $in: [] } } },
+		{ $facet: { one: [] } },
+		{ $replaceRoot: { newRoot: { $literal: row } } }
+	];
+	if (having) stages.push({ $match: buildMongoFilter(having) });
+	if (skip) stages.push({ $skip: skip });
+	if (limit) stages.push({ $limit: limit });
+	return stages;
+}
+/**
+* `allowDiskUse` for a pipeline that sorts before it groups (`first` / `last`
+* order every matching row by `$rowOrder` first, which may exceed the
+* in-memory sort limit); `undefined` otherwise.
+*/
+function aggregateOptions(pipeline) {
+	const group = pipeline.findIndex((stage) => "$group" in stage);
+	return pipeline.slice(0, group < 0 ? 0 : group).some((stage) => "$sort" in stage) ? { allowDiskUse: true } : void 0;
+}
+/**
 * 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
@@ -188,13 +291,14 @@ function buildAggregatePipeline(query, searchStage) {
 * `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, searchStage) {
+function buildCountPipeline(query, searchStage, filterOptions) {
 	const { pipeline } = buildGroupedStages(query, {
 		accumulators: Boolean(query.controls?.$having),
-		searchStage
+		searchStage,
+		filterOptions
 	});
 	pipeline.push({ $count: "count" });
 	return pipeline;
 }
 //#endregion
-export { bucketExpression, buildAggregatePipeline, buildCountPipeline };
+export { aggregateOptions, bucketExpression, buildAggregatePipeline, buildCountPipeline, buildMatchedProbe, emptyGroupRow, emptyGroupStages };