@atscript/mongo 0.0.15 → 0.0.17

package/dist/index.cjs

@@ -30,7 +30,8 @@ const mongodb = __toESM(require("mongodb"));
 const primitives = { mongo: { extensions: {
 	objectId: {
 		type: "string",
-		documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n"
+		documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+		expect: { pattern: /^[a-fA-F0-9]{24}$/ }
 	},
 	vector: {
 		type: {
@@ -249,7 +250,35 @@ 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;
+		}
+	}) }
 } };
 
 //#endregion
@@ -288,9 +317,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}`;
 }
@@ -302,6 +336,57 @@ 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(this.idType === "objectId" ? { skipList: new Set(["_id"]) } : {}));
+				break;
+			}
+			case "update": {
+				this.validators.set(purpose, this.type.validator());
+				break;
+			}
+			case "patch": {
+				this.validators.set(purpose, this.type.validator({ partial: (def, path) => {
+					return path === "" || def.metadata.get("mongo.patch.strategy") === "merge";
+				} }));
+				break;
+			}
+			default: throw new Error(`Unknown validator purpose: ${purpose}`);
+		}
+		return this.validators.get(purpose);
+	}
 	get type() {
 		return this._type;
 	}
@@ -349,11 +434,13 @@ else {
 	_flattenType(type, prefix) {
 		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);
 				break;
 			case "array":
-				this._flattenType(type.type.of, prefix);
+				this._flatMap?.set(prefix || "", type);
+				if (type.type.of.type.kind) this._flattenType(type.type.of, prefix);
 				break;
 			case "intersection":
 			case "tuple":
@@ -501,18 +588,53 @@ else toUpdate.add(remote.name);
 			default:
 		}
 	}
+	prepareInsert(payload) {
+		const v = this.getValidator("insert");
+		if (v.validate(payload)) {
+			const data = { ...payload };
+			if (data._id) data._id = this.prepareId(data._id);
+else if (this.idType !== "objectId") throw new Error("Missing \"_id\" field");
+			return data;
+		}
+		throw new Error("Invalid payload");
+	}
+	prepareUpdate(payload) {
+		const v = this.getValidator("insert");
+		if (v.validate(payload)) {
+			const data = { ...payload };
+			data._id = this.prepareId(data._id);
+			return data;
+		}
+		throw new Error("Invalid payload");
+	}
+	preparePatch(payload) {
+		const v = this.getValidator("patch");
+		if (v.validate(payload)) return { $set: this._flattenPayload(payload) };
+		throw new Error("Invalid payload");
+	}
+	_flattenPayload(payload, prefix = "", obj = {}) {
+		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		for (const [_key, value] of Object.entries(payload)) {
+			const key = evalKey(_key);
+			if (typeof value === "object" && this.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge") this._flattenPayload(value, key, obj);
+else obj[key] = value;
+		}
+		return obj;
+	}
 	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);
 		this.asMongo = asMongo;
 		this._type = _type;
 		this.logger = logger;
+		this.validators = new Map();
 		this._indexes = new Map();
 		this._vectorFilters = new Map();
 		if (!(0, __atscript_typescript.isAnnotatedType)(_type)) throw new Error("Atscript Annotated Type expected");

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { TAtscriptPlugin } from '@atscript/core';
-import { TAtscriptAnnotatedType, TAtscriptTypeObject, TMetadataMap } from '@atscript/typescript';
+import { TAtscriptAnnotatedTypeConstructor, TAtscriptAnnotatedType, TAtscriptTypeObject, TMetadataMap } from '@atscript/typescript';
 import * as mongodb from 'mongodb';
-import { MongoClient, Collection } from 'mongodb';
+import { MongoClient, Collection, ObjectId, WithId, UpdateFilter, MatchKeysAndValues } from 'mongodb';
 
 declare const MongoPlugin: () => TAtscriptPlugin;
 
@@ -21,7 +21,7 @@ declare class AsMongo {
     protected collectionsList?: Promise<Set<string>>;
     protected getCollectionsList(): Promise<Set<string>>;
     collectionExists(name: string): Promise<boolean>;
-    getCollection<T extends TAtscriptAnnotatedType & (new (...args: any[]) => any)>(type: T, logger?: TGenericLogger): AsCollection<T>;
+    getCollection<T extends TAtscriptAnnotatedTypeConstructor>(type: T, logger?: TGenericLogger): AsCollection<T>;
 }
 
 type TPlainIndex = {
@@ -34,30 +34,39 @@ type TSearchIndex = {
     definition: TMongoSearchIndexDefinition;
 };
 type TIndex = TPlainIndex | TSearchIndex;
-declare class AsCollection<T extends TAtscriptAnnotatedType & (new (...args: any[]) => any)> {
+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>;
+    get idType(): 'string' | 'number' | 'objectId';
+    prepareId<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+    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 _prepareIndexesForCollection(): void;
     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>;
+    prepareInsert(payload: any): InstanceType<T>;
+    prepareUpdate(payload: any): WithId<InstanceType<T>>;
+    preparePatch(payload: any): UpdateFilter<InstanceType<T>>;
+    protected _flattenPayload(payload: T, prefix?: string, obj?: MatchKeysAndValues<InstanceType<T>>): MatchKeysAndValues<InstanceType<T>>;
 }
 type TVectorSimilarity = 'cosine' | 'euclidean' | 'dotProduct';
 type TMongoSearchIndexDefinition = {

package/dist/index.mjs

@@ -1,12 +1,13 @@
-import { AnnotationSpec, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
 import { isAnnotatedType } from "@atscript/typescript";
-import { MongoClient } from "mongodb";
+import { MongoClient, ObjectId } from "mongodb";
 
 //#region packages/mongo/src/plugin/primitives.ts
 const primitives = { mongo: { extensions: {
 	objectId: {
 		type: "string",
-		documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n"
+		documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+		expect: { pattern: /^[a-fA-F0-9]{24}$/ }
 	},
 	vector: {
 		type: {
@@ -225,7 +226,35 @@ 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;
+		}
+	}) }
 } };
 
 //#endregion
@@ -264,9 +293,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}`;
 }
@@ -278,6 +312,57 @@ 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(this.idType === "objectId" ? { skipList: new Set(["_id"]) } : {}));
+				break;
+			}
+			case "update": {
+				this.validators.set(purpose, this.type.validator());
+				break;
+			}
+			case "patch": {
+				this.validators.set(purpose, this.type.validator({ partial: (def, path) => {
+					return path === "" || def.metadata.get("mongo.patch.strategy") === "merge";
+				} }));
+				break;
+			}
+			default: throw new Error(`Unknown validator purpose: ${purpose}`);
+		}
+		return this.validators.get(purpose);
+	}
 	get type() {
 		return this._type;
 	}
@@ -325,11 +410,13 @@ else {
 	_flattenType(type, prefix) {
 		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);
 				break;
 			case "array":
-				this._flattenType(type.type.of, prefix);
+				this._flatMap?.set(prefix || "", type);
+				if (type.type.of.type.kind) this._flattenType(type.type.of, prefix);
 				break;
 			case "intersection":
 			case "tuple":
@@ -477,18 +564,53 @@ else toUpdate.add(remote.name);
 			default:
 		}
 	}
+	prepareInsert(payload) {
+		const v = this.getValidator("insert");
+		if (v.validate(payload)) {
+			const data = { ...payload };
+			if (data._id) data._id = this.prepareId(data._id);
+else if (this.idType !== "objectId") throw new Error("Missing \"_id\" field");
+			return data;
+		}
+		throw new Error("Invalid payload");
+	}
+	prepareUpdate(payload) {
+		const v = this.getValidator("insert");
+		if (v.validate(payload)) {
+			const data = { ...payload };
+			data._id = this.prepareId(data._id);
+			return data;
+		}
+		throw new Error("Invalid payload");
+	}
+	preparePatch(payload) {
+		const v = this.getValidator("patch");
+		if (v.validate(payload)) return { $set: this._flattenPayload(payload) };
+		throw new Error("Invalid payload");
+	}
+	_flattenPayload(payload, prefix = "", obj = {}) {
+		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		for (const [_key, value] of Object.entries(payload)) {
+			const key = evalKey(_key);
+			if (typeof value === "object" && this.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge") this._flattenPayload(value, key, obj);
+else obj[key] = value;
+		}
+		return obj;
+	}
 	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);
 		this.asMongo = asMongo;
 		this._type = _type;
 		this.logger = logger;
+		this.validators = new Map();
 		this._indexes = new Map();
 		this._vectorFilters = new Map();
 		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/mongo",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Mongodb plugin for atscript.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -35,8 +35,8 @@
   "license": "ISC",
   "dependencies": {
     "mongodb": "^6.13.0",
-    "@atscript/core": "^0.0.15",
-    "@atscript/typescript": "^0.0.15"
+    "@atscript/core": "^0.0.17",
+    "@atscript/typescript": "^0.0.17"
   },
   "devDependencies": {
     "vitest": "^3.0.0"