@atscript/db-mongo 0.1.101 → 0.1.102

package/dist/agg.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_filter = require("./mongo-filter-AihWWQXp.cjs");
+const require_mongo_filter = require("./mongo-filter-1EpqdD-T.cjs");
 let _atscript_db_agg = require("@atscript/db/agg");
 //#region src/agg.ts
 /** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */

package/dist/agg.mjs

@@ -1,4 +1,4 @@
-import { t as buildMongoFilter } from "./mongo-filter-BsocUQG3.mjs";
+import { t as buildMongoFilter } from "./mongo-filter-DBYaF9aH.mjs";
 import { resolveAlias } from "@atscript/db/agg";
 //#region src/agg.ts
 /** Simple accumulators that map directly to `{ $<fn>: '$field' }`. */

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mongo_filter = require("./mongo-filter-AihWWQXp.cjs");
+const require_mongo_filter = require("./mongo-filter-1EpqdD-T.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
 //#region src/lib/projection-dedupe.ts
@@ -72,6 +72,9 @@ function containsAggregationExpr(v) {
 * `$set` map.
 */
 var CollectionPatcher = class {
+	collection;
+	payload;
+	ops;
 	constructor(collection, payload, ops) {
 		this.collection = collection;
 		this.payload = payload;
@@ -630,13 +633,13 @@ function isVectorSearchableImpl(host) {
 }
 /** Text search via $search aggregation stage. */
 async function searchImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName);
+	const plan = buildSearchStage(host, text, indexName, query.controls);
 	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 	return runSearchPipeline(host, plan.stage, query, "search", void 0, plan.classicText);
 }
 /** Text search with faceted count. */
 async function searchWithCountImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName);
+	const plan = buildSearchStage(host, text, indexName, query.controls);
 	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 	return runSearchWithCountPipeline(host, plan.stage, query, "searchWithCount", void 0, plan.classicText);
 }
@@ -672,7 +675,7 @@ function resolveThreshold(host, controls, indexName) {
 * MongoDB the stage is unsupported entirely — even though the table reports
 * `searchable: true`. The discriminator is the resolved index's `type`.
 */
-function buildSearchStage(host, text, indexName) {
+function buildSearchStage(host, text, indexName, controls) {
 	const index = host.getMongoSearchIndex(indexName);
 	if (!index) return;
 	if (index.type === "vector") throw new Error("Vector indexes cannot be used with text search. Use vectorSearch() instead.");
@@ -680,17 +683,58 @@ function buildSearchStage(host, text, indexName) {
 		stage: { $match: { $text: { $search: text } } },
 		classicText: true
 	};
+	const searchIndex = index;
+	const fuzzy = resolveSearchFuzzy(searchIndex, controls);
+	const strategy = searchIndex.strategy ?? "compound";
+	const autocompletePaths = autocompleteFieldPaths(searchIndex);
+	const textClause = () => ({ text: {
+		query: text,
+		path: { wildcard: "*" },
+		...fuzzy ? { fuzzy } : {}
+	} });
+	const autocompleteClause = (path) => ({ autocomplete: {
+		query: text,
+		path,
+		...fuzzy ? { fuzzy } : {}
+	} });
+	let body;
+	if (strategy === "text" || autocompletePaths.length === 0) body = textClause();
+	else if (strategy === "autocomplete") {
+		const clauses = autocompletePaths.map(autocompleteClause);
+		body = clauses.length === 1 ? clauses[0] : { compound: {
+			should: clauses,
+			minimumShouldMatch: 1
+		} };
+	} else body = { compound: {
+		should: [textClause(), ...autocompletePaths.map(autocompleteClause)],
+		minimumShouldMatch: 1
+	} };
 	return {
 		stage: { $search: {
 			index: index.key,
-			text: {
-				query: text,
-				path: { wildcard: "*" }
-			}
+			...body
 		} },
 		classicText: false
 	};
 }
+/**
+* Resolves query-time fuzzy (typo tolerance): the `$fuzzy` request control
+* overrides the schema-declared `@db.mongo.search.*` fuzzy. Only an edit distance
+* of 1 or 2 is emitted (Atlas rejects 0) — anything else means "no fuzzy".
+*/
+function resolveSearchFuzzy(index, controls) {
+	const override = controls?.$fuzzy;
+	const maxEdits = override === void 0 ? index.fuzzy?.maxEdits : Number(override);
+	return maxEdits === 1 || maxEdits === 2 ? { maxEdits } : void 0;
+}
+/** Field paths in this index that carry an `autocomplete` mapping. */
+function autocompleteFieldPaths(index) {
+	const fields = index.definition.mappings?.fields;
+	if (!fields) return [];
+	const paths = [];
+	for (const [path, mapping] of Object.entries(fields)) if ((Array.isArray(mapping) ? mapping : [mapping]).some((m) => m.type === "autocomplete")) paths.push(path);
+	return paths;
+}
 /** Builds a $vectorSearch aggregation stage from a pre-computed vector. */
 function buildVectorSearchStage(host, vector, indexName, limit) {
 	let index;
@@ -1289,10 +1333,26 @@ function fieldsMatch(left, right) {
 	if (leftKeys.length !== rightKeys.length) return false;
 	for (const key of leftKeys) {
 		if (!(key in right)) return false;
-		if (left[key].type !== right[key].type || left[key].analyzer !== right[key].analyzer) return false;
+		if (!fieldMappingEqual(left[key], right[key])) return false;
 	}
 	return true;
 }
+/** Order-independent structural compare of a field's Atlas type mapping(s). */
+function fieldMappingEqual(a, b) {
+	const am = mappingsByType(a);
+	const bm = mappingsByType(b);
+	if (am.size !== bm.size) return false;
+	for (const [type, av] of am) {
+		const bv = bm.get(type);
+		if (!bv || av.analyzer !== bv.analyzer || av.tokenization !== bv.tokenization || av.minGrams !== bv.minGrams || av.maxGrams !== bv.maxGrams || av.foldDiacritics !== bv.foldDiacritics) return false;
+	}
+	return true;
+}
+function mappingsByType(m) {
+	const map = /* @__PURE__ */ new Map();
+	for (const x of Array.isArray(m) ? m : [m]) map.set(x.type, x);
+	return map;
+}
 function vectorFieldsMatch(left, right) {
 	if (left.length !== (right || []).length) return false;
 	const rightMap = /* @__PURE__ */ new Map();
@@ -1318,6 +1378,8 @@ const validateMongoIdPlugin = (ctx, def, value) => {
 //#endregion
 //#region src/lib/mongo-adapter.ts
 var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
+	db;
+	client;
 	_collection;
 	/** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
 	_mongoIndexes = /* @__PURE__ */ new Map();
@@ -1508,13 +1570,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		const dynamicText = typeMeta.get("db.mongo.search.dynamic");
 		if (dynamicText) this._setSearchIndex("dynamic_text", "_", {
 			mappings: { dynamic: true },
-			analyzer: dynamicText.analyzer,
-			text: { fuzzy: { maxEdits: dynamicText.fuzzy || 0 } }
-		});
+			analyzer: dynamicText.analyzer
+		}, { fuzzy: normalizeSearchFuzzy(dynamicText.fuzzy) });
 		for (const textSearch of typeMeta.get("db.mongo.search.static") || []) this._setSearchIndex("search_text", textSearch.indexName, {
 			mappings: { fields: {} },
-			analyzer: textSearch.analyzer,
-			text: { fuzzy: { maxEdits: textSearch.fuzzy || 0 } }
+			analyzer: textSearch.analyzer
+		}, {
+			fuzzy: normalizeSearchFuzzy(textSearch.fuzzy),
+			strategy: normalizeSearchStrategy(textSearch.strategy)
 		});
 	}
 	onFieldScanned(field, _type, metadata) {
@@ -1528,7 +1591,24 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 			const startValue = metadata.get("db.default.increment");
 			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
 		}
-		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, index.analyzer);
+		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, [index.analyzer ? {
+			type: "string",
+			analyzer: index.analyzer
+		} : { type: "string" }]);
+		for (const ac of metadata.get("db.mongo.search.autocomplete") || []) {
+			const autocomplete = {
+				type: "autocomplete",
+				tokenization: ac.tokenization || "edgeGram",
+				minGrams: ac.minGrams ?? 2,
+				maxGrams: ac.maxGrams ?? 15,
+				foldDiacritics: ac.foldDiacritics ?? true
+			};
+			const companion = ac.analyzer ? {
+				type: "string",
+				analyzer: ac.analyzer
+			} : { type: "string" };
+			this._addFieldToSearchIndex("search_text", ac.indexName, field, [autocomplete, companion]);
+		}
 		const vectorIndex = metadata.get("db.search.vector");
 		if (vectorIndex) {
 			const indexName = vectorIndex.indexName || field;
@@ -1989,32 +2069,68 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		}
 		if (weight) index.weights[field] = weight;
 	}
-	_setSearchIndex(type, name, definition) {
+	_setSearchIndex(type, name, definition, meta) {
 		const key = mongoIndexKey(type, name || "DEFAULT");
-		this._mongoIndexes.set(key, {
+		const index = {
 			key,
 			name: name || "DEFAULT",
 			type,
-			definition
-		});
+			definition,
+			fuzzy: meta?.fuzzy,
+			strategy: meta?.strategy
+		};
+		this._mongoIndexes.set(key, index);
+		return index;
 	}
-	_addFieldToSearchIndex(type, _name, fieldName, analyzer) {
+	/**
+	* Adds (and merges, by mapping `type`) one or more Atlas field-type mappings to
+	* a `search_text` index. Multiple annotations on the same field — e.g.
+	* `@db.mongo.search.text` (string) plus `@db.mongo.search.autocomplete`
+	* (autocomplete + string) — accumulate into a single multi-type mapping
+	* instead of overwriting one another.
+	*/
+	_addFieldToSearchIndex(type, _name, fieldName, mappings) {
 		const name = _name || "DEFAULT";
 		let index = this._mongoIndexes.get(mongoIndexKey(type, name));
-		if (!index && type === "search_text") {
-			this._setSearchIndex(type, name, {
-				mappings: { fields: {} },
-				text: { fuzzy: { maxEdits: 0 } }
-			});
-			index = this._mongoIndexes.get(mongoIndexKey(type, name));
-		}
+		if (!index && type === "search_text") index = this._setSearchIndex(type, name, { mappings: { fields: {} } });
 		if (index) {
-			index.definition.mappings.fields[fieldName] = { type: "string" };
-			if (analyzer) index.definition.mappings.fields[fieldName].analyzer = analyzer;
+			const fields = index.definition.mappings.fields;
+			fields[fieldName] = mergeFieldMappings(fields[fieldName], mappings);
 		}
 	}
 };
 /**
+* Normalizes a declared `fuzzy` arg (`0-2`) into the query-time metadata Atlas
+* accepts. Atlas only honors an edit distance of `1` or `2`; `0`/undefined means
+* "no fuzzy", returned as `undefined` so no `fuzzy` clause is ever emitted.
+*/
+function normalizeSearchFuzzy(fuzzy) {
+	return fuzzy === 1 || fuzzy === 2 ? { maxEdits: fuzzy } : void 0;
+}
+/** Narrows the declared `strategy` arg to a known value (undefined → query layer defaults to "compound"). */
+function normalizeSearchStrategy(strategy) {
+	return strategy === "compound" || strategy === "autocomplete" || strategy === "text" ? strategy : void 0;
+}
+/**
+* Merges incoming Atlas field-type mappings into a field's existing mapping,
+* keyed by `type` (a later mapping of the same type replaces the earlier one).
+* Collapses to a single object when one type remains, else an array (Atlas's
+* multi-type field form).
+*/
+function mergeFieldMappings(existing, incoming) {
+	const byType = /* @__PURE__ */ new Map();
+	const order = [];
+	const add = (m) => {
+		if (!byType.has(m.type)) order.push(m.type);
+		byType.set(m.type, m);
+	};
+	if (Array.isArray(existing)) existing.forEach(add);
+	else if (existing) add(existing);
+	incoming.forEach(add);
+	const merged = order.map((t) => byType.get(t));
+	return merged.length === 1 ? merged[0] : merged;
+}
+/**
 * Builds a MongoDB update document from a data object that may contain
 * field ops (`{ $inc: N }`, `{ $dec: N }`, `{ $mul: N }`).
 * Regular fields go into `$set`, ops go into `$inc` / `$mul`. When

package/dist/index.d.cts

@@ -165,16 +165,45 @@ interface TSearchIndex {
   name: string;
   type: "dynamic_text" | "search_text" | "vector";
   definition: TMongoSearchIndexDefinition;
+  /**
+   * Query-time fuzzy (typo tolerance) declared via `@db.mongo.search.dynamic` /
+   * `@db.mongo.search.static`. Carried as index metadata — NOT part of the Atlas
+   * index `definition` (Atlas applies fuzzy at query time on the `text`/
+   * `autocomplete` operator, not in the index schema). `buildSearchStage` reads
+   * this and attaches it to the emitted operator.
+   */
+  fuzzy?: {
+    maxEdits: number;
+  };
+  /**
+   * The match strategy declared via `@db.mongo.search.static`, locking this
+   * index's query shape. `buildSearchStage` reads it; undefined → `"compound"`.
+   * - `compound` — wildcard `text` + per-field `autocomplete` (exact ranks above prefix).
+   * - `autocomplete` — autocomplete fields only (pure typeahead, no word clause).
+   * - `text` — single `text` operator over all string-mapped fields.
+   */
+  strategy?: "compound" | "autocomplete" | "text";
 }
 type TMongoIndex = TPlainIndex | TSearchIndex;
 type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
+/**
+ * One Atlas Search field-type mapping. `type: "string"` is plain word matching;
+ * `type: "autocomplete"` enables prefix/typeahead (edgeGram) or substring (nGram).
+ * A field may carry several mappings at once (an array of these) — e.g. an
+ * autocomplete field double-mapped as `string` so exact-word hits still rank.
+ */
+interface TSearchFieldMapping {
+  type: string;
+  analyzer?: string;
+  tokenization?: "edgeGram" | "rightEdgeGram" | "nGram";
+  minGrams?: number;
+  maxGrams?: number;
+  foldDiacritics?: boolean;
+}
 interface TMongoSearchIndexDefinition {
   mappings?: {
     dynamic?: boolean;
-    fields?: Record<string, {
-      type: string;
-      analyzer?: string;
-    }>;
+    fields?: Record<string, TSearchFieldMapping | TSearchFieldMapping[]>;
   };
   fields?: Array<{
     path: string;
@@ -183,11 +212,6 @@ interface TMongoSearchIndexDefinition {
     numDimensions?: number;
   }>;
   analyzer?: string;
-  text?: {
-    fuzzy?: {
-      maxEdits: number;
-    };
-  };
 }
 //#endregion
 //#region src/lib/mongo-adapter.d.ts
@@ -351,8 +375,20 @@ declare class MongoAdapter extends BaseDbAdapter {
    */
   private _getCollationOpts;
   protected _addMongoIndexField(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 _setSearchIndex(type: TSearchIndex["type"], name: string | undefined, definition: TMongoSearchIndexDefinition, meta?: {
+    fuzzy?: {
+      maxEdits: number;
+    };
+    strategy?: TSearchIndex["strategy"];
+  }): TSearchIndex;
+  /**
+   * Adds (and merges, by mapping `type`) one or more Atlas field-type mappings to
+   * a `search_text` index. Multiple annotations on the same field — e.g.
+   * `@db.mongo.search.text` (string) plus `@db.mongo.search.autocomplete`
+   * (autocomplete + string) — accumulate into a single multi-type mapping
+   * instead of overwriting one another.
+   */
+  protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, mappings: TSearchFieldMapping[]): void;
 }
 //#endregion
 //#region src/lib/mongo-filter.d.ts

package/dist/index.d.mts

@@ -165,16 +165,45 @@ interface TSearchIndex {
   name: string;
   type: "dynamic_text" | "search_text" | "vector";
   definition: TMongoSearchIndexDefinition;
+  /**
+   * Query-time fuzzy (typo tolerance) declared via `@db.mongo.search.dynamic` /
+   * `@db.mongo.search.static`. Carried as index metadata — NOT part of the Atlas
+   * index `definition` (Atlas applies fuzzy at query time on the `text`/
+   * `autocomplete` operator, not in the index schema). `buildSearchStage` reads
+   * this and attaches it to the emitted operator.
+   */
+  fuzzy?: {
+    maxEdits: number;
+  };
+  /**
+   * The match strategy declared via `@db.mongo.search.static`, locking this
+   * index's query shape. `buildSearchStage` reads it; undefined → `"compound"`.
+   * - `compound` — wildcard `text` + per-field `autocomplete` (exact ranks above prefix).
+   * - `autocomplete` — autocomplete fields only (pure typeahead, no word clause).
+   * - `text` — single `text` operator over all string-mapped fields.
+   */
+  strategy?: "compound" | "autocomplete" | "text";
 }
 type TMongoIndex = TPlainIndex | TSearchIndex;
 type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
+/**
+ * One Atlas Search field-type mapping. `type: "string"` is plain word matching;
+ * `type: "autocomplete"` enables prefix/typeahead (edgeGram) or substring (nGram).
+ * A field may carry several mappings at once (an array of these) — e.g. an
+ * autocomplete field double-mapped as `string` so exact-word hits still rank.
+ */
+interface TSearchFieldMapping {
+  type: string;
+  analyzer?: string;
+  tokenization?: "edgeGram" | "rightEdgeGram" | "nGram";
+  minGrams?: number;
+  maxGrams?: number;
+  foldDiacritics?: boolean;
+}
 interface TMongoSearchIndexDefinition {
   mappings?: {
     dynamic?: boolean;
-    fields?: Record<string, {
-      type: string;
-      analyzer?: string;
-    }>;
+    fields?: Record<string, TSearchFieldMapping | TSearchFieldMapping[]>;
   };
   fields?: Array<{
     path: string;
@@ -183,11 +212,6 @@ interface TMongoSearchIndexDefinition {
     numDimensions?: number;
   }>;
   analyzer?: string;
-  text?: {
-    fuzzy?: {
-      maxEdits: number;
-    };
-  };
 }
 //#endregion
 //#region src/lib/mongo-adapter.d.ts
@@ -351,8 +375,20 @@ declare class MongoAdapter extends BaseDbAdapter {
    */
   private _getCollationOpts;
   protected _addMongoIndexField(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 _setSearchIndex(type: TSearchIndex["type"], name: string | undefined, definition: TMongoSearchIndexDefinition, meta?: {
+    fuzzy?: {
+      maxEdits: number;
+    };
+    strategy?: TSearchIndex["strategy"];
+  }): TSearchIndex;
+  /**
+   * Adds (and merges, by mapping `type`) one or more Atlas field-type mappings to
+   * a `search_text` index. Multiple annotations on the same field — e.g.
+   * `@db.mongo.search.text` (string) plus `@db.mongo.search.autocomplete`
+   * (autocomplete + string) — accumulate into a single multi-type mapping
+   * instead of overwriting one another.
+   */
+  protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, mappings: TSearchFieldMapping[]): void;
 }
 //#endregion
 //#region src/lib/mongo-filter.d.ts

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as buildMongoFilter } from "./mongo-filter-BsocUQG3.mjs";
+import { t as buildMongoFilter } from "./mongo-filter-DBYaF9aH.mjs";
 import { AtscriptDbView, BaseDbAdapter, DbError, DbSpace, computeInsights, getDbFieldOp, getKeyProps, resolveDesignType } from "@atscript/db";
 import { MongoClient, MongoServerError, ObjectId } from "mongodb";
 //#region src/lib/projection-dedupe.ts
@@ -71,6 +71,9 @@ function containsAggregationExpr(v) {
 * `$set` map.
 */
 var CollectionPatcher = class {
+	collection;
+	payload;
+	ops;
 	constructor(collection, payload, ops) {
 		this.collection = collection;
 		this.payload = payload;
@@ -629,13 +632,13 @@ function isVectorSearchableImpl(host) {
 }
 /** Text search via $search aggregation stage. */
 async function searchImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName);
+	const plan = buildSearchStage(host, text, indexName, query.controls);
 	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 	return runSearchPipeline(host, plan.stage, query, "search", void 0, plan.classicText);
 }
 /** Text search with faceted count. */
 async function searchWithCountImpl(host, text, query, indexName) {
-	const plan = buildSearchStage(host, text, indexName);
+	const plan = buildSearchStage(host, text, indexName, query.controls);
 	if (!plan) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 	return runSearchWithCountPipeline(host, plan.stage, query, "searchWithCount", void 0, plan.classicText);
 }
@@ -671,7 +674,7 @@ function resolveThreshold(host, controls, indexName) {
 * MongoDB the stage is unsupported entirely — even though the table reports
 * `searchable: true`. The discriminator is the resolved index's `type`.
 */
-function buildSearchStage(host, text, indexName) {
+function buildSearchStage(host, text, indexName, controls) {
 	const index = host.getMongoSearchIndex(indexName);
 	if (!index) return;
 	if (index.type === "vector") throw new Error("Vector indexes cannot be used with text search. Use vectorSearch() instead.");
@@ -679,17 +682,58 @@ function buildSearchStage(host, text, indexName) {
 		stage: { $match: { $text: { $search: text } } },
 		classicText: true
 	};
+	const searchIndex = index;
+	const fuzzy = resolveSearchFuzzy(searchIndex, controls);
+	const strategy = searchIndex.strategy ?? "compound";
+	const autocompletePaths = autocompleteFieldPaths(searchIndex);
+	const textClause = () => ({ text: {
+		query: text,
+		path: { wildcard: "*" },
+		...fuzzy ? { fuzzy } : {}
+	} });
+	const autocompleteClause = (path) => ({ autocomplete: {
+		query: text,
+		path,
+		...fuzzy ? { fuzzy } : {}
+	} });
+	let body;
+	if (strategy === "text" || autocompletePaths.length === 0) body = textClause();
+	else if (strategy === "autocomplete") {
+		const clauses = autocompletePaths.map(autocompleteClause);
+		body = clauses.length === 1 ? clauses[0] : { compound: {
+			should: clauses,
+			minimumShouldMatch: 1
+		} };
+	} else body = { compound: {
+		should: [textClause(), ...autocompletePaths.map(autocompleteClause)],
+		minimumShouldMatch: 1
+	} };
 	return {
 		stage: { $search: {
 			index: index.key,
-			text: {
-				query: text,
-				path: { wildcard: "*" }
-			}
+			...body
 		} },
 		classicText: false
 	};
 }
+/**
+* Resolves query-time fuzzy (typo tolerance): the `$fuzzy` request control
+* overrides the schema-declared `@db.mongo.search.*` fuzzy. Only an edit distance
+* of 1 or 2 is emitted (Atlas rejects 0) — anything else means "no fuzzy".
+*/
+function resolveSearchFuzzy(index, controls) {
+	const override = controls?.$fuzzy;
+	const maxEdits = override === void 0 ? index.fuzzy?.maxEdits : Number(override);
+	return maxEdits === 1 || maxEdits === 2 ? { maxEdits } : void 0;
+}
+/** Field paths in this index that carry an `autocomplete` mapping. */
+function autocompleteFieldPaths(index) {
+	const fields = index.definition.mappings?.fields;
+	if (!fields) return [];
+	const paths = [];
+	for (const [path, mapping] of Object.entries(fields)) if ((Array.isArray(mapping) ? mapping : [mapping]).some((m) => m.type === "autocomplete")) paths.push(path);
+	return paths;
+}
 /** Builds a $vectorSearch aggregation stage from a pre-computed vector. */
 function buildVectorSearchStage(host, vector, indexName, limit) {
 	let index;
@@ -1288,10 +1332,26 @@ function fieldsMatch(left, right) {
 	if (leftKeys.length !== rightKeys.length) return false;
 	for (const key of leftKeys) {
 		if (!(key in right)) return false;
-		if (left[key].type !== right[key].type || left[key].analyzer !== right[key].analyzer) return false;
+		if (!fieldMappingEqual(left[key], right[key])) return false;
 	}
 	return true;
 }
+/** Order-independent structural compare of a field's Atlas type mapping(s). */
+function fieldMappingEqual(a, b) {
+	const am = mappingsByType(a);
+	const bm = mappingsByType(b);
+	if (am.size !== bm.size) return false;
+	for (const [type, av] of am) {
+		const bv = bm.get(type);
+		if (!bv || av.analyzer !== bv.analyzer || av.tokenization !== bv.tokenization || av.minGrams !== bv.minGrams || av.maxGrams !== bv.maxGrams || av.foldDiacritics !== bv.foldDiacritics) return false;
+	}
+	return true;
+}
+function mappingsByType(m) {
+	const map = /* @__PURE__ */ new Map();
+	for (const x of Array.isArray(m) ? m : [m]) map.set(x.type, x);
+	return map;
+}
 function vectorFieldsMatch(left, right) {
 	if (left.length !== (right || []).length) return false;
 	const rightMap = /* @__PURE__ */ new Map();
@@ -1317,6 +1377,8 @@ const validateMongoIdPlugin = (ctx, def, value) => {
 //#endregion
 //#region src/lib/mongo-adapter.ts
 var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
+	db;
+	client;
 	_collection;
 	/** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
 	_mongoIndexes = /* @__PURE__ */ new Map();
@@ -1507,13 +1569,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		const dynamicText = typeMeta.get("db.mongo.search.dynamic");
 		if (dynamicText) this._setSearchIndex("dynamic_text", "_", {
 			mappings: { dynamic: true },
-			analyzer: dynamicText.analyzer,
-			text: { fuzzy: { maxEdits: dynamicText.fuzzy || 0 } }
-		});
+			analyzer: dynamicText.analyzer
+		}, { fuzzy: normalizeSearchFuzzy(dynamicText.fuzzy) });
 		for (const textSearch of typeMeta.get("db.mongo.search.static") || []) this._setSearchIndex("search_text", textSearch.indexName, {
 			mappings: { fields: {} },
-			analyzer: textSearch.analyzer,
-			text: { fuzzy: { maxEdits: textSearch.fuzzy || 0 } }
+			analyzer: textSearch.analyzer
+		}, {
+			fuzzy: normalizeSearchFuzzy(textSearch.fuzzy),
+			strategy: normalizeSearchStrategy(textSearch.strategy)
 		});
 	}
 	onFieldScanned(field, _type, metadata) {
@@ -1527,7 +1590,24 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			const startValue = metadata.get("db.default.increment");
 			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
 		}
-		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, index.analyzer);
+		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, [index.analyzer ? {
+			type: "string",
+			analyzer: index.analyzer
+		} : { type: "string" }]);
+		for (const ac of metadata.get("db.mongo.search.autocomplete") || []) {
+			const autocomplete = {
+				type: "autocomplete",
+				tokenization: ac.tokenization || "edgeGram",
+				minGrams: ac.minGrams ?? 2,
+				maxGrams: ac.maxGrams ?? 15,
+				foldDiacritics: ac.foldDiacritics ?? true
+			};
+			const companion = ac.analyzer ? {
+				type: "string",
+				analyzer: ac.analyzer
+			} : { type: "string" };
+			this._addFieldToSearchIndex("search_text", ac.indexName, field, [autocomplete, companion]);
+		}
 		const vectorIndex = metadata.get("db.search.vector");
 		if (vectorIndex) {
 			const indexName = vectorIndex.indexName || field;
@@ -1988,32 +2068,68 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		}
 		if (weight) index.weights[field] = weight;
 	}
-	_setSearchIndex(type, name, definition) {
+	_setSearchIndex(type, name, definition, meta) {
 		const key = mongoIndexKey(type, name || "DEFAULT");
-		this._mongoIndexes.set(key, {
+		const index = {
 			key,
 			name: name || "DEFAULT",
 			type,
-			definition
-		});
+			definition,
+			fuzzy: meta?.fuzzy,
+			strategy: meta?.strategy
+		};
+		this._mongoIndexes.set(key, index);
+		return index;
 	}
-	_addFieldToSearchIndex(type, _name, fieldName, analyzer) {
+	/**
+	* Adds (and merges, by mapping `type`) one or more Atlas field-type mappings to
+	* a `search_text` index. Multiple annotations on the same field — e.g.
+	* `@db.mongo.search.text` (string) plus `@db.mongo.search.autocomplete`
+	* (autocomplete + string) — accumulate into a single multi-type mapping
+	* instead of overwriting one another.
+	*/
+	_addFieldToSearchIndex(type, _name, fieldName, mappings) {
 		const name = _name || "DEFAULT";
 		let index = this._mongoIndexes.get(mongoIndexKey(type, name));
-		if (!index && type === "search_text") {
-			this._setSearchIndex(type, name, {
-				mappings: { fields: {} },
-				text: { fuzzy: { maxEdits: 0 } }
-			});
-			index = this._mongoIndexes.get(mongoIndexKey(type, name));
-		}
+		if (!index && type === "search_text") index = this._setSearchIndex(type, name, { mappings: { fields: {} } });
 		if (index) {
-			index.definition.mappings.fields[fieldName] = { type: "string" };
-			if (analyzer) index.definition.mappings.fields[fieldName].analyzer = analyzer;
+			const fields = index.definition.mappings.fields;
+			fields[fieldName] = mergeFieldMappings(fields[fieldName], mappings);
 		}
 	}
 };
 /**
+* Normalizes a declared `fuzzy` arg (`0-2`) into the query-time metadata Atlas
+* accepts. Atlas only honors an edit distance of `1` or `2`; `0`/undefined means
+* "no fuzzy", returned as `undefined` so no `fuzzy` clause is ever emitted.
+*/
+function normalizeSearchFuzzy(fuzzy) {
+	return fuzzy === 1 || fuzzy === 2 ? { maxEdits: fuzzy } : void 0;
+}
+/** Narrows the declared `strategy` arg to a known value (undefined → query layer defaults to "compound"). */
+function normalizeSearchStrategy(strategy) {
+	return strategy === "compound" || strategy === "autocomplete" || strategy === "text" ? strategy : void 0;
+}
+/**
+* Merges incoming Atlas field-type mappings into a field's existing mapping,
+* keyed by `type` (a later mapping of the same type replaces the earlier one).
+* Collapses to a single object when one type remains, else an array (Atlas's
+* multi-type field form).
+*/
+function mergeFieldMappings(existing, incoming) {
+	const byType = /* @__PURE__ */ new Map();
+	const order = [];
+	const add = (m) => {
+		if (!byType.has(m.type)) order.push(m.type);
+		byType.set(m.type, m);
+	};
+	if (Array.isArray(existing)) existing.forEach(add);
+	else if (existing) add(existing);
+	incoming.forEach(add);
+	const merged = order.map((t) => byType.get(t));
+	return merged.length === 1 ? merged[0] : merged;
+}
+/**
 * Builds a MongoDB update document from a data object that may contain
 * field ops (`{ $inc: N }`, `{ $dec: N }`, `{ $mul: N }`).
 * Regular fields go into `$set`, ops go into `$inc` / `$mul`. When

package/dist/plugin.cjs

@@ -20,6 +20,18 @@ const analyzers = [
 	"lucene.russian",
 	"lucene.arabic"
 ];
+const tokenizations = [
+	"edgeGram",
+	"rightEdgeGram",
+	"nGram"
+];
+const searchStrategies = [
+	"compound",
+	"autocomplete",
+	"text"
+];
+const strategyDescription = "How `search()` matches a term against this index. Locks the query shape into the index — there is no query-time mode switching.\n\n- `compound` (default) → rank exact-word hits above prefix hits: a wildcard `text` clause **plus** one `autocomplete` clause per autocomplete field. Degrades to plain `text` when the index has no autocomplete field.\n- `autocomplete` → **prefix/typeahead only** — query just the autocomplete fields, no word-match ranking clause.\n- `text` → **word matching only** — a single `text` operator over all string-mapped fields (autocomplete fields are matched via their companion `string` mapping).\n\nTo use the same data with a different strategy, declare a second index and select it per request with `$index`.";
+const fuzzyDescription = "Maximum typo tolerance, applied **at query time** to the search operator.\n\n- `0` (default) → no fuzzy matching (exact tokens).\n- `1` → allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → more typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`).\n\nAtlas only accepts an edit distance of `1` or `2`; `0` simply disables fuzzy. Can be overridden per request via the `$fuzzy` query control.";
 /**
 * MongoDB-specific annotations.
 *
@@ -107,7 +119,7 @@ const annotations = {
 				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\"`)."
+				description: fuzzyDescription
 			}]
 		}),
 		static: new _atscript_core.AnnotationSpec({
@@ -126,13 +138,20 @@ const annotations = {
 					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\")."
+					description: fuzzyDescription
 				},
 				{
 					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\"`."
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text` or `@db.mongo.search.autocomplete`. If not set, defaults to `\"DEFAULT\"`."
+				},
+				{
+					optional: true,
+					name: "strategy",
+					type: "string",
+					description: strategyDescription,
+					values: searchStrategies
 				}
 			]
 		}),
@@ -152,6 +171,51 @@ const annotations = {
 				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\"`."
 			}]
+		}),
+		autocomplete: new _atscript_core.AnnotationSpec({
+			description: "Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).\n\n**Example:**\n```atscript\n@db.mongo.search.autocomplete \"users\"\nusername: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The **name of the search index** (defined by `@db.mongo.search.static`) this field joins. If not set, defaults to `\"DEFAULT\"`."
+				},
+				{
+					optional: true,
+					name: "tokenization",
+					type: "string",
+					description: "How the field is tokenized for partial matching:\n\n- `\"edgeGram\"` (default) → **prefix** matching from the start of each word (`\"art\"` → `\"Artem\"`).\n- `\"nGram\"` → **substring/infix** matching anywhere inside a word (`\"tem\"` → `\"Artem\"`); larger index, slower builds.\n- `\"rightEdgeGram\"` → **suffix** matching from the end of each word.",
+					values: tokenizations
+				},
+				{
+					optional: true,
+					name: "minGrams",
+					type: "number",
+					description: "Minimum number of characters per indexed sequence. Defaults to `2`."
+				},
+				{
+					optional: true,
+					name: "maxGrams",
+					type: "number",
+					description: "Maximum number of characters per indexed sequence. Defaults to `15`."
+				},
+				{
+					optional: true,
+					name: "foldDiacritics",
+					type: "boolean",
+					description: "Whether to fold (ignore) diacritics so `\"café\"` matches `\"cafe\"`. Defaults to `true`."
+				},
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for the companion `string` mapping. Defaults to `\"lucene.standard\"`.",
+					values: analyzers
+				}
+			]
 		})
 	}
 };

package/dist/plugin.mjs

@@ -16,6 +16,18 @@ const analyzers = [
 	"lucene.russian",
 	"lucene.arabic"
 ];
+const tokenizations = [
+	"edgeGram",
+	"rightEdgeGram",
+	"nGram"
+];
+const searchStrategies = [
+	"compound",
+	"autocomplete",
+	"text"
+];
+const strategyDescription = "How `search()` matches a term against this index. Locks the query shape into the index — there is no query-time mode switching.\n\n- `compound` (default) → rank exact-word hits above prefix hits: a wildcard `text` clause **plus** one `autocomplete` clause per autocomplete field. Degrades to plain `text` when the index has no autocomplete field.\n- `autocomplete` → **prefix/typeahead only** — query just the autocomplete fields, no word-match ranking clause.\n- `text` → **word matching only** — a single `text` operator over all string-mapped fields (autocomplete fields are matched via their companion `string` mapping).\n\nTo use the same data with a different strategy, declare a second index and select it per request with `$index`.";
+const fuzzyDescription = "Maximum typo tolerance, applied **at query time** to the search operator.\n\n- `0` (default) → no fuzzy matching (exact tokens).\n- `1` → allows small typos (e.g., `\"mongo\"` ≈ `\"mango\"`).\n- `2` → more typo tolerance (e.g., `\"mongodb\"` ≈ `\"mangodb\"`).\n\nAtlas only accepts an edit distance of `1` or `2`; `0` simply disables fuzzy. Can be overridden per request via the `$fuzzy` query control.";
 /**
 * MongoDB-specific annotations.
 *
@@ -103,7 +115,7 @@ const annotations = {
 				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\"`)."
+				description: fuzzyDescription
 			}]
 		}),
 		static: new AnnotationSpec({
@@ -122,13 +134,20 @@ const annotations = {
 					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\")."
+					description: fuzzyDescription
 				},
 				{
 					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\"`."
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text` or `@db.mongo.search.autocomplete`. If not set, defaults to `\"DEFAULT\"`."
+				},
+				{
+					optional: true,
+					name: "strategy",
+					type: "string",
+					description: strategyDescription,
+					values: searchStrategies
 				}
 			]
 		}),
@@ -148,6 +167,51 @@ const annotations = {
 				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\"`."
 			}]
+		}),
+		autocomplete: new AnnotationSpec({
+			description: "Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).\n\n**Example:**\n```atscript\n@db.mongo.search.autocomplete \"users\"\nusername: string\n```\n",
+			nodeType: ["prop"],
+			multiple: true,
+			argument: [
+				{
+					optional: true,
+					name: "indexName",
+					type: "string",
+					description: "The **name of the search index** (defined by `@db.mongo.search.static`) this field joins. If not set, defaults to `\"DEFAULT\"`."
+				},
+				{
+					optional: true,
+					name: "tokenization",
+					type: "string",
+					description: "How the field is tokenized for partial matching:\n\n- `\"edgeGram\"` (default) → **prefix** matching from the start of each word (`\"art\"` → `\"Artem\"`).\n- `\"nGram\"` → **substring/infix** matching anywhere inside a word (`\"tem\"` → `\"Artem\"`); larger index, slower builds.\n- `\"rightEdgeGram\"` → **suffix** matching from the end of each word.",
+					values: tokenizations
+				},
+				{
+					optional: true,
+					name: "minGrams",
+					type: "number",
+					description: "Minimum number of characters per indexed sequence. Defaults to `2`."
+				},
+				{
+					optional: true,
+					name: "maxGrams",
+					type: "number",
+					description: "Maximum number of characters per indexed sequence. Defaults to `15`."
+				},
+				{
+					optional: true,
+					name: "foldDiacritics",
+					type: "boolean",
+					description: "Whether to fold (ignore) diacritics so `\"café\"` matches `\"cafe\"`. Defaults to `true`."
+				},
+				{
+					optional: true,
+					name: "analyzer",
+					type: "string",
+					description: "The text analyzer for the companion `string` mapping. Defaults to `\"lucene.standard\"`.",
+					values: analyzers
+				}
+			]
 		})
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.101",
+  "version": "0.1.102",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -56,7 +56,7 @@
     "@atscript/core": "^0.1.74",
     "@atscript/typescript": "^0.1.74",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.101"
+    "@atscript/db": "^0.1.102"
   },
   "scripts": {
     "postinstall": "asc -f dts",