@atscript/db-mongo 0.1.151 → 0.1.153

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { a as buildMongoQuery, c as planStages, d as orNull, f as queryNodeToExpr, i as buildMongoFilter, l as exprToMongo, n as distinctCountExpr, o as collationOfAdapter, p as correlate, r as REL_FILTER_TEMP_PREFIX, s as mongoFilterStages, t as buildAccumulator } from "./mongo-accumulator-DYhg8usT.mjs";
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, andFilters, bucketTimeZoneUnavailable, computeInsights, containsRelationFilter, createFailureCollector, defaultFulltextIndex, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, isAtscriptDbView, isFieldRef, isPlainObject, relationStaticFilter, resolveDesignType, searchIndexNotFoundMessage, searchTermInteger, tableNameOf, translateQueryTree, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
+import { a as buildMongoQuery, c as planStages, f as sortStages, g as queryNodeToExpr, h as orNull, i as buildMongoFilter, l as correlate, n as distinctCountExpr, o as collationOfAdapter, p as exprToMongo, r as REL_FILTER_TEMP_PREFIX, s as mongoFilterStages, t as buildAccumulator, u as hasNullsPlacement } from "./mongo-accumulator-DMPFOscc.mjs";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, andFilters, bucketTimeZoneUnavailable, computeInsights, containsRelationFilter, createFailureCollector, defaultFulltextIndex, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, isAtscriptDbView, isFieldRef, isPlainObject, isViewType, queryReadColumns, relationStaticFilter, resolveDesignType, searchIndexNotFoundMessage, searchTermInteger, tableNameOf, translateQueryTree, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { MongoBulkWriteError, MongoClient, MongoServerError, ObjectId } from "mongodb";
 import { resolveAggregateSearch } from "@atscript/db/agg";
 //#region src/lib/path-utils.ts
@@ -394,6 +394,262 @@ function mongoIndexKey(type, name) {
 	return `${INDEX_PREFIX}${type}__${name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 117 - type.length - 2)}`;
 }
 //#endregion
+//#region src/lib/mongo-view-pipeline.ts
+/** Where a joined table's document lands (`$lookup.as`, then unwound). */
+function joinedAs(table) {
+	return `${JOINED_PREFIX}${table}`;
+}
+/**
+* Builds the aggregation pipeline of a managed MongoDB view (created with
+* `viewOn: <entry collection>`):
+*
+* 1. per join, in declaration order: `$lookup` + `$unwind` (inner joins drop
+*    unmatched documents, left joins keep them — `preserveNullAndEmptyArrays`);
+* 2. `@db.view.filter` → `$match`;
+* 3. aggregates → `$group` (+ `$addFields` turning `countDistinct` sets into
+*    their sizes, + `@db.view.having` → `$match`) + `$project`, otherwise a
+*    flat `$project`. A conditional aggregate's predicate reads the same
+*    pipeline paths (SQL null semantics — `queryNodeToExpr`).
+*
+* All field paths are PHYSICAL document paths (`@db.column` renames), joined
+* tables live under `__joined_<scope>` — the physical collection, or the
+* `@db.alias` type name for an aliased join (`__joined_Manager`), whose
+* `$lookup.from` stays the physical collection (since 0.1.141).
+* `variant` (since 0.1.153) renders a pruned read variant of the view
+* (`AtscriptDbView.readPlan`) instead of its full definition.
+* The entry collection and a `$lookup.from` may be views. A column whose source may be missing
+* (`nullable` mapping) reads as null; every other column is a plain path, so
+* a `$match` / `$sort` on the view can still push down to an index.
+* @since 0.1.136
+*/
+function buildViewPipeline(view, variant) {
+	const plan = variant?.plan ?? view.viewPlan;
+	const columns = variant?.columns ?? view.getViewColumnMappings();
+	const pipeline = [];
+	const prefixes = new Map([[plan.entryTable, ""]]);
+	const pathOf = (ref) => {
+		const { table, source } = view.resolveRefSource(ref);
+		const prefix = prefixes.get(table);
+		if (prefix === void 0) throw new Error(`View "${view.tableName}": "${table}" is not joined before it is referenced`);
+		return prefix + source.column;
+	};
+	for (const join of plan.joins) {
+		pipeline.push(buildLookup(view, join, prefixes));
+		pipeline.push({ $unwind: {
+			path: `$${joinedAs(join.scope)}`,
+			preserveNullAndEmptyArrays: join.kind === "left"
+		} });
+		prefixes.set(join.scope, `${joinedAs(join.scope)}.`);
+	}
+	if (plan.filter) pipeline.push({ $match: viewMatch(plan.filter, pathOf) });
+	/** A column's source field as an aggregation operand. */
+	const colSourceField = (col) => `$${prefixes.get(col.sourceTable) ?? ""}${col.sourceColumn}`;
+	const colValue = (col) => col.nullable ? orNull(colSourceField(col)) : colSourceField(col);
+	const byPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const rendered = /* @__PURE__ */ new Map();
+	const computedExpr = (col, leaf) => {
+		let out = rendered.get(col.viewPath);
+		if (out === void 0) {
+			out = exprToMongo(col.expr, (path) => {
+				const c = byPath.get(path);
+				return c.expr === void 0 ? { $toDouble: leaf(c) } : computedExpr(c, leaf);
+			});
+			rendered.set(col.viewPath, out);
+		}
+		return out;
+	};
+	if (columns.some((c) => c.aggFn)) {
+		const group = { _id: {} };
+		const project = { _id: 0 };
+		const distinctSizes = {};
+		const computed = {};
+		for (const col of columns) if (col.expr !== void 0) {
+			computed[col.viewColumn] = computedExpr(col, (c) => c.aggFn ? `$${c.viewColumn}` : `$_id.${c.viewColumn}`);
+			project[col.viewColumn] = `$${col.viewColumn}`;
+		} else if (col.aggFn) {
+			const predicate = col.aggFilter ? queryNodeToExpr(col.aggFilter, (ref) => `$${pathOf(ref)}`) : void 0;
+			group[col.viewColumn] = buildAccumulator(col.aggFn, col.aggField === "*" ? "*" : colSourceField(col), predicate, col.viewColumn);
+			project[col.viewColumn] = `$${col.viewColumn}`;
+			if (col.aggFn === "countDistinct") distinctSizes[col.viewColumn] = distinctCountExpr(`$${col.viewColumn}`);
+		} else {
+			group._id[col.viewColumn] = colValue(col);
+			project[col.viewColumn] = `$_id.${col.viewColumn}`;
+		}
+		pipeline.push({ $group: group });
+		if (Object.keys(distinctSizes).length > 0) pipeline.push({ $addFields: distinctSizes });
+		if (Object.keys(computed).length > 0) pipeline.push({ $addFields: computed });
+		if (plan.having) pipeline.push({ $match: havingMatch(plan.having, byPath) });
+		pipeline.push({ $project: project });
+	} else {
+		const project = { _id: 0 };
+		for (const col of columns) project[col.viewColumn] = col.expr === void 0 ? colValue(col) : computedExpr(col, colValue);
+		pipeline.push({ $project: project });
+	}
+	return pipeline;
+}
+/**
+* One join's `$lookup`.
+*
+* The simple `localField` / `foreignField` form is used whenever it is exact:
+* a single `=` between a field of the joined table and a field of an outer
+* table (the entry or an earlier join), with the joined field REQUIRED — the
+* simple form matches a null / missing local value to null / missing foreign
+* values, which a required foreign field can never hold. It is kept (rather
+* than always using the pipeline form) because it can use an index on the
+* foreign field on every MongoDB version; the pipeline form's `$expr` match
+* can't before MongoDB 5.0. Everything else uses the pipeline form (`let` +
+* `$match: { $expr }`, SQL null semantics).
+*/
+function buildLookup(view, join, outer) {
+	const scope = join.scope;
+	const as = joinedAs(scope);
+	const simple = join.first ? void 0 : simpleJoinFields(view, join, outer);
+	if (simple) return { $lookup: {
+		from: join.targetTable,
+		...simple,
+		as
+	} };
+	const letVars = {};
+	const varByPath = /* @__PURE__ */ new Map();
+	const pathOf = (ref) => {
+		const { table, source } = view.resolveRefSource(ref);
+		if (table === scope) return `$${source.column}`;
+		const prefix = outer.get(table);
+		if (prefix === void 0) throw new Error(`View "${view.tableName}": the join on "${scope}" references "${table}", which is not joined before it`);
+		const outerPath = prefix + source.column;
+		let varName = varByPath.get(outerPath);
+		if (!varName) {
+			varName = `v${varByPath.size}`;
+			varByPath.set(outerPath, varName);
+			letVars[varName] = `$${outerPath}`;
+		}
+		return `$$${varName}`;
+	};
+	const pipeline = [{ $match: { $expr: queryNodeToExpr(join.condition, pathOf) } }];
+	if (join.first) {
+		const sort = {};
+		for (const { ref, desc } of join.first.order) sort[view.resolveRefSource(ref).source.column] = desc ? -1 : 1;
+		pipeline.push({ $sort: sort }, { $limit: 1 });
+	}
+	return { $lookup: {
+		from: join.targetTable,
+		...varByPath.size > 0 ? { let: letVars } : {},
+		pipeline,
+		as
+	} };
+}
+/** `{ localField, foreignField }` when the simple `$lookup` form is exact, else `undefined`. */
+function simpleJoinFields(view, join, outer) {
+	let node = join.condition;
+	if ("$and" in node) {
+		const children = node.$and;
+		if (children.length !== 1) return void 0;
+		node = children[0];
+	}
+	if ("$or" in node || "$not" in node || "$and" in node) return void 0;
+	const comp = node;
+	if (comp.op !== "$eq" || !isFieldRef(comp.right)) return void 0;
+	const scope = join.scope;
+	const left = view.resolveRefSource(comp.left);
+	const right = view.resolveRefSource(comp.right);
+	let target;
+	let local;
+	if (left.table === scope && right.table !== scope) {
+		target = left;
+		local = right;
+	} else if (right.table === scope && left.table !== scope) {
+		target = right;
+		local = left;
+	} else return;
+	const localPrefix = outer.get(local.table);
+	if (localPrefix === void 0) return void 0;
+	const foreign = target.source;
+	if (!(!foreign.optional && foreign.designType !== "union" && foreign.designType !== "unknown")) return void 0;
+	return {
+		localField: localPrefix + local.source.column,
+		foreignField: foreign.column
+	};
+}
+/**
+* A view predicate (`@db.view.filter`, `@db.view.having`) as a `$match`
+* over pipeline paths: the shared query translation (`translateQueryTree` →
+* `buildMongoFilter`), so operators mean what they mean in queries (`exists`
+* = holds a value, `matches` takes `/re/flags`); a field-to-field comparison
+* becomes `$expr`.
+*/
+function viewMatch(node, pathOf) {
+	return buildMongoFilter(translateQueryTree(node, pathOf), { fieldOperands: true });
+}
+/**
+* `@db.view.having` as a `$match` after `$group`: refs name view fields —
+* aggregates are top-level, dimensions under `_id`.
+*/
+function havingMatch(node, colMap) {
+	return viewMatch(node, (ref) => {
+		const col = ref.type ? void 0 : colMap.get(ref.field);
+		if (!col) return ref.field;
+		return col.aggFn || col.expr !== void 0 ? col.viewColumn : `_id.${col.viewColumn}`;
+	});
+}
+//#endregion
+//#region src/lib/mongo-view-read.ts
+/** Rendered prefixes per read variant (variants are memoised by their view). */
+const prefixes = /* @__PURE__ */ new WeakMap();
+/**
+* The pruned read of `view` for `query`, or `undefined` to read the stored
+* view: nothing droppable, an external view, or an entry that is itself a
+* view (its collation and pipeline would be read twice).
+*/
+function mongoViewRead(view, query, kind) {
+	const variant = view.readPlan(queryReadColumns(query, kind));
+	if (!variant || isViewType(variant.plan.entryType())) return void 0;
+	let prefix = prefixes.get(variant);
+	if (!prefix) {
+		prefix = buildViewPipeline(view, variant);
+		prefixes.set(variant, prefix);
+	}
+	return {
+		entry: variant.plan.entryTable,
+		prefix,
+		dropped: variant.droppedColumns
+	};
+}
+function isPlainObject$1(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Whether any stage may read one of the `dropped` view columns: a field path
+* string (`"$col"`, `"col.sub"`, a `localField`), an object key naming it, or
+* a whole-document variable (`$$ROOT` / `$$CURRENT`). Literals that happen to
+* equal a column name match too — that only falls back to the stored view.
+*
+* MongoDB never rejects a missing field, so this scan — not an engine error —
+* is what keeps a column reference the read-column collector did not report
+* from silently reading `null`.
+*/
+function stagesReadAny(stages, dropped) {
+	if (dropped.length === 0) return false;
+	const names = (raw) => {
+		if (raw.startsWith("$$")) {
+			const variable = raw.slice(2).split(".")[0];
+			return variable === "ROOT" || variable === "CURRENT";
+		}
+		const path = raw.startsWith("$") ? raw.slice(1) : raw;
+		if (!path) return false;
+		return dropped.some((col) => path === col || path.startsWith(`${col}.`) || col.startsWith(`${path}.`));
+	};
+	const visit = (value) => {
+		if (typeof value === "string") return names(value);
+		if (Array.isArray(value)) return value.some(visit);
+		if (!isPlainObject$1(value)) return false;
+		for (const [key, child] of Object.entries(value)) if (names(key) || visit(child)) return true;
+		return false;
+	};
+	return visit(stages);
+}
+//#endregion
 //#region src/lib/mongo-relations.ts
 /** Join key of a row's primary key values (`fields` = the row's own names for them). */
 function buildPKKey(fields, doc) {
@@ -618,21 +874,23 @@ function buildLookupInnerPipeline(target, withRel, relation, requiredFields) {
 	const flatRel = withRel;
 	const nested = withRel.controls || {};
 	const sort = nested.$sort || flatRel.$sort;
+	const nulls = nested.$nulls || flatRel.$nulls;
 	const limit = nested.$limit ?? flatRel.$limit;
 	const skip = nested.$skip ?? flatRel.$skip;
 	const select = nested.$select || flatRel.$select;
 	const statics = relationStaticFilter(relation, withRel.name);
 	const controls = {};
 	if (sort) controls.$sort = sort;
+	if (nulls) controls.$nulls = nulls;
 	if (select) controls.$select = select;
 	const translated = target._translateForAdapter({
 		filter: andFilters(statics.target, withRel.filter),
 		controls
 	});
-	const page = [];
-	if (translated.controls?.$sort) page.push({ $sort: translated.controls.$sort });
+	const { stages: page, cleanup } = sortStages(translated.controls);
 	if (skip) page.push({ $skip: skip });
 	if (limit !== null && limit !== void 0) page.push({ $limit: limit });
+	if (cleanup) page.push(cleanup);
 	const projection = translated.controls?.$select?.asProjection;
 	if (projection) {
 		const project = { ...projection };
@@ -901,13 +1159,22 @@ function resolveGeoKeyPath(host, indexName) {
 	}]);
 	return field;
 }
-/** Appends a `$project` stage, keeping the computed distance in inclusion mode. */
+/**
+* Appends a `$project` stage, keeping the computed distance in inclusion mode.
+* The distance key goes on a COPY: `asProjection` (and `dedupeProjection`)
+* hand back the caller's own `$select` map when nothing needs rewriting — an
+* object the caller may share across queries (moost-db memoizes, and in dev /
+* test deep-freezes, the projection of a read without `$select`).
+*/
 function pushGeoProjection(stages, controls) {
 	const projection = controls?.$select?.asProjection;
 	if (!projection) return;
 	const deduped = dedupeProjection(projection);
-	if (Object.values(deduped).some((v) => v === 1)) deduped[DISTANCE_FIELD] = 1;
-	stages.push({ $project: deduped });
+	const isInclusion = Object.values(deduped).some((v) => v === 1);
+	stages.push({ $project: isInclusion ? {
+		...deduped,
+		[DISTANCE_FIELD]: 1
+	} : deduped });
 }
 /** Renames the internal distance field to the public `$distance` pseudo-field. */
 function renameDistance(row) {
@@ -1217,11 +1484,13 @@ async function runSearchPipeline(host, stage, query, label, { threshold, classic
 		pipeline.push({ $match: { _score: { $gte: threshold } } });
 	} else if (classicText) pipeline.push({ $addFields: { _score: { $meta: "textScore" } } });
 	pipeline.push(...filterStages ?? mongoFilterStages(query.filter, filterOptionsOf(host)));
-	if (controls.$sort) pipeline.push({ $sort: controls.$sort });
+	const { stages: sorted, cleanup } = sortStages(controls);
+	if (sorted.length > 0) pipeline.push(...sorted);
 	else if (classicText) pipeline.push({ $sort: { _score: -1 } });
 	if (controls.$skip) pipeline.push({ $skip: controls.$skip });
 	if (controls.$limit) pipeline.push({ $limit: controls.$limit });
 	else pipeline.push({ $limit: 1e3 });
+	if (cleanup) pipeline.push(cleanup);
 	if (controls.$select) {
 		const projection = controls.$select.asProjection;
 		if (projection) pipeline.push({ $project: dedupeProjection(projection) });
@@ -1246,11 +1515,11 @@ async function runSearchWithCountPipeline(host, stage, query, label, { threshold
 		preStages.push({ $addFields: { _score: { $meta: "vectorSearchScore" } } });
 		preStages.push({ $match: { _score: { $gte: threshold } } });
 	} else if (classicText) preStages.push({ $addFields: { _score: { $meta: "textScore" } } });
-	const dataStages = [];
-	if (controls.$sort) dataStages.push({ $sort: controls.$sort });
-	else if (classicText) dataStages.push({ $sort: { _score: -1 } });
+	const { stages: dataStages, cleanup } = sortStages(controls);
+	if (dataStages.length === 0 && classicText) dataStages.push({ $sort: { _score: -1 } });
 	if (controls.$skip) dataStages.push({ $skip: controls.$skip });
 	if (controls.$limit) dataStages.push({ $limit: controls.$limit });
+	if (cleanup) dataStages.push(cleanup);
 	if (controls.$select) {
 		const projection = controls.$select.asProjection;
 		if (projection) dataStages.push({ $project: dedupeProjection(projection) });
@@ -1300,202 +1569,6 @@ async function runSearchWithMeta(host, stage, dataStages, label) {
 	};
 }
 //#endregion
-//#region src/lib/mongo-view-pipeline.ts
-/** Where a joined table's document lands (`$lookup.as`, then unwound). */
-function joinedAs(table) {
-	return `${JOINED_PREFIX}${table}`;
-}
-/**
-* Builds the aggregation pipeline of a managed MongoDB view (created with
-* `viewOn: <entry collection>`):
-*
-* 1. per join, in declaration order: `$lookup` + `$unwind` (inner joins drop
-*    unmatched documents, left joins keep them — `preserveNullAndEmptyArrays`);
-* 2. `@db.view.filter` → `$match`;
-* 3. aggregates → `$group` (+ `$addFields` turning `countDistinct` sets into
-*    their sizes, + `@db.view.having` → `$match`) + `$project`, otherwise a
-*    flat `$project`. A conditional aggregate's predicate reads the same
-*    pipeline paths (SQL null semantics — `queryNodeToExpr`).
-*
-* All field paths are PHYSICAL document paths (`@db.column` renames), joined
-* tables live under `__joined_<scope>` — the physical collection, or the
-* `@db.alias` type name for an aliased join (`__joined_Manager`), whose
-* `$lookup.from` stays the physical collection (since 0.1.141).
-* The entry collection and a `$lookup.from` may be views. A column whose source may be missing
-* (`nullable` mapping) reads as null; every other column is a plain path, so
-* a `$match` / `$sort` on the view can still push down to an index.
-* @since 0.1.136
-*/
-function buildViewPipeline(view) {
-	const plan = view.viewPlan;
-	const columns = view.getViewColumnMappings();
-	const pipeline = [];
-	const prefixes = new Map([[plan.entryTable, ""]]);
-	const pathOf = (ref) => {
-		const { table, source } = view.resolveRefSource(ref);
-		const prefix = prefixes.get(table);
-		if (prefix === void 0) throw new Error(`View "${view.tableName}": "${table}" is not joined before it is referenced`);
-		return prefix + source.column;
-	};
-	for (const join of plan.joins) {
-		pipeline.push(buildLookup(view, join, prefixes));
-		pipeline.push({ $unwind: {
-			path: `$${joinedAs(join.scope)}`,
-			preserveNullAndEmptyArrays: join.kind === "left"
-		} });
-		prefixes.set(join.scope, `${joinedAs(join.scope)}.`);
-	}
-	if (plan.filter) pipeline.push({ $match: viewMatch(plan.filter, pathOf) });
-	/** A column's source field as an aggregation operand. */
-	const colSourceField = (col) => `$${prefixes.get(col.sourceTable) ?? ""}${col.sourceColumn}`;
-	const colValue = (col) => col.nullable ? orNull(colSourceField(col)) : colSourceField(col);
-	const byPath = new Map(columns.map((c) => [c.viewPath, c]));
-	const rendered = /* @__PURE__ */ new Map();
-	const computedExpr = (col, leaf) => {
-		let out = rendered.get(col.viewPath);
-		if (out === void 0) {
-			out = exprToMongo(col.expr, (path) => {
-				const c = byPath.get(path);
-				return c.expr === void 0 ? { $toDouble: leaf(c) } : computedExpr(c, leaf);
-			});
-			rendered.set(col.viewPath, out);
-		}
-		return out;
-	};
-	if (columns.some((c) => c.aggFn)) {
-		const group = { _id: {} };
-		const project = { _id: 0 };
-		const distinctSizes = {};
-		const computed = {};
-		for (const col of columns) if (col.expr !== void 0) {
-			computed[col.viewColumn] = computedExpr(col, (c) => c.aggFn ? `$${c.viewColumn}` : `$_id.${c.viewColumn}`);
-			project[col.viewColumn] = `$${col.viewColumn}`;
-		} else if (col.aggFn) {
-			const predicate = col.aggFilter ? queryNodeToExpr(col.aggFilter, (ref) => `$${pathOf(ref)}`) : void 0;
-			group[col.viewColumn] = buildAccumulator(col.aggFn, col.aggField === "*" ? "*" : colSourceField(col), predicate, col.viewColumn);
-			project[col.viewColumn] = `$${col.viewColumn}`;
-			if (col.aggFn === "countDistinct") distinctSizes[col.viewColumn] = distinctCountExpr(`$${col.viewColumn}`);
-		} else {
-			group._id[col.viewColumn] = colValue(col);
-			project[col.viewColumn] = `$_id.${col.viewColumn}`;
-		}
-		pipeline.push({ $group: group });
-		if (Object.keys(distinctSizes).length > 0) pipeline.push({ $addFields: distinctSizes });
-		if (Object.keys(computed).length > 0) pipeline.push({ $addFields: computed });
-		if (plan.having) pipeline.push({ $match: havingMatch(plan.having, byPath) });
-		pipeline.push({ $project: project });
-	} else {
-		const project = { _id: 0 };
-		for (const col of columns) project[col.viewColumn] = col.expr === void 0 ? colValue(col) : computedExpr(col, colValue);
-		pipeline.push({ $project: project });
-	}
-	return pipeline;
-}
-/**
-* One join's `$lookup`.
-*
-* The simple `localField` / `foreignField` form is used whenever it is exact:
-* a single `=` between a field of the joined table and a field of an outer
-* table (the entry or an earlier join), with the joined field REQUIRED — the
-* simple form matches a null / missing local value to null / missing foreign
-* values, which a required foreign field can never hold. It is kept (rather
-* than always using the pipeline form) because it can use an index on the
-* foreign field on every MongoDB version; the pipeline form's `$expr` match
-* can't before MongoDB 5.0. Everything else uses the pipeline form (`let` +
-* `$match: { $expr }`, SQL null semantics).
-*/
-function buildLookup(view, join, outer) {
-	const scope = join.scope;
-	const as = joinedAs(scope);
-	const simple = join.first ? void 0 : simpleJoinFields(view, join, outer);
-	if (simple) return { $lookup: {
-		from: join.targetTable,
-		...simple,
-		as
-	} };
-	const letVars = {};
-	const varByPath = /* @__PURE__ */ new Map();
-	const pathOf = (ref) => {
-		const { table, source } = view.resolveRefSource(ref);
-		if (table === scope) return `$${source.column}`;
-		const prefix = outer.get(table);
-		if (prefix === void 0) throw new Error(`View "${view.tableName}": the join on "${scope}" references "${table}", which is not joined before it`);
-		const outerPath = prefix + source.column;
-		let varName = varByPath.get(outerPath);
-		if (!varName) {
-			varName = `v${varByPath.size}`;
-			varByPath.set(outerPath, varName);
-			letVars[varName] = `$${outerPath}`;
-		}
-		return `$$${varName}`;
-	};
-	const pipeline = [{ $match: { $expr: queryNodeToExpr(join.condition, pathOf) } }];
-	if (join.first) {
-		const sort = {};
-		for (const { ref, desc } of join.first.order) sort[view.resolveRefSource(ref).source.column] = desc ? -1 : 1;
-		pipeline.push({ $sort: sort }, { $limit: 1 });
-	}
-	return { $lookup: {
-		from: join.targetTable,
-		...varByPath.size > 0 ? { let: letVars } : {},
-		pipeline,
-		as
-	} };
-}
-/** `{ localField, foreignField }` when the simple `$lookup` form is exact, else `undefined`. */
-function simpleJoinFields(view, join, outer) {
-	let node = join.condition;
-	if ("$and" in node) {
-		const children = node.$and;
-		if (children.length !== 1) return void 0;
-		node = children[0];
-	}
-	if ("$or" in node || "$not" in node || "$and" in node) return void 0;
-	const comp = node;
-	if (comp.op !== "$eq" || !isFieldRef(comp.right)) return void 0;
-	const scope = join.scope;
-	const left = view.resolveRefSource(comp.left);
-	const right = view.resolveRefSource(comp.right);
-	let target;
-	let local;
-	if (left.table === scope && right.table !== scope) {
-		target = left;
-		local = right;
-	} else if (right.table === scope && left.table !== scope) {
-		target = right;
-		local = left;
-	} else return;
-	const localPrefix = outer.get(local.table);
-	if (localPrefix === void 0) return void 0;
-	const foreign = target.source;
-	if (!(!foreign.optional && foreign.designType !== "union" && foreign.designType !== "unknown")) return void 0;
-	return {
-		localField: localPrefix + local.source.column,
-		foreignField: foreign.column
-	};
-}
-/**
-* A view predicate (`@db.view.filter`, `@db.view.having`) as a `$match`
-* over pipeline paths: the shared query translation (`translateQueryTree` →
-* `buildMongoFilter`), so operators mean what they mean in queries (`exists`
-* = holds a value, `matches` takes `/re/flags`); a field-to-field comparison
-* becomes `$expr`.
-*/
-function viewMatch(node, pathOf) {
-	return buildMongoFilter(translateQueryTree(node, pathOf), { fieldOperands: true });
-}
-/**
-* `@db.view.having` as a `$match` after `$group`: refs name view fields —
-* aggregates are top-level, dimensions under `_id`.
-*/
-function havingMatch(node, colMap) {
-	return viewMatch(node, (ref) => {
-		const col = ref.type ? void 0 : colMap.get(ref.field);
-		if (!col) return ref.field;
-		return col.aggFn || col.expr !== void 0 ? col.viewColumn : `_id.${col.viewColumn}`;
-	});
-}
-//#endregion
 //#region src/lib/mongo-schema-sync.ts
 const DESTRUCTIVE_OPTION_KEYS = new Set([
 	"capped",
@@ -2085,6 +2158,7 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		this.db = db;
 		this.client = client;
 		this.options = options;
+		this.viewJoinPruning = options.viewJoinPruning !== false;
 	}
 	get _client() {
 		return this.client;
@@ -2177,15 +2251,17 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			return (applied ?? await run(stages))[0];
 		};
 		const searchStage = buildAggregateSearchStage(this, query.controls);
+		const run = (pipeline, label) => {
+			const pruned = searchStage ? void 0 : this._viewRead(query, "aggregate", pipeline);
+			if (pruned) return this._readPipeline(query, pipeline, label, pruned, aggregateOptions(pipeline));
+			this._log(label, pipeline);
+			return wrapInvalidQuery(() => this.aggregatePipeline(pipeline, aggregateOptions(pipeline)).toArray());
+		};
 		if (query.controls?.$count) {
-			const pipeline = buildCountPipeline(query, searchStage, this._predicateFilterOpts);
-			this._log("aggregate (count)", pipeline);
-			const result = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline, aggregateOptions(pipeline)).toArray());
+			const result = await run(buildCountPipeline(query, searchStage, this._predicateFilterOpts), "aggregate (count)");
 			return result.length > 0 ? result : [{ count: await emptyGroup(true) ? 1 : 0 }];
 		}
-		const pipeline = buildAggregatePipeline(query, searchStage, this._predicateFilterOpts);
-		this._log("aggregate", pipeline);
-		const rows = await wrapInvalidQuery(() => this.aggregatePipeline(pipeline, aggregateOptions(pipeline)).toArray());
+		const rows = await run(buildAggregatePipeline(query, searchStage, this._predicateFilterOpts), "aggregate");
 		const empty = rows.length === 0 ? await emptyGroup(false) : void 0;
 		return empty ? [empty] : rows;
 	}
@@ -2235,6 +2311,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/**
+	* `$nulls` placement (since 0.1.153): a placed `$sort` / `$rowOrder` key
+	* gets a null-or-missing flag ordered before it (`mongo-sort.ts`) — reads
+	* then run as a pipeline with a blocking sort instead of `find().sort()`.
+	*/
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
@@ -2456,7 +2540,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		if (this._hasExplicitId) return {
 			addPrimaryKeys: ["_id"],
 			removePrimaryKeys: meta.originalMetaIdFields.filter((f) => f !== "_id"),
-			addUniqueFields: uniqueFields.length > 0 ? uniqueFields : void 0
+			addUniqueFields: uniqueFields.length === 1 ? uniqueFields : void 0,
+			addUniqueKeys: uniqueFields.length > 1 ? [[...uniqueFields]] : void 0
 		};
 		const effectiveUnique = uniqueFields.filter((f) => meta.primaryKeys.length <= 1 || !meta.primaryKeys.includes(f));
 		effectiveUnique.push("_id");
@@ -2630,8 +2715,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			data: pageStages(query.controls),
 			meta: [{ $count: "count" }]
 		} }];
-		this._log("aggregate (findManyWithCount)", pipeline);
-		const result = await wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray());
+		const pruned = this._viewRead(query, "rows", pipeline);
+		const result = await this._readPipeline(query, pipeline, "aggregate (findManyWithCount)", pruned, placedSortOptions(query.controls));
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -2895,7 +2980,12 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}
 	}
 	async findOne(query) {
-		if (containsRelationFilter(query.filter)) {
+		const pruned = this._prunedFind(query, "findOne", 1);
+		if (pruned) {
+			const [row] = await pruned;
+			return row ?? null;
+		}
+		if (containsRelationFilter(query.filter) || hasNullsPlacement(query.controls)) {
 			const [row] = await this._aggregateFind(query, "findOne", 1);
 			return row ?? null;
 		}
@@ -2909,7 +2999,9 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}));
 	}
 	async findMany(query) {
-		if (containsRelationFilter(query.filter)) return this._aggregateFind(query, "findMany");
+		const pruned = this._prunedFind(query, "findMany");
+		if (pruned) return pruned;
+		if (containsRelationFilter(query.filter) || hasNullsPlacement(query.controls)) return this._aggregateFind(query, "findMany");
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
 		this._log("findMany", filter, opts);
@@ -2920,10 +3012,11 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}).toArray());
 	}
 	async count(query) {
-		if (containsRelationFilter(query.filter)) {
-			const pipeline = [...mongoFilterStages(query.filter, this._predicateFilterOpts), { $count: "count" }];
-			this._log("aggregate (count)", pipeline);
-			return (await wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray()))[0]?.count ?? 0;
+		const stages = () => [...mongoFilterStages(query.filter, this._predicateFilterOpts), { $count: "count" }];
+		const pruned = this._viewRead(query, "count", stages);
+		if (pruned || containsRelationFilter(query.filter)) {
+			const pipeline = pruned?.pipeline ?? stages();
+			return (await this._readPipeline(query, pipeline, "aggregate (count)", pruned))[0]?.count ?? 0;
 		}
 		const filter = buildMongoFilter(query.filter);
 		if (this._estimatesCount() && Object.keys(filter).length === 0) {
@@ -3128,14 +3221,71 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			fieldCounters.set(physical, next + 1);
 		}
 	}
-	/** A find whose filter holds relational predicates, as an aggregation pipeline. */
+	/**
+	* The pruned read of this adapter's managed view for `query` followed by
+	* `stages` (`mongoViewRead`, since 0.1.153): the view pipeline without the
+	* joins the read does not need, on the entry collection — or `undefined`
+	* to read the stored view: pruning off, not a view, nothing droppable, an
+	* operation-wide collation (it would govern the view's join keys too), or
+	* stages that may read a dropped column ({@link stagesReadAny}).
+	*/
+	_viewRead(query, kind, stages) {
+		if (!this.viewJoinPruning || !this._table?.isView) return void 0;
+		if (!containsRelationFilter(query.filter) && this._getCollationOpts(query)) return void 0;
+		const read = mongoViewRead(this._table, query, kind);
+		if (!read) return void 0;
+		const own = typeof stages === "function" ? stages() : stages;
+		if (stagesReadAny(own, read.dropped)) return void 0;
+		return {
+			collection: this.db.collection(read.entry),
+			pipeline: [...read.prefix, ...own]
+		};
+	}
+	/**
+	* Runs a read pipeline — through the pruned view read `pruned` when there
+	* is one, on the bound collection otherwise. A view's own default
+	* collation is the simple one, so the pruned read pins it: the entry
+	* collection's default must not apply.
+	*/
+	_readPipeline(query, stages, label, pruned, options) {
+		if (pruned) {
+			this._log(`${label} (pruned view)`, pruned.pipeline);
+			return wrapInvalidQuery(() => pruned.collection.aggregate(pruned.pipeline, {
+				...options,
+				collation: { locale: "simple" },
+				...this._getSessionOpts()
+			}).toArray());
+		}
+		this._log(label, stages);
+		return wrapInvalidQuery(() => this.collection.aggregate(stages, {
+			...options,
+			...this._readOpts(query)
+		}).toArray());
+	}
+	/** A find over the pruned view read, or `undefined` when the stored view is read. */
+	_prunedFind(query, label, limit) {
+		const pruned = this._viewRead(query, "rows", () => [...mongoFilterStages(query.filter, this._predicateFilterOpts), ...pageStages(limit ? {
+			...query.controls,
+			$limit: limit
+		} : query.controls)]);
+		return pruned && this._readPipeline(query, pruned.pipeline, `aggregate (${label})`, pruned, placedSortOptions(query.controls));
+	}
+	/**
+	* A find as an aggregation pipeline: its filter holds relational
+	* predicates, or its `$sort` places NULL (`$nulls` — `find().sort()` cannot
+	* express it; the placed sort is a blocking sort, so it may spill to disk).
+	*/
 	async _aggregateFind(query, label, limit) {
 		const pipeline = [...mongoFilterStages(query.filter, this._predicateFilterOpts), ...pageStages(limit ? {
 			...query.controls,
 			$limit: limit
 		} : query.controls)];
 		this._log(`aggregate (${label})`, pipeline);
-		return wrapInvalidQuery(() => this.collection.aggregate(pipeline, this._readOpts(query)).toArray());
+		const opts = {
+			...placedSortOptions(query.controls),
+			...this._readOpts(query)
+		};
+		return wrapInvalidQuery(() => this.collection.aggregate(pipeline, opts).toArray());
 	}
 	_buildFindOptions(controls) {
 		const opts = {};
@@ -3248,13 +3398,24 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		return node.fields;
 	}
 };
-/** `$sort` → `$skip` → `$limit` → `$project` stages of a read's controls. */
+/**
+* `allowDiskUse` for a read whose `$sort` places NULL (`$nulls`): the null
+* flags make it a blocking sort no index serves, so it may need to spill.
+*/
+function placedSortOptions(controls) {
+	return hasNullsPlacement(controls) ? { allowDiskUse: true } : void 0;
+}
+/**
+* `$sort` → `$skip` → `$limit` → `$project` stages of a read's controls (a
+* `$nulls` placement adds its flags before the `$sort` and drops them after
+* `$limit` — see {@link sortStages}).
+*/
 function pageStages(controls) {
-	const stages = [];
-	if (!controls) return stages;
-	if (controls.$sort) stages.push({ $sort: controls.$sort });
+	if (!controls) return [];
+	const { stages, cleanup } = sortStages(controls);
 	if (controls.$skip) stages.push({ $skip: controls.$skip });
 	if (controls.$limit) stages.push({ $limit: controls.$limit });
+	if (cleanup) stages.push(cleanup);
 	if (controls.$select) {
 		const projection = controls.$select.asProjection;
 		if (projection) stages.push({ $project: dedupeProjection(projection) });