@atscript/mongo 0.1.35 → 0.1.36

package/dist/index.cjs

@@ -24,26 +24,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __atscript_utils_db = __toESM(require("@atscript/utils-db"));
 const mongodb = __toESM(require("mongodb"));
-const __atscript_typescript_utils = __toESM(require("@atscript/typescript/utils"));
 
-//#region packages/mongo/src/lib/logger.ts
-const NoopLogger = {
-	error: () => {},
-	warn: () => {},
-	log: () => {},
-	info: () => {},
-	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);
-};
-
-//#endregion
 //#region packages/mongo/src/lib/collection-patcher.ts
-function _define_property$2(obj, key, value) {
+function _define_property$1(obj, key, value) {
 	if (key in obj) Object.defineProperty(obj, key, {
 		value,
 		enumerable: true,
@@ -53,50 +36,7 @@ function _define_property$2(obj, key, value) {
 else obj[key] = value;
 	return obj;
 }
-var CollectionPatcher = class CollectionPatcher {
-	/**
-	* Build a runtime *Validator* that understands the extended patch payload.
-	*
-	*  * Adds per‑array *patch* wrappers (the `$replace`, `$insert`, … fields).
-	*  * Honors `db.patch.strategy === "merge"` metadata.
-	*
-	* @param collection Target collection wrapper
-	* @returns Atscript Validator
-	*/ static prepareValidator(context) {
-		return context.createValidator({
-			plugins: [validateMongoIdPlugin],
-			replace: (def, path) => {
-				if (path === "" && def.type.kind === "object") {
-					const obj = (0, __atscript_typescript_utils.defineAnnotatedType)("object").copyMetadata(def.metadata);
-					for (const [prop, type] of def.type.props.entries()) obj.prop(prop, (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(type).copyMetadata(type.metadata).optional(prop !== "_id").$type);
-					return obj.$type;
-				}
-				if (def.type.kind === "array" && context.flatMap.get(path)?.metadata.get("db.mongo.__topLevelArray") && !def.metadata.has("db.mongo.__patchArrayValue")) {
-					const defArray = def;
-					const mergeStrategy = defArray.metadata.get("db.patch.strategy") === "merge";
-					function getPatchType() {
-						const isPrimitive = (0, __atscript_typescript_utils.isAnnotatedTypeOfPrimitive)(defArray.type.of);
-						if (isPrimitive) return (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(def).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
-						if (defArray.type.of.type.kind === "object") {
-							const objType = defArray.type.of.type;
-							const t = (0, __atscript_typescript_utils.defineAnnotatedType)("object").copyMetadata(defArray.type.of.metadata);
-							const keyProps = CollectionPatcher.getKeyProps(defArray);
-							for (const [key, val] of objType.props.entries()) if (keyProps.size > 0) if (keyProps.has(key)) t.prop(key, (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).$type);
-else t.prop(key, (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).optional().$type);
-else t.prop(key, (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(val).copyMetadata(def.metadata).optional(!!val.optional).$type);
-							return (0, __atscript_typescript_utils.defineAnnotatedType)("array").of(t.$type).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
-						}
-						return undefined;
-					}
-					const fullType = (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(def).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
-					const patchType = getPatchType();
-					return patchType ? (0, __atscript_typescript_utils.defineAnnotatedType)("object").prop("$replace", fullType).prop("$insert", fullType).prop("$upsert", fullType).prop("$update", mergeStrategy ? patchType : fullType).prop("$remove", patchType).optional().$type : (0, __atscript_typescript_utils.defineAnnotatedType)("object").prop("$replace", fullType).prop("$insert", fullType).optional().$type;
-				}
-				return def;
-			},
-			partial: (def, path) => path !== "" && def.metadata.get("db.patch.strategy") === "merge"
-		});
-	}
+var CollectionPatcher = class {
 	/**
 	* Entry point – walk the payload, build `filter`, `update` and `options`.
 	*
@@ -143,8 +83,8 @@ else t.prop(key, (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(va
 		for (const [_key, value] of Object.entries(payload)) {
 			const key = evalKey(_key);
 			const flatType = this.collection.flatMap.get(key);
-			const topLevelArray = flatType?.metadata?.get("db.mongo.__topLevelArray");
-			if (typeof value === "object" && topLevelArray) this.parseArrayPatch(key, value, flatType);
+			const topLevelArray = flatType?.metadata?.get("db.__topLevelArray");
+			if (typeof value === "object" && !Array.isArray(value) && topLevelArray && !flatType?.metadata?.has("db.json")) this.parseArrayPatch(key, value, flatType);
 else if (typeof value === "object" && flatType?.metadata?.get("db.patch.strategy") === "merge") this.flattenPayload(value, key);
 else if (key !== "_id") this._set(key, value);
 		}
@@ -208,22 +148,37 @@ 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, keys, _flatType) {
+	*/ _upsert(key, input, keys, flatType) {
 		if (!input?.length) return;
 		if (keys.length > 0) {
+			const mergeStrategy = flatType.metadata?.get("db.patch.strategy") === "merge";
+			const vars = {
+				acc: "$$value",
+				cand: "$$this"
+			};
+			let appendExpr = "$$cand";
+			if (mergeStrategy) {
+				vars.existing = { $arrayElemAt: [{ $filter: {
+					input: "$$value",
+					as: "el",
+					cond: this._keysEqual(keys, "$$el", "$$this")
+				} }, 0] };
+				appendExpr = { $cond: [
+					{ $ifNull: ["$$existing", false] },
+					{ $mergeObjects: ["$$existing", "$$cand"] },
+					"$$cand"
+				] };
+			}
 			this._set(key, { $reduce: {
 				input,
 				initialValue: { $ifNull: [`$${key}`, []] },
 				in: { $let: {
-					vars: {
-						acc: "$$value",
-						cand: "$$this"
-					},
+					vars,
 					in: { $concatArrays: [{ $filter: {
 						input: "$$acc",
 						as: "el",
 						cond: { $not: this._keysEqual(keys, "$$el", "$$cand") }
-					} }, ["$$cand"]] }
+					} }, [appendExpr]] }
 				} }
 			} });
 			return;
@@ -274,15 +229,15 @@ else this._set(key, { $concatArrays: [{ $ifNull: [`$${key}`, []] }, input] });
 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);
+		_define_property$1(this, "collection", void 0);
+		_define_property$1(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);
-		/** Current `$set` stage being populated. */ _define_property$2(this, "currentSetStage", void 0);
-		/** Additional *options* (mainly `arrayFilters`). */ _define_property$2(this, "optionsObj", void 0);
+		*/ _define_property$1(this, "filterObj", void 0);
+		/** MongoDB *update* document being built. */ _define_property$1(this, "updatePipeline", void 0);
+		/** Current `$set` stage being populated. */ _define_property$1(this, "currentSetStage", void 0);
+		/** Additional *options* (mainly `arrayFilters`). */ _define_property$1(this, "optionsObj", void 0);
 		this.collection = collection;
 		this.payload = payload;
 		this.filterObj = {};
@@ -291,7 +246,7 @@ else this._set(key, { $setDifference: [{ $ifNull: [`$${key}`, []] }, input] });
 		this.optionsObj = {};
 	}
 };
-_define_property$2(CollectionPatcher, "getKeyProps", __atscript_utils_db.getKeyProps);
+_define_property$1(CollectionPatcher, "getKeyProps", __atscript_utils_db.getKeyProps);
 
 //#endregion
 //#region packages/mongo/src/lib/mongo-filter.ts
@@ -320,9 +275,21 @@ function buildMongoFilter(filter) {
 	return (0, __atscript_utils_db.walkFilter)(filter, mongoVisitor) ?? EMPTY;
 }
 
+//#endregion
+//#region packages/mongo/src/lib/validate-plugins.ts
+const validateMongoIdPlugin = (ctx, def, value) => {
+	if (def.type.tags?.has("objectId")) {
+		if (ctx.path === "_id" && (value === undefined || value === null)) {
+			const dbCtx = ctx.context;
+			if (dbCtx && (dbCtx.mode === "insert" || dbCtx.mode === "replace")) return true;
+		}
+		return ctx.validateAnnotatedType(def, value instanceof mongodb.ObjectId ? value.toString() : value);
+	}
+};
+
 //#endregion
 //#region packages/mongo/src/lib/mongo-adapter.ts
-function _define_property$1(obj, key, value) {
+function _define_property(obj, key, value) {
 	if (key in obj) Object.defineProperty(obj, key, {
 		value,
 		enumerable: true,
@@ -334,13 +301,14 @@ else obj[key] = value;
 }
 const INDEX_PREFIX = "atscript__";
 const DEFAULT_INDEX_NAME = "DEFAULT";
+const JOINED_PREFIX = "__joined_";
 function mongoIndexKey(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}`;
 }
 var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter {
 	get _client() {
-		return this.asMongo?.client;
+		return this.client;
 	}
 	async _beginTransaction() {
 		if (this._txDisabled || !this._client) return undefined;
@@ -427,30 +395,260 @@ var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter
 	getValidatorPlugins() {
 		return [validateMongoIdPlugin];
 	}
-	getTopLevelArrayTag() {
-		return "db.mongo.__topLevelArray";
-	}
 	getAdapterTableName(type) {
 		return undefined;
 	}
-	buildInsertValidator(table) {
-		return table.createValidator({
-			plugins: this.getValidatorPlugins(),
-			replace: (type, path) => {
-				if (path === "_id" && type.type.tags?.has("objectId")) return {
-					...type,
-					optional: true
-				};
-				if (table.defaults.has(path)) return {
-					...type,
-					optional: true
-				};
-				return type;
+	supportsNativeRelations() {
+		return true;
+	}
+	async loadRelations(rows, withRelations, relations, foreignKeys, tableResolver) {
+		if (rows.length === 0 || withRelations.length === 0) return;
+		const primaryKeys = this._table.primaryKeys;
+		const relMeta = [];
+		for (const withRel of withRelations) {
+			if (withRel.name.includes(".")) continue;
+			const relation = relations.get(withRel.name);
+			if (!relation) throw new Error(`Unknown relation "${withRel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
+			const lookupResult = this._buildRelationLookup(withRel, relation, foreignKeys, tableResolver);
+			if (!lookupResult) continue;
+			relMeta.push({
+				name: withRel.name,
+				isArray: lookupResult.isArray,
+				relation,
+				nestedWith: this._extractNestedWith(withRel),
+				stages: lookupResult.stages
+			});
+		}
+		if (relMeta.length === 0) return;
+		const pkMatchFilter = this._buildPKMatchFilter(rows, primaryKeys);
+		if (pkMatchFilter) {
+			const pipeline = [{ $match: pkMatchFilter }];
+			for (const meta of relMeta) pipeline.push(...meta.stages);
+			const results = await this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
+			this._mergeRelationResults(rows, results, primaryKeys, relMeta);
+		} else for (const row of rows) for (const meta of relMeta) row[meta.name] = meta.isArray ? [] : null;
+		await this._loadNestedRelations(rows, relMeta, tableResolver);
+	}
+	/** Builds a $match filter to re-select source rows by PK. */ _buildPKMatchFilter(rows, primaryKeys) {
+		if (primaryKeys.length === 1) {
+			const pk = primaryKeys[0];
+			const values = new Set();
+			for (const row of rows) {
+				const v = row[pk];
+				if (v !== null && v !== undefined) values.add(v);
 			}
-		});
+			if (values.size === 0) return undefined;
+			return { [pk]: { $in: [...values] } };
+		}
+		const seen = new Set();
+		const orFilters = [];
+		for (const row of rows) {
+			const key = primaryKeys.map((pk) => String(row[pk] ?? "")).join("\0");
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const condition = {};
+			let valid = true;
+			for (const pk of primaryKeys) {
+				const val = row[pk];
+				if (val === null || val === undefined) {
+					valid = false;
+					break;
+				}
+				condition[pk] = val;
+			}
+			if (valid) orFilters.push(condition);
+		}
+		if (orFilters.length === 0) return undefined;
+		return orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
+	}
+	/** Dispatches to the correct $lookup builder based on relation direction. */ _buildRelationLookup(withRel, relation, foreignKeys, tableResolver) {
+		switch (relation.direction) {
+			case "to": return this._buildToLookup(withRel, relation, foreignKeys);
+			case "from": return this._buildFromLookup(withRel, relation, tableResolver);
+			case "via": return this._buildViaLookup(withRel, relation, tableResolver);
+			default: return undefined;
+		}
+	}
+	/** Builds `let` variable bindings and the corresponding `$expr` match for `$lookup`. */ _buildLookupJoin(localFields, remoteFields, varPrefix) {
+		const letVars = Object.fromEntries(localFields.map((f, i) => [`${varPrefix}${i}`, `$${f}`]));
+		const exprMatch = remoteFields.length === 1 ? { $eq: [`$${remoteFields[0]}`, `$$${varPrefix}0`] } : { $and: remoteFields.map((rf, i) => ({ $eq: [`$${rf}`, `$$${varPrefix}${i}`] })) };
+		return {
+			letVars,
+			exprMatch
+		};
+	}
+	/** $lookup for TO relations (FK is on this table → target). Always single-valued. */ _buildToLookup(withRel, relation, foreignKeys) {
+		const fk = this._findFKForRelationLookup(relation, foreignKeys);
+		if (!fk) return undefined;
+		const innerPipeline = this._buildLookupInnerPipeline(withRel, fk.targetFields);
+		const { letVars, exprMatch } = this._buildLookupJoin(fk.localFields, fk.targetFields, "fk_");
+		const stages = [{ $lookup: {
+			from: fk.targetTable,
+			let: letVars,
+			pipeline: [{ $match: { $expr: exprMatch } }, ...innerPipeline],
+			as: withRel.name
+		} }, { $unwind: {
+			path: `$${withRel.name}`,
+			preserveNullAndEmptyArrays: true
+		} }];
+		return {
+			stages,
+			isArray: false
+		};
+	}
+	/** $lookup for FROM relations (FK is on target → this table). */ _buildFromLookup(withRel, relation, tableResolver) {
+		const targetType = relation.targetType();
+		if (!targetType || !tableResolver) return undefined;
+		const targetMeta = tableResolver(targetType);
+		if (!targetMeta) return undefined;
+		const remoteFK = this._findRemoteFKFromMeta(targetMeta, this._table.tableName, relation.alias);
+		if (!remoteFK) return undefined;
+		const targetTableName = this._resolveRelTargetTableName(relation);
+		const innerPipeline = this._buildLookupInnerPipeline(withRel, remoteFK.fields);
+		const { letVars, exprMatch } = this._buildLookupJoin(remoteFK.targetFields, remoteFK.fields, "pk_");
+		const stages = [{ $lookup: {
+			from: targetTableName,
+			let: letVars,
+			pipeline: [{ $match: { $expr: exprMatch } }, ...innerPipeline],
+			as: withRel.name
+		} }];
+		if (!relation.isArray) stages.push({ $unwind: {
+			path: `$${withRel.name}`,
+			preserveNullAndEmptyArrays: true
+		} });
+		return {
+			stages,
+			isArray: relation.isArray
+		};
+	}
+	/** $lookup for VIA relations (M:N through junction table). Always array. */ _buildViaLookup(withRel, relation, tableResolver) {
+		if (!relation.viaType || !tableResolver) return undefined;
+		const junctionType = relation.viaType();
+		if (!junctionType) return undefined;
+		const junctionMeta = tableResolver(junctionType);
+		if (!junctionMeta) return undefined;
+		const junctionTableName = junctionType.metadata?.get("db.table") || junctionType.id || "";
+		const targetTableName = this._resolveRelTargetTableName(relation);
+		const fkToThis = this._findRemoteFKFromMeta(junctionMeta, this._table.tableName);
+		if (!fkToThis) return undefined;
+		const fkToTarget = this._findRemoteFKFromMeta(junctionMeta, targetTableName);
+		if (!fkToTarget) return undefined;
+		const innerPipeline = this._buildLookupInnerPipeline(withRel, fkToTarget.targetFields);
+		const { letVars, exprMatch } = this._buildLookupJoin(fkToThis.targetFields, fkToThis.fields, "pk_");
+		const stages = [{ $lookup: {
+			from: junctionTableName,
+			let: letVars,
+			pipeline: [
+				{ $match: { $expr: exprMatch } },
+				{ $lookup: {
+					from: targetTableName,
+					localField: fkToTarget.fields[0],
+					foreignField: fkToTarget.targetFields[0],
+					pipeline: innerPipeline,
+					as: "__target"
+				} },
+				{ $unwind: {
+					path: "$__target",
+					preserveNullAndEmptyArrays: false
+				} },
+				{ $replaceRoot: { newRoot: "$__target" } }
+			],
+			as: withRel.name
+		} }];
+		return {
+			stages,
+			isArray: true
+		};
 	}
-	buildPatchValidator(table) {
-		return CollectionPatcher.prepareValidator(this.getPatcherContext());
+	/** Builds inner pipeline stages for relation controls ($sort, $limit, $skip, $select, filter). */ _buildLookupInnerPipeline(withRel, requiredFields) {
+		const pipeline = [];
+		const flatRel = withRel;
+		const nested = withRel.controls || {};
+		const filter = withRel.filter;
+		const sort = nested.$sort || flatRel.$sort;
+		const limit = nested.$limit ?? flatRel.$limit;
+		const skip = nested.$skip ?? flatRel.$skip;
+		const select = nested.$select || flatRel.$select;
+		if (filter && Object.keys(filter).length > 0) pipeline.push({ $match: buildMongoFilter(filter) });
+		if (sort) pipeline.push({ $sort: sort });
+		if (skip) pipeline.push({ $skip: skip });
+		if (limit !== null && limit !== undefined) pipeline.push({ $limit: limit });
+		if (select) {
+			const projection = {};
+			for (const f of select) projection[f] = 1;
+			for (const f of requiredFields) projection[f] = 1;
+			if (!select.includes("_id") && !requiredFields.includes("_id")) projection["_id"] = 0;
+			pipeline.push({ $project: projection });
+		}
+		return pipeline;
+	}
+	/** Extracts nested $with from a WithRelation's controls. */ _extractNestedWith(withRel) {
+		const flatRel = withRel;
+		const nested = withRel.controls || {};
+		const nestedWith = nested.$with || flatRel.$with;
+		return nestedWith && nestedWith.length > 0 ? nestedWith : undefined;
+	}
+	/** Post-processes nested $with by delegating to the target table's own relation loading. */ async _loadNestedRelations(rows, relMeta, tableResolver) {
+		if (!tableResolver) return;
+		const tasks = [];
+		for (const meta of relMeta) {
+			if (!meta.nestedWith || meta.nestedWith.length === 0) continue;
+			const targetType = meta.relation.targetType();
+			if (!targetType) continue;
+			const targetTable = tableResolver(targetType);
+			if (!targetTable) continue;
+			const subRows = [];
+			for (const row of rows) {
+				const val = row[meta.name];
+				if (meta.isArray && Array.isArray(val)) for (const item of val) subRows.push(item);
+else if (val && typeof val === "object") subRows.push(val);
+			}
+			if (subRows.length === 0) continue;
+			tasks.push(targetTable.loadRelations(subRows, meta.nestedWith));
+		}
+		await Promise.all(tasks);
+	}
+	/** Merges aggregation results back onto the original rows by PK. */ _mergeRelationResults(rows, results, primaryKeys, relMeta) {
+		const resultIndex = new Map();
+		for (const doc of results) {
+			const key = primaryKeys.map((pk) => String(doc[pk] ?? "")).join("\0");
+			resultIndex.set(key, doc);
+		}
+		for (const row of rows) {
+			const key = primaryKeys.map((pk) => String(row[pk] ?? "")).join("\0");
+			const enriched = resultIndex.get(key);
+			for (const meta of relMeta) if (enriched) {
+				const value = enriched[meta.name];
+				if (!meta.isArray && Array.isArray(value)) row[meta.name] = value[0] ?? null;
+else row[meta.name] = value ?? (meta.isArray ? [] : null);
+			} else row[meta.name] = meta.isArray ? [] : null;
+		}
+	}
+	/** Finds FK entry for a TO relation from this table's foreignKeys map. */ _findFKForRelationLookup(relation, foreignKeys) {
+		const targetTableName = this._resolveRelTargetTableName(relation);
+		for (const fk of foreignKeys.values()) if (relation.alias) {
+			if (fk.alias === relation.alias) return {
+				localFields: fk.fields,
+				targetFields: fk.targetFields,
+				targetTable: fk.targetTable
+			};
+		} else if (fk.targetTable === targetTableName) return {
+			localFields: fk.fields,
+			targetFields: fk.targetFields,
+			targetTable: fk.targetTable
+		};
+		return undefined;
+	}
+	/** Finds a FK on a remote table that points back to the given table name. */ _findRemoteFKFromMeta(target, thisTableName, alias) {
+		for (const fk of target.foreignKeys.values()) {
+			if (alias && fk.alias === alias && fk.targetTable === thisTableName) return fk;
+			if (!alias && fk.targetTable === thisTableName) return fk;
+		}
+		return undefined;
+	}
+	/** Resolves the target table/collection name from a relation's target type. */ _resolveRelTargetTableName(relation) {
+		const targetType = relation.targetType();
+		return targetType?.metadata?.get("db.table") || targetType?.id || "";
 	}
 	/** Returns the context object used by CollectionPatcher. */ getPatcherContext() {
 		return {
@@ -493,8 +691,8 @@ var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter
 		});
 	}
 	onFieldScanned(field, type, metadata) {
+		if (field === "_id") this._hasExplicitId = true;
 		if (field !== "_id" && metadata.has("meta.id")) {
-			this._table.removePrimaryKey(field);
 			this._addMongoIndexField("unique", "__pk", field);
 			this._table.addUniqueField(field);
 		}
@@ -519,7 +717,28 @@ var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter
 		for (const index of metadata.get("db.mongo.search.filter") || []) this._vectorFilters.set(mongoIndexKey("vector", index.indexName), field);
 	}
 	onAfterFlatten() {
-		this._table.addPrimaryKey("_id");
+		if (this._hasExplicitId) {
+			this._table.addPrimaryKey("_id");
+			for (const field of this._table.originalMetaIdFields) if (field !== "_id") this._table.removePrimaryKey(field);
+		} else {
+			this._table.flatMap.set("_id", {
+				__is_atscript_annotated_type: true,
+				type: {
+					kind: "",
+					designType: "string",
+					tags: new Set(["objectId", "mongo"])
+				},
+				metadata: new Map()
+			});
+			this._table.addUniqueField("_id");
+		}
+		if (this._table.navFields.size > 0) {
+			const isUnderNav = (path) => {
+				for (const nav of this._table.navFields) if (path.startsWith(`${nav}.`)) return true;
+				return false;
+			};
+			for (const field of this._incrementFields) if (isUnderNav(field)) this._incrementFields.delete(field);
+		}
 		for (const [key, value] of this._vectorFilters.entries()) {
 			const index = this._mongoIndexes.get(key);
 			if (index && index.type === "vector") index.definition.fields?.push({
@@ -577,7 +796,7 @@ var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter
 	/**
 	* Builds a MongoDB `$search` pipeline stage.
 	* Override `buildVectorSearchStage` in subclasses to provide embeddings.
-	*/ buildSearchStage(text, indexName) {
+	*/ async buildSearchStage(text, indexName) {
 		const index = this.getMongoSearchIndex(indexName);
 		if (!index) return undefined;
 		if (index.type === "vector") return this.buildVectorSearchStage(text, index);
@@ -592,11 +811,11 @@ var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter
 	/**
 	* Builds a vector search stage. Override in subclasses to generate embeddings.
 	* Returns `undefined` by default (vector search requires custom implementation).
-	*/ buildVectorSearchStage(text, index) {
+	*/ async buildVectorSearchStage(text, index) {
 		return undefined;
 	}
 	async search(text, query, indexName) {
-		const searchStage = this.buildSearchStage(text, indexName);
+		const searchStage = await this.buildSearchStage(text, indexName);
 		if (!searchStage) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 		const filter = buildMongoFilter(query.filter);
 		const controls = query.controls || {};
@@ -610,7 +829,7 @@ else pipeline.push({ $limit: 1e3 });
 		return this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 	}
 	async searchWithCount(text, query, indexName) {
-		const searchStage = this.buildSearchStage(text, indexName);
+		const searchStage = await this.buildSearchStage(text, indexName);
 		if (!searchStage) throw new Error(indexName ? `Search index "${indexName}" not found` : "No search index available");
 		const filter = buildMongoFilter(query.filter);
 		const controls = query.controls || {};
@@ -654,7 +873,6 @@ else pipeline.push({ $limit: 1e3 });
 		};
 	}
 	async collectionExists() {
-		if (this.asMongo) return this.asMongo.collectionExists(this._table.tableName);
 		const cols = await this.db.listCollections({ name: this._table.tableName }).toArray();
 		return cols.length > 0;
 	}
@@ -671,39 +889,48 @@ else pipeline.push({ $limit: 1e3 });
 			await this.db.createCollection(this._table.tableName, opts);
 		}
 	}
+	/**
+	* Wraps an async operation to catch MongoDB duplicate key errors
+	* (code 11000) and rethrow as structured `DbError`.
+	*/ async _wrapDuplicateKeyError(fn) {
+		try {
+			return await fn();
+		} catch (e) {
+			if (e instanceof mongodb.MongoServerError && e.code === 11e3) {
+				const field = e.keyPattern ? Object.keys(e.keyPattern)[0] ?? "" : "";
+				throw new __atscript_utils_db.DbError("CONFLICT", [{
+					path: field,
+					message: e.message
+				}]);
+			}
+			throw e;
+		}
+	}
 	async insertOne(data) {
 		if (this._incrementFields.size > 0) {
 			const fields = this._fieldsNeedingIncrement(data);
 			if (fields.length > 0) {
-				const maxValues = await this._getMaxValues(fields);
-				for (const physical of fields) data[physical] = (maxValues.get(physical) ?? 0) + 1;
+				const nextValues = await this._allocateIncrementValues(fields, 1);
+				for (const physical of fields) data[physical] = nextValues.get(physical) ?? 1;
 			}
 		}
 		this._log("insertOne", data);
-		const result = await this.collection.insertOne(data, this._getSessionOpts());
-		return { insertedId: result.insertedId };
+		const result = await this._wrapDuplicateKeyError(() => this.collection.insertOne(data, this._getSessionOpts()));
+		const metaIdPhysical = this._getMetaIdPhysical();
+		return { insertedId: metaIdPhysical ? data[metaIdPhysical] ?? result.insertedId : result.insertedId };
 	}
 	async insertMany(data) {
 		if (this._incrementFields.size > 0) {
 			const allFields = new Set();
 			for (const item of data) for (const f of this._fieldsNeedingIncrement(item)) allFields.add(f);
-			if (allFields.size > 0) {
-				const maxValues = await this._getMaxValues([...allFields]);
-				for (const item of data) for (const physical of allFields) if (item[physical] === undefined || item[physical] === null) {
-					const next = (maxValues.get(physical) ?? 0) + 1;
-					item[physical] = next;
-					maxValues.set(physical, next);
-				} else if (typeof item[physical] === "number") {
-					const current = maxValues.get(physical) ?? 0;
-					if (item[physical] > current) maxValues.set(physical, item[physical]);
-				}
-			}
+			if (allFields.size > 0) await this._assignBatchIncrements(data, allFields);
 		}
 		this._log("insertMany", `${data.length} docs`);
-		const result = await this.collection.insertMany(data, this._getSessionOpts());
+		const result = await this._wrapDuplicateKeyError(() => this.collection.insertMany(data, this._getSessionOpts()));
+		const metaIdPhysical = this._getMetaIdPhysical();
 		return {
 			insertedCount: result.insertedCount,
-			insertedIds: Object.values(result.insertedIds)
+			insertedIds: metaIdPhysical ? data.map((item, i) => item[metaIdPhysical] ?? result.insertedIds[i]) : Object.values(result.insertedIds)
 		};
 	}
 	async findOne(query) {
@@ -741,7 +968,7 @@ else pipeline.push({ $limit: 1e3 });
 	async replaceOne(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
 		this._log("replaceOne", mongoFilter, data);
-		const result = await this.collection.replaceOne(mongoFilter, data, this._getSessionOpts());
+		const result = await this._wrapDuplicateKeyError(() => this.collection.replaceOne(mongoFilter, data, this._getSessionOpts()));
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -777,14 +1004,180 @@ else pipeline.push({ $limit: 1e3 });
 		const result = await this.collection.deleteMany(mongoFilter, this._getSessionOpts());
 		return { deletedCount: result.deletedCount };
 	}
+	async tableExists() {
+		return this.collectionExists();
+	}
+	async detectTableOptionDrift() {
+		if (!this._cappedOptions) return false;
+		const cols = await this.db.listCollections({ name: this._table.tableName }, { nameOnly: false }).toArray();
+		if (cols.length === 0) return false;
+		const opts = cols[0].options;
+		if (!opts?.capped) return true;
+		if (opts.size !== this._cappedOptions.size) return true;
+		if ((opts.max ?? undefined) !== (this._cappedOptions.max ?? undefined)) return true;
+		return false;
+	}
 	async ensureTable() {
+		if (this._table instanceof __atscript_utils_db.AtscriptDbView && !this._table.isExternal) return this._ensureView(this._table);
 		return this.ensureCollectionExists();
 	}
+	/**
+	* Creates a MongoDB view from the AtscriptDbView's view plan.
+	* Translates joins → $lookup/$unwind, filter → $match, columns → $project.
+	*/ async _ensureView(view) {
+		const exists = await this.collectionExists();
+		if (exists) return;
+		const plan = view.viewPlan;
+		const columns = view.getViewColumnMappings();
+		const pipeline = [];
+		for (const join of plan.joins) {
+			const { localField, foreignField } = this._resolveJoinFields(join.condition, plan.entryTable, join.targetTable);
+			pipeline.push({ $lookup: {
+				from: join.targetTable,
+				localField,
+				foreignField,
+				as: `${JOINED_PREFIX}${join.targetTable}`
+			} });
+			pipeline.push({ $unwind: {
+				path: `$__joined_${join.targetTable}`,
+				preserveNullAndEmptyArrays: true
+			} });
+		}
+		if (plan.filter) {
+			const matchExpr = this._queryNodeToMatch(plan.filter, plan.entryTable);
+			pipeline.push({ $match: matchExpr });
+		}
+		const project = { _id: 0 };
+		for (const col of columns) if (col.sourceTable === plan.entryTable) project[col.viewColumn] = `$${col.sourceColumn}`;
+else project[col.viewColumn] = `$${JOINED_PREFIX}${col.sourceTable}.${col.sourceColumn}`;
+		pipeline.push({ $project: project });
+		this._log("createView", this._table.tableName, plan.entryTable, pipeline);
+		await this.db.createCollection(this._table.tableName, {
+			viewOn: plan.entryTable,
+			pipeline
+		});
+	}
+	/**
+	* Extracts localField/foreignField from a join condition like `User.id = Task.assigneeId`.
+	* The condition is a comparison node with two field refs.
+	*/ _resolveJoinFields(condition, entryTable, joinTable) {
+		const comp = "$and" in condition ? condition.$and[0] : condition;
+		const c = comp;
+		const leftTable = c.left.type ? c.left.type()?.metadata?.get("db.table") || "" : entryTable;
+		if (leftTable === joinTable) return {
+			localField: c.right.field,
+			foreignField: c.left.field
+		};
+		return {
+			localField: c.left.field,
+			foreignField: c.right.field
+		};
+	}
+	/**
+	* Translates an AtscriptQueryNode to a MongoDB $match expression.
+	* Field refs are resolved to dot-path references (joined fields use JOINED_PREFIX).
+	*/ _queryNodeToMatch(node, entryTable) {
+		if ("$and" in node) return { $and: node.$and.map((n) => this._queryNodeToMatch(n, entryTable)) };
+		if ("$or" in node) return { $or: node.$or.map((n) => this._queryNodeToMatch(n, entryTable)) };
+		if ("$not" in node) return { $not: this._queryNodeToMatch(node.$not, entryTable) };
+		const comp = node;
+		const fieldPath = this._resolveViewFieldPath(comp.left, entryTable);
+		if (comp.right && typeof comp.right === "object" && "field" in comp.right) {
+			const rightPath = this._resolveViewFieldPath(comp.right, entryTable);
+			return { $expr: { [comp.op]: [`$${fieldPath}`, `$${rightPath}`] } };
+		}
+		if (comp.op === "$eq") return { [fieldPath]: comp.right };
+		if (comp.op === "$ne") return { [fieldPath]: { $ne: comp.right } };
+		return { [fieldPath]: { [comp.op]: comp.right } };
+	}
+	/**
+	* Resolves a field ref to a MongoDB dot path for view pipeline expressions.
+	*/ _resolveViewFieldPath(ref, entryTable) {
+		if (!ref.type) return ref.field;
+		const table = ref.type()?.metadata?.get("db.table") || "";
+		if (table === entryTable) return ref.field;
+		return `${JOINED_PREFIX}${table}.${ref.field}`;
+	}
 	async dropTable() {
 		this._log("drop", this._table.tableName);
 		await this.collection.drop();
 		this._collection = undefined;
 	}
+	async dropViewByName(viewName) {
+		this._log("dropView", viewName);
+		try {
+			await this.db.collection(viewName).drop();
+		} catch {}
+	}
+	async dropTableByName(tableName) {
+		this._log("dropByName", tableName);
+		try {
+			await this.db.collection(tableName).drop();
+		} catch {}
+	}
+	async recreateTable() {
+		const tableName = this._table.tableName;
+		this._log("recreateTable", tableName);
+		const tempName = `${tableName}__tmp_${Date.now()}`;
+		const source = this.db.collection(tableName);
+		const count = await source.countDocuments();
+		if (count > 0) await source.aggregate([{ $out: tempName }]).toArray();
+		await this.collection.drop();
+		this._collection = undefined;
+		await this.ensureCollectionExists();
+		if (count > 0) {
+			const temp = this.db.collection(tempName);
+			await temp.aggregate([{ $merge: { into: tableName } }]).toArray();
+			await temp.drop();
+		}
+	}
+	async syncColumns(diff) {
+		const renamed = [];
+		const added = [];
+		const update = {};
+		if (diff.renamed.length > 0) {
+			const renameSpec = {};
+			for (const r of diff.renamed) {
+				renameSpec[r.oldName] = r.field.physicalName;
+				renamed.push(r.field.physicalName);
+			}
+			update.$rename = renameSpec;
+		}
+		if (diff.added.length > 0) {
+			const setSpec = {};
+			for (const field of diff.added) {
+				const defaultVal = this._resolveSyncDefault(field);
+				if (defaultVal !== undefined) setSpec[field.physicalName] = defaultVal;
+				added.push(field.physicalName);
+			}
+			if (Object.keys(setSpec).length > 0) update.$set = setSpec;
+		}
+		if (Object.keys(update).length > 0) await this.collection.updateMany({}, update, this._getSessionOpts());
+		return {
+			added,
+			renamed
+		};
+	}
+	async dropColumns(columns) {
+		if (columns.length === 0) return;
+		const unsetSpec = {};
+		for (const col of columns) unsetSpec[col] = "";
+		await this.collection.updateMany({}, { $unset: unsetSpec }, this._getSessionOpts());
+	}
+	async renameTable(oldName) {
+		const newName = this.resolveTableName(false);
+		this._log("renameTable", oldName, "→", newName);
+		await this.db.renameCollection(oldName, newName);
+		this._collection = undefined;
+	}
+	/**
+	* Resolves a field's default value for bulk $set during column sync.
+	* Returns `undefined` if no concrete default can be determined.
+	*/ _resolveSyncDefault(field) {
+		if (!field.defaultValue) return field.optional ? null : undefined;
+		if (field.defaultValue.kind === "value") return field.defaultValue.value;
+		return undefined;
+	}
 	async syncIndexes() {
 		await this.ensureCollectionExists();
 		const allIndexes = new Map();
@@ -917,25 +1310,84 @@ else toUpdate.add(remote.name);
 			}
 		} catch {}
 	}
+	/**
+	* Returns the physical column name of the single @meta.id field (if any).
+	* Used to return the user's logical ID instead of MongoDB's _id on insert.
+	*/ _getMetaIdPhysical() {
+		if (this._metaIdPhysical === undefined) {
+			const fields = this._table.originalMetaIdFields;
+			if (fields.length === 1) {
+				const field = fields[0];
+				this._metaIdPhysical = this._table.columnMap.get(field) ?? field;
+			} else this._metaIdPhysical = null;
+		}
+		return this._metaIdPhysical;
+	}
+	/** Returns the counters collection used for atomic auto-increment. */ get _countersCollection() {
+		return this.db.collection("__atscript_counters");
+	}
 	/** Returns physical field names of increment fields that are undefined in the data. */ _fieldsNeedingIncrement(data) {
 		const result = [];
 		for (const physical of this._incrementFields) if (data[physical] === undefined || data[physical] === null) result.push(physical);
 		return result;
 	}
-	/** Reads current max value for each field via $group aggregation. */ async _getMaxValues(physicalFields) {
-		const aliases = physicalFields.map((f) => [`max__${f.replace(/\./g, "__")}`, f]);
-		const group = { _id: null };
-		for (const [alias, field] of aliases) group[alias] = { $max: `$${field}` };
-		const result = await this.collection.aggregate([{ $group: group }], this._getSessionOpts()).toArray();
-		const maxMap = new Map();
-		if (result.length > 0) {
-			const row = result[0];
-			for (const [alias, field] of aliases) {
-				const val = row[alias];
-				maxMap.set(field, typeof val === "number" ? val : 0);
+	/**
+	* Atomically allocates `count` sequential values for each increment field
+	* using a counter collection. Returns a map of field → first allocated value.
+	*/ async _allocateIncrementValues(physicalFields, count) {
+		const counters = this._countersCollection;
+		const collectionName = this._table.tableName;
+		const result = new Map();
+		for (const field of physicalFields) {
+			const counterId = `${collectionName}.${field}`;
+			const doc = await counters.findOneAndUpdate({ _id: counterId }, { $inc: { seq: count } }, {
+				upsert: true,
+				returnDocument: "after",
+				...this._getSessionOpts()
+			});
+			const seq = doc?.seq ?? count;
+			if (seq === count) {
+				const currentMax = await this._getCurrentFieldMax(field);
+				if (currentMax >= seq) {
+					const adjusted = currentMax + count;
+					await counters.updateOne({ _id: counterId }, { $max: { seq: adjusted } }, this._getSessionOpts());
+					result.set(field, currentMax + 1);
+					continue;
+				}
 			}
+			result.set(field, seq - count + 1);
+		}
+		return result;
+	}
+	/** Reads current max value for a single field via $group aggregation. */ async _getCurrentFieldMax(field) {
+		const alias = `max__${field.replace(/\./g, "__")}`;
+		const agg = await this.collection.aggregate([{ $group: {
+			_id: null,
+			[alias]: { $max: `$${field}` }
+		} }], this._getSessionOpts()).toArray();
+		if (agg.length > 0) {
+			const val = agg[0][alias];
+			if (typeof val === "number") return val;
+		}
+		return 0;
+	}
+	/** Allocates increment values for a batch of items, assigning in order. */ async _assignBatchIncrements(data, allFields) {
+		const fieldCounts = new Map();
+		for (const physical of allFields) {
+			let count = 0;
+			for (const item of data) if (item[physical] === undefined || item[physical] === null) count++;
+			if (count > 0) fieldCounts.set(physical, count);
+		}
+		const fieldCounters = new Map();
+		for (const [physical, count] of fieldCounts) {
+			const allocated = await this._allocateIncrementValues([physical], count);
+			fieldCounters.set(physical, allocated.get(physical) ?? 1);
+		}
+		for (const item of data) for (const physical of allFields) if (item[physical] === undefined || item[physical] === null) {
+			const next = fieldCounters.get(physical) ?? 1;
+			item[physical] = next;
+			fieldCounters.set(physical, next + 1);
 		}
-		return maxMap;
 	}
 	_buildFindOptions(controls) {
 		const opts = {};
@@ -987,11 +1439,11 @@ else {
 			if (analyzer) index.definition.mappings.fields[fieldName].analyzer = analyzer;
 		}
 	}
-	constructor(db, asMongo) {
-		super(), _define_property$1(this, "db", void 0), _define_property$1(this, "asMongo", void 0), _define_property$1(this, "_collection", void 0), _define_property$1(this, "_mongoIndexes", void 0), _define_property$1(this, "_vectorFilters", void 0), _define_property$1(this, "_searchIndexesMap", void 0), _define_property$1(this, "_incrementFields", void 0), _define_property$1(this, "_cappedOptions", void 0), _define_property$1(this, "_txDisabled", void 0), this.db = db, this.asMongo = asMongo, this._mongoIndexes = new Map(), this._vectorFilters = new Map(), this._incrementFields = new Set(), this._txDisabled = false;
+	constructor(db, client) {
+		super(), _define_property(this, "db", void 0), _define_property(this, "client", void 0), _define_property(this, "_collection", void 0), _define_property(this, "_mongoIndexes", void 0), _define_property(this, "_vectorFilters", void 0), _define_property(this, "_searchIndexesMap", void 0), _define_property(this, "_incrementFields", void 0), _define_property(this, "_cappedOptions", void 0), _define_property(this, "_hasExplicitId", void 0), _define_property(this, "_txDisabled", void 0), _define_property(this, "_metaIdPhysical", void 0), this.db = db, this.client = client, this._mongoIndexes = new Map(), this._vectorFilters = new Map(), this._incrementFields = new Set(), this._hasExplicitId = false, this._txDisabled = false;
 	}
 };
-_define_property$1(MongoAdapter, "_noSession", Object.freeze({}));
+_define_property(MongoAdapter, "_noSession", Object.freeze({}));
 function objMatch(o1, o2) {
 	const keys1 = Object.keys(o1);
 	const keys2 = Object.keys(o2);
@@ -1020,51 +1472,15 @@ function vectorFieldsMatch(left, right) {
 	return true;
 }
 
-//#endregion
-//#region packages/mongo/src/lib/as-mongo.ts
-function _define_property(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 AsMongo = class extends __atscript_utils_db.DbSpace {
-	get db() {
-		return this.client.db();
-	}
-	getCollectionsList() {
-		if (!this.collectionsList) this.collectionsList = this.db.listCollections().toArray().then((c) => new Set(c.map((c$1) => c$1.name)));
-		return this.collectionsList;
-	}
-	async collectionExists(name) {
-		const list = await this.getCollectionsList();
-		return list.has(name);
-	}
-	/**
-	* Returns the MongoAdapter for the given type.
-	* Convenience accessor for Mongo-specific adapter operations.
-	*/ getAdapter(type) {
-		return super.getAdapter(type);
-	}
-	constructor(client, logger = NoopLogger) {
-		const resolvedClient = typeof client === "string" ? new mongodb.MongoClient(client) : client;
-		super(() => new MongoAdapter(this.db, this), logger), _define_property(this, "client", void 0), _define_property(this, "collectionsList", void 0);
-		this.client = resolvedClient;
-	}
-};
-
 //#endregion
 //#region packages/mongo/src/lib/index.ts
 function createAdapter(connection, _options) {
-	return new AsMongo(connection);
+	const client = new mongodb.MongoClient(connection);
+	const db = client.db();
+	return new __atscript_utils_db.DbSpace(() => new MongoAdapter(db, client));
 }
 
 //#endregion
-exports.AsMongo = AsMongo
 exports.CollectionPatcher = CollectionPatcher
 exports.MongoAdapter = MongoAdapter
 exports.buildMongoFilter = buildMongoFilter