@atscript/db-mongo 0.1.136 → 0.1.137

package/dist/agg.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_accumulator = require("./mongo-accumulator-C8J36t07.cjs");
+const require_mongo_accumulator = require("./mongo-accumulator-BalE9LkU.cjs");
 let _atscript_db_agg = require("@atscript/db/agg");
 let _uniqu_core = require("@uniqu/core");
 //#region src/agg.ts

package/dist/agg.mjs

@@ -1,4 +1,4 @@
-import { a as buildMongoFilter, n as distinctCountExpr, r as orNull, t as buildAccumulator } from "./mongo-accumulator-Dh6eEkyR.mjs";
+import { i as orNull, n as distinctCountExpr, r as buildMongoFilter, t as buildAccumulator } from "./mongo-accumulator-Dc0w4t0l.mjs";
 import { resolveAlias } from "@atscript/db/agg";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/agg.ts

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_accumulator = require("./mongo-accumulator-C8J36t07.cjs");
+const require_mongo_accumulator = require("./mongo-accumulator-BalE9LkU.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
 let _atscript_db_agg = require("@atscript/db/agg");
@@ -1297,65 +1297,75 @@ async function renameTableImpl(host, oldName) {
 async function syncColumnsImpl(host, diff) {
 	const renamed = [];
 	const added = [];
-	const update = {};
-	if (diff.renamed.length > 0) {
-		const renameSpec = {};
-		for (const r of diff.renamed) {
-			if (pathCrossesArray(host, r.field.path)) {
-				host._log("syncColumns: skipping $rename for array-element field", r.oldName, "→", r.field.physicalName, "(Mongo $rename cannot traverse arrays)");
-				continue;
-			}
-			renameSpec[r.oldName] = r.field.physicalName;
-			renamed.push(r.field.physicalName);
+	const renameSpec = {};
+	for (const r of diff.renamed) {
+		if (pathCrossesArray(host, r.field.path)) {
+			host._log("syncColumns: skipping $rename for array-element field", r.oldName, "→", r.field.physicalName, "(Mongo $rename cannot traverse arrays)");
+			continue;
 		}
-		if (Object.keys(renameSpec).length > 0) update.$rename = renameSpec;
-	}
-	if (diff.added.length > 0) {
-		const setSpec = {};
-		for (const field of diff.added) {
-			const defaultVal = resolveSyncDefault(field);
-			if (defaultVal !== void 0) setSpec[arraySafePath(host, field.physicalName, field.path)] = defaultVal;
-			added.push(field.physicalName);
-		}
-		if (Object.keys(setSpec).length > 0) update.$set = setSpec;
+		renameSpec[r.oldName] = r.field.physicalName;
+		renamed.push(r.field.physicalName);
+	}
+	if (renamed.length > 0) await host.collection.updateMany({}, { $rename: renameSpec }, host._getSessionOpts());
+	for (const field of diff.added) {
+		const value = resolveSyncDefault(field);
+		if (value !== void 0) await defaultBackfill(host, field.path, value);
+		added.push(field.physicalName);
 	}
-	if (Object.keys(update).length > 0) await host.collection.updateMany({}, update, host._getSessionOpts());
 	return {
 		added,
 		renamed
 	};
 }
+/**
+* Backfills an added field's `@db.default` literal where the field is
+* missing — a stored value is never overwritten. Optional fields without a
+* default get no backfill (absent = "optional" in Mongo). A path crossing an
+* array narrows the innermost `$[]` to an `arrayFilters` element missing the
+* sub-path; outer arrays keep `$[]`, so empty arrays are a no-op (a bare
+* dotted path into an empty array is rejected with code 28).
+*/
+async function defaultBackfill(host, logicalPath, value) {
+	const segments = positionalSegments(host, logicalPath);
+	const inner = segments.lastIndexOf("$[]");
+	const opts = host._getSessionOpts();
+	if (inner === -1) {
+		const path = segments.join(".");
+		await host.collection.updateMany({ [path]: { $exists: false } }, { $set: { [path]: value } }, opts);
+		return;
+	}
+	segments[inner] = "$[backfill]";
+	const rest = segments.slice(inner + 1).join(".");
+	await host.collection.updateMany({}, { $set: { [segments.join(".")]: value } }, {
+		...opts,
+		arrayFilters: [{ [`backfill.${rest}`]: { $exists: false } }]
+	});
+}
 async function dropColumnsImpl(host, columns) {
 	if (columns.length === 0) return;
 	const dropped = new Set(columns);
 	const minimal = columns.filter((col) => !hasAncestorIn(col, dropped));
 	const unsetSpec = {};
-	for (const col of minimal) unsetSpec[arraySafePath(host, col, col)] = "";
+	for (const col of minimal) unsetSpec[positionalSegments(host, col, col).join(".")] = "";
 	await host.collection.updateMany({}, { $unset: unsetSpec }, host._getSessionOpts());
 }
 /**
-* Rewrites a dotted physical path to use Mongo's all-positional $[] operator
-* at every segment that's typed as an array in the table's flatMap. Returns
-* the input unchanged when no segment crosses an array boundary.
-*
-* `logicalPath` drives the array-boundary walk (flatMap is keyed by logical
-* path); the leaf of `physicalPath` is preserved so any `@db.column` rename
-* on the leaf still applies.
+* The segments of a field's physical document path with `$[]` after every
+* segment whose logical prefix is an array in the flatMap — Mongo's
+* all-positional operator walks every element. `physicalPath` defaults to
+* the logical path's document path (same segment count).
 */
-function arraySafePath(host, physicalPath, logicalPath) {
-	const logicalSegments = logicalPath.split(".");
-	if (logicalSegments.length < 2) return physicalPath;
-	const physicalSegments = physicalPath.split(".");
-	const physicalLeaf = physicalSegments[physicalSegments.length - 1];
+function positionalSegments(host, logicalPath, physicalPath = host._table.getMetadata().documentPath(logicalPath)) {
+	const logical = logicalPath.split(".");
+	const physical = physicalPath.split(".");
 	const out = [];
 	let prefix = "";
-	for (let i = 0; i < logicalSegments.length; i++) {
-		const isLeaf = i === logicalSegments.length - 1;
-		out.push(isLeaf ? physicalLeaf : logicalSegments[i]);
-		prefix = joinPath(prefix, logicalSegments[i]);
-		if (!isLeaf && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
+	for (let i = 0; i < logical.length; i++) {
+		out.push(physical[i]);
+		prefix = joinPath(prefix, logical[i]);
+		if (i < logical.length - 1 && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
 	}
-	return out.join(".");
+	return out;
 }
 /** Returns true if any non-leaf segment of the path is typed as an array. */
 function pathCrossesArray(host, logicalPath) {
@@ -1818,6 +1828,13 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	aggregateFns() {
 		return _atscript_db.ALL_AGGREGATE_FNS;
 	}
+	/**
+	* See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
+	* BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
+	*/
+	viewRenderRevision() {
+		return "2";
+	}
 	getValidatorPlugins() {
 		return [validateMongoIdPlugin];
 	}
@@ -1926,11 +1943,6 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 			this._addMongoIndexField("unique", "__pk", field);
 			this._pendingUniqueFields.push(field);
 		}
-		if (metadata.has("db.default.increment")) {
-			const physicalName = metadata.get("db.column") ?? field;
-			const startValue = metadata.get("db.default.increment");
-			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
-		}
 		for (const index of metadata.get("db.mongo.search.text") || []) this._pendingSearchFields.push({
 			indexName: index.indexName,
 			field,
@@ -2006,9 +2018,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 				path: value
 			});
 		}
-		for (const fd of this._table.fieldDescriptors) if (fd.collate && fd.collate !== "binary") {
-			if (!this._collateFields) this._collateFields = /* @__PURE__ */ new Map();
-			this._collateFields.set(fd.physicalName, fd.collate);
+		for (const fd of this._table.fieldDescriptors) {
+			if (fd.collate && fd.collate !== "binary") {
+				this._collateFields ??= /* @__PURE__ */ new Map();
+				this._collateFields.set(fd.path, fd.collate);
+				this._collateFields.set(fd.physicalName, fd.collate);
+			}
+			const def = fd.defaultValue;
+			if (def?.kind === "fn" && def.fn === "increment") this._incrementFields.set(fd.physicalName, def.start);
 		}
 	}
 	/** Returns MongoDB-specific search index map (internal). */

package/dist/index.d.cts

@@ -305,6 +305,11 @@ declare class MongoAdapter extends BaseDbAdapter {
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /**
+   * See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
+   * BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
+   */
+  viewRenderRevision(): string;
   getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
   /**
    * Mongo can filter on JSON-stored fields natively — arrays via implicit

package/dist/index.d.mts

@@ -305,6 +305,11 @@ declare class MongoAdapter extends BaseDbAdapter {
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /**
+   * See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
+   * BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
+   */
+  viewRenderRevision(): string;
   getValidatorPlugins(): ReturnType<BaseDbAdapter["getValidatorPlugins"]>;
   /**
    * Mongo can filter on JSON-stored fields natively — arrays via implicit

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as buildMongoFilter, i as queryNodeToExpr, n as distinctCountExpr, r as orNull, t as buildAccumulator } from "./mongo-accumulator-Dh6eEkyR.mjs";
+import { a as queryNodeToExpr, i as orNull, n as distinctCountExpr, r as buildMongoFilter, t as buildAccumulator } from "./mongo-accumulator-Dc0w4t0l.mjs";
 import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, computeInsights, createFailureCollector, getDbFieldOp, getKeyProps, isAtscriptDbView, isFieldRef, resolveDesignType, tableNameOf, translateQueryTree } from "@atscript/db";
 import { MongoClient, MongoServerError, ObjectId } from "mongodb";
 import { resolveAggregateSearch } from "@atscript/db/agg";
@@ -1296,65 +1296,75 @@ async function renameTableImpl(host, oldName) {
 async function syncColumnsImpl(host, diff) {
 	const renamed = [];
 	const added = [];
-	const update = {};
-	if (diff.renamed.length > 0) {
-		const renameSpec = {};
-		for (const r of diff.renamed) {
-			if (pathCrossesArray(host, r.field.path)) {
-				host._log("syncColumns: skipping $rename for array-element field", r.oldName, "→", r.field.physicalName, "(Mongo $rename cannot traverse arrays)");
-				continue;
-			}
-			renameSpec[r.oldName] = r.field.physicalName;
-			renamed.push(r.field.physicalName);
+	const renameSpec = {};
+	for (const r of diff.renamed) {
+		if (pathCrossesArray(host, r.field.path)) {
+			host._log("syncColumns: skipping $rename for array-element field", r.oldName, "→", r.field.physicalName, "(Mongo $rename cannot traverse arrays)");
+			continue;
 		}
-		if (Object.keys(renameSpec).length > 0) update.$rename = renameSpec;
-	}
-	if (diff.added.length > 0) {
-		const setSpec = {};
-		for (const field of diff.added) {
-			const defaultVal = resolveSyncDefault(field);
-			if (defaultVal !== void 0) setSpec[arraySafePath(host, field.physicalName, field.path)] = defaultVal;
-			added.push(field.physicalName);
-		}
-		if (Object.keys(setSpec).length > 0) update.$set = setSpec;
+		renameSpec[r.oldName] = r.field.physicalName;
+		renamed.push(r.field.physicalName);
+	}
+	if (renamed.length > 0) await host.collection.updateMany({}, { $rename: renameSpec }, host._getSessionOpts());
+	for (const field of diff.added) {
+		const value = resolveSyncDefault(field);
+		if (value !== void 0) await defaultBackfill(host, field.path, value);
+		added.push(field.physicalName);
 	}
-	if (Object.keys(update).length > 0) await host.collection.updateMany({}, update, host._getSessionOpts());
 	return {
 		added,
 		renamed
 	};
 }
+/**
+* Backfills an added field's `@db.default` literal where the field is
+* missing — a stored value is never overwritten. Optional fields without a
+* default get no backfill (absent = "optional" in Mongo). A path crossing an
+* array narrows the innermost `$[]` to an `arrayFilters` element missing the
+* sub-path; outer arrays keep `$[]`, so empty arrays are a no-op (a bare
+* dotted path into an empty array is rejected with code 28).
+*/
+async function defaultBackfill(host, logicalPath, value) {
+	const segments = positionalSegments(host, logicalPath);
+	const inner = segments.lastIndexOf("$[]");
+	const opts = host._getSessionOpts();
+	if (inner === -1) {
+		const path = segments.join(".");
+		await host.collection.updateMany({ [path]: { $exists: false } }, { $set: { [path]: value } }, opts);
+		return;
+	}
+	segments[inner] = "$[backfill]";
+	const rest = segments.slice(inner + 1).join(".");
+	await host.collection.updateMany({}, { $set: { [segments.join(".")]: value } }, {
+		...opts,
+		arrayFilters: [{ [`backfill.${rest}`]: { $exists: false } }]
+	});
+}
 async function dropColumnsImpl(host, columns) {
 	if (columns.length === 0) return;
 	const dropped = new Set(columns);
 	const minimal = columns.filter((col) => !hasAncestorIn(col, dropped));
 	const unsetSpec = {};
-	for (const col of minimal) unsetSpec[arraySafePath(host, col, col)] = "";
+	for (const col of minimal) unsetSpec[positionalSegments(host, col, col).join(".")] = "";
 	await host.collection.updateMany({}, { $unset: unsetSpec }, host._getSessionOpts());
 }
 /**
-* Rewrites a dotted physical path to use Mongo's all-positional $[] operator
-* at every segment that's typed as an array in the table's flatMap. Returns
-* the input unchanged when no segment crosses an array boundary.
-*
-* `logicalPath` drives the array-boundary walk (flatMap is keyed by logical
-* path); the leaf of `physicalPath` is preserved so any `@db.column` rename
-* on the leaf still applies.
+* The segments of a field's physical document path with `$[]` after every
+* segment whose logical prefix is an array in the flatMap — Mongo's
+* all-positional operator walks every element. `physicalPath` defaults to
+* the logical path's document path (same segment count).
 */
-function arraySafePath(host, physicalPath, logicalPath) {
-	const logicalSegments = logicalPath.split(".");
-	if (logicalSegments.length < 2) return physicalPath;
-	const physicalSegments = physicalPath.split(".");
-	const physicalLeaf = physicalSegments[physicalSegments.length - 1];
+function positionalSegments(host, logicalPath, physicalPath = host._table.getMetadata().documentPath(logicalPath)) {
+	const logical = logicalPath.split(".");
+	const physical = physicalPath.split(".");
 	const out = [];
 	let prefix = "";
-	for (let i = 0; i < logicalSegments.length; i++) {
-		const isLeaf = i === logicalSegments.length - 1;
-		out.push(isLeaf ? physicalLeaf : logicalSegments[i]);
-		prefix = joinPath(prefix, logicalSegments[i]);
-		if (!isLeaf && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
+	for (let i = 0; i < logical.length; i++) {
+		out.push(physical[i]);
+		prefix = joinPath(prefix, logical[i]);
+		if (i < logical.length - 1 && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
 	}
-	return out.join(".");
+	return out;
 }
 /** Returns true if any non-leaf segment of the path is typed as an array. */
 function pathCrossesArray(host, logicalPath) {
@@ -1817,6 +1827,13 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	aggregateFns() {
 		return ALL_AGGREGATE_FNS;
 	}
+	/**
+	* See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
+	* BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
+	*/
+	viewRenderRevision() {
+		return "2";
+	}
 	getValidatorPlugins() {
 		return [validateMongoIdPlugin];
 	}
@@ -1925,11 +1942,6 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			this._addMongoIndexField("unique", "__pk", field);
 			this._pendingUniqueFields.push(field);
 		}
-		if (metadata.has("db.default.increment")) {
-			const physicalName = metadata.get("db.column") ?? field;
-			const startValue = metadata.get("db.default.increment");
-			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
-		}
 		for (const index of metadata.get("db.mongo.search.text") || []) this._pendingSearchFields.push({
 			indexName: index.indexName,
 			field,
@@ -2005,9 +2017,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 				path: value
 			});
 		}
-		for (const fd of this._table.fieldDescriptors) if (fd.collate && fd.collate !== "binary") {
-			if (!this._collateFields) this._collateFields = /* @__PURE__ */ new Map();
-			this._collateFields.set(fd.physicalName, fd.collate);
+		for (const fd of this._table.fieldDescriptors) {
+			if (fd.collate && fd.collate !== "binary") {
+				this._collateFields ??= /* @__PURE__ */ new Map();
+				this._collateFields.set(fd.path, fd.collate);
+				this._collateFields.set(fd.physicalName, fd.collate);
+			}
+			const def = fd.defaultValue;
+			if (def?.kind === "fn" && def.fn === "increment") this._incrementFields.set(fd.physicalName, def.start);
 		}
 	}
 	/** Returns MongoDB-specific search index map (internal). */

package/dist/{mongo-accumulator-C8J36t07.cjs → mongo-accumulator-BalE9LkU.cjs}

@@ -1,85 +1,5 @@
 let _atscript_db = require("@atscript/db");
 let _atscript_db_agg = require("@atscript/db/agg");
-//#region src/lib/mongo-filter.ts
-const EMPTY = {};
-function parseRegexString(value) {
-	if (value instanceof RegExp) return {
-		pattern: value.source,
-		flags: value.flags
-	};
-	const str = String(value);
-	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
-	if (match) return {
-		pattern: match[1],
-		flags: match[2]
-	};
-	return {
-		pattern: str,
-		flags: ""
-	};
-}
-/**
-* Earth radius in meters used by MongoDB's `$centerSphere` radians conversion
-* (Mongo documents dividing by 6378.1 km).
-*/
-const EARTH_RADIUS_M = 6378100;
-const mongoVisitor = {
-	comparison(field, op, value) {
-		if (op === "$eq") return { [field]: value };
-		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
-		if (op === "$regex") {
-			const { pattern, flags } = parseRegexString(value);
-			return flags ? { [field]: {
-				$regex: pattern,
-				$options: flags
-			} } : { [field]: { $regex: pattern } };
-		}
-		if (op === "$geoWithin") {
-			const { center, radius } = value;
-			return { [field]: { $geoWithin: { $centerSphere: [center, radius / EARTH_RADIUS_M] } } };
-		}
-		return { [field]: { [op]: value } };
-	},
-	and(children) {
-		if (children.length === 0) return EMPTY;
-		if (children.length === 1) return children[0];
-		return { $and: children };
-	},
-	or(children) {
-		if (children.length === 0) return { _impossible: true };
-		if (children.length === 1) return children[0];
-		return { $or: children };
-	},
-	not(child) {
-		return { $nor: [child] };
-	}
-};
-/** A `{ $field: path }` comparison operand (a field-to-field comparison). */
-function isFieldOperand(value) {
-	return value !== null && typeof value === "object" && typeof value.$field === "string";
-}
-/** {@link mongoVisitor} plus field-to-field comparisons (`{ $field }` operands → `$expr`). */
-const fieldOperandVisitor = {
-	...mongoVisitor,
-	comparison(field, op, value) {
-		return isFieldOperand(value) ? { $expr: { [op]: [`$${field}`, `$${value.$field}`] } } : mongoVisitor.comparison(field, op, value);
-	}
-};
-/**
-* Translates a generic {@link FilterExpr} into a MongoDB-compatible
-* {@link Filter} document.
-*
-* MongoDB's query language is nearly identical to the `FilterExpr` structure,
-* so this is largely a structural pass-through via the `walkFilter` visitor.
-* `fieldOperands` (view predicates only — `translateQueryTree` output) turns
-* `{ $field: path }` operands into field-to-field `$expr` comparisons; a
-* request filter never gets that reading.
-*/
-function buildMongoFilter(filter, { fieldOperands = false } = {}) {
-	if (!filter || Object.keys(filter).length === 0) return EMPTY;
-	return (0, _atscript_db.walkFilter)(filter, fieldOperands ? fieldOperandVisitor : mongoVisitor) ?? EMPTY;
-}
-//#endregion
 //#region src/lib/mongo-view-expr.ts
 /**
 * `x IS NOT NULL` in SQL terms — true when `x` is neither null nor missing.
@@ -122,6 +42,15 @@ function guarded(operands, cond) {
 	return { $and: [...operands.map((o) => notNullExpr(o)), cond] };
 }
 /**
+* Field-to-field comparison `x <op> y` (`$eq` … `$lte`): both operands must
+* be non-null (SQL `NULL = NULL` is UNKNOWN) — view predicates and
+* `buildMongoFilter`'s field operands.
+* @since 0.1.137
+*/
+function fieldCompareExpr(op, x, y) {
+	return guarded([x, y], { [op]: [x, y] });
+}
+/**
 * Translates a view predicate (join condition, conditional-aggregate filter)
 * to an aggregation expression for `$match: { $expr }` / `$cond`, matching
 * SQL's three-valued logic wherever a NULL operand makes SQL's comparison
@@ -156,10 +85,7 @@ function queryNodeToExpr(node, pathOf) {
 	}
 	const op = COMPARISONS[comp.op];
 	if (!op) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
-	if ((0, _atscript_db.isFieldRef)(comp.right)) {
-		const y = pathOf(comp.right);
-		return guarded([x, y], { [op]: [x, y] });
-	}
+	if ((0, _atscript_db.isFieldRef)(comp.right)) return fieldCompareExpr(op, x, pathOf(comp.right));
 	if (comp.right === null || comp.right === void 0) {
 		if (op === "$eq") return isNullExpr(x);
 		if (op === "$ne") return notNullExpr(x);
@@ -170,6 +96,89 @@ function queryNodeToExpr(node, pathOf) {
 	return guarded([x], { [op]: [x, value] });
 }
 //#endregion
+//#region src/lib/mongo-filter.ts
+const EMPTY = {};
+function parseRegexString(value) {
+	if (value instanceof RegExp) return {
+		pattern: value.source,
+		flags: value.flags
+	};
+	const str = String(value);
+	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
+	if (match) return {
+		pattern: match[1],
+		flags: match[2]
+	};
+	return {
+		pattern: str,
+		flags: ""
+	};
+}
+/**
+* Earth radius in meters used by MongoDB's `$centerSphere` radians conversion
+* (Mongo documents dividing by 6378.1 km).
+*/
+const EARTH_RADIUS_M = 6378100;
+const mongoVisitor = {
+	comparison(field, op, value) {
+		if (op === "$eq") return { [field]: value };
+		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
+		if (op === "$regex") {
+			const { pattern, flags } = parseRegexString(value);
+			return flags ? { [field]: {
+				$regex: pattern,
+				$options: flags
+			} } : { [field]: { $regex: pattern } };
+		}
+		if (op === "$geoWithin") {
+			const { center, radius } = value;
+			return { [field]: { $geoWithin: { $centerSphere: [center, radius / EARTH_RADIUS_M] } } };
+		}
+		return { [field]: { [op]: value } };
+	},
+	and(children) {
+		if (children.length === 0) return EMPTY;
+		if (children.length === 1) return children[0];
+		return { $and: children };
+	},
+	or(children) {
+		if (children.length === 0) return { _impossible: true };
+		if (children.length === 1) return children[0];
+		return { $or: children };
+	},
+	not(child) {
+		return { $nor: [child] };
+	}
+};
+/** A `{ $field: path }` comparison operand (a field-to-field comparison). */
+function isFieldOperand(value) {
+	return value !== null && typeof value === "object" && typeof value.$field === "string";
+}
+/**
+* {@link mongoVisitor} plus field-to-field comparisons (`{ $field }` operands →
+* `$expr`), null-guarded like SQL ({@link fieldCompareExpr}).
+*/
+const fieldOperandVisitor = {
+	...mongoVisitor,
+	comparison(field, op, value) {
+		return isFieldOperand(value) ? { $expr: fieldCompareExpr(op, `$${field}`, `$${value.$field}`) } : mongoVisitor.comparison(field, op, value);
+	}
+};
+/**
+* Translates a generic {@link FilterExpr} into a MongoDB-compatible
+* {@link Filter} document.
+*
+* MongoDB's query language is nearly identical to the `FilterExpr` structure,
+* so this is largely a structural pass-through via the `walkFilter` visitor.
+* `fieldOperands` (view predicates only — `translateQueryTree` output) turns
+* `{ $field: path }` operands into field-to-field `$expr` comparisons; a
+* request filter never gets that reading.
+*/
+function buildMongoFilter(filter, { fieldOperands = false } = {}) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY;
+	return (0, _atscript_db.walkFilter)(filter, fieldOperands ? fieldOperandVisitor : mongoVisitor) ?? EMPTY;
+}
+//#endregion
 //#region src/lib/mongo-accumulator.ts
 /**
 * The `$group` accumulator of one aggregate — shared by grouped queries

package/dist/{mongo-accumulator-Dh6eEkyR.mjs → mongo-accumulator-Dc0w4t0l.mjs}

@@ -1,85 +1,5 @@
 import { isFieldRef, walkFilter } from "@atscript/db";
 import { assertAggregateFn } from "@atscript/db/agg";
-//#region src/lib/mongo-filter.ts
-const EMPTY = {};
-function parseRegexString(value) {
-	if (value instanceof RegExp) return {
-		pattern: value.source,
-		flags: value.flags
-	};
-	const str = String(value);
-	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
-	if (match) return {
-		pattern: match[1],
-		flags: match[2]
-	};
-	return {
-		pattern: str,
-		flags: ""
-	};
-}
-/**
-* Earth radius in meters used by MongoDB's `$centerSphere` radians conversion
-* (Mongo documents dividing by 6378.1 km).
-*/
-const EARTH_RADIUS_M = 6378100;
-const mongoVisitor = {
-	comparison(field, op, value) {
-		if (op === "$eq") return { [field]: value };
-		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
-		if (op === "$regex") {
-			const { pattern, flags } = parseRegexString(value);
-			return flags ? { [field]: {
-				$regex: pattern,
-				$options: flags
-			} } : { [field]: { $regex: pattern } };
-		}
-		if (op === "$geoWithin") {
-			const { center, radius } = value;
-			return { [field]: { $geoWithin: { $centerSphere: [center, radius / EARTH_RADIUS_M] } } };
-		}
-		return { [field]: { [op]: value } };
-	},
-	and(children) {
-		if (children.length === 0) return EMPTY;
-		if (children.length === 1) return children[0];
-		return { $and: children };
-	},
-	or(children) {
-		if (children.length === 0) return { _impossible: true };
-		if (children.length === 1) return children[0];
-		return { $or: children };
-	},
-	not(child) {
-		return { $nor: [child] };
-	}
-};
-/** A `{ $field: path }` comparison operand (a field-to-field comparison). */
-function isFieldOperand(value) {
-	return value !== null && typeof value === "object" && typeof value.$field === "string";
-}
-/** {@link mongoVisitor} plus field-to-field comparisons (`{ $field }` operands → `$expr`). */
-const fieldOperandVisitor = {
-	...mongoVisitor,
-	comparison(field, op, value) {
-		return isFieldOperand(value) ? { $expr: { [op]: [`$${field}`, `$${value.$field}`] } } : mongoVisitor.comparison(field, op, value);
-	}
-};
-/**
-* Translates a generic {@link FilterExpr} into a MongoDB-compatible
-* {@link Filter} document.
-*
-* MongoDB's query language is nearly identical to the `FilterExpr` structure,
-* so this is largely a structural pass-through via the `walkFilter` visitor.
-* `fieldOperands` (view predicates only — `translateQueryTree` output) turns
-* `{ $field: path }` operands into field-to-field `$expr` comparisons; a
-* request filter never gets that reading.
-*/
-function buildMongoFilter(filter, { fieldOperands = false } = {}) {
-	if (!filter || Object.keys(filter).length === 0) return EMPTY;
-	return walkFilter(filter, fieldOperands ? fieldOperandVisitor : mongoVisitor) ?? EMPTY;
-}
-//#endregion
 //#region src/lib/mongo-view-expr.ts
 /**
 * `x IS NOT NULL` in SQL terms — true when `x` is neither null nor missing.
@@ -122,6 +42,15 @@ function guarded(operands, cond) {
 	return { $and: [...operands.map((o) => notNullExpr(o)), cond] };
 }
 /**
+* Field-to-field comparison `x <op> y` (`$eq` … `$lte`): both operands must
+* be non-null (SQL `NULL = NULL` is UNKNOWN) — view predicates and
+* `buildMongoFilter`'s field operands.
+* @since 0.1.137
+*/
+function fieldCompareExpr(op, x, y) {
+	return guarded([x, y], { [op]: [x, y] });
+}
+/**
 * Translates a view predicate (join condition, conditional-aggregate filter)
 * to an aggregation expression for `$match: { $expr }` / `$cond`, matching
 * SQL's three-valued logic wherever a NULL operand makes SQL's comparison
@@ -156,10 +85,7 @@ function queryNodeToExpr(node, pathOf) {
 	}
 	const op = COMPARISONS[comp.op];
 	if (!op) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
-	if (isFieldRef(comp.right)) {
-		const y = pathOf(comp.right);
-		return guarded([x, y], { [op]: [x, y] });
-	}
+	if (isFieldRef(comp.right)) return fieldCompareExpr(op, x, pathOf(comp.right));
 	if (comp.right === null || comp.right === void 0) {
 		if (op === "$eq") return isNullExpr(x);
 		if (op === "$ne") return notNullExpr(x);
@@ -170,6 +96,89 @@ function queryNodeToExpr(node, pathOf) {
 	return guarded([x], { [op]: [x, value] });
 }
 //#endregion
+//#region src/lib/mongo-filter.ts
+const EMPTY = {};
+function parseRegexString(value) {
+	if (value instanceof RegExp) return {
+		pattern: value.source,
+		flags: value.flags
+	};
+	const str = String(value);
+	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
+	if (match) return {
+		pattern: match[1],
+		flags: match[2]
+	};
+	return {
+		pattern: str,
+		flags: ""
+	};
+}
+/**
+* Earth radius in meters used by MongoDB's `$centerSphere` radians conversion
+* (Mongo documents dividing by 6378.1 km).
+*/
+const EARTH_RADIUS_M = 6378100;
+const mongoVisitor = {
+	comparison(field, op, value) {
+		if (op === "$eq") return { [field]: value };
+		if (op === "$exists") return value ? { [field]: { $ne: null } } : { [field]: null };
+		if (op === "$regex") {
+			const { pattern, flags } = parseRegexString(value);
+			return flags ? { [field]: {
+				$regex: pattern,
+				$options: flags
+			} } : { [field]: { $regex: pattern } };
+		}
+		if (op === "$geoWithin") {
+			const { center, radius } = value;
+			return { [field]: { $geoWithin: { $centerSphere: [center, radius / EARTH_RADIUS_M] } } };
+		}
+		return { [field]: { [op]: value } };
+	},
+	and(children) {
+		if (children.length === 0) return EMPTY;
+		if (children.length === 1) return children[0];
+		return { $and: children };
+	},
+	or(children) {
+		if (children.length === 0) return { _impossible: true };
+		if (children.length === 1) return children[0];
+		return { $or: children };
+	},
+	not(child) {
+		return { $nor: [child] };
+	}
+};
+/** A `{ $field: path }` comparison operand (a field-to-field comparison). */
+function isFieldOperand(value) {
+	return value !== null && typeof value === "object" && typeof value.$field === "string";
+}
+/**
+* {@link mongoVisitor} plus field-to-field comparisons (`{ $field }` operands →
+* `$expr`), null-guarded like SQL ({@link fieldCompareExpr}).
+*/
+const fieldOperandVisitor = {
+	...mongoVisitor,
+	comparison(field, op, value) {
+		return isFieldOperand(value) ? { $expr: fieldCompareExpr(op, `$${field}`, `$${value.$field}`) } : mongoVisitor.comparison(field, op, value);
+	}
+};
+/**
+* Translates a generic {@link FilterExpr} into a MongoDB-compatible
+* {@link Filter} document.
+*
+* MongoDB's query language is nearly identical to the `FilterExpr` structure,
+* so this is largely a structural pass-through via the `walkFilter` visitor.
+* `fieldOperands` (view predicates only — `translateQueryTree` output) turns
+* `{ $field: path }` operands into field-to-field `$expr` comparisons; a
+* request filter never gets that reading.
+*/
+function buildMongoFilter(filter, { fieldOperands = false } = {}) {
+	if (!filter || Object.keys(filter).length === 0) return EMPTY;
+	return walkFilter(filter, fieldOperands ? fieldOperandVisitor : mongoVisitor) ?? EMPTY;
+}
+//#endregion
 //#region src/lib/mongo-accumulator.ts
 /**
 * The `$group` accumulator of one aggregate — shared by grouped queries
@@ -224,4 +233,4 @@ function distinctCountExpr(set) {
 	return { $size: set };
 }
 //#endregion
-export { buildMongoFilter as a, queryNodeToExpr as i, distinctCountExpr as n, orNull as r, buildAccumulator as t };
+export { queryNodeToExpr as a, orNull as i, distinctCountExpr as n, buildMongoFilter as r, buildAccumulator as t };

package/package.json

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