@atscript/db-mongo 0.1.95 → 0.1.97

package/dist/index.cjs

@@ -1064,12 +1064,14 @@ async function syncIndexesImpl(host) {
 			mongoType = index.type;
 			for (const f of index.fields) fields[f.name] = 1;
 		}
+		const partialFilterExpression = index.type === "unique" ? buildPresentOnlyFilter(index.fields) : void 0;
 		allIndexes.set(key, {
 			key,
 			name: index.name,
 			type: mongoType,
 			fields,
-			weights
+			weights,
+			...partialFilterExpression ? { partialFilterExpression } : {}
 		});
 	}
 	for (const [key, index] of host._mongoIndexes.entries()) if (index.type === "text") {
@@ -1088,13 +1090,17 @@ async function syncIndexesImpl(host) {
 			switch (local.type) {
 				case "plain":
 				case "unique":
-				case "text":
-					if ((local.type === "text" || objMatch(local.fields, remote.key)) && objMatch(local.weights || {}, remote.weights || {})) indexesToCreate.delete(remote.name);
+				case "text": {
+					const fieldsMatch = local.type === "text" || objMatch(local.fields, remote.key);
+					const weightsMatch = objMatch(local.weights || {}, remote.weights || {});
+					const optionsMatch = local.type === "text" || local.type === "unique" === (remote.unique === true) && partialFilterEqual(local.partialFilterExpression, remote.partialFilterExpression);
+					if (fieldsMatch && weightsMatch && optionsMatch) indexesToCreate.delete(remote.name);
 					else {
 						host._log("dropIndex", remote.name);
 						await host.collection.dropIndex(remote.name);
 					}
 					break;
+				}
 				default:
 			}
 		} else {
@@ -1110,10 +1116,11 @@ async function syncIndexesImpl(host) {
 			break;
 		case "unique":
 			if (!indexesToCreate.has(key)) continue;
-			host._log("createIndex (unique)", key, value.fields);
+			host._log("createIndex (unique)", key, value.fields, value.partialFilterExpression);
 			await host.collection.createIndex(value.fields, {
 				name: key,
-				unique: true
+				unique: true,
+				...value.partialFilterExpression ? { partialFilterExpression: value.partialFilterExpression } : {}
 			});
 			break;
 		case "text":
@@ -1173,6 +1180,77 @@ async function syncIndexesImpl(host) {
 		}
 	} catch {}
 }
+/**
+* Maps an engine-agnostic design type to the MongoDB BSON `$type` alias(es)
+* meaning "a present value of this type". Using `$type` (rather than a bare
+* `sparse: true` or `$exists: true`) excludes BOTH absent and explicit-null
+* values, so a row whose optional field was written as `null` — e.g. by a
+* replace-strategy patch — is still tolerated by the unique constraint.
+*/
+function bsonPresentTypes(designType) {
+	switch (designType) {
+		case "string": return "string";
+		case "objectId": return ["objectId", "string"];
+		case "number":
+		case "decimal": return "number";
+		case "boolean": return "bool";
+		default: return [
+			"double",
+			"string",
+			"object",
+			"array",
+			"binData",
+			"objectId",
+			"bool",
+			"date",
+			"regex",
+			"int",
+			"timestamp",
+			"long",
+			"decimal"
+		];
+	}
+}
+/**
+* Builds a `partialFilterExpression` restricting a unique index to rows where
+* every OPTIONAL field is present. Returns undefined when no field is optional
+* (a plain unique index — no nulls possible — needs no filter).
+*
+* Filtering on the optional fields (not the required ones) matches SQL's NULLS
+* DISTINCT: a composite unique row is exempt as soon as any nullable column is
+* null, so many value-less rows coexist while fully populated rows stay unique.
+*/
+function buildPresentOnlyFilter(indexFields) {
+	const optional = indexFields.filter((f) => f.optional);
+	if (optional.length === 0) return;
+	const clauses = optional.map((f) => ({
+		name: f.name,
+		clause: { [f.name]: { $type: bsonPresentTypes(f.designType) } }
+	})).toSorted((a, b) => a.name.localeCompare(b.name)).map((c) => c.clause);
+	return clauses.length === 1 ? clauses[0] : { $and: clauses };
+}
+/**
+* Deep structural equality for `partialFilterExpression` objects, used to detect
+* when a unique index's present-only filter has changed. Object keys compare
+* order-insensitively; arrays (`$and`, `$type` lists) are order-sensitive,
+* matching this module's deterministic emission. A missing filter (undefined)
+* and an explicit `null` both mean "no filter" and compare equal.
+*/
+function partialFilterEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a == null && b == null;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, i) => partialFilterEqual(item, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const ka = Object.keys(a);
+		const kb = Object.keys(b);
+		if (ka.length !== kb.length) return false;
+		return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && partialFilterEqual(a[k], b[k]));
+	}
+	return false;
+}
 function objMatch(o1, o2) {
 	const keys1 = Object.keys(o1);
 	const keys2 = Object.keys(o2);

package/dist/index.d.cts

@@ -151,6 +151,14 @@ interface TPlainIndex {
   type: "plain" | "unique" | "text";
   fields: Record<string, 1 | "text">;
   weights: Record<string, number>;
+  /**
+   * For "present-only" unique indexes on optional fields: a MongoDB
+   * `partialFilterExpression` restricting the index to rows where the optional
+   * field(s) are present. This lets multiple value-less rows coexist (matching
+   * SQL's `NULLS DISTINCT`) while present values stay unique. Absent for plain
+   * unique indexes (all fields required) and non-unique indexes.
+   */
+  partialFilterExpression?: Record<string, unknown>;
 }
 interface TSearchIndex {
   key: string;

package/dist/index.d.mts

@@ -151,6 +151,14 @@ interface TPlainIndex {
   type: "plain" | "unique" | "text";
   fields: Record<string, 1 | "text">;
   weights: Record<string, number>;
+  /**
+   * For "present-only" unique indexes on optional fields: a MongoDB
+   * `partialFilterExpression` restricting the index to rows where the optional
+   * field(s) are present. This lets multiple value-less rows coexist (matching
+   * SQL's `NULLS DISTINCT`) while present values stay unique. Absent for plain
+   * unique indexes (all fields required) and non-unique indexes.
+   */
+  partialFilterExpression?: Record<string, unknown>;
 }
 interface TSearchIndex {
   key: string;

package/dist/index.mjs

@@ -1063,12 +1063,14 @@ async function syncIndexesImpl(host) {
 			mongoType = index.type;
 			for (const f of index.fields) fields[f.name] = 1;
 		}
+		const partialFilterExpression = index.type === "unique" ? buildPresentOnlyFilter(index.fields) : void 0;
 		allIndexes.set(key, {
 			key,
 			name: index.name,
 			type: mongoType,
 			fields,
-			weights
+			weights,
+			...partialFilterExpression ? { partialFilterExpression } : {}
 		});
 	}
 	for (const [key, index] of host._mongoIndexes.entries()) if (index.type === "text") {
@@ -1087,13 +1089,17 @@ async function syncIndexesImpl(host) {
 			switch (local.type) {
 				case "plain":
 				case "unique":
-				case "text":
-					if ((local.type === "text" || objMatch(local.fields, remote.key)) && objMatch(local.weights || {}, remote.weights || {})) indexesToCreate.delete(remote.name);
+				case "text": {
+					const fieldsMatch = local.type === "text" || objMatch(local.fields, remote.key);
+					const weightsMatch = objMatch(local.weights || {}, remote.weights || {});
+					const optionsMatch = local.type === "text" || local.type === "unique" === (remote.unique === true) && partialFilterEqual(local.partialFilterExpression, remote.partialFilterExpression);
+					if (fieldsMatch && weightsMatch && optionsMatch) indexesToCreate.delete(remote.name);
 					else {
 						host._log("dropIndex", remote.name);
 						await host.collection.dropIndex(remote.name);
 					}
 					break;
+				}
 				default:
 			}
 		} else {
@@ -1109,10 +1115,11 @@ async function syncIndexesImpl(host) {
 			break;
 		case "unique":
 			if (!indexesToCreate.has(key)) continue;
-			host._log("createIndex (unique)", key, value.fields);
+			host._log("createIndex (unique)", key, value.fields, value.partialFilterExpression);
 			await host.collection.createIndex(value.fields, {
 				name: key,
-				unique: true
+				unique: true,
+				...value.partialFilterExpression ? { partialFilterExpression: value.partialFilterExpression } : {}
 			});
 			break;
 		case "text":
@@ -1172,6 +1179,77 @@ async function syncIndexesImpl(host) {
 		}
 	} catch {}
 }
+/**
+* Maps an engine-agnostic design type to the MongoDB BSON `$type` alias(es)
+* meaning "a present value of this type". Using `$type` (rather than a bare
+* `sparse: true` or `$exists: true`) excludes BOTH absent and explicit-null
+* values, so a row whose optional field was written as `null` — e.g. by a
+* replace-strategy patch — is still tolerated by the unique constraint.
+*/
+function bsonPresentTypes(designType) {
+	switch (designType) {
+		case "string": return "string";
+		case "objectId": return ["objectId", "string"];
+		case "number":
+		case "decimal": return "number";
+		case "boolean": return "bool";
+		default: return [
+			"double",
+			"string",
+			"object",
+			"array",
+			"binData",
+			"objectId",
+			"bool",
+			"date",
+			"regex",
+			"int",
+			"timestamp",
+			"long",
+			"decimal"
+		];
+	}
+}
+/**
+* Builds a `partialFilterExpression` restricting a unique index to rows where
+* every OPTIONAL field is present. Returns undefined when no field is optional
+* (a plain unique index — no nulls possible — needs no filter).
+*
+* Filtering on the optional fields (not the required ones) matches SQL's NULLS
+* DISTINCT: a composite unique row is exempt as soon as any nullable column is
+* null, so many value-less rows coexist while fully populated rows stay unique.
+*/
+function buildPresentOnlyFilter(indexFields) {
+	const optional = indexFields.filter((f) => f.optional);
+	if (optional.length === 0) return;
+	const clauses = optional.map((f) => ({
+		name: f.name,
+		clause: { [f.name]: { $type: bsonPresentTypes(f.designType) } }
+	})).toSorted((a, b) => a.name.localeCompare(b.name)).map((c) => c.clause);
+	return clauses.length === 1 ? clauses[0] : { $and: clauses };
+}
+/**
+* Deep structural equality for `partialFilterExpression` objects, used to detect
+* when a unique index's present-only filter has changed. Object keys compare
+* order-insensitively; arrays (`$and`, `$type` lists) are order-sensitive,
+* matching this module's deterministic emission. A missing filter (undefined)
+* and an explicit `null` both mean "no filter" and compare equal.
+*/
+function partialFilterEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a == null && b == null;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, i) => partialFilterEqual(item, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const ka = Object.keys(a);
+		const kb = Object.keys(b);
+		if (ka.length !== kb.length) return false;
+		return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && partialFilterEqual(a[k], b[k]));
+	}
+	return false;
+}
 function objMatch(o1, o2) {
 	const keys1 = Object.keys(o1);
 	const keys2 = Object.keys(o2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -46,17 +46,17 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.68",
-    "@atscript/typescript": "^0.1.68",
+    "@atscript/core": "^0.1.70",
+    "@atscript/typescript": "^0.1.70",
     "mongodb": "^6.17.0",
     "mongodb-memory-server-core": "^10.0.0",
-    "unplugin-atscript": "^0.1.68"
+    "unplugin-atscript": "^0.1.70"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.68",
-    "@atscript/typescript": "^0.1.68",
+    "@atscript/core": "^0.1.70",
+    "@atscript/typescript": "^0.1.70",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.95"
+    "@atscript/db": "^0.1.97"
   },
   "scripts": {
     "postinstall": "asc -f dts",