@atscript/mongo 0.1.31 → 0.1.32

package/dist/plugin.cjs

@@ -0,0 +1,228 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __atscript_core = __toESM(require("@atscript/core"));
+
+//#region packages/mongo/src/plugin/annotations.ts
+const analyzers = [
+	"lucene.standard",
+	"lucene.simple",
+	"lucene.whitespace",
+	"lucene.english",
+	"lucene.french",
+	"lucene.german",
+	"lucene.italian",
+	"lucene.portuguese",
+	"lucene.spanish",
+	"lucene.chinese",
+	"lucene.hindi",
+	"lucene.bengali",
+	"lucene.russian",
+	"lucene.arabic"
+];
+const annotations = {
+	collection: new __atscript_core.AnnotationSpec({
+		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		nodeType: ["interface"],
+		validate(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			const errors = [];
+			if ((0, __atscript_core.isInterface)(parent) && parent.props.has("_id") && (0, __atscript_core.isStructure)(struc)) {
+				const _id = parent.props.get("_id");
+				const isOptional = !!_id.token("optional");
+				if (isOptional) errors.push({
+					message: `[db.mongo] _id can't be optional in Mongo Collection`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+				const definition = _id.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.isPrimitive)(def) && !["string", "number"].includes(def.config.type)) wrongType = true;
+				} else wrongType = true;
+				if (wrongType) errors.push({
+					message: `[db.mongo] _id must be of type string, number or mongo.objectId`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+			}
+			return errors;
+		},
+		modify(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			if ((0, __atscript_core.isInterface)(parent) && !parent.props.has("_id") && (0, __atscript_core.isStructure)(struc)) struc.addVirtualProp({
+				name: "_id",
+				type: "mongo.objectId",
+				documentation: "Mongodb Primary Key ObjectId"
+			});
+		}
+	}),
+	search: {
+		dynamic: new __atscript_core.AnnotationSpec({
+			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: false,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The **text analyzer** for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "fuzzy",
+				type: "number",
+				description: "Maximum typo tolerance (`0-2`). Defaults to `0` (no fuzzy search).\n\n- `0` → Exact match required.\n- `1` → Allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → More typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`)."
+			}]
+		}),
+		static: new __atscript_core.AnnotationSpec({
+			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+					values: analyzers
+				},
+				{
+					optional: true,
+					name: "fuzzy",
+					type: "number",
+					description: "Maximum typo tolerance (`0-2`). **Defaults to `0` (no fuzzy matching).**\n\n- `0` → No typos allowed (exact match required).\n- `1` → Allows small typos (e.g., \"mongo\" ≈ \"mango\").\n- `2` → More typo tolerance (e.g., \"mongodb\" ≈ \"mangodb\")."
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
+				}
+			]
+		}),
+		text: new __atscript_core.AnnotationSpec({
+			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the search index** defined in `@db.mongo.search.static`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
+			}]
+		}),
+		vector: new __atscript_core.AnnotationSpec({
+			description: "Creates a **MongoDB Vector Search Index** for **semantic search, embeddings, and AI-powered search**.\n\n- Each field that stores vector embeddings **must define its own vector index**.\n- Supports **cosine similarity, Euclidean distance, and dot product similarity**.\n- Vector fields must be an **array of numbers**.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: mongo.vector\n```\n",
+			nodeType: ["prop"],
+			multiple: false,
+			argument: [
+				{
+					optional: false,
+					name: "dimensions",
+					type: "number",
+					description: "The **number of dimensions in the vector** (e.g., 512 for OpenAI embeddings).",
+					values: [
+						"512",
+						"768",
+						"1024",
+						"1536",
+						"3072",
+						"4096"
+					]
+				},
+				{
+					optional: true,
+					name: "similarity",
+					type: "string",
+					description: "The **similarity metric** used for vector search. Defaults to `\"cosine\"`.\n\n**Available options:** `\"cosine\"`, `\"euclidean\"`, `\"dotProduct\"`.",
+					values: [
+						"cosine",
+						"euclidean",
+						"dotProduct"
+					]
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The **name of the vector search index** (optional, defaults to property name)."
+				}
+			]
+		}),
+		filter: new __atscript_core.AnnotationSpec({
+			description: "Assigns a field as a **filter field** for a **MongoDB Vector Search Index**.\n\n- The assigned field **must be indexed** for efficient filtering.\n- Filters allow vector search queries to return results **only within a specific category, user group, or tag**.\n- The vector index must be defined using `@db.mongo.search.vector`.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: number[]\n\n@db.mongo.search.filter \"embedding\"\ncategory: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: false,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the vector search index** this field should be used as a filter for."
+			}]
+		})
+	}
+};
+
+//#endregion
+//#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",
+		annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
+	},
+	vector: {
+		type: {
+			kind: "array",
+			of: "number"
+		},
+		documentation: "Represents a **MongoDB Vector (Array of Numbers)** for **Vector Search**.\n\n- Equivalent to `number[]` but explicitly used for **vector embeddings**.\n\n**Example:**\n```atscript\nembedding: mongo.vector\n```\n"
+	}
+} } };
+
+//#endregion
+//#region packages/mongo/src/plugin/index.ts
+const MongoPlugin = () => ({
+	name: "mongo",
+	config() {
+		return {
+			primitives,
+			annotations: { db: { mongo: annotations } }
+		};
+	}
+});
+
+//#endregion
+exports.MongoPlugin = MongoPlugin

package/dist/plugin.d.ts

@@ -0,0 +1,5 @@
+import { TAtscriptPlugin } from '@atscript/core';
+
+declare const MongoPlugin: () => TAtscriptPlugin;
+
+export { MongoPlugin };

package/dist/plugin.mjs

@@ -0,0 +1,204 @@
+import { AnnotationSpec, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+
+//#region packages/mongo/src/plugin/annotations.ts
+const analyzers = [
+	"lucene.standard",
+	"lucene.simple",
+	"lucene.whitespace",
+	"lucene.english",
+	"lucene.french",
+	"lucene.german",
+	"lucene.italian",
+	"lucene.portuguese",
+	"lucene.spanish",
+	"lucene.chinese",
+	"lucene.hindi",
+	"lucene.bengali",
+	"lucene.russian",
+	"lucene.arabic"
+];
+const annotations = {
+	collection: new AnnotationSpec({
+		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		nodeType: ["interface"],
+		validate(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			const errors = [];
+			if (isInterface(parent) && parent.props.has("_id") && isStructure(struc)) {
+				const _id = parent.props.get("_id");
+				const isOptional = !!_id.token("optional");
+				if (isOptional) errors.push({
+					message: `[db.mongo] _id can't be optional in Mongo Collection`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+				const definition = _id.getDefinition();
+				if (!definition) return errors;
+				let wrongType = false;
+				if (isRef(definition)) {
+					const def = doc.unwindType(definition.id, definition.chain)?.def;
+					if (isPrimitive(def) && !["string", "number"].includes(def.config.type)) wrongType = true;
+				} else wrongType = true;
+				if (wrongType) errors.push({
+					message: `[db.mongo] _id must be of type string, number or mongo.objectId`,
+					severity: 1,
+					range: _id.token("identifier").range
+				});
+			}
+			return errors;
+		},
+		modify(token, args, doc) {
+			const parent = token.parentNode;
+			const struc = parent?.getDefinition();
+			if (isInterface(parent) && !parent.props.has("_id") && isStructure(struc)) struc.addVirtualProp({
+				name: "_id",
+				type: "mongo.objectId",
+				documentation: "Mongodb Primary Key ObjectId"
+			});
+		}
+	}),
+	search: {
+		dynamic: new AnnotationSpec({
+			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: false,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The **text analyzer** for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "fuzzy",
+				type: "number",
+				description: "Maximum typo tolerance (`0-2`). Defaults to `0` (no fuzzy search).\n\n- `0` → Exact match required.\n- `1` → Allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → More typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`)."
+			}]
+		}),
+		static: new AnnotationSpec({
+			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			nodeType: ["interface"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+					values: analyzers
+				},
+				{
+					optional: true,
+					name: "fuzzy",
+					type: "number",
+					description: "Maximum typo tolerance (`0-2`). **Defaults to `0` (no fuzzy matching).**\n\n- `0` → No typos allowed (exact match required).\n- `1` → Allows small typos (e.g., \"mongo\" ≈ \"mango\").\n- `2` → More typo tolerance (e.g., \"mongodb\" ≈ \"mangodb\")."
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
+				}
+			]
+		}),
+		text: new AnnotationSpec({
+			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: true,
+				name: "analyzer",
+				type: "string",
+				description: "The text analyzer for tokenization. Defaults to `\"lucene.standard\"`.\n\n**Available options:** `\"lucene.standard\"`, `\"lucene.english\"`, `\"lucene.spanish\"`, `\"lucene.german\"`, etc.",
+				values: analyzers
+			}, {
+				optional: true,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the search index** defined in `@db.mongo.search.static`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
+			}]
+		}),
+		vector: new AnnotationSpec({
+			description: "Creates a **MongoDB Vector Search Index** for **semantic search, embeddings, and AI-powered search**.\n\n- Each field that stores vector embeddings **must define its own vector index**.\n- Supports **cosine similarity, Euclidean distance, and dot product similarity**.\n- Vector fields must be an **array of numbers**.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: mongo.vector\n```\n",
+			nodeType: ["prop"],
+			multiple: false,
+			argument: [
+				{
+					optional: false,
+					name: "dimensions",
+					type: "number",
+					description: "The **number of dimensions in the vector** (e.g., 512 for OpenAI embeddings).",
+					values: [
+						"512",
+						"768",
+						"1024",
+						"1536",
+						"3072",
+						"4096"
+					]
+				},
+				{
+					optional: true,
+					name: "similarity",
+					type: "string",
+					description: "The **similarity metric** used for vector search. Defaults to `\"cosine\"`.\n\n**Available options:** `\"cosine\"`, `\"euclidean\"`, `\"dotProduct\"`.",
+					values: [
+						"cosine",
+						"euclidean",
+						"dotProduct"
+					]
+				},
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The **name of the vector search index** (optional, defaults to property name)."
+				}
+			]
+		}),
+		filter: new AnnotationSpec({
+			description: "Assigns a field as a **filter field** for a **MongoDB Vector Search Index**.\n\n- The assigned field **must be indexed** for efficient filtering.\n- Filters allow vector search queries to return results **only within a specific category, user group, or tag**.\n- The vector index must be defined using `@db.mongo.search.vector`.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: number[]\n\n@db.mongo.search.filter \"embedding\"\ncategory: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [{
+				optional: false,
+				name: "indexName",
+				type: "string",
+				description: "The **name of the vector search index** this field should be used as a filter for."
+			}]
+		})
+	}
+};
+
+//#endregion
+//#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",
+		annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
+	},
+	vector: {
+		type: {
+			kind: "array",
+			of: "number"
+		},
+		documentation: "Represents a **MongoDB Vector (Array of Numbers)** for **Vector Search**.\n\n- Equivalent to `number[]` but explicitly used for **vector embeddings**.\n\n**Example:**\n```atscript\nembedding: mongo.vector\n```\n"
+	}
+} } };
+
+//#endregion
+//#region packages/mongo/src/plugin/index.ts
+const MongoPlugin = () => ({
+	name: "mongo",
+	config() {
+		return {
+			primitives,
+			annotations: { db: { mongo: annotations } }
+		};
+	}
+});
+
+//#endregion
+export { MongoPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/mongo",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -29,12 +29,27 @@
   },
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "plugin": [
+        "dist/plugin.d.ts"
+      ],
+      "": [
+        "dist/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.mjs",
+      "require": "./dist/plugin.cjs"
+    },
     "./package.json": "./package.json"
   },
   "devDependencies": {
@@ -42,9 +57,19 @@
   },
   "peerDependencies": {
     "mongodb": "^6.17.0",
-    "@atscript/core": "^0.1.31",
-    "@atscript/typescript": "^0.1.31"
+    "@atscript/core": "^0.1.32",
+    "@atscript/utils-db": "^0.1.32",
+    "@atscript/typescript": "^0.1.32"
   },
+  "build": [
+    {},
+    {
+      "entries": [
+        "src/plugin.ts"
+      ],
+      "dts": true
+    }
+  ],
   "scripts": {
     "pub": "pnpm publish --access public",
     "test": "vitest",

package/skills/atscript-mongo/core.md

@@ -17,7 +17,7 @@ Add `MongoPlugin()` to your `atscript.config.ts`:
 ```typescript
 import { defineConfig } from '@atscript/core'
 import { ts } from '@atscript/typescript'
-import { MongoPlugin } from '@atscript/mongo'
+import { MongoPlugin } from '@atscript/mongo/plugin'
 
 export default defineConfig({
   rootDir: 'src',