@atscript/db-mongo 0.1.152 → 0.1.154

package/dist/{mongo-accumulator-BQBMx4GC.cjs → mongo-accumulator-BW-RNFg0.cjs}

@@ -1,40 +1,7 @@
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
+let _uniqu_core = require("@uniqu/core");
 let _atscript_db_agg = require("@atscript/db/agg");
-//#region src/lib/lookup-join.ts
-/**
-* The correlation of a pipeline `$lookup`: `let` binds each outer field to a
-* variable (`<prefix>k<i>`), and the first sub-pipeline stages match the
-* inner field against it with SQL `=` semantics — a NULL or missing key on
-* either side never relates (aggregation `$eq(null, null)` is true, and a
-* missing `let` field would equal a missing inner field):
-*
-* 1. `$match: { $expr: { $eq: [inner, $$var] } }` (an `$and` of `$eq`s for a
-*    composite key) — kept bare so the lookup can use an index on the inner
-*    field(s); anything else inside that `$expr` turns every lookup into a
-*    collection scan;
-* 2. `$match: { <inner>: { $ne: null } }` per key part — the NULL guard, as a
-*    query-level stage. A NULL / missing outer key (`$ifNull` folds "missing"
-*    into `null`) only `$eq`s inner NULL / missing values, which this stage
-*    drops.
-*/
-function correlate(prefix, pairs) {
-	if (pairs.length === 0) throw new Error("A $lookup correlation needs at least one key pair");
-	const vars = {};
-	const eqs = [];
-	const guard = {};
-	for (const [i, pair] of pairs.entries()) {
-		const name = `${prefix}k${i}`;
-		vars[name] = { $ifNull: [`$${pair.outer}`, null] };
-		eqs.push({ $eq: [`$${pair.inner}`, `$$${name}`] });
-		guard[pair.inner] = { $ne: null };
-	}
-	return {
-		let: vars,
-		stages: [{ $match: { $expr: eqs.length === 1 ? eqs[0] : { $and: eqs } } }, { $match: guard }]
-	};
-}
-//#endregion
 //#region src/lib/mongo-view-expr.ts
 /**
 * `x IS NOT NULL` in SQL terms — true when `x` is neither null nor missing.
@@ -161,6 +128,123 @@ function exprToMongo(node, operand) {
 	}
 }
 //#endregion
+//#region src/lib/mongo-sort.ts
+/**
+* Prefix of the temporary fields a NULL-placement sort adds (one per placed
+* key: `__atscript_nulls_0`, `__atscript_nulls_1`, …). Reserved — a stored
+* field never carries it — and dropped before any row leaves the pipeline.
+*
+* @since 0.1.153
+*/
+const NULLS_FLAG_PREFIX = "__atscript_nulls_";
+/**
+* Whether `controls` places NULL for at least one of its `$sort` keys
+* differently from BSON order (null and missing smallest: `'first'`
+* ascending and `'last'` descending need no flag — {@link placedKey}).
+*/
+function hasNullsPlacement(controls) {
+	const { $sort: sort, $nulls: nulls } = controls ?? {};
+	if (!sort || !nulls) return false;
+	for (const [key, dir] of Object.entries(sort)) if (placedKey(nulls[key], dir)) return true;
+	return false;
+}
+/**
+* The placement of one `$sort` key when it differs from BSON order, else
+* `undefined` — a native placement keeps the plain, index-served sort.
+*/
+function placedKey(placement, dir) {
+	if (!(0, _uniqu_core.isNullsPlacement)(placement)) return void 0;
+	return placement === "first" === (dir !== -1) ? void 0 : placement;
+}
+/**
+* The stages ordering rows by `$sort` with the `$nulls` placement of its keys.
+*
+* Without a placement entry that differs from BSON order (null and missing
+* are the smallest values) this is exactly `[{ $sort }]`. Otherwise each
+* placed key `k` gets a flag — `true` when `k` is null or missing — added before the
+* sort and ordered right before `k`: descending for `'first'`, ascending for
+* `'last'`, whatever `k`'s own direction. `cleanup` drops the flags again;
+* the caller emits it after `$skip` / `$limit` and before any projection.
+*
+* `find().sort()` cannot express this — a placed sort runs as a pipeline,
+* and it is a blocking sort (no index serves the computed flag).
+*/
+function sortStages(controls) {
+	const { $sort: sort, $nulls: nulls } = controls ?? {};
+	if (!sort) return { stages: [] };
+	if (!hasNullsPlacement(controls)) return { stages: [{ $sort: sort }] };
+	const flags = {};
+	const drop = {};
+	const ordered = {};
+	let n = 0;
+	for (const [key, dir] of Object.entries(sort)) {
+		const placement = placedKey(nulls[key], dir);
+		if (placement) {
+			const flag = `${NULLS_FLAG_PREFIX}${n++}`;
+			flags[flag] = isNullExpr(`$${key}`);
+			drop[flag] = 0;
+			ordered[flag] = placement === "first" ? -1 : 1;
+		}
+		ordered[key] = dir;
+	}
+	return {
+		stages: [{ $addFields: flags }, { $sort: ordered }],
+		cleanup: { $project: drop }
+	};
+}
+/**
+* The `$sort` of a `first()` / `last()` row order (`TRowOrderKey[]`), with
+* the flags its `nulls` entries need. Rows are grouped right after, so the
+* flags never reach a row — `$last` reads the same forward order, so a
+* placement holds for both ends.
+*/
+function rowOrderStages(rowOrder) {
+	const sort = {};
+	const nulls = {};
+	for (const k of rowOrder) {
+		sort[k.column] = k.desc ? -1 : 1;
+		if (k.nulls) nulls[k.column] = k.nulls;
+	}
+	return sortStages({
+		$sort: sort,
+		$nulls: nulls
+	}).stages;
+}
+//#endregion
+//#region src/lib/lookup-join.ts
+/**
+* The correlation of a pipeline `$lookup`: `let` binds each outer field to a
+* variable (`<prefix>k<i>`), and the first sub-pipeline stages match the
+* inner field against it with SQL `=` semantics — a NULL or missing key on
+* either side never relates (aggregation `$eq(null, null)` is true, and a
+* missing `let` field would equal a missing inner field):
+*
+* 1. `$match: { $expr: { $eq: [inner, $$var] } }` (an `$and` of `$eq`s for a
+*    composite key) — kept bare so the lookup can use an index on the inner
+*    field(s); anything else inside that `$expr` turns every lookup into a
+*    collection scan;
+* 2. `$match: { <inner>: { $ne: null } }` per key part — the NULL guard, as a
+*    query-level stage. A NULL / missing outer key (`$ifNull` folds "missing"
+*    into `null`) only `$eq`s inner NULL / missing values, which this stage
+*    drops.
+*/
+function correlate(prefix, pairs) {
+	if (pairs.length === 0) throw new Error("A $lookup correlation needs at least one key pair");
+	const vars = {};
+	const eqs = [];
+	const guard = {};
+	for (const [i, pair] of pairs.entries()) {
+		const name = `${prefix}k${i}`;
+		vars[name] = { $ifNull: [`$${pair.outer}`, null] };
+		eqs.push({ $eq: [`$${pair.inner}`, `$$${name}`] });
+		guard[pair.inner] = { $ne: null };
+	}
+	return {
+		let: vars,
+		stages: [{ $match: { $expr: eqs.length === 1 ? eqs[0] : { $and: eqs } } }, { $match: guard }]
+	};
+}
+//#endregion
 //#region src/lib/mongo-filter.ts
 const EMPTY = {};
 function parseRegexString(value) {
@@ -594,6 +678,12 @@ Object.defineProperty(exports, "exprToMongo", {
 		return exprToMongo;
 	}
 });
+Object.defineProperty(exports, "hasNullsPlacement", {
+	enumerable: true,
+	get: function() {
+		return hasNullsPlacement;
+	}
+});
 Object.defineProperty(exports, "mongoFilterStages", {
 	enumerable: true,
 	get: function() {
@@ -624,3 +714,15 @@ Object.defineProperty(exports, "queryNodeToExpr", {
 		return queryNodeToExpr;
 	}
 });
+Object.defineProperty(exports, "rowOrderStages", {
+	enumerable: true,
+	get: function() {
+		return rowOrderStages;
+	}
+});
+Object.defineProperty(exports, "sortStages", {
+	enumerable: true,
+	get: function() {
+		return sortStages;
+	}
+});

package/dist/{mongo-accumulator-DYhg8usT.mjs → mongo-accumulator-DMPFOscc.mjs}

@@ -1,40 +1,7 @@
 import { DbError, INTEGER_REGEX_OP, andFilters, containsRelationFilter, isFieldRef, isResolvedRelationFilter, walkFilter } from "@atscript/db";
 import { BSONRegExp } from "mongodb";
+import { isNullsPlacement } from "@uniqu/core";
 import { assertAggregateFn } from "@atscript/db/agg";
-//#region src/lib/lookup-join.ts
-/**
-* The correlation of a pipeline `$lookup`: `let` binds each outer field to a
-* variable (`<prefix>k<i>`), and the first sub-pipeline stages match the
-* inner field against it with SQL `=` semantics — a NULL or missing key on
-* either side never relates (aggregation `$eq(null, null)` is true, and a
-* missing `let` field would equal a missing inner field):
-*
-* 1. `$match: { $expr: { $eq: [inner, $$var] } }` (an `$and` of `$eq`s for a
-*    composite key) — kept bare so the lookup can use an index on the inner
-*    field(s); anything else inside that `$expr` turns every lookup into a
-*    collection scan;
-* 2. `$match: { <inner>: { $ne: null } }` per key part — the NULL guard, as a
-*    query-level stage. A NULL / missing outer key (`$ifNull` folds "missing"
-*    into `null`) only `$eq`s inner NULL / missing values, which this stage
-*    drops.
-*/
-function correlate(prefix, pairs) {
-	if (pairs.length === 0) throw new Error("A $lookup correlation needs at least one key pair");
-	const vars = {};
-	const eqs = [];
-	const guard = {};
-	for (const [i, pair] of pairs.entries()) {
-		const name = `${prefix}k${i}`;
-		vars[name] = { $ifNull: [`$${pair.outer}`, null] };
-		eqs.push({ $eq: [`$${pair.inner}`, `$$${name}`] });
-		guard[pair.inner] = { $ne: null };
-	}
-	return {
-		let: vars,
-		stages: [{ $match: { $expr: eqs.length === 1 ? eqs[0] : { $and: eqs } } }, { $match: guard }]
-	};
-}
-//#endregion
 //#region src/lib/mongo-view-expr.ts
 /**
 * `x IS NOT NULL` in SQL terms — true when `x` is neither null nor missing.
@@ -161,6 +128,123 @@ function exprToMongo(node, operand) {
 	}
 }
 //#endregion
+//#region src/lib/mongo-sort.ts
+/**
+* Prefix of the temporary fields a NULL-placement sort adds (one per placed
+* key: `__atscript_nulls_0`, `__atscript_nulls_1`, …). Reserved — a stored
+* field never carries it — and dropped before any row leaves the pipeline.
+*
+* @since 0.1.153
+*/
+const NULLS_FLAG_PREFIX = "__atscript_nulls_";
+/**
+* Whether `controls` places NULL for at least one of its `$sort` keys
+* differently from BSON order (null and missing smallest: `'first'`
+* ascending and `'last'` descending need no flag — {@link placedKey}).
+*/
+function hasNullsPlacement(controls) {
+	const { $sort: sort, $nulls: nulls } = controls ?? {};
+	if (!sort || !nulls) return false;
+	for (const [key, dir] of Object.entries(sort)) if (placedKey(nulls[key], dir)) return true;
+	return false;
+}
+/**
+* The placement of one `$sort` key when it differs from BSON order, else
+* `undefined` — a native placement keeps the plain, index-served sort.
+*/
+function placedKey(placement, dir) {
+	if (!isNullsPlacement(placement)) return void 0;
+	return placement === "first" === (dir !== -1) ? void 0 : placement;
+}
+/**
+* The stages ordering rows by `$sort` with the `$nulls` placement of its keys.
+*
+* Without a placement entry that differs from BSON order (null and missing
+* are the smallest values) this is exactly `[{ $sort }]`. Otherwise each
+* placed key `k` gets a flag — `true` when `k` is null or missing — added before the
+* sort and ordered right before `k`: descending for `'first'`, ascending for
+* `'last'`, whatever `k`'s own direction. `cleanup` drops the flags again;
+* the caller emits it after `$skip` / `$limit` and before any projection.
+*
+* `find().sort()` cannot express this — a placed sort runs as a pipeline,
+* and it is a blocking sort (no index serves the computed flag).
+*/
+function sortStages(controls) {
+	const { $sort: sort, $nulls: nulls } = controls ?? {};
+	if (!sort) return { stages: [] };
+	if (!hasNullsPlacement(controls)) return { stages: [{ $sort: sort }] };
+	const flags = {};
+	const drop = {};
+	const ordered = {};
+	let n = 0;
+	for (const [key, dir] of Object.entries(sort)) {
+		const placement = placedKey(nulls[key], dir);
+		if (placement) {
+			const flag = `${NULLS_FLAG_PREFIX}${n++}`;
+			flags[flag] = isNullExpr(`$${key}`);
+			drop[flag] = 0;
+			ordered[flag] = placement === "first" ? -1 : 1;
+		}
+		ordered[key] = dir;
+	}
+	return {
+		stages: [{ $addFields: flags }, { $sort: ordered }],
+		cleanup: { $project: drop }
+	};
+}
+/**
+* The `$sort` of a `first()` / `last()` row order (`TRowOrderKey[]`), with
+* the flags its `nulls` entries need. Rows are grouped right after, so the
+* flags never reach a row — `$last` reads the same forward order, so a
+* placement holds for both ends.
+*/
+function rowOrderStages(rowOrder) {
+	const sort = {};
+	const nulls = {};
+	for (const k of rowOrder) {
+		sort[k.column] = k.desc ? -1 : 1;
+		if (k.nulls) nulls[k.column] = k.nulls;
+	}
+	return sortStages({
+		$sort: sort,
+		$nulls: nulls
+	}).stages;
+}
+//#endregion
+//#region src/lib/lookup-join.ts
+/**
+* The correlation of a pipeline `$lookup`: `let` binds each outer field to a
+* variable (`<prefix>k<i>`), and the first sub-pipeline stages match the
+* inner field against it with SQL `=` semantics — a NULL or missing key on
+* either side never relates (aggregation `$eq(null, null)` is true, and a
+* missing `let` field would equal a missing inner field):
+*
+* 1. `$match: { $expr: { $eq: [inner, $$var] } }` (an `$and` of `$eq`s for a
+*    composite key) — kept bare so the lookup can use an index on the inner
+*    field(s); anything else inside that `$expr` turns every lookup into a
+*    collection scan;
+* 2. `$match: { <inner>: { $ne: null } }` per key part — the NULL guard, as a
+*    query-level stage. A NULL / missing outer key (`$ifNull` folds "missing"
+*    into `null`) only `$eq`s inner NULL / missing values, which this stage
+*    drops.
+*/
+function correlate(prefix, pairs) {
+	if (pairs.length === 0) throw new Error("A $lookup correlation needs at least one key pair");
+	const vars = {};
+	const eqs = [];
+	const guard = {};
+	for (const [i, pair] of pairs.entries()) {
+		const name = `${prefix}k${i}`;
+		vars[name] = { $ifNull: [`$${pair.outer}`, null] };
+		eqs.push({ $eq: [`$${pair.inner}`, `$$${name}`] });
+		guard[pair.inner] = { $ne: null };
+	}
+	return {
+		let: vars,
+		stages: [{ $match: { $expr: eqs.length === 1 ? eqs[0] : { $and: eqs } } }, { $match: guard }]
+	};
+}
+//#endregion
 //#region src/lib/mongo-filter.ts
 const EMPTY = {};
 function parseRegexString(value) {
@@ -546,4 +630,4 @@ function distinctCountExpr(set) {
 	return { $size: set };
 }
 //#endregion
-export { buildMongoQuery as a, planStages as c, orNull as d, queryNodeToExpr as f, buildMongoFilter as i, exprToMongo as l, distinctCountExpr as n, collationOfAdapter as o, correlate as p, REL_FILTER_TEMP_PREFIX as r, mongoFilterStages as s, buildAccumulator as t, notNullExpr as u };
+export { buildMongoQuery as a, planStages as c, rowOrderStages as d, sortStages as f, queryNodeToExpr as g, orNull as h, buildMongoFilter as i, correlate as l, notNullExpr as m, distinctCountExpr as n, collationOfAdapter as o, exprToMongo as p, REL_FILTER_TEMP_PREFIX as r, mongoFilterStages as s, buildAccumulator as t, hasNullsPlacement as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.152",
+  "version": "0.1.154",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -46,19 +46,19 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
     "mongodb": "^6.17.0",
     "mongodb-memory-server-core": "^10.0.0",
-    "unplugin-atscript": "^0.1.102"
+    "unplugin-atscript": "^0.1.103"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.152"
+    "@atscript/db": "^0.1.154"
   },
   "scripts": {
     "postinstall": "asc -f dts",