@atscript/mongo 0.1.33 → 0.1.35

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Atscript
+Copyright (c) 2025-present Artem Maltsev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.cjs

@@ -26,6 +26,16 @@ 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);
@@ -307,7 +317,7 @@ const mongoVisitor = {
 };
 function buildMongoFilter(filter) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY;
-	return (0, __atscript_utils_db.walkFilter)(filter, mongoVisitor);
+	return (0, __atscript_utils_db.walkFilter)(filter, mongoVisitor) ?? EMPTY;
 }
 
 //#endregion
@@ -328,13 +338,58 @@ 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 extends __atscript_utils_db.BaseDbAdapter {
+var MongoAdapter = class MongoAdapter extends __atscript_utils_db.BaseDbAdapter {
+	get _client() {
+		return this.asMongo?.client;
+	}
+	async _beginTransaction() {
+		if (this._txDisabled || !this._client) return undefined;
+		try {
+			const topology = this._client.topology;
+			if (topology) {
+				const desc = topology.description ?? topology.s?.description;
+				const type = desc?.type;
+				if (type === "Single" || type === "Unknown") {
+					this._txDisabled = true;
+					return undefined;
+				}
+			}
+			const session = this._client.startSession();
+			session.startTransaction();
+			return session;
+		} catch {
+			this._txDisabled = true;
+			return undefined;
+		}
+	}
+	async _commitTransaction(state) {
+		if (!state) return;
+		const session = state;
+		try {
+			await session.commitTransaction();
+		} finally {
+			session.endSession();
+		}
+	}
+	async _rollbackTransaction(state) {
+		if (!state) return;
+		const session = state;
+		try {
+			await session.abortTransaction();
+		} finally {
+			session.endSession();
+		}
+	}
+	/** Returns `{ session }` opts if inside a transaction, empty object otherwise. */ _getSessionOpts() {
+		const session = this._getTransactionState();
+		return session ? { session } : MongoAdapter._noSession;
+	}
 	get collection() {
 		if (!this._collection) this._collection = this.db.collection(this.resolveTableName(false));
 		return this._collection;
 	}
 	aggregate(pipeline) {
-		return this.collection.aggregate(pipeline);
+		return this.collection.aggregate(pipeline, this._getSessionOpts());
 	}
 	get idType() {
 		const idProp = this._table.type.type.props.get("_id");
@@ -408,7 +463,11 @@ var MongoAdapter = class extends __atscript_utils_db.BaseDbAdapter {
 		const mongoFilter = buildMongoFilter(filter);
 		const patcher = new CollectionPatcher(this.getPatcherContext(), patch);
 		const { updateFilter, updateOptions } = patcher.preparePatch();
-		const result = await this.collection.updateOne(mongoFilter, updateFilter, updateOptions);
+		this._log("updateOne (patch)", mongoFilter, updateFilter);
+		const result = await this.collection.updateOne(mongoFilter, updateFilter, {
+			...updateOptions,
+			...this._getSessionOpts()
+		});
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -416,6 +475,11 @@ var MongoAdapter = class extends __atscript_utils_db.BaseDbAdapter {
 	}
 	onBeforeFlatten(type) {
 		const typeMeta = type.metadata;
+		const capped = typeMeta.get("db.mongo.capped");
+		if (capped) this._cappedOptions = {
+			size: capped.size,
+			max: capped.max
+		};
 		const dynamicText = typeMeta.get("db.mongo.search.dynamic");
 		if (dynamicText) this._setSearchIndex("dynamic_text", "_", {
 			mappings: { dynamic: true },
@@ -542,7 +606,8 @@ var MongoAdapter = class extends __atscript_utils_db.BaseDbAdapter {
 		if (controls.$limit) pipeline.push({ $limit: controls.$limit });
 else pipeline.push({ $limit: 1e3 });
 		if (controls.$select) pipeline.push({ $project: controls.$select.asProjection });
-		return this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (search)", pipeline);
+		return this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 	}
 	async searchWithCount(text, query, indexName) {
 		const searchStage = this.buildSearchStage(text, indexName);
@@ -562,7 +627,8 @@ else pipeline.push({ $limit: 1e3 });
 				meta: [{ $count: "count" }]
 			} }
 		];
-		const result = await this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (searchWithCount)", pipeline);
+		const result = await this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -580,7 +646,8 @@ else pipeline.push({ $limit: 1e3 });
 			].filter(Boolean),
 			meta: [{ $count: "count" }]
 		} }];
-		const result = await this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (findManyWithCount)", pipeline);
+		const result = await this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -593,7 +660,16 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async ensureCollectionExists() {
 		const exists = await this.collectionExists();
-		if (!exists) await this.db.createCollection(this._table.tableName, { comment: "Created by Atscript Mongo Adapter" });
+		if (!exists) {
+			this._log("createCollection", this._table.tableName);
+			const opts = { comment: "Created by Atscript Mongo Adapter" };
+			if (this._cappedOptions) {
+				opts.capped = true;
+				opts.size = this._cappedOptions.size;
+				if (this._cappedOptions.max !== null && this._cappedOptions.max !== undefined) opts.max = this._cappedOptions.max;
+			}
+			await this.db.createCollection(this._table.tableName, opts);
+		}
 	}
 	async insertOne(data) {
 		if (this._incrementFields.size > 0) {
@@ -603,7 +679,8 @@ else pipeline.push({ $limit: 1e3 });
 				for (const physical of fields) data[physical] = (maxValues.get(physical) ?? 0) + 1;
 			}
 		}
-		const result = await this.collection.insertOne(data);
+		this._log("insertOne", data);
+		const result = await this.collection.insertOne(data, this._getSessionOpts());
 		return { insertedId: result.insertedId };
 	}
 	async insertMany(data) {
@@ -622,7 +699,8 @@ else pipeline.push({ $limit: 1e3 });
 				}
 			}
 		}
-		const result = await this.collection.insertMany(data);
+		this._log("insertMany", `${data.length} docs`);
+		const result = await this.collection.insertMany(data, this._getSessionOpts());
 		return {
 			insertedCount: result.insertedCount,
 			insertedIds: Object.values(result.insertedIds)
@@ -631,20 +709,30 @@ else pipeline.push({ $limit: 1e3 });
 	async findOne(query) {
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
-		return this.collection.findOne(filter, opts);
+		this._log("findOne", filter, opts);
+		return this.collection.findOne(filter, {
+			...opts,
+			...this._getSessionOpts()
+		});
 	}
 	async findMany(query) {
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
-		return this.collection.find(filter, opts).toArray();
+		this._log("findMany", filter, opts);
+		return this.collection.find(filter, {
+			...opts,
+			...this._getSessionOpts()
+		}).toArray();
 	}
 	async count(query) {
 		const filter = buildMongoFilter(query.filter);
-		return this.collection.countDocuments(filter);
+		this._log("countDocuments", filter);
+		return this.collection.countDocuments(filter, this._getSessionOpts());
 	}
 	async updateOne(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateOne(mongoFilter, { $set: data });
+		this._log("updateOne", mongoFilter, { $set: data });
+		const result = await this.collection.updateOne(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -652,7 +740,8 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async replaceOne(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.replaceOne(mongoFilter, data);
+		this._log("replaceOne", mongoFilter, data);
+		const result = await this.collection.replaceOne(mongoFilter, data, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -660,12 +749,14 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async deleteOne(filter) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.deleteOne(mongoFilter);
+		this._log("deleteOne", mongoFilter);
+		const result = await this.collection.deleteOne(mongoFilter, this._getSessionOpts());
 		return { deletedCount: result.deletedCount };
 	}
 	async updateMany(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateMany(mongoFilter, { $set: data });
+		this._log("updateMany", mongoFilter, { $set: data });
+		const result = await this.collection.updateMany(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -673,7 +764,8 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async replaceMany(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateMany(mongoFilter, { $set: data });
+		this._log("replaceMany", mongoFilter, { $set: data });
+		const result = await this.collection.updateMany(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -681,12 +773,18 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async deleteMany(filter) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.deleteMany(mongoFilter);
+		this._log("deleteMany", mongoFilter);
+		const result = await this.collection.deleteMany(mongoFilter, this._getSessionOpts());
 		return { deletedCount: result.deletedCount };
 	}
 	async ensureTable() {
 		return this.ensureCollectionExists();
 	}
+	async dropTable() {
+		this._log("drop", this._table.tableName);
+		await this.collection.drop();
+		this._collection = undefined;
+	}
 	async syncIndexes() {
 		await this.ensureCollectionExists();
 		const allIndexes = new Map();
@@ -730,21 +828,29 @@ else pipeline.push({ $limit: 1e3 });
 					case "unique":
 					case "text": {
 						if ((local.type === "text" || objMatch(local.fields, remote.key)) && objMatch(local.weights || {}, remote.weights || {})) indexesToCreate.delete(remote.name);
-else await this.collection.dropIndex(remote.name);
+else {
+							this._log("dropIndex", remote.name);
+							await this.collection.dropIndex(remote.name);
+						}
 						break;
 					}
 					default:
 				}
-			} else await this.collection.dropIndex(remote.name);
+			} else {
+				this._log("dropIndex", remote.name);
+				await this.collection.dropIndex(remote.name);
+			}
 		}
 		for (const [key, value] of allIndexes.entries()) switch (value.type) {
 			case "plain": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex", key, value.fields);
 				await this.collection.createIndex(value.fields, { name: key });
 				break;
 			}
 			case "unique": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex (unique)", key, value.fields);
 				await this.collection.createIndex(value.fields, {
 					name: key,
 					unique: true
@@ -753,6 +859,7 @@ else await this.collection.dropIndex(remote.name);
 			}
 			case "text": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex (text)", key, value.fields);
 				await this.collection.createIndex(value.fields, {
 					weights: value.weights,
 					name: key
@@ -784,18 +891,26 @@ else toUpdate.add(remote.name);
 						}
 						default:
 					}
-				} else if (remote.status !== "DELETING") await this.collection.dropSearchIndex(remote.name);
+				} else if (remote.status !== "DELETING") {
+					this._log("dropSearchIndex", remote.name);
+					await this.collection.dropSearchIndex(remote.name);
+				}
 			}
 			for (const [key, value] of indexesToCreate.entries()) switch (value.type) {
 				case "dynamic_text":
 				case "search_text":
 				case "vector": {
-					if (toUpdate.has(key)) await this.collection.updateSearchIndex(key, value.definition);
-else await this.collection.createSearchIndex({
-						name: key,
-						type: value.type === "vector" ? "vectorSearch" : "search",
-						definition: value.definition
-					});
+					if (toUpdate.has(key)) {
+						this._log("updateSearchIndex", key, value.definition);
+						await this.collection.updateSearchIndex(key, value.definition);
+					} else {
+						this._log("createSearchIndex", key, value.type);
+						await this.collection.createSearchIndex({
+							name: key,
+							type: value.type === "vector" ? "vectorSearch" : "search",
+							definition: value.definition
+						});
+					}
 					break;
 				}
 				default:
@@ -811,7 +926,7 @@ else await this.collection.createSearchIndex({
 		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 }]).toArray();
+		const result = await this.collection.aggregate([{ $group: group }], this._getSessionOpts()).toArray();
 		const maxMap = new Map();
 		if (result.length > 0) {
 			const row = result[0];
@@ -873,9 +988,10 @@ else {
 		}
 	}
 	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), this.db = db, this.asMongo = asMongo, this._mongoIndexes = new Map(), this._vectorFilters = new Map(), this._incrementFields = new Set();
+		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;
 	}
 };
+_define_property$1(MongoAdapter, "_noSession", Object.freeze({}));
 function objMatch(o1, o2) {
 	const keys1 = Object.keys(o1);
 	const keys2 = Object.keys(o2);
@@ -904,16 +1020,6 @@ function vectorFieldsMatch(left, right) {
 	return true;
 }
 
-//#endregion
-//#region packages/mongo/src/lib/logger.ts
-const NoopLogger = {
-	error: () => {},
-	warn: () => {},
-	log: () => {},
-	info: () => {},
-	debug: () => {}
-};
-
 //#endregion
 //#region packages/mongo/src/lib/as-mongo.ts
 function _define_property(obj, key, value) {
@@ -926,7 +1032,7 @@ function _define_property(obj, key, value) {
 else obj[key] = value;
 	return obj;
 }
-var AsMongo = class {
+var AsMongo = class extends __atscript_utils_db.DbSpace {
 	get db() {
 		return this.client.db();
 	}
@@ -938,39 +1044,29 @@ var AsMongo = class {
 		const list = await this.getCollectionsList();
 		return list.has(name);
 	}
-	getAdapter(type) {
-		this._ensureCreated(type);
-		return this._adapters.get(type);
-	}
-	getTable(type, logger) {
-		this._ensureCreated(type, logger);
-		return this._tables.get(type);
-	}
-	_ensureCreated(type, logger) {
-		if (!this._adapters.has(type)) {
-			const adapter = new MongoAdapter(this.db, this);
-			const table = new __atscript_utils_db.AtscriptDbTable(type, adapter, logger || this.logger);
-			this._adapters.set(type, adapter);
-			this._tables.set(type, table);
-		}
+	/**
+	* Returns the MongoAdapter for the given type.
+	* Convenience accessor for Mongo-specific adapter operations.
+	*/ getAdapter(type) {
+		return super.getAdapter(type);
 	}
 	constructor(client, logger = NoopLogger) {
-		_define_property(this, "logger", void 0);
-		_define_property(this, "client", void 0);
-		_define_property(this, "collectionsList", void 0);
-		_define_property(this, "_adapters", void 0);
-		_define_property(this, "_tables", void 0);
-		this.logger = logger;
-		this._adapters = new WeakMap();
-		this._tables = new WeakMap();
-		if (typeof client === "string") this.client = new mongodb.MongoClient(client);
-else this.client = client;
+		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);
+}
+
 //#endregion
 exports.AsMongo = AsMongo
 exports.CollectionPatcher = CollectionPatcher
 exports.MongoAdapter = MongoAdapter
 exports.buildMongoFilter = buildMongoFilter
+exports.createAdapter = createAdapter
 exports.validateMongoIdPlugin = validateMongoIdPlugin

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { TAtscriptAnnotatedType, TValidatorOptions, Validator, TValidatorPlugin, TMetadataMap } from '@atscript/typescript/utils';
-import { AtscriptDbTable, getKeyProps, BaseDbAdapter, FilterExpr, TDbUpdateResult, TSearchIndexInfo, DbQuery, TDbInsertResult, TDbInsertManyResult, TDbDeleteResult } from '@atscript/utils-db';
 import * as mongodb from 'mongodb';
-import { MongoClient, Filter, UpdateFilter, Document, UpdateOptions, Db, Collection, AggregationCursor, ObjectId } from 'mongodb';
+import { Filter, UpdateFilter, Document, UpdateOptions, Db, ClientSession, Collection, AggregationCursor, ObjectId, MongoClient } from 'mongodb';
+import { TAtscriptAnnotatedType, TValidatorOptions, Validator, TValidatorPlugin, TMetadataMap } from '@atscript/typescript/utils';
+import { getKeyProps, BaseDbAdapter, AtscriptDbTable, FilterExpr, TDbUpdateResult, TSearchIndexInfo, DbQuery, TDbInsertResult, TDbInsertManyResult, TDbDeleteResult, DbSpace } from '@atscript/utils-db';
 
 interface TGenericLogger {
     error(...messages: any[]): void;
@@ -11,21 +11,6 @@ interface TGenericLogger {
     debug(...messages: any[]): void;
 }
 
-declare class AsMongo {
-    protected readonly logger: TGenericLogger;
-    readonly client: MongoClient;
-    constructor(client: string | MongoClient, logger?: TGenericLogger);
-    get db(): mongodb.Db;
-    protected collectionsList?: Promise<Set<string>>;
-    protected getCollectionsList(): Promise<Set<string>>;
-    collectionExists(name: string): Promise<boolean>;
-    getAdapter<T extends TAtscriptAnnotatedType>(type: T): MongoAdapter;
-    getTable<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbTable<T, any, any, any>;
-    private _ensureCreated;
-    private _adapters;
-    private _tables;
-}
-
 /**
  * Context interface for CollectionPatcher.
  * Decouples the patcher from AsCollection, allowing MongoAdapter to provide this.
@@ -192,7 +177,23 @@ declare class MongoAdapter extends BaseDbAdapter {
     protected _searchIndexesMap?: Map<string, TMongoIndex>;
     /** Physical field names with @db.default.fn "increment". */
     protected _incrementFields: Set<string>;
+    /** Capped collection options from @db.mongo.capped. */
+    protected _cappedOptions?: {
+        size: number;
+        max?: number;
+    };
     constructor(db: Db, asMongo?: AsMongo | undefined);
+    private get _client();
+    /** Whether transaction support has been detected as unavailable (standalone MongoDB). */
+    private _txDisabled;
+    protected _beginTransaction(): Promise<unknown>;
+    protected _commitTransaction(state: unknown): Promise<void>;
+    protected _rollbackTransaction(state: unknown): Promise<void>;
+    private static readonly _noSession;
+    /** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
+    protected _getSessionOpts(): {
+        session: ClientSession;
+    } | Record<string, never>;
     get collection(): Collection<any>;
     aggregate(pipeline: Document[]): AggregationCursor;
     get idType(): 'string' | 'number' | 'objectId';
@@ -254,6 +255,7 @@ declare class MongoAdapter extends BaseDbAdapter {
     replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
     ensureTable(): Promise<void>;
+    dropTable(): Promise<void>;
     syncIndexes(): Promise<void>;
     /** Returns physical field names of increment fields that are undefined in the data. */
     private _fieldsNeedingIncrement;
@@ -287,6 +289,31 @@ interface TMongoSearchIndexDefinition {
     };
 }
 
+/**
+ * MongoDB database space — extends {@link DbSpace} with MongoDB-specific
+ * features (cached collection list, `Db` access, `MongoAdapter` factory).
+ *
+ * ```typescript
+ * const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
+ * const users = asMongo.getTable(UsersType)
+ * const posts = asMongo.getTable(PostsType)
+ * // Relation loading via $with works automatically
+ * ```
+ */
+declare class AsMongo extends DbSpace {
+    readonly client: MongoClient;
+    constructor(client: string | MongoClient, logger?: TGenericLogger);
+    get db(): mongodb.Db;
+    protected collectionsList?: Promise<Set<string>>;
+    protected getCollectionsList(): Promise<Set<string>>;
+    collectionExists(name: string): Promise<boolean>;
+    /**
+     * Returns the MongoAdapter for the given type.
+     * Convenience accessor for Mongo-specific adapter operations.
+     */
+    getAdapter(type: TAtscriptAnnotatedType): MongoAdapter;
+}
+
 /**
  * Translates a generic {@link FilterExpr} into a MongoDB-compatible
  * {@link Filter} document.
@@ -298,5 +325,7 @@ declare function buildMongoFilter(filter: FilterExpr): Filter<any>;
 
 declare const validateMongoIdPlugin: TValidatorPlugin;
 
-export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, validateMongoIdPlugin };
+declare function createAdapter(connection: string, _options?: Record<string, unknown>): AsMongo;
+
+export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, createAdapter, validateMongoIdPlugin };
 export type { TCollectionPatcherContext, TMongoIndex, TMongoSearchIndexDefinition, TPlainIndex, TSearchIndex };

package/dist/index.mjs

@@ -1,7 +1,17 @@
-import { AtscriptDbTable, BaseDbAdapter, getKeyProps, walkFilter } from "@atscript/utils-db";
+import { BaseDbAdapter, DbSpace, getKeyProps, walkFilter } from "@atscript/utils-db";
 import { MongoClient, ObjectId } from "mongodb";
 import { defineAnnotatedType, isAnnotatedTypeOfPrimitive } from "@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 ObjectId ? value.toString() : value);
@@ -283,7 +293,7 @@ const mongoVisitor = {
 };
 function buildMongoFilter(filter) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY;
-	return walkFilter(filter, mongoVisitor);
+	return walkFilter(filter, mongoVisitor) ?? EMPTY;
 }
 
 //#endregion
@@ -304,13 +314,58 @@ 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 extends BaseDbAdapter {
+var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
+	get _client() {
+		return this.asMongo?.client;
+	}
+	async _beginTransaction() {
+		if (this._txDisabled || !this._client) return undefined;
+		try {
+			const topology = this._client.topology;
+			if (topology) {
+				const desc = topology.description ?? topology.s?.description;
+				const type = desc?.type;
+				if (type === "Single" || type === "Unknown") {
+					this._txDisabled = true;
+					return undefined;
+				}
+			}
+			const session = this._client.startSession();
+			session.startTransaction();
+			return session;
+		} catch {
+			this._txDisabled = true;
+			return undefined;
+		}
+	}
+	async _commitTransaction(state) {
+		if (!state) return;
+		const session = state;
+		try {
+			await session.commitTransaction();
+		} finally {
+			session.endSession();
+		}
+	}
+	async _rollbackTransaction(state) {
+		if (!state) return;
+		const session = state;
+		try {
+			await session.abortTransaction();
+		} finally {
+			session.endSession();
+		}
+	}
+	/** Returns `{ session }` opts if inside a transaction, empty object otherwise. */ _getSessionOpts() {
+		const session = this._getTransactionState();
+		return session ? { session } : MongoAdapter._noSession;
+	}
 	get collection() {
 		if (!this._collection) this._collection = this.db.collection(this.resolveTableName(false));
 		return this._collection;
 	}
 	aggregate(pipeline) {
-		return this.collection.aggregate(pipeline);
+		return this.collection.aggregate(pipeline, this._getSessionOpts());
 	}
 	get idType() {
 		const idProp = this._table.type.type.props.get("_id");
@@ -384,7 +439,11 @@ var MongoAdapter = class extends BaseDbAdapter {
 		const mongoFilter = buildMongoFilter(filter);
 		const patcher = new CollectionPatcher(this.getPatcherContext(), patch);
 		const { updateFilter, updateOptions } = patcher.preparePatch();
-		const result = await this.collection.updateOne(mongoFilter, updateFilter, updateOptions);
+		this._log("updateOne (patch)", mongoFilter, updateFilter);
+		const result = await this.collection.updateOne(mongoFilter, updateFilter, {
+			...updateOptions,
+			...this._getSessionOpts()
+		});
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -392,6 +451,11 @@ var MongoAdapter = class extends BaseDbAdapter {
 	}
 	onBeforeFlatten(type) {
 		const typeMeta = type.metadata;
+		const capped = typeMeta.get("db.mongo.capped");
+		if (capped) this._cappedOptions = {
+			size: capped.size,
+			max: capped.max
+		};
 		const dynamicText = typeMeta.get("db.mongo.search.dynamic");
 		if (dynamicText) this._setSearchIndex("dynamic_text", "_", {
 			mappings: { dynamic: true },
@@ -518,7 +582,8 @@ var MongoAdapter = class extends BaseDbAdapter {
 		if (controls.$limit) pipeline.push({ $limit: controls.$limit });
 else pipeline.push({ $limit: 1e3 });
 		if (controls.$select) pipeline.push({ $project: controls.$select.asProjection });
-		return this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (search)", pipeline);
+		return this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 	}
 	async searchWithCount(text, query, indexName) {
 		const searchStage = this.buildSearchStage(text, indexName);
@@ -538,7 +603,8 @@ else pipeline.push({ $limit: 1e3 });
 				meta: [{ $count: "count" }]
 			} }
 		];
-		const result = await this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (searchWithCount)", pipeline);
+		const result = await this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -556,7 +622,8 @@ else pipeline.push({ $limit: 1e3 });
 			].filter(Boolean),
 			meta: [{ $count: "count" }]
 		} }];
-		const result = await this.collection.aggregate(pipeline).toArray();
+		this._log("aggregate (findManyWithCount)", pipeline);
+		const result = await this.collection.aggregate(pipeline, this._getSessionOpts()).toArray();
 		return {
 			data: result[0]?.data || [],
 			count: result[0]?.meta[0]?.count || 0
@@ -569,7 +636,16 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async ensureCollectionExists() {
 		const exists = await this.collectionExists();
-		if (!exists) await this.db.createCollection(this._table.tableName, { comment: "Created by Atscript Mongo Adapter" });
+		if (!exists) {
+			this._log("createCollection", this._table.tableName);
+			const opts = { comment: "Created by Atscript Mongo Adapter" };
+			if (this._cappedOptions) {
+				opts.capped = true;
+				opts.size = this._cappedOptions.size;
+				if (this._cappedOptions.max !== null && this._cappedOptions.max !== undefined) opts.max = this._cappedOptions.max;
+			}
+			await this.db.createCollection(this._table.tableName, opts);
+		}
 	}
 	async insertOne(data) {
 		if (this._incrementFields.size > 0) {
@@ -579,7 +655,8 @@ else pipeline.push({ $limit: 1e3 });
 				for (const physical of fields) data[physical] = (maxValues.get(physical) ?? 0) + 1;
 			}
 		}
-		const result = await this.collection.insertOne(data);
+		this._log("insertOne", data);
+		const result = await this.collection.insertOne(data, this._getSessionOpts());
 		return { insertedId: result.insertedId };
 	}
 	async insertMany(data) {
@@ -598,7 +675,8 @@ else pipeline.push({ $limit: 1e3 });
 				}
 			}
 		}
-		const result = await this.collection.insertMany(data);
+		this._log("insertMany", `${data.length} docs`);
+		const result = await this.collection.insertMany(data, this._getSessionOpts());
 		return {
 			insertedCount: result.insertedCount,
 			insertedIds: Object.values(result.insertedIds)
@@ -607,20 +685,30 @@ else pipeline.push({ $limit: 1e3 });
 	async findOne(query) {
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
-		return this.collection.findOne(filter, opts);
+		this._log("findOne", filter, opts);
+		return this.collection.findOne(filter, {
+			...opts,
+			...this._getSessionOpts()
+		});
 	}
 	async findMany(query) {
 		const filter = buildMongoFilter(query.filter);
 		const opts = this._buildFindOptions(query.controls);
-		return this.collection.find(filter, opts).toArray();
+		this._log("findMany", filter, opts);
+		return this.collection.find(filter, {
+			...opts,
+			...this._getSessionOpts()
+		}).toArray();
 	}
 	async count(query) {
 		const filter = buildMongoFilter(query.filter);
-		return this.collection.countDocuments(filter);
+		this._log("countDocuments", filter);
+		return this.collection.countDocuments(filter, this._getSessionOpts());
 	}
 	async updateOne(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateOne(mongoFilter, { $set: data });
+		this._log("updateOne", mongoFilter, { $set: data });
+		const result = await this.collection.updateOne(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -628,7 +716,8 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async replaceOne(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.replaceOne(mongoFilter, data);
+		this._log("replaceOne", mongoFilter, data);
+		const result = await this.collection.replaceOne(mongoFilter, data, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -636,12 +725,14 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async deleteOne(filter) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.deleteOne(mongoFilter);
+		this._log("deleteOne", mongoFilter);
+		const result = await this.collection.deleteOne(mongoFilter, this._getSessionOpts());
 		return { deletedCount: result.deletedCount };
 	}
 	async updateMany(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateMany(mongoFilter, { $set: data });
+		this._log("updateMany", mongoFilter, { $set: data });
+		const result = await this.collection.updateMany(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -649,7 +740,8 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async replaceMany(filter, data) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.updateMany(mongoFilter, { $set: data });
+		this._log("replaceMany", mongoFilter, { $set: data });
+		const result = await this.collection.updateMany(mongoFilter, { $set: data }, this._getSessionOpts());
 		return {
 			matchedCount: result.matchedCount,
 			modifiedCount: result.modifiedCount
@@ -657,12 +749,18 @@ else pipeline.push({ $limit: 1e3 });
 	}
 	async deleteMany(filter) {
 		const mongoFilter = buildMongoFilter(filter);
-		const result = await this.collection.deleteMany(mongoFilter);
+		this._log("deleteMany", mongoFilter);
+		const result = await this.collection.deleteMany(mongoFilter, this._getSessionOpts());
 		return { deletedCount: result.deletedCount };
 	}
 	async ensureTable() {
 		return this.ensureCollectionExists();
 	}
+	async dropTable() {
+		this._log("drop", this._table.tableName);
+		await this.collection.drop();
+		this._collection = undefined;
+	}
 	async syncIndexes() {
 		await this.ensureCollectionExists();
 		const allIndexes = new Map();
@@ -706,21 +804,29 @@ else pipeline.push({ $limit: 1e3 });
 					case "unique":
 					case "text": {
 						if ((local.type === "text" || objMatch(local.fields, remote.key)) && objMatch(local.weights || {}, remote.weights || {})) indexesToCreate.delete(remote.name);
-else await this.collection.dropIndex(remote.name);
+else {
+							this._log("dropIndex", remote.name);
+							await this.collection.dropIndex(remote.name);
+						}
 						break;
 					}
 					default:
 				}
-			} else await this.collection.dropIndex(remote.name);
+			} else {
+				this._log("dropIndex", remote.name);
+				await this.collection.dropIndex(remote.name);
+			}
 		}
 		for (const [key, value] of allIndexes.entries()) switch (value.type) {
 			case "plain": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex", key, value.fields);
 				await this.collection.createIndex(value.fields, { name: key });
 				break;
 			}
 			case "unique": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex (unique)", key, value.fields);
 				await this.collection.createIndex(value.fields, {
 					name: key,
 					unique: true
@@ -729,6 +835,7 @@ else await this.collection.dropIndex(remote.name);
 			}
 			case "text": {
 				if (!indexesToCreate.has(key)) continue;
+				this._log("createIndex (text)", key, value.fields);
 				await this.collection.createIndex(value.fields, {
 					weights: value.weights,
 					name: key
@@ -760,18 +867,26 @@ else toUpdate.add(remote.name);
 						}
 						default:
 					}
-				} else if (remote.status !== "DELETING") await this.collection.dropSearchIndex(remote.name);
+				} else if (remote.status !== "DELETING") {
+					this._log("dropSearchIndex", remote.name);
+					await this.collection.dropSearchIndex(remote.name);
+				}
 			}
 			for (const [key, value] of indexesToCreate.entries()) switch (value.type) {
 				case "dynamic_text":
 				case "search_text":
 				case "vector": {
-					if (toUpdate.has(key)) await this.collection.updateSearchIndex(key, value.definition);
-else await this.collection.createSearchIndex({
-						name: key,
-						type: value.type === "vector" ? "vectorSearch" : "search",
-						definition: value.definition
-					});
+					if (toUpdate.has(key)) {
+						this._log("updateSearchIndex", key, value.definition);
+						await this.collection.updateSearchIndex(key, value.definition);
+					} else {
+						this._log("createSearchIndex", key, value.type);
+						await this.collection.createSearchIndex({
+							name: key,
+							type: value.type === "vector" ? "vectorSearch" : "search",
+							definition: value.definition
+						});
+					}
 					break;
 				}
 				default:
@@ -787,7 +902,7 @@ else await this.collection.createSearchIndex({
 		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 }]).toArray();
+		const result = await this.collection.aggregate([{ $group: group }], this._getSessionOpts()).toArray();
 		const maxMap = new Map();
 		if (result.length > 0) {
 			const row = result[0];
@@ -849,9 +964,10 @@ else {
 		}
 	}
 	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), this.db = db, this.asMongo = asMongo, this._mongoIndexes = new Map(), this._vectorFilters = new Map(), this._incrementFields = new Set();
+		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;
 	}
 };
+_define_property$1(MongoAdapter, "_noSession", Object.freeze({}));
 function objMatch(o1, o2) {
 	const keys1 = Object.keys(o1);
 	const keys2 = Object.keys(o2);
@@ -880,16 +996,6 @@ function vectorFieldsMatch(left, right) {
 	return true;
 }
 
-//#endregion
-//#region packages/mongo/src/lib/logger.ts
-const NoopLogger = {
-	error: () => {},
-	warn: () => {},
-	log: () => {},
-	info: () => {},
-	debug: () => {}
-};
-
 //#endregion
 //#region packages/mongo/src/lib/as-mongo.ts
 function _define_property(obj, key, value) {
@@ -902,7 +1008,7 @@ function _define_property(obj, key, value) {
 else obj[key] = value;
 	return obj;
 }
-var AsMongo = class {
+var AsMongo = class extends DbSpace {
 	get db() {
 		return this.client.db();
 	}
@@ -914,35 +1020,24 @@ var AsMongo = class {
 		const list = await this.getCollectionsList();
 		return list.has(name);
 	}
-	getAdapter(type) {
-		this._ensureCreated(type);
-		return this._adapters.get(type);
-	}
-	getTable(type, logger) {
-		this._ensureCreated(type, logger);
-		return this._tables.get(type);
-	}
-	_ensureCreated(type, logger) {
-		if (!this._adapters.has(type)) {
-			const adapter = new MongoAdapter(this.db, this);
-			const table = new AtscriptDbTable(type, adapter, logger || this.logger);
-			this._adapters.set(type, adapter);
-			this._tables.set(type, table);
-		}
+	/**
+	* Returns the MongoAdapter for the given type.
+	* Convenience accessor for Mongo-specific adapter operations.
+	*/ getAdapter(type) {
+		return super.getAdapter(type);
 	}
 	constructor(client, logger = NoopLogger) {
-		_define_property(this, "logger", void 0);
-		_define_property(this, "client", void 0);
-		_define_property(this, "collectionsList", void 0);
-		_define_property(this, "_adapters", void 0);
-		_define_property(this, "_tables", void 0);
-		this.logger = logger;
-		this._adapters = new WeakMap();
-		this._tables = new WeakMap();
-		if (typeof client === "string") this.client = new MongoClient(client);
-else this.client = client;
+		const resolvedClient = typeof client === "string" ? new 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
-export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, validateMongoIdPlugin };
+//#region packages/mongo/src/lib/index.ts
+function createAdapter(connection, _options) {
+	return new AsMongo(connection);
+}
+
+//#endregion
+export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, createAdapter, validateMongoIdPlugin };

package/dist/plugin.cjs

@@ -82,6 +82,22 @@ const annotations = {
 			});
 		}
 	}),
+	capped: new __atscript_core.AnnotationSpec({
+		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: [{
+			optional: false,
+			name: "size",
+			type: "number",
+			description: "Maximum size of the collection in **bytes**."
+		}, {
+			optional: true,
+			name: "max",
+			type: "number",
+			description: "Maximum number of documents in the collection. If omitted, only the byte size limit applies."
+		}]
+	}),
 	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",

package/dist/plugin.mjs

@@ -58,6 +58,22 @@ const annotations = {
 			});
 		}
 	}),
+	capped: new AnnotationSpec({
+		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: [{
+			optional: false,
+			name: "size",
+			type: "number",
+			description: "Maximum size of the collection in **bytes**."
+		}, {
+			optional: true,
+			name: "max",
+			type: "number",
+			description: "Maximum number of documents in the collection. If omitted, only the byte size limit applies."
+		}]
+	}),
 	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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/mongo",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/moostjs/atscript/issues"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "Artem Maltsev",
   "repository": {
     "type": "git",
@@ -57,9 +57,9 @@
   },
   "peerDependencies": {
     "mongodb": "^6.17.0",
-    "@atscript/core": "^0.1.33",
-    "@atscript/utils-db": "^0.1.33",
-    "@atscript/typescript": "^0.1.33"
+    "@atscript/core": "^0.1.35",
+    "@atscript/typescript": "^0.1.35",
+    "@atscript/utils-db": "^0.1.35"
   },
   "build": [
     {},