@atscript/mongo 0.0.16 → 0.0.18

package/dist/index.cjs

@@ -106,6 +106,15 @@ const annotations = { mongo: {
 			});
 		}
 	}),
+	autoIndexes: new __atscript_core.AnnotationSpec({
+		description: "Switch on/off the automatic index creation. Works with as-mongo moost controller.\n\nDefault: true",
+		nodeType: ["interface"],
+		argument: {
+			name: "type",
+			type: "boolean",
+			description: "On/Off the automatic index creation"
+		}
+	}),
 	index: {
 		plain: new __atscript_core.AnnotationSpec({
 			description: "Defines a **standard MongoDB index** on a field.\n\n- Improves query performance on indexed fields.\n- Can be used for **single-field** or **compound** indexes.\n\n**Example:**\n```atscript\n@mongo.index.plain \"departmentIndex\"\ndepartment: string\n```\n",
@@ -250,7 +259,57 @@ const annotations = { mongo: {
 				description: "The **name of the vector search index** this field should be used as a filter for."
 			}]
 		})
-	}
+	},
+	patch: { strategy: new __atscript_core.AnnotationSpec({
+		description: "Defines the **patching strategy** for updating MongoDB documents.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@mongo.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "strategy",
+			type: "string",
+			description: "The **patch strategy** for this field: `\"replace\"` (default) or `\"merge\"`.",
+			values: ["replace", "merge"]
+		},
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const errors = [];
+			const definition = field.getDefinition();
+			if (!definition) return errors;
+			let wrongType = false;
+			if ((0, __atscript_core.isRef)(definition)) {
+				const def = doc.unwindType(definition.id, definition.chain)?.def;
+				if (!(0, __atscript_core.isStructure)(def) && !(0, __atscript_core.isInterface)(def) && !(0, __atscript_core.isArray)(def)) wrongType = true;
+			} else if (!(0, __atscript_core.isStructure)(definition) && !(0, __atscript_core.isInterface)(definition) && !(0, __atscript_core.isArray)(definition)) wrongType = true;
+			if (wrongType) errors.push({
+				message: `[mongo] type of object or array expected when using @mongo.patch.strategy`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) },
+	array: { uniqueItems: new __atscript_core.AnnotationSpec({
+		description: "Marks an **array field** as containing *globally unique items* when handling **patch `$insert` operations**.\n\n- Forces the patcher to use **set-semantics** (`$setUnion`) instead of a plain append, so duplicates are silently skipped.\n- Has **no effect** on `$replace`, `$update`, or `$remove`.\n- If the array’s element type already defines one or more `@meta.isKey` properties, *uniqueness is implied* and this annotation is unnecessary (but harmless).\n\n**Example:**\n```atscript\n@mongo.array.uniqueItems\ntags: string[]\n\n// Later in a patch payload …\n{\n  $insert: {\n    tags: [\"mongo\", \"mongo\"] // second \"mongo\" is ignored\n  }\n}\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const errors = [];
+			const definition = field.getDefinition();
+			if (!definition) return errors;
+			let wrongType = false;
+			if ((0, __atscript_core.isRef)(definition)) {
+				const def = doc.unwindType(definition.id, definition.chain)?.def;
+				if (!(0, __atscript_core.isArray)(def)) wrongType = true;
+			} else if (!(0, __atscript_core.isArray)(definition)) wrongType = true;
+			if (wrongType) errors.push({
+				message: `[mongo] type of array expected when using @mongo.array.uniqueItems`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) }
 } };
 
 //#endregion
@@ -277,6 +336,304 @@ const NoopLogger = {
 	debug: () => {}
 };
 
+//#endregion
+//#region packages/mongo/src/lib/validate-plugins.ts
+const validateMongoIdPlugin = (ctx, def, value) => {
+	if (ctx.path === "_id" && def.type.tags.has("objectId")) return ctx.validateAnnotatedType(def, value instanceof mongodb.ObjectId ? value.toString() : value);
+};
+const validateMongoUniqueArrayItemsPlugin = (ctx, def, value) => {
+	if (def.metadata.has("mongo.array.uniqueItems") && def.type.kind === "array") {
+		if (Array.isArray(value)) {
+			const separator = "▼↩";
+			const seen = new Set();
+			const keyProps = CollectionPatcher.getKeyProps(def);
+			for (const item of value) {
+				let key = "";
+				if (keyProps.size) for (const prop of keyProps) key += JSON.stringify(item[prop]) + separator;
+else key = JSON.stringify(item);
+				if (seen.has(key)) {
+					ctx.error(`Duplicate items are not allowed`);
+					return false;
+				}
+				seen.add(key);
+			}
+		}
+	}
+	return undefined;
+};
+
+//#endregion
+//#region packages/mongo/src/lib/collection-patcher.ts
+function _define_property$2(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+var CollectionPatcher = class CollectionPatcher {
+	/**
+	* Extract a set of *key properties* (annotated with `@meta.isKey`) from an
+	* array‐of‐objects type definition. These keys uniquely identify an element
+	* inside the array and are later used for `$update`, `$remove` and `$upsert`.
+	*
+	* @param def Atscript array type
+	* @returns Set of property names marked as keys; empty set if none
+	*/ static getKeyProps(def) {
+		if (def.type.of.type.kind === "object") {
+			const objType = def.type.of.type;
+			const keyProps = new Set();
+			for (const [key, val] of objType.props.entries()) if (val.metadata.get("meta.isKey")) keyProps.add(key);
+			return keyProps;
+		}
+		return new Set();
+	}
+	/**
+	* Build a runtime *Validator* that understands the extended patch payload.
+	*
+	*  * Adds per‑array *patch* wrappers (the `$replace`, `$insert`, … fields).
+	*  * Honors `mongo.patch.strategy === "merge"` metadata.
+	*
+	* @param collection Target collection wrapper
+	* @returns Atscript Validator
+	*/ static prepareValidator(collection) {
+		return collection.type.validator({
+			plugins: [validateMongoIdPlugin, validateMongoUniqueArrayItemsPlugin],
+			replace: (def, path) => {
+				if (path === "" && def.type.kind === "object") {
+					const obj = (0, __atscript_typescript.defineAnnotatedType)("object").copyMetadata(def.metadata);
+					for (const [prop, type] of def.type.props.entries()) obj.prop(prop, (0, __atscript_typescript.defineAnnotatedType)().refTo(type).copyMetadata(type.metadata).optional(prop !== "_id").$type);
+					return obj.$type;
+				}
+				if (def.type.kind === "array" && collection.flatMap.get(path)?.metadata.get("mongo.__topLevelArray") && !def.metadata.has("mongo.__patchArrayValue")) {
+					const defArray = def;
+					const mergeStrategy = defArray.metadata.get("mongo.patch.strategy") === "merge";
+					function getPatchType() {
+						const isPrimitive$1 = (0, __atscript_typescript.isAnnotatedTypeOfPrimitive)(defArray.type.of);
+						if (isPrimitive$1) return (0, __atscript_typescript.defineAnnotatedType)().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+						if (defArray.type.of.type.kind === "object") {
+							const objType = defArray.type.of.type;
+							const t = (0, __atscript_typescript.defineAnnotatedType)("object").copyMetadata(defArray.type.of.metadata);
+							const keyProps = CollectionPatcher.getKeyProps(defArray);
+							for (const [key, val] of objType.props.entries()) if (keyProps.size) if (keyProps.has(key)) t.prop(key, (0, __atscript_typescript.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).$type);
+else t.prop(key, (0, __atscript_typescript.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).optional().$type);
+else t.prop(key, (0, __atscript_typescript.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).optional(!!val.optional).$type);
+							return (0, __atscript_typescript.defineAnnotatedType)("array").of(t.$type).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+						}
+						return undefined;
+					}
+					const fullType = (0, __atscript_typescript.defineAnnotatedType)().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+					const patchType = getPatchType();
+					return patchType ? (0, __atscript_typescript.defineAnnotatedType)("object").prop("$replace", fullType).prop("$insert", fullType).prop("$upsert", fullType).prop("$update", mergeStrategy ? patchType : fullType).prop("$remove", patchType).optional().$type : (0, __atscript_typescript.defineAnnotatedType)("object").prop("$replace", fullType).prop("$insert", fullType).optional().$type;
+				}
+				return def;
+			},
+			partial: (def, path) => {
+				return path !== "" && def.metadata.get("mongo.patch.strategy") === "merge";
+			}
+		});
+	}
+	/**
+	* Entry point – walk the payload, build `filter`, `update` and `options`.
+	*
+	* @returns Helper object exposing both individual parts and
+	*          a `.toArgs()` convenience callback.
+	*/ preparePatch() {
+		this.filterObj = { _id: this.collection.prepareId(this.payload._id) };
+		this.flattenPayload(this.payload);
+		let updateFilter = this.updatePipeline;
+		return {
+			toArgs: () => [
+				this.filterObj,
+				updateFilter,
+				this.optionsObj
+			],
+			filter: this.filterObj,
+			updateFilter,
+			updateOptions: this.optionsObj
+		};
+	}
+	/**
+	* Helper – lazily create `$set` section and assign *key* → *value*.
+	*
+	* @param key Fully‑qualified dotted path
+	* @param val Value to be written
+	* @private
+	*/ _set(key, val) {
+		for (const pipe of this.updatePipeline) {
+			if (!pipe.$set) pipe.$set = {};
+			if (!pipe.$set[key]) {
+				pipe.$set[key] = val;
+				return;
+			}
+		}
+		this.updatePipeline.push({ $set: { [key]: val } });
+	}
+	/**
+	* Recursively walk through the patch *payload* and convert it into `$set`/…
+	* statements. Top‑level arrays are delegated to {@link parseArrayPatch}.
+	*
+	* @param payload Current payload chunk
+	* @param prefix  Dotted path accumulated so far
+	* @private
+	*/ flattenPayload(payload, prefix = "") {
+		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		for (const [_key, value] of Object.entries(payload)) {
+			const key = evalKey(_key);
+			const flatType = this.collection.flatMap.get(key);
+			const topLevelArray = flatType?.metadata?.get("mongo.__topLevelArray");
+			if (typeof value === "object" && topLevelArray) this.parseArrayPatch(key, value);
+else if (typeof value === "object" && this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge") this.flattenPayload(value, key);
+else if (key !== "_id") this._set(key, value);
+		}
+		return this.updatePipeline;
+	}
+	/**
+	* Dispatch a *single* array patch. Exactly one of `$replace`, `$insert`,
+	* `$upsert`, `$update`, `$remove` must be present – otherwise we throw.
+	*
+	* @param key   Dotted path to the array field
+	* @param value Payload slice for that field
+	* @private
+	*/ parseArrayPatch(key, value) {
+		const flatType = this.collection.flatMap.get(key);
+		const toRemove = value.$remove;
+		const toReplace = value.$replace;
+		const toInsert = value.$insert;
+		const toUpsert = value.$upsert;
+		const toUpdate = value.$update;
+		const keyProps = flatType?.type.kind === "array" ? CollectionPatcher.getKeyProps(flatType) : new Set();
+		this._remove(key, toRemove, keyProps);
+		this._replace(key, toReplace);
+		this._insert(key, toInsert, keyProps);
+		this._upsert(key, toUpsert, keyProps);
+		this._update(key, toUpdate, keyProps);
+	}
+	/**
+	* Build an *aggregation‐expression* that checks equality by **all** keys in
+	* `keys`.  Example output for keys `["id", "lang"]` and bases `a`, `b`:
+	* ```json
+	* { "$and": [ { "$eq": ["$$a.id", "$$b.id"] }, { "$eq": ["$$a.lang", "$$b.lang"] } ] }
+	* ```
+	*
+	* @param keys  Ordered list of key property names
+	* @param left  Base token for *left* expression (e.g. `"$$el"`)
+	* @param right Base token for *right* expression (e.g. `"$$this"`)
+	*/ _keysEqual(keys, left, right) {
+		return keys.map((k) => ({ $eq: [`${left}.${k}`, `${right}.${k}`] })).reduce((acc, cur) => acc ? { $and: [acc, cur] } : cur);
+	}
+	/**
+	* `$replace` – overwrite the entire array with `input`.
+	*
+	* @param key   Dotted path to the array
+	* @param input New array value (may be `undefined`)
+	* @private
+	*/ _replace(key, input) {
+		if (input) this._set(key, input);
+	}
+	/**
+	* `$insert`
+	* - plain append      → $concatArrays
+	* - unique / keyed    → delegate to _upsert (insert-or-update)
+	*/ _insert(key, input, keyProps) {
+		if (!input?.length) return;
+		const uniqueItems = this.collection.flatMap.get(key)?.metadata?.has("mongo.array.uniqueItems");
+		if (uniqueItems || keyProps.size > 0) this._upsert(key, input, keyProps);
+else this._set(key, { $concatArrays: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$upsert`
+	* - keyed  → remove existing matching by key(s) then append candidate
+	* - unique → $setUnion (deep equality)
+	*/ _upsert(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const keys = [...keyProps];
+			this._set(key, { $reduce: {
+				input,
+				initialValue: { $ifNull: [`$${key}`, []] },
+				in: { $let: {
+					vars: {
+						acc: "$$value",
+						cand: "$$this"
+					},
+					in: { $concatArrays: [{ $filter: {
+						input: "$$acc",
+						as: "el",
+						cond: { $not: this._keysEqual(keys, "$$el", "$$cand") }
+					} }, ["$$cand"]] }
+				} }
+			} });
+			return;
+		}
+		this._set(key, { $setUnion: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$update`
+	* - keyed       → map array and merge / replace matching element(s)
+	* - non-keyed   → behave like `$addToSet` (insert only when not present)
+	*/ _update(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const mergeStrategy = this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge";
+			const keys = [...keyProps];
+			this._set(key, { $reduce: {
+				input,
+				initialValue: { $ifNull: [`$${key}`, []] },
+				in: { $map: {
+					input: "$$value",
+					as: "el",
+					in: { $cond: [
+						this._keysEqual(keys, "$$el", "$$this"),
+						mergeStrategy ? { $mergeObjects: ["$$el", "$$this"] } : "$$this",
+						"$$el"
+					] }
+				} }
+			} });
+		} else this._set(key, { $setUnion: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$remove`
+	* - keyed     → filter out any element whose key set matches a payload item
+	* - non-keyed → deep equality remove (`$setDifference`)
+	*/ _remove(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const keys = [...keyProps];
+			this._set(key, { $let: {
+				vars: { rem: input },
+				in: { $filter: {
+					input: { $ifNull: [`$${key}`, []] },
+					as: "el",
+					cond: { $not: { $anyElementTrue: { $map: {
+						input: "$$rem",
+						as: "r",
+						in: this._keysEqual(keys, "$$el", "$$r")
+					} } } }
+				} }
+			} });
+		} else this._set(key, { $setDifference: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	constructor(collection, payload) {
+		_define_property$2(this, "collection", void 0);
+		_define_property$2(this, "payload", void 0);
+		/**
+		* Internal accumulator: filter passed to `updateOne()`.
+		* Filled only with the `_id` field right now.
+		*/ _define_property$2(this, "filterObj", void 0);
+		/** MongoDB *update* document being built. */ _define_property$2(this, "updatePipeline", void 0);
+		/** Additional *options* (mainly `arrayFilters`). */ _define_property$2(this, "optionsObj", void 0);
+		this.collection = collection;
+		this.payload = payload;
+		this.filterObj = {};
+		this.updatePipeline = [];
+		this.optionsObj = {};
+	}
+};
+
 //#endregion
 //#region packages/mongo/src/lib/as-collection.ts
 function _define_property$1(obj, key, value) {
@@ -289,9 +646,14 @@ function _define_property$1(obj, key, value) {
 else obj[key] = value;
 	return obj;
 }
-const INDEX_PREFIX = "anscript__";
+const INDEX_PREFIX = "atscript__";
 const DEFAULT_INDEX_NAME = "DEFAULT";
-function indexKey(type, name) {
+/**
+* Generates a key for mongo index
+* @param type index type
+* @param name index name
+* @returns index key
+*/ function indexKey(type, name) {
 	const cleanName = name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 127 - INDEX_PREFIX.length - type.length - 2);
 	return `${INDEX_PREFIX}${type}__${cleanName}`;
 }
@@ -303,6 +665,64 @@ var AsCollection = class {
 		const exists = await this.exists();
 		if (!exists) await this.asMongo.db.createCollection(this.name, { comment: "Created by Atscript Mongo Collection" });
 	}
+	/**
+	* Returns the a type definition of the "_id" prop.
+	*/ get idType() {
+		const idProp = this.type.type.props.get("_id");
+		const idTags = idProp?.type.tags;
+		if (idTags?.has("objectId") && idTags?.has("mongo")) return "objectId";
+		if (idProp?.type.kind === "") return idProp.type.designType;
+		return "objectId";
+	}
+	/**
+	* Transforms an "_id" value to the expected type (`ObjectId`, `number`, or `string`).
+	* Assumes input has already been validated.
+	*
+	* @param {string | number | ObjectId} id - The validated ID.
+	* @returns {string | number | ObjectId} - The transformed ID.
+	* @throws {Error} If the `_id` type is unknown.
+	*/ prepareId(id) {
+		switch (this.idType) {
+			case "objectId": return id instanceof mongodb.ObjectId ? id : new mongodb.ObjectId(id);
+			case "number": return Number(id);
+			case "string": return String(id);
+			default: throw new Error("Unknown \"_id\" type");
+		}
+	}
+	/**
+	* Retrieves a validator for a given purpose. If the validator is not already cached,
+	* it creates and stores a new one based on the purpose.
+	*
+	* @param {TValidatorPurpose} purpose - The validation purpose (`input`, `update`, `patch`).
+	* @returns {Validator} The corresponding validator instance.
+	* @throws {Error} If an unknown purpose is provided.
+	*/ getValidator(purpose) {
+		if (!this.validators.has(purpose)) switch (purpose) {
+			case "insert": {
+				this.validators.set(purpose, this.type.validator({
+					plugins: [validateMongoIdPlugin, validateMongoUniqueArrayItemsPlugin],
+					replace(type, path) {
+						if (path === "_id" && type.type.tags.has("objectId")) return {
+							...type,
+							optional: true
+						};
+						return type;
+					}
+				}));
+				break;
+			}
+			case "update": {
+				this.validators.set(purpose, this.type.validator({ plugins: [validateMongoIdPlugin] }));
+				break;
+			}
+			case "patch": {
+				this.validators.set(purpose, CollectionPatcher.prepareValidator(this));
+				break;
+			}
+			default: throw new Error(`Unknown validator purpose: ${purpose}`);
+		}
+		return this.validators.get(purpose);
+	}
 	get type() {
 		return this._type;
 	}
@@ -347,18 +767,24 @@ else {
 			if (analyzer) index.definition.mappings.fields[fieldName].analyzer = analyzer;
 		}
 	}
-	_flattenType(type, prefix) {
+	_flattenType(type, prefix = "", inComplexTypeOrArray = false) {
 		switch (type.type.kind) {
 			case "object":
+				this._flatMap?.set(prefix || "", type);
 				const items = Array.from(type.type.props.entries());
-				for (const [key, value] of items) this._flattenType(value, prefix ? `${prefix}.${key}` : key);
+				for (const [key, value] of items) this._flattenType(value, prefix ? `${prefix}.${key}` : key, inComplexTypeOrArray);
 				break;
 			case "array":
-				this._flattenType(type.type.of, prefix);
+				let typeArray = type;
+				if (!inComplexTypeOrArray) {
+					typeArray = (0, __atscript_typescript.defineAnnotatedType)().refTo(type).copyMetadata(type.metadata).$type;
+					typeArray.metadata.set("mongo.__topLevelArray", true);
+				}
+				this._flatMap?.set(prefix || "", typeArray);
 				break;
 			case "intersection":
 			case "tuple":
-			case "union": for (const item of type.type.items) this._flattenType(item, prefix);
+			case "union": for (const item of type.type.items) this._flattenType(item, prefix, true);
 			default:
 				this._flatMap?.set(prefix || "", type);
 				break;
@@ -379,6 +805,9 @@ else {
 			text: { fuzzy: { maxEdits: textSearch.fuzzy || 0 } }
 		});
 	}
+	get uniqueProps() {
+		return this._uniqueProps;
+	}
 	_finalizeIndexesForCollection() {
 		for (const [key, value] of Array.from(this._vectorFilters.entries())) {
 			const index = this._indexes.get(key);
@@ -387,6 +816,10 @@ else {
 				path: value
 			});
 		}
+		for (const [, value] of Array.from(this._indexes.entries())) if (value.type === "unique") {
+			const keys = Object.keys(value.fields);
+			if (keys.length === 1) this._uniqueProps.add(keys[0]);
+		}
 	}
 	_prepareIndexesForField(fieldName, metadata) {
 		for (const index of metadata.get("mongo.index.plain") || []) this._addIndexField("plain", index === true ? fieldName : index, fieldName);
@@ -502,20 +935,80 @@ else toUpdate.add(remote.name);
 			default:
 		}
 	}
+	insert(payload, options) {
+		const toInsert = this.prepareInsert(payload);
+		return Array.isArray(toInsert) ? this.collection.insertMany(toInsert, options) : this.collection.insertOne(toInsert, options);
+	}
+	replace(payload, options) {
+		const [filter, replace, opts] = this.prepareReplace(payload).toArgs();
+		return this.collection.replaceOne(filter, replace, {
+			...opts,
+			...options
+		});
+	}
+	update(payload, options) {
+		const [filter, update, opts] = this.prepareUpdate(payload).toArgs();
+		return this.collection.updateOne(filter, update, {
+			...opts,
+			...options
+		});
+	}
+	prepareInsert(payload) {
+		const v = this.getValidator("insert");
+		const arr = Array.isArray(payload) ? payload : [payload];
+		const prepared = [];
+		for (const item of arr) if (v.validate(item)) {
+			const data = { ...item };
+			if (data._id) data._id = this.prepareId(data._id);
+else if (this.idType !== "objectId") throw new Error("Missing \"_id\" field");
+			prepared.push(data);
+		} else throw new Error("Invalid payload");
+		return prepared.length === 1 ? prepared[0] : prepared;
+	}
+	prepareReplace(payload) {
+		const v = this.getValidator("update");
+		if (v.validate(payload)) {
+			const _id = this.prepareId(payload._id);
+			const data = {
+				...payload,
+				_id
+			};
+			return {
+				toArgs: () => [
+					{ _id },
+					data,
+					{}
+				],
+				filter: { _id },
+				updateFilter: data,
+				updateOptions: {}
+			};
+		}
+		throw new Error("Invalid payload");
+	}
+	prepareUpdate(payload) {
+		const v = this.getValidator("patch");
+		if (v.validate(payload)) return new CollectionPatcher(this, payload).preparePatch();
+		throw new Error("Invalid payload");
+	}
 	constructor(asMongo, _type, logger = NoopLogger) {
 		_define_property$1(this, "asMongo", void 0);
 		_define_property$1(this, "_type", void 0);
 		_define_property$1(this, "logger", void 0);
 		_define_property$1(this, "name", void 0);
 		_define_property$1(this, "collection", void 0);
+		_define_property$1(this, "validators", void 0);
 		_define_property$1(this, "_indexes", void 0);
 		_define_property$1(this, "_vectorFilters", void 0);
 		_define_property$1(this, "_flatMap", void 0);
+		_define_property$1(this, "_uniqueProps", void 0);
 		this.asMongo = asMongo;
 		this._type = _type;
 		this.logger = logger;
+		this.validators = new Map();
 		this._indexes = new Map();
 		this._vectorFilters = new Map();
+		this._uniqueProps = new Set();
 		if (!(0, __atscript_typescript.isAnnotatedType)(_type)) throw new Error("Atscript Annotated Type expected");
 		const name = _type.metadata.get("mongo.collection");
 		if (!name) throw new Error("@mongo.collection annotation expected with collection name");

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { TAtscriptPlugin } from '@atscript/core';
-import { TAtscriptAnnotatedTypeConstructor, TAtscriptAnnotatedType, TAtscriptTypeObject, TMetadataMap } from '@atscript/typescript';
 import * as mongodb from 'mongodb';
-import { MongoClient, Collection } from 'mongodb';
+import { MongoClient, Collection, ObjectId, InsertOneOptions, ReplaceOptions, UpdateOptions, OptionalUnlessRequiredId, Filter, WithoutId } from 'mongodb';
+import { TAtscriptAnnotatedTypeConstructor, TAtscriptAnnotatedType, TAtscriptTypeObject, TMetadataMap } from '@atscript/typescript';
 
 declare const MongoPlugin: () => TAtscriptPlugin;
 
@@ -34,30 +34,88 @@ type TSearchIndex = {
     definition: TMongoSearchIndexDefinition;
 };
 type TIndex = TPlainIndex | TSearchIndex;
+type TValidatorPurpose = 'insert' | 'update' | 'patch';
 declare class AsCollection<T extends TAtscriptAnnotatedTypeConstructor> {
     protected readonly asMongo: AsMongo;
     protected readonly _type: T;
     protected readonly logger: TGenericLogger;
     readonly name: string;
     readonly collection: Collection<InstanceType<T>>;
+    protected readonly validators: Map<TValidatorPurpose, Validator<T>>;
+    protected _indexes: Map<string, TIndex>;
+    protected _vectorFilters: Map<string, string>;
+    protected _flatMap?: Map<string, TAtscriptAnnotatedType>;
     constructor(asMongo: AsMongo, _type: T, logger?: TGenericLogger);
     exists(): Promise<boolean>;
     ensureExists(): Promise<void>;
+    /**
+     * Returns the a type definition of the "_id" prop.
+     */
+    get idType(): 'string' | 'number' | 'objectId';
+    /**
+     * Transforms an "_id" value to the expected type (`ObjectId`, `number`, or `string`).
+     * Assumes input has already been validated.
+     *
+     * @param {string | number | ObjectId} id - The validated ID.
+     * @returns {string | number | ObjectId} - The transformed ID.
+     * @throws {Error} If the `_id` type is unknown.
+     */
+    prepareId<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+    /**
+     * Retrieves a validator for a given purpose. If the validator is not already cached,
+     * it creates and stores a new one based on the purpose.
+     *
+     * @param {TValidatorPurpose} purpose - The validation purpose (`input`, `update`, `patch`).
+     * @returns {Validator} The corresponding validator instance.
+     * @throws {Error} If an unknown purpose is provided.
+     */
+    getValidator(purpose: TValidatorPurpose): any;
     get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
-    protected _indexes: Map<string, TIndex>;
-    protected _vectorFilters: Map<string, string>;
     get indexes(): Map<string, TIndex>;
     protected _addIndexField(type: TPlainIndex['type'], name: string, field: string, weight?: number): void;
     protected _setSearchIndex(type: TSearchIndex['type'], name: string | undefined, definition: TMongoSearchIndexDefinition): void;
     protected _addFieldToSearchIndex(type: TSearchIndex['type'], _name: string | undefined, fieldName: string, analyzer?: string): void;
-    protected _flatMap?: Map<string, TAtscriptAnnotatedType>;
-    protected _flattenType(type: TAtscriptAnnotatedType, prefix?: string): void;
+    protected _flattenType(type: TAtscriptAnnotatedType, prefix?: string, inComplexTypeOrArray?: boolean): void;
     protected _prepareIndexesForCollection(): void;
+    protected _uniqueProps: Set<string>;
+    get uniqueProps(): Set<string>;
     protected _finalizeIndexesForCollection(): void;
     protected _prepareIndexesForField(fieldName: string, metadata: TMetadataMap<AtscriptMetadata>): void;
     protected _flatten(): void;
-    get flatMap(): Map<string, TAtscriptAnnotatedType> | undefined;
+    get flatMap(): Map<string, TAtscriptAnnotatedType>;
     syncIndexes(): Promise<void>;
+    insert(payload: (Omit<InstanceType<T>, '_id'> & {
+        _id?: InstanceType<T>['_id'] | ObjectId;
+    }) | (Omit<InstanceType<T>, '_id'> & {
+        _id?: InstanceType<T>['_id'] | ObjectId;
+    })[], options?: InsertOneOptions): Promise<mongodb.InsertManyResult<InstanceType<T>>> | Promise<mongodb.InsertOneResult<InstanceType<T>>>;
+    replace(payload: Omit<InstanceType<T>, '_id'> & {
+        _id: InstanceType<T>['_id'] | ObjectId;
+    }, options?: ReplaceOptions): Promise<mongodb.UpdateResult<InstanceType<T>>>;
+    update(payload: AsMongoPatch<Omit<InstanceType<T>, '_id'>> & {
+        _id: InstanceType<T>['_id'] | ObjectId;
+    }, options?: UpdateOptions): Promise<mongodb.UpdateResult<InstanceType<T>>>;
+    prepareInsert(payload: (Omit<InstanceType<T>, '_id'> & {
+        _id?: InstanceType<T>['_id'] | ObjectId;
+    }) | (Omit<InstanceType<T>, '_id'> & {
+        _id?: InstanceType<T>['_id'] | ObjectId;
+    })[]): OptionalUnlessRequiredId<InstanceType<T>> | OptionalUnlessRequiredId<InstanceType<T>>[];
+    prepareReplace(payload: Omit<InstanceType<T>, '_id'> & {
+        _id: InstanceType<T>['_id'] | ObjectId;
+    }): {
+        toArgs: () => [Filter<InstanceType<T>>, WithoutId<InstanceType<T>>, ReplaceOptions];
+        filter: Filter<InstanceType<T>>;
+        updateFilter: WithoutId<InstanceType<T>>;
+        updateOptions: ReplaceOptions;
+    };
+    prepareUpdate(payload: AsMongoPatch<Omit<InstanceType<T>, '_id'>> & {
+        _id: InstanceType<T>['_id'] | ObjectId;
+    }): {
+        toArgs: () => [Filter<InstanceType<T>>, mongodb.Document[] | mongodb.UpdateFilter<InstanceType<T>>, UpdateOptions];
+        filter: Filter<InstanceType<T>>;
+        updateFilter: mongodb.Document[];
+        updateOptions: UpdateOptions;
+    };
 }
 type TVectorSimilarity = 'cosine' | 'euclidean' | 'dotProduct';
 type TMongoSearchIndexDefinition = {
@@ -81,5 +139,26 @@ type TMongoSearchIndexDefinition = {
         };
     };
 };
+type TArrayPatch<A extends readonly unknown[]> = {
+    $replace?: A;
+    $insert?: A;
+    $upsert?: A;
+    $update?: Partial<TArrayElement<A>>[];
+    $remove?: Partial<TArrayElement<A>>[];
+};
+type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
+/**
+ * AsMongoPatch<T>
+ * ─────────────────
+ * - For every key K in T:
+ *     • if T[K] is `X[]`, rewrite it to `TArrayPatch<X[]>`
+ *     • otherwise omit the key (feel free to keep it if you want)
+ *
+ * The result is an *optional* property bag that matches a patch payload
+ * for array fields only.
+ */
+type AsMongoPatch<T> = {
+    [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]>;
+};
 
 export { AsCollection, AsMongo, MongoPlugin };

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { AnnotationSpec, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
-import { isAnnotatedType } from "@atscript/typescript";
-import { MongoClient } from "mongodb";
+import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive } from "@atscript/typescript";
+import { MongoClient, ObjectId } from "mongodb";
 
 //#region packages/mongo/src/plugin/primitives.ts
 const primitives = { mongo: { extensions: {
@@ -82,6 +82,15 @@ const annotations = { mongo: {
 			});
 		}
 	}),
+	autoIndexes: new AnnotationSpec({
+		description: "Switch on/off the automatic index creation. Works with as-mongo moost controller.\n\nDefault: true",
+		nodeType: ["interface"],
+		argument: {
+			name: "type",
+			type: "boolean",
+			description: "On/Off the automatic index creation"
+		}
+	}),
 	index: {
 		plain: new AnnotationSpec({
 			description: "Defines a **standard MongoDB index** on a field.\n\n- Improves query performance on indexed fields.\n- Can be used for **single-field** or **compound** indexes.\n\n**Example:**\n```atscript\n@mongo.index.plain \"departmentIndex\"\ndepartment: string\n```\n",
@@ -226,7 +235,57 @@ const annotations = { mongo: {
 				description: "The **name of the vector search index** this field should be used as a filter for."
 			}]
 		})
-	}
+	},
+	patch: { strategy: new AnnotationSpec({
+		description: "Defines the **patching strategy** for updating MongoDB documents.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@mongo.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "strategy",
+			type: "string",
+			description: "The **patch strategy** for this field: `\"replace\"` (default) or `\"merge\"`.",
+			values: ["replace", "merge"]
+		},
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const errors = [];
+			const definition = field.getDefinition();
+			if (!definition) return errors;
+			let wrongType = false;
+			if (isRef(definition)) {
+				const def = doc.unwindType(definition.id, definition.chain)?.def;
+				if (!isStructure(def) && !isInterface(def) && !isArray(def)) wrongType = true;
+			} else if (!isStructure(definition) && !isInterface(definition) && !isArray(definition)) wrongType = true;
+			if (wrongType) errors.push({
+				message: `[mongo] type of object or array expected when using @mongo.patch.strategy`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) },
+	array: { uniqueItems: new AnnotationSpec({
+		description: "Marks an **array field** as containing *globally unique items* when handling **patch `$insert` operations**.\n\n- Forces the patcher to use **set-semantics** (`$setUnion`) instead of a plain append, so duplicates are silently skipped.\n- Has **no effect** on `$replace`, `$update`, or `$remove`.\n- If the array’s element type already defines one or more `@meta.isKey` properties, *uniqueness is implied* and this annotation is unnecessary (but harmless).\n\n**Example:**\n```atscript\n@mongo.array.uniqueItems\ntags: string[]\n\n// Later in a patch payload …\n{\n  $insert: {\n    tags: [\"mongo\", \"mongo\"] // second \"mongo\" is ignored\n  }\n}\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		validate(token, args, doc) {
+			const field = token.parentNode;
+			const errors = [];
+			const definition = field.getDefinition();
+			if (!definition) return errors;
+			let wrongType = false;
+			if (isRef(definition)) {
+				const def = doc.unwindType(definition.id, definition.chain)?.def;
+				if (!isArray(def)) wrongType = true;
+			} else if (!isArray(definition)) wrongType = true;
+			if (wrongType) errors.push({
+				message: `[mongo] type of array expected when using @mongo.array.uniqueItems`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}) }
 } };
 
 //#endregion
@@ -253,6 +312,304 @@ const NoopLogger = {
 	debug: () => {}
 };
 
+//#endregion
+//#region packages/mongo/src/lib/validate-plugins.ts
+const validateMongoIdPlugin = (ctx, def, value) => {
+	if (ctx.path === "_id" && def.type.tags.has("objectId")) return ctx.validateAnnotatedType(def, value instanceof ObjectId ? value.toString() : value);
+};
+const validateMongoUniqueArrayItemsPlugin = (ctx, def, value) => {
+	if (def.metadata.has("mongo.array.uniqueItems") && def.type.kind === "array") {
+		if (Array.isArray(value)) {
+			const separator = "▼↩";
+			const seen = new Set();
+			const keyProps = CollectionPatcher.getKeyProps(def);
+			for (const item of value) {
+				let key = "";
+				if (keyProps.size) for (const prop of keyProps) key += JSON.stringify(item[prop]) + separator;
+else key = JSON.stringify(item);
+				if (seen.has(key)) {
+					ctx.error(`Duplicate items are not allowed`);
+					return false;
+				}
+				seen.add(key);
+			}
+		}
+	}
+	return undefined;
+};
+
+//#endregion
+//#region packages/mongo/src/lib/collection-patcher.ts
+function _define_property$2(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+var CollectionPatcher = class CollectionPatcher {
+	/**
+	* Extract a set of *key properties* (annotated with `@meta.isKey`) from an
+	* array‐of‐objects type definition. These keys uniquely identify an element
+	* inside the array and are later used for `$update`, `$remove` and `$upsert`.
+	*
+	* @param def Atscript array type
+	* @returns Set of property names marked as keys; empty set if none
+	*/ static getKeyProps(def) {
+		if (def.type.of.type.kind === "object") {
+			const objType = def.type.of.type;
+			const keyProps = new Set();
+			for (const [key, val] of objType.props.entries()) if (val.metadata.get("meta.isKey")) keyProps.add(key);
+			return keyProps;
+		}
+		return new Set();
+	}
+	/**
+	* Build a runtime *Validator* that understands the extended patch payload.
+	*
+	*  * Adds per‑array *patch* wrappers (the `$replace`, `$insert`, … fields).
+	*  * Honors `mongo.patch.strategy === "merge"` metadata.
+	*
+	* @param collection Target collection wrapper
+	* @returns Atscript Validator
+	*/ static prepareValidator(collection) {
+		return collection.type.validator({
+			plugins: [validateMongoIdPlugin, validateMongoUniqueArrayItemsPlugin],
+			replace: (def, path) => {
+				if (path === "" && def.type.kind === "object") {
+					const obj = defineAnnotatedType("object").copyMetadata(def.metadata);
+					for (const [prop, type] of def.type.props.entries()) obj.prop(prop, defineAnnotatedType().refTo(type).copyMetadata(type.metadata).optional(prop !== "_id").$type);
+					return obj.$type;
+				}
+				if (def.type.kind === "array" && collection.flatMap.get(path)?.metadata.get("mongo.__topLevelArray") && !def.metadata.has("mongo.__patchArrayValue")) {
+					const defArray = def;
+					const mergeStrategy = defArray.metadata.get("mongo.patch.strategy") === "merge";
+					function getPatchType() {
+						const isPrimitive$1 = isAnnotatedTypeOfPrimitive(defArray.type.of);
+						if (isPrimitive$1) return defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+						if (defArray.type.of.type.kind === "object") {
+							const objType = defArray.type.of.type;
+							const t = defineAnnotatedType("object").copyMetadata(defArray.type.of.metadata);
+							const keyProps = CollectionPatcher.getKeyProps(defArray);
+							for (const [key, val] of objType.props.entries()) if (keyProps.size) if (keyProps.has(key)) t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).$type);
+else t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).optional().$type);
+else t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).optional(!!val.optional).$type);
+							return defineAnnotatedType("array").of(t.$type).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+						}
+						return undefined;
+					}
+					const fullType = defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+					const patchType = getPatchType();
+					return patchType ? defineAnnotatedType("object").prop("$replace", fullType).prop("$insert", fullType).prop("$upsert", fullType).prop("$update", mergeStrategy ? patchType : fullType).prop("$remove", patchType).optional().$type : defineAnnotatedType("object").prop("$replace", fullType).prop("$insert", fullType).optional().$type;
+				}
+				return def;
+			},
+			partial: (def, path) => {
+				return path !== "" && def.metadata.get("mongo.patch.strategy") === "merge";
+			}
+		});
+	}
+	/**
+	* Entry point – walk the payload, build `filter`, `update` and `options`.
+	*
+	* @returns Helper object exposing both individual parts and
+	*          a `.toArgs()` convenience callback.
+	*/ preparePatch() {
+		this.filterObj = { _id: this.collection.prepareId(this.payload._id) };
+		this.flattenPayload(this.payload);
+		let updateFilter = this.updatePipeline;
+		return {
+			toArgs: () => [
+				this.filterObj,
+				updateFilter,
+				this.optionsObj
+			],
+			filter: this.filterObj,
+			updateFilter,
+			updateOptions: this.optionsObj
+		};
+	}
+	/**
+	* Helper – lazily create `$set` section and assign *key* → *value*.
+	*
+	* @param key Fully‑qualified dotted path
+	* @param val Value to be written
+	* @private
+	*/ _set(key, val) {
+		for (const pipe of this.updatePipeline) {
+			if (!pipe.$set) pipe.$set = {};
+			if (!pipe.$set[key]) {
+				pipe.$set[key] = val;
+				return;
+			}
+		}
+		this.updatePipeline.push({ $set: { [key]: val } });
+	}
+	/**
+	* Recursively walk through the patch *payload* and convert it into `$set`/…
+	* statements. Top‑level arrays are delegated to {@link parseArrayPatch}.
+	*
+	* @param payload Current payload chunk
+	* @param prefix  Dotted path accumulated so far
+	* @private
+	*/ flattenPayload(payload, prefix = "") {
+		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		for (const [_key, value] of Object.entries(payload)) {
+			const key = evalKey(_key);
+			const flatType = this.collection.flatMap.get(key);
+			const topLevelArray = flatType?.metadata?.get("mongo.__topLevelArray");
+			if (typeof value === "object" && topLevelArray) this.parseArrayPatch(key, value);
+else if (typeof value === "object" && this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge") this.flattenPayload(value, key);
+else if (key !== "_id") this._set(key, value);
+		}
+		return this.updatePipeline;
+	}
+	/**
+	* Dispatch a *single* array patch. Exactly one of `$replace`, `$insert`,
+	* `$upsert`, `$update`, `$remove` must be present – otherwise we throw.
+	*
+	* @param key   Dotted path to the array field
+	* @param value Payload slice for that field
+	* @private
+	*/ parseArrayPatch(key, value) {
+		const flatType = this.collection.flatMap.get(key);
+		const toRemove = value.$remove;
+		const toReplace = value.$replace;
+		const toInsert = value.$insert;
+		const toUpsert = value.$upsert;
+		const toUpdate = value.$update;
+		const keyProps = flatType?.type.kind === "array" ? CollectionPatcher.getKeyProps(flatType) : new Set();
+		this._remove(key, toRemove, keyProps);
+		this._replace(key, toReplace);
+		this._insert(key, toInsert, keyProps);
+		this._upsert(key, toUpsert, keyProps);
+		this._update(key, toUpdate, keyProps);
+	}
+	/**
+	* Build an *aggregation‐expression* that checks equality by **all** keys in
+	* `keys`.  Example output for keys `["id", "lang"]` and bases `a`, `b`:
+	* ```json
+	* { "$and": [ { "$eq": ["$$a.id", "$$b.id"] }, { "$eq": ["$$a.lang", "$$b.lang"] } ] }
+	* ```
+	*
+	* @param keys  Ordered list of key property names
+	* @param left  Base token for *left* expression (e.g. `"$$el"`)
+	* @param right Base token for *right* expression (e.g. `"$$this"`)
+	*/ _keysEqual(keys, left, right) {
+		return keys.map((k) => ({ $eq: [`${left}.${k}`, `${right}.${k}`] })).reduce((acc, cur) => acc ? { $and: [acc, cur] } : cur);
+	}
+	/**
+	* `$replace` – overwrite the entire array with `input`.
+	*
+	* @param key   Dotted path to the array
+	* @param input New array value (may be `undefined`)
+	* @private
+	*/ _replace(key, input) {
+		if (input) this._set(key, input);
+	}
+	/**
+	* `$insert`
+	* - plain append      → $concatArrays
+	* - unique / keyed    → delegate to _upsert (insert-or-update)
+	*/ _insert(key, input, keyProps) {
+		if (!input?.length) return;
+		const uniqueItems = this.collection.flatMap.get(key)?.metadata?.has("mongo.array.uniqueItems");
+		if (uniqueItems || keyProps.size > 0) this._upsert(key, input, keyProps);
+else this._set(key, { $concatArrays: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$upsert`
+	* - keyed  → remove existing matching by key(s) then append candidate
+	* - unique → $setUnion (deep equality)
+	*/ _upsert(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const keys = [...keyProps];
+			this._set(key, { $reduce: {
+				input,
+				initialValue: { $ifNull: [`$${key}`, []] },
+				in: { $let: {
+					vars: {
+						acc: "$$value",
+						cand: "$$this"
+					},
+					in: { $concatArrays: [{ $filter: {
+						input: "$$acc",
+						as: "el",
+						cond: { $not: this._keysEqual(keys, "$$el", "$$cand") }
+					} }, ["$$cand"]] }
+				} }
+			} });
+			return;
+		}
+		this._set(key, { $setUnion: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$update`
+	* - keyed       → map array and merge / replace matching element(s)
+	* - non-keyed   → behave like `$addToSet` (insert only when not present)
+	*/ _update(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const mergeStrategy = this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge";
+			const keys = [...keyProps];
+			this._set(key, { $reduce: {
+				input,
+				initialValue: { $ifNull: [`$${key}`, []] },
+				in: { $map: {
+					input: "$$value",
+					as: "el",
+					in: { $cond: [
+						this._keysEqual(keys, "$$el", "$$this"),
+						mergeStrategy ? { $mergeObjects: ["$$el", "$$this"] } : "$$this",
+						"$$el"
+					] }
+				} }
+			} });
+		} else this._set(key, { $setUnion: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	/**
+	* `$remove`
+	* - keyed     → filter out any element whose key set matches a payload item
+	* - non-keyed → deep equality remove (`$setDifference`)
+	*/ _remove(key, input, keyProps) {
+		if (!input?.length) return;
+		if (keyProps.size) {
+			const keys = [...keyProps];
+			this._set(key, { $let: {
+				vars: { rem: input },
+				in: { $filter: {
+					input: { $ifNull: [`$${key}`, []] },
+					as: "el",
+					cond: { $not: { $anyElementTrue: { $map: {
+						input: "$$rem",
+						as: "r",
+						in: this._keysEqual(keys, "$$el", "$$r")
+					} } } }
+				} }
+			} });
+		} else this._set(key, { $setDifference: [{ $ifNull: [`$${key}`, []] }, input] });
+	}
+	constructor(collection, payload) {
+		_define_property$2(this, "collection", void 0);
+		_define_property$2(this, "payload", void 0);
+		/**
+		* Internal accumulator: filter passed to `updateOne()`.
+		* Filled only with the `_id` field right now.
+		*/ _define_property$2(this, "filterObj", void 0);
+		/** MongoDB *update* document being built. */ _define_property$2(this, "updatePipeline", void 0);
+		/** Additional *options* (mainly `arrayFilters`). */ _define_property$2(this, "optionsObj", void 0);
+		this.collection = collection;
+		this.payload = payload;
+		this.filterObj = {};
+		this.updatePipeline = [];
+		this.optionsObj = {};
+	}
+};
+
 //#endregion
 //#region packages/mongo/src/lib/as-collection.ts
 function _define_property$1(obj, key, value) {
@@ -265,9 +622,14 @@ function _define_property$1(obj, key, value) {
 else obj[key] = value;
 	return obj;
 }
-const INDEX_PREFIX = "anscript__";
+const INDEX_PREFIX = "atscript__";
 const DEFAULT_INDEX_NAME = "DEFAULT";
-function indexKey(type, name) {
+/**
+* Generates a key for mongo index
+* @param type index type
+* @param name index name
+* @returns index key
+*/ function indexKey(type, name) {
 	const cleanName = name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 127 - INDEX_PREFIX.length - type.length - 2);
 	return `${INDEX_PREFIX}${type}__${cleanName}`;
 }
@@ -279,6 +641,64 @@ var AsCollection = class {
 		const exists = await this.exists();
 		if (!exists) await this.asMongo.db.createCollection(this.name, { comment: "Created by Atscript Mongo Collection" });
 	}
+	/**
+	* Returns the a type definition of the "_id" prop.
+	*/ get idType() {
+		const idProp = this.type.type.props.get("_id");
+		const idTags = idProp?.type.tags;
+		if (idTags?.has("objectId") && idTags?.has("mongo")) return "objectId";
+		if (idProp?.type.kind === "") return idProp.type.designType;
+		return "objectId";
+	}
+	/**
+	* Transforms an "_id" value to the expected type (`ObjectId`, `number`, or `string`).
+	* Assumes input has already been validated.
+	*
+	* @param {string | number | ObjectId} id - The validated ID.
+	* @returns {string | number | ObjectId} - The transformed ID.
+	* @throws {Error} If the `_id` type is unknown.
+	*/ prepareId(id) {
+		switch (this.idType) {
+			case "objectId": return id instanceof ObjectId ? id : new ObjectId(id);
+			case "number": return Number(id);
+			case "string": return String(id);
+			default: throw new Error("Unknown \"_id\" type");
+		}
+	}
+	/**
+	* Retrieves a validator for a given purpose. If the validator is not already cached,
+	* it creates and stores a new one based on the purpose.
+	*
+	* @param {TValidatorPurpose} purpose - The validation purpose (`input`, `update`, `patch`).
+	* @returns {Validator} The corresponding validator instance.
+	* @throws {Error} If an unknown purpose is provided.
+	*/ getValidator(purpose) {
+		if (!this.validators.has(purpose)) switch (purpose) {
+			case "insert": {
+				this.validators.set(purpose, this.type.validator({
+					plugins: [validateMongoIdPlugin, validateMongoUniqueArrayItemsPlugin],
+					replace(type, path) {
+						if (path === "_id" && type.type.tags.has("objectId")) return {
+							...type,
+							optional: true
+						};
+						return type;
+					}
+				}));
+				break;
+			}
+			case "update": {
+				this.validators.set(purpose, this.type.validator({ plugins: [validateMongoIdPlugin] }));
+				break;
+			}
+			case "patch": {
+				this.validators.set(purpose, CollectionPatcher.prepareValidator(this));
+				break;
+			}
+			default: throw new Error(`Unknown validator purpose: ${purpose}`);
+		}
+		return this.validators.get(purpose);
+	}
 	get type() {
 		return this._type;
 	}
@@ -323,18 +743,24 @@ else {
 			if (analyzer) index.definition.mappings.fields[fieldName].analyzer = analyzer;
 		}
 	}
-	_flattenType(type, prefix) {
+	_flattenType(type, prefix = "", inComplexTypeOrArray = false) {
 		switch (type.type.kind) {
 			case "object":
+				this._flatMap?.set(prefix || "", type);
 				const items = Array.from(type.type.props.entries());
-				for (const [key, value] of items) this._flattenType(value, prefix ? `${prefix}.${key}` : key);
+				for (const [key, value] of items) this._flattenType(value, prefix ? `${prefix}.${key}` : key, inComplexTypeOrArray);
 				break;
 			case "array":
-				this._flattenType(type.type.of, prefix);
+				let typeArray = type;
+				if (!inComplexTypeOrArray) {
+					typeArray = defineAnnotatedType().refTo(type).copyMetadata(type.metadata).$type;
+					typeArray.metadata.set("mongo.__topLevelArray", true);
+				}
+				this._flatMap?.set(prefix || "", typeArray);
 				break;
 			case "intersection":
 			case "tuple":
-			case "union": for (const item of type.type.items) this._flattenType(item, prefix);
+			case "union": for (const item of type.type.items) this._flattenType(item, prefix, true);
 			default:
 				this._flatMap?.set(prefix || "", type);
 				break;
@@ -355,6 +781,9 @@ else {
 			text: { fuzzy: { maxEdits: textSearch.fuzzy || 0 } }
 		});
 	}
+	get uniqueProps() {
+		return this._uniqueProps;
+	}
 	_finalizeIndexesForCollection() {
 		for (const [key, value] of Array.from(this._vectorFilters.entries())) {
 			const index = this._indexes.get(key);
@@ -363,6 +792,10 @@ else {
 				path: value
 			});
 		}
+		for (const [, value] of Array.from(this._indexes.entries())) if (value.type === "unique") {
+			const keys = Object.keys(value.fields);
+			if (keys.length === 1) this._uniqueProps.add(keys[0]);
+		}
 	}
 	_prepareIndexesForField(fieldName, metadata) {
 		for (const index of metadata.get("mongo.index.plain") || []) this._addIndexField("plain", index === true ? fieldName : index, fieldName);
@@ -478,20 +911,80 @@ else toUpdate.add(remote.name);
 			default:
 		}
 	}
+	insert(payload, options) {
+		const toInsert = this.prepareInsert(payload);
+		return Array.isArray(toInsert) ? this.collection.insertMany(toInsert, options) : this.collection.insertOne(toInsert, options);
+	}
+	replace(payload, options) {
+		const [filter, replace, opts] = this.prepareReplace(payload).toArgs();
+		return this.collection.replaceOne(filter, replace, {
+			...opts,
+			...options
+		});
+	}
+	update(payload, options) {
+		const [filter, update, opts] = this.prepareUpdate(payload).toArgs();
+		return this.collection.updateOne(filter, update, {
+			...opts,
+			...options
+		});
+	}
+	prepareInsert(payload) {
+		const v = this.getValidator("insert");
+		const arr = Array.isArray(payload) ? payload : [payload];
+		const prepared = [];
+		for (const item of arr) if (v.validate(item)) {
+			const data = { ...item };
+			if (data._id) data._id = this.prepareId(data._id);
+else if (this.idType !== "objectId") throw new Error("Missing \"_id\" field");
+			prepared.push(data);
+		} else throw new Error("Invalid payload");
+		return prepared.length === 1 ? prepared[0] : prepared;
+	}
+	prepareReplace(payload) {
+		const v = this.getValidator("update");
+		if (v.validate(payload)) {
+			const _id = this.prepareId(payload._id);
+			const data = {
+				...payload,
+				_id
+			};
+			return {
+				toArgs: () => [
+					{ _id },
+					data,
+					{}
+				],
+				filter: { _id },
+				updateFilter: data,
+				updateOptions: {}
+			};
+		}
+		throw new Error("Invalid payload");
+	}
+	prepareUpdate(payload) {
+		const v = this.getValidator("patch");
+		if (v.validate(payload)) return new CollectionPatcher(this, payload).preparePatch();
+		throw new Error("Invalid payload");
+	}
 	constructor(asMongo, _type, logger = NoopLogger) {
 		_define_property$1(this, "asMongo", void 0);
 		_define_property$1(this, "_type", void 0);
 		_define_property$1(this, "logger", void 0);
 		_define_property$1(this, "name", void 0);
 		_define_property$1(this, "collection", void 0);
+		_define_property$1(this, "validators", void 0);
 		_define_property$1(this, "_indexes", void 0);
 		_define_property$1(this, "_vectorFilters", void 0);
 		_define_property$1(this, "_flatMap", void 0);
+		_define_property$1(this, "_uniqueProps", void 0);
 		this.asMongo = asMongo;
 		this._type = _type;
 		this.logger = logger;
+		this.validators = new Map();
 		this._indexes = new Map();
 		this._vectorFilters = new Map();
+		this._uniqueProps = new Set();
 		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");
 		const name = _type.metadata.get("mongo.collection");
 		if (!name) throw new Error("@mongo.collection annotation expected with collection name");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/mongo",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Mongodb plugin for atscript.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -14,8 +14,7 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist",
-    "cli.cjs"
+    "dist"
   ],
   "keywords": [
     "atscript",
@@ -33,13 +32,13 @@
   },
   "homepage": "https://github.com/moostjs/atscript/tree/main/packages/mongo#readme",
   "license": "ISC",
-  "dependencies": {
-    "mongodb": "^6.13.0",
-    "@atscript/core": "^0.0.16",
-    "@atscript/typescript": "^0.0.16"
+  "peerDependencies": {
+    "mongodb": "^6.17.0",
+    "@atscript/core": "^0.0.18",
+    "@atscript/typescript": "^0.0.18"
   },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "vitest": "3.2.4"
   },
   "scripts": {
     "pub": "pnpm publish --access public",