@atscript/moost-mongo 0.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Atscript
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @atscript/moost-mongo
+
+Simple generator‑free CRUD for **MongoDB** collections defined with
+**atscript** and served by
+[Moost](https://moost.org/).
+
+- ✅ **Zero boilerplate** – one decorator turns your `.as` model into a fully‑featured controller.
+- 🔌 **Pluggable** – override protected hooks to adjust validation, projections, or write logic.
+- ⚙️ **URLQL** powered filtering / paging / projections on **GET /query** & **GET /pages**.
+- 🧱 **Type‑safe** – everything is inferred from your annotated interface.
+
+---
+
+## Installation
+
+```bash
+pnpm add @atscript/moost-mongo        # this package
+pnpm add @atscript/mongo mongodb      # runtime peer deps
+pnpm add moost @moostjs/event-http    # your HTTP adapter
+```
+
+---
+
+## Quick start
+
+### 1  Describe your collection
+
+```ts
+// src/collections/user.collection.as
+@mongo.collection 'users'
+export interface User {
+  @mongo.index.unique
+  email: string
+  name: string
+  age: number
+}
+```
+
+### 2  Subclass the controller
+
+```ts
+import { AsMongoController, CollectionController } from '@atscript/moost-mongo'
+import type { User } from '../collections/user.collection.as'
+
+/* Provide AsMongo connection for the controller */
+@Provide(AsMongo, () => new AsMongo(process.env.MONGO_URI!))
+@CollectionController(User) // optional prefix param available
+export class UsersController extends AsMongoController<typeof User> {}
+```
+
+### 3  Bootstrap Moost
+
+```ts
+import { Moost } from 'moost'
+import { MoostHttp } from '@moostjs/event-http'
+import { UsersController } from './controllers/users.controller'
+
+const app = new Moost()
+
+void app.adapter(new MoostHttp()).listen(3000)
+void app.registerControllers(UsersController).init()
+```
+
+Hit the endpoints:
+
+```
+GET  /users/query   ?$filter=age>18&$select=name,email
+GET  /users/pages   ?$page=2&$size=20&$sort=age:-1
+GET  /users/one/{id}
+POST /users         (JSON body)                        – insert 1‒n documents
+PUT  /users         (JSON body with _id)               – replace
+PATCH/DELETE        analogously
+```
+
+---
+
+## API
+
+### `class AsMongoController<T>`
+
+Base class you extend. **T** is the atscript constructor exported from the
+`.as` file.
+
+| Hook / Method               | When to override                     | Typical use‑case                        |
+| --------------------------- | ------------------------------------ | --------------------------------------- |
+| `protected init()`          | Once at controller creation          | Create indexes, seed data               |
+| `transformProjection()`     | Before running `find()`              | Force whitelist / blacklist projections |
+| `validate*Controls()`       | Per endpoint                         | Custom URLQL control validation         |
+| `onRemove(id, opts)`        | Before `deleteOne`                   | Soft‑delete or veto                     |
+| `onWrite(action,data,opts)` | Before any insert / update / replace | Auto‑populate fields, audit, veto       |
+
+All CRUD endpoints are already wired – just subclass and go.
+
+### `CollectionController(type, prefix?)`
+
+Decorator that glues your subclass to Moost:
+
+1. Registers the collection constructor under DI token `__atscript_mongo_collection_def`.
+2. Marks the class as a `@Controller(prefix)` (defaults to the collection name).
+3. Ensures route metadata from the parent is inherited (`@Inherit`).
+
+```ts
+@CollectionController(User, 'users')
+export class UsersController extends AsMongoController<typeof User> {}
+```
+
+---
+
+## Route reference
+
+| Route                    | Description                                                 | Query controls                                             |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- |
+| `GET  /<prefix>/query`   | List documents / count mode                                 | `$filter`, `$select`, `$sort`, `$limit`, `$skip`, `$count` |
+| `GET  /<prefix>/pages`   | Paged list with meta                                        | same + `$page`, `$size`                                    |
+| `GET  /<prefix>/one/:id` | Single document by `_id` or any `@mongo.index.unique` field | `$select` only                                             |
+| `POST /<prefix>`         | Insert one or many                                          | –                                                          |
+| `PUT  /<prefix>`         | Replace by `_id`                                            | –                                                          |
+| `PATCH /<prefix>`        | Update by `_id`                                             | –                                                          |
+| `DELETE /<prefix>/:id`   | Remove by `_id`                                             | –                                                          |
+
+---
+
+## Extending example
+
+```ts
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {
+  /** Add `createdAt` on every insert. */
+  protected async onWrite(action, data) {
+    if (action === 'insert' && data) {
+      ;(data as any).createdAt = new Date()
+    }
+    return data
+  }
+
+  /** Soft delete instead of hard delete. */
+  protected async onRemove(id, opts) {
+    await this.asCollection.collection.updateOne(
+      { _id: this.asCollection.prepareId(id) },
+      { $set: { deleted: true, deletedAt: new Date() } }
+    )
+    // prevent actual deleteOne
+    return undefined
+  }
+}
+```
+
+---
+
+## License
+
+MIT © 2025 Artem Maltsev

package/dist/index.cjs

@@ -0,0 +1,465 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __moostjs_event_http = __toESM(require("@moostjs/event-http"));
+const moost = __toESM(require("moost"));
+const urlql = __toESM(require("urlql"));
+const __atscript_typescript = __toESM(require("@atscript/typescript"));
+const __atscript_mongo = __toESM(require("@atscript/mongo"));
+
+//#region packages/moost-mongo/src/dto/controls.dto.as.js
+function _define_property$1(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 QueryControlsDto = class {};
+_define_property$1(QueryControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(QueryControlsDto, "type", {});
+_define_property$1(QueryControlsDto, "metadata", new Map());
+var PagesControlsDto = class {};
+_define_property$1(PagesControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(PagesControlsDto, "type", {});
+_define_property$1(PagesControlsDto, "metadata", new Map());
+var GetOneControlsDto = class {};
+_define_property$1(GetOneControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(GetOneControlsDto, "type", {});
+_define_property$1(GetOneControlsDto, "metadata", new Map());
+let SortControlDto = class SortControlDto$1 {};
+_define_property$1(SortControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SortControlDto, "type", {});
+_define_property$1(SortControlDto, "metadata", new Map());
+let SelectControlDto = class SelectControlDto$1 {};
+_define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SelectControlDto, "type", {});
+_define_property$1(SelectControlDto, "metadata", new Map());
+(0, __atscript_typescript.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, __atscript_typescript.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.min", 0).annotate("expect.int", true).optional().$type).prop("$limit", (0, __atscript_typescript.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.min", 0).annotate("expect.int", true).optional().$type).prop("$count", (0, __atscript_typescript.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, __atscript_typescript.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript.defineAnnotatedType)().refTo(SelectControlDto).optional().$type);
+(0, __atscript_typescript.defineAnnotatedType)("object", PagesControlsDto).prop("$page", (0, __atscript_typescript.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$size", (0, __atscript_typescript.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$sort", (0, __atscript_typescript.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript.defineAnnotatedType)().refTo(SelectControlDto).optional().$type);
+(0, __atscript_typescript.defineAnnotatedType)("object", GetOneControlsDto).prop("$select", (0, __atscript_typescript.defineAnnotatedType)().refTo(SelectControlDto).optional().$type);
+(0, __atscript_typescript.defineAnnotatedType)("object", SortControlDto).propPattern(/./, (0, __atscript_typescript.defineAnnotatedType)("union").item((0, __atscript_typescript.defineAnnotatedType)().designType("number").value(1).$type).item((0, __atscript_typescript.defineAnnotatedType)().designType("number").value(-1).$type).$type);
+(0, __atscript_typescript.defineAnnotatedType)("object", SelectControlDto).propPattern(/./, (0, __atscript_typescript.defineAnnotatedType)("union").item((0, __atscript_typescript.defineAnnotatedType)().designType("number").value(1).$type).item((0, __atscript_typescript.defineAnnotatedType)().designType("number").value(0).$type).$type);
+
+//#endregion
+//#region packages/moost-mongo/src/decorators.ts
+const COLLECTION_DEF = "__atscript_mongo_collection_def";
+const CollectionController = (type, prefix) => {
+	return (0, moost.ApplyDecorators)((0, moost.Provide)(COLLECTION_DEF, () => type), (0, moost.Controller)(prefix || type.metadata.get("mongo.collection") || type.name), (0, moost.Inherit)());
+};
+
+//#endregion
+//#region packages/moost-mongo/src/as-mongo.controller.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;
+}
+function _ts_decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+var AsMongoController = class {
+	/**
+	* One‑time initialization hook executed right after the collection is obtained.
+	*
+	* Default behaviour:
+	* * Automatically synchronises MongoDB indexes unless
+	*   `mongo.autoIndexes` metadata flag is set to `false` on the model.
+	*
+	* Override to seed data, register change streams, etc. Both sync and async
+	* return types are supported.
+	*/ init() {
+		if (this.type.metadata.get("mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
+	}
+	/** Returns (and memoises) validator for *query* endpoint controls. */ get queryControlsValidator() {
+		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
+		return this._queryControlsValidator;
+	}
+	/** Returns (and memoises) validator for *pages* endpoint controls. */ get pagesControlsValidator() {
+		if (!this._pagesControlsValidator) this._pagesControlsValidator = PagesControlsDto.validator();
+		return this._pagesControlsValidator;
+	}
+	/** Returns (and memoises) validator for *one* endpoint controls. */ get getOneControlsValidator() {
+		if (!this._getOneControlsValidator) this._getOneControlsValidator = GetOneControlsDto.validator();
+		return this._getOneControlsValidator;
+	}
+	/**
+	* Validates `$limit`, `$skip`, `$sort`, `$select`, `$count` controls for the
+	* **query** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateQueryControls(controls) {
+		this.queryControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates pagination‑specific controls for the **pages** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validatePagesControls(controls) {
+		this.pagesControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates controls for the **one /: id ** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateGetOneControls(controls) {
+		this.getOneControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates the `insights` section ensuring only known projection fields are used.
+	*
+	* @param insights - Map of insight keys.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateInsights(insights) {
+		for (const key of insights.keys()) if (!this.asCollection.flatMap.has(key)) return `Unknown field "${key}"`;
+		return undefined;
+	}
+	/**
+	* Runs all validations relevant to current endpoint and returns a ready‑to‑send
+	* `HttpError` instance if something is invalid.
+	*
+	* @param parsed - Full parsed URLQL query.
+	* @param controlsType - Which controls validator to apply.
+	*/ async validateUrlql(parsed, controlsType) {
+		const controlsValidators = {
+			query: this.validateQueryControls.bind(this),
+			pages: this.validatePagesControls.bind(this),
+			getOne: this.validateGetOneControls.bind(this)
+		};
+		try {
+			const error = await controlsValidators[controlsType](parsed.controls);
+			if (error) return new __moostjs_event_http.HttpError(400, error);
+		} catch (e) {
+			return new __moostjs_event_http.HttpError(400, e.message);
+		}
+		try {
+			const error = await this.validateInsights(parsed.insights);
+			if (error) return new __moostjs_event_http.HttpError(400, error);
+		} catch (e) {
+			return new __moostjs_event_http.HttpError(400, e.message);
+		}
+	}
+	/**
+	* Allows subclasses to translate field projection (e.g. whitelist vs blacklist).
+	*
+	* @param projection - Mongo projection generated by `urlql` `$select` control.
+	* @returns Adjusted projection (may return `Promise`).
+	*/ transformProjection(projection) {
+		return projection;
+	}
+	/**
+	* Builds MongoDB `FindOptions` object out of URLQL controls.
+	*
+	* @param controls - Parsed `controls` object.
+	*/ prepareQueryOptions(controls) {
+		return {
+			projection: this.transformProjection(controls.$select),
+			sort: controls.$sort,
+			limit: controls.$limit,
+			skip: controls.$skip
+		};
+	}
+	/**
+	* **GET /query** – returns an array of documents or a count depending on
+	* presence of `$count` control.
+	*
+	* @param url - Full request URL provided by Moost (includes query string).
+	* @returns Documents array **or** document count number.
+	*/ async query(url) {
+		const query = url.split("?").slice(1).join("?");
+		const parsed = (0, urlql.parseUrlql)(query);
+		const error = await this.validateUrlql(parsed, "query");
+		if (error) return error;
+		return parsed.controls.$count ? this.asCollection.collection.countDocuments(parsed.filter) : this.asCollection.collection.find(parsed.filter, this.prepareQueryOptions(parsed.controls)).toArray();
+	}
+	/**
+	* **GET /pages** – returns paginated documents plus basic pagination meta.
+	*
+	* @param url - Full request URL.
+	* @returns An object with keys: `documents`, `page`, `size`, `totalPages`, `totalDocuments`.
+	*/ async pages(url) {
+		const query = url.split("?").slice(1).join("?");
+		const parsed = (0, urlql.parseUrlql)(query);
+		const error = await this.validateUrlql(parsed, "pages");
+		if (error) return error;
+		const controls = parsed.controls;
+		const page = Math.max(Number(controls.$page || 1), 1);
+		const size = Math.max(Number(controls.$size || 10), 1);
+		const skip = (page - 1) * size;
+		const result = await this.asCollection.collection.aggregate([{ $match: parsed.filter }, { $facet: {
+			documents: [
+				controls.$sort ? { $sort: controls.$sort } : undefined,
+				{ $skip: skip },
+				{ $limit: size },
+				controls.$select ? { $project: controls.$select } : undefined
+			].filter(Boolean),
+			meta: [{ $count: "count" }]
+		} }]).toArray();
+		const totalDocuments = result[0].meta[0].count;
+		return {
+			documents: result[0].documents,
+			page,
+			size,
+			totalPages: Math.ceil(totalDocuments / size),
+			totalDocuments
+		};
+	}
+	/**
+	* **GET /one/:id** – retrieves a single document. The identifier may be a
+	* Mongo `ObjectId` **or** the value of any `unique` property registered on
+	* the model.
+	*
+	* Filtering is not allowed on this route.
+	*
+	* @param id - Document `_id` or alternate unique key value.
+	* @param url - Full request URL (supports `$select`, `$insights`, etc.).
+	*/ async getOne(id, url) {
+		const idValidator = this.asCollection.flatMap.get("_id")?.validator();
+		const query = url.split("?").slice(1).join("?");
+		const parsed = (0, urlql.parseUrlql)(query);
+		if (Object.keys(parsed.filter).length) return new __moostjs_event_http.HttpError(400, "Filtering is not allowed for \"one\" endpoint");
+		const error = await this.validateUrlql(parsed, "getOne");
+		if (error) return error;
+		if (idValidator?.validate(id, true)) return this.returnOne(this.asCollection.collection.find({ _id: this.asCollection.prepareId(id) }, this.prepareQueryOptions(parsed.controls)).toArray());
+else if (this.asCollection.uniqueProps.size > 0) {
+			const filter = [];
+			for (const prop of this.asCollection.uniqueProps) filter.push({ [prop]: id });
+			return this.returnOne(this.asCollection.collection.find({ $or: filter }, this.prepareQueryOptions(parsed.controls)).toArray());
+		}
+		if (idValidator) return new __atscript_typescript.ValidatorError(idValidator.errors);
+		return new __moostjs_event_http.HttpError(500, "Unknown error");
+	}
+	/**
+	* Helper that unwraps a promise returning an array of documents and
+	* guarantees zero‑or‑one semantics expected by **one** endpoint.
+	*
+	* @param result - Promise resolving to an array of documents.
+	* @returns Document, 400 or 404 { @link HttpError }.
+	*/ async returnOne(result) {
+		const items = await result;
+		if (items.length > 1) return new __moostjs_event_http.HttpError(400, "Found more than one record");
+else if (items.length === 0) return new __moostjs_event_http.HttpError(404);
+else return items[0];
+	}
+	/**
+	* **POST /** – inserts one or many documents.
+	*
+	* @param payload - Raw request body to be inserted.
+	*/ async insert(payload) {
+		const data = this.asCollection.prepareInsert(payload);
+		const opts = {};
+		if (Array.isArray(data)) {
+			const newData = await this.onWrite("insertMany", data, opts);
+			if (newData) return this.asCollection.collection.insertMany(newData, opts);
+else return new __moostjs_event_http.HttpError(500, "Not saved");
+		}
+		if (data) {
+			const newData = await this.onWrite("insert", data, opts);
+			if (newData) return this.asCollection.collection.insertOne(newData, opts);
+else return new __moostjs_event_http.HttpError(500, "Not saved");
+		}
+		return new __moostjs_event_http.HttpError(500, "Not saved");
+	}
+	/**
+	* **PUT /** – fully replaces a document matched by `_id`.
+	*
+	* @param payload - Object containing `_id` plus full replacement document.
+	*/ async replace(payload) {
+		const args = this.asCollection.prepareReplace(payload).toArgs();
+		const newData = await this.onWrite("replace", args[1], args[2]);
+		if (newData) return this.asCollection.collection.replaceOne(args[0], newData, args[2]);
+		return new __moostjs_event_http.HttpError(500, "Not saved");
+	}
+	/**
+	* **PATCH /** – updates one document using MongoDB update operators.
+	*
+	* @param payload - Update payload produced by `asCollection.prepareUpdate`.
+	*/ async update(payload) {
+		const args = this.asCollection.prepareUpdate(payload).toArgs();
+		const newData = await this.onWrite("update", args[1], args[2]);
+		if (newData) return this.asCollection.collection.updateOne(args[0], newData, args[2]);
+		return new __moostjs_event_http.HttpError(500, "Not saved");
+	}
+	/**
+	* **DELETE /:id** – removes a single document by `_id`.
+	*
+	* @param id - Document identifier.
+	*/ async remove(id) {
+		const opts = {};
+		id = await this.onRemove(id, opts);
+		if (id !== undefined) {
+			const result = await this.asCollection.collection.deleteOne({ _id: this.asCollection.prepareId(id) }, opts);
+			if (result.deletedCount < 1) throw new __moostjs_event_http.HttpError(404);
+			return result;
+		}
+		return new __moostjs_event_http.HttpError(500, "Not deleted");
+	}
+	/**
+	* Intercepts delete operation allowing subclasses to veto or mutate it.
+	*
+	* @param id - Requested document ID.
+	* @param opts - Mutable `DeleteOptions` passed to Mongo driver.
+	* @returns Final ID to be deleted (can be async).
+	*/ onRemove(id, opts) {
+		return id;
+	}
+	onWrite(action, data, opts) {
+		return data;
+	}
+	/**
+	* Creates a controller instance and resolves the underlying collection.
+	*
+	* > Do **not** perform heavy asynchronous work directly inside the
+	* > constructor – override {@link init} instead.
+	*
+	* @param asMongo - Shared `AsMongo` driver instance.
+	* @param type - AtScript annotated model constructor for the collection.
+	* @param app - The current `Moost` application (used for retrieving a logger).
+	* @throws Rethrows any error emitted from {@link init} to stop controller registration.
+	*/ constructor(asMongo, type, app) {
+		_define_property(this, "asMongo", void 0);
+		_define_property(this, "type", void 0);
+		/** Reference to the lazily created {@link AsCollection}. */ _define_property(this, "asCollection", void 0);
+		/** Application‑scoped logger bound to the collection name. */ _define_property(this, "logger", void 0);
+		_define_property(this, "_queryControlsValidator", void 0);
+		_define_property(this, "_pagesControlsValidator", void 0);
+		_define_property(this, "_getOneControlsValidator", void 0);
+		this.asMongo = asMongo;
+		this.type = type;
+		this.logger = app.getLogger(`mongo [${type.metadata.get("mongo.collection") || ""}]`);
+		this.asCollection = this.asMongo.getCollection(type, this.logger);
+		this.logger.info(`Initializing Collection`);
+		try {
+			const p = this.init();
+			if (p instanceof Promise) p.catch((e) => {
+				this.logger.error(e);
+			});
+		} catch (e) {
+			this.logger.error(e);
+			throw e;
+		}
+	}
+};
+_ts_decorate([
+	(0, __moostjs_event_http.Get)("query"),
+	_ts_param(0, (0, __moostjs_event_http.Url)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "query", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Get)("pages"),
+	_ts_param(0, (0, __moostjs_event_http.Url)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "pages", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Get)("one/:id"),
+	_ts_param(0, (0, moost.Param)("id")),
+	_ts_param(1, (0, __moostjs_event_http.Url)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String, String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "getOne", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Post)(""),
+	_ts_param(0, (0, __moostjs_event_http.Body)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "insert", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Put)(""),
+	_ts_param(0, (0, __moostjs_event_http.Body)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "replace", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Patch)(""),
+	_ts_param(0, (0, __moostjs_event_http.Body)()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "update", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Delete)(":id"),
+	_ts_param(0, (0, moost.Param)("id")),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "remove", null);
+AsMongoController = _ts_decorate([
+	_ts_param(1, (0, moost.Inject)(COLLECTION_DEF)),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [
+		typeof __atscript_mongo.AsMongo === "undefined" ? Object : __atscript_mongo.AsMongo,
+		typeof T === "undefined" ? Object : T,
+		typeof moost.Moost === "undefined" ? Object : moost.Moost
+	])
+], AsMongoController);
+
+//#endregion
+Object.defineProperty(exports, 'AsMongoController', {
+  enumerable: true,
+  get: function () {
+    return AsMongoController;
+  }
+});
+exports.COLLECTION_DEF = COLLECTION_DEF
+exports.CollectionController = CollectionController

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import { HttpError } from '@moostjs/event-http';
+import { TConsoleBase, Moost } from 'moost';
+import { UrlqlQuery } from 'urlql';
+import { AsMongo, AsCollection } from '@atscript/mongo';
+import { TAtscriptAnnotatedTypeConstructor, ValidatorError } from '@atscript/typescript';
+import { WithId, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, DeleteOptions, ObjectId, OptionalUnlessRequiredId, InsertOneOptions, BulkWriteOptions, WithoutId, ReplaceOptions, UpdateFilter, UpdateOptions } from 'mongodb';
+
+/**
+ * Generic **Moost** controller that exposes a full REST‑style CRUD surface over a
+ * MongoDB collection described with **atscript** and handled by **@atscript/mongo**.
+ *
+ * The controller is intentionally designed for extension – simply subclass it and
+ * provide your model constructor. Every important step is overridable via the
+ * `protected` hooks documented below.
+ *
+ * ```ts
+ * ‎@Provide(AsMongo, () => new AsMongo(CONNECTION_STRING))
+ * ‎@CollectionController(MyCollectionType)
+ * export class MyCollectionController
+ *     extends AsMongoController<typeof MyCollectionType> {}
+ * ```
+ *
+ * @typeParam T - The **atscript** annotated class (constructor) representing the
+ *               collection schema. Must be decorated with `@AsCollection`.
+ */
+declare class AsMongoController<T extends TAtscriptAnnotatedTypeConstructor> {
+    protected asMongo: AsMongo;
+    protected type: T;
+    /** Reference to the lazily created {@link AsCollection}. */
+    protected asCollection: AsCollection<T>;
+    /** Application‑scoped logger bound to the collection name. */
+    protected logger: TConsoleBase;
+    /**
+     * Creates a controller instance and resolves the underlying collection.
+     *
+     * > Do **not** perform heavy asynchronous work directly inside the
+     * > constructor – override {@link init} instead.
+     *
+     * @param asMongo - Shared `AsMongo` driver instance.
+     * @param type - AtScript annotated model constructor for the collection.
+     * @param app - The current `Moost` application (used for retrieving a logger).
+     * @throws Rethrows any error emitted from {@link init} to stop controller registration.
+     */
+    constructor(asMongo: AsMongo, type: T, app: Moost);
+    /**
+     * One‑time initialization hook executed right after the collection is obtained.
+     *
+     * Default behaviour:
+     * * Automatically synchronises MongoDB indexes unless
+     *   `mongo.autoIndexes` metadata flag is set to `false` on the model.
+     *
+     * Override to seed data, register change streams, etc. Both sync and async
+     * return types are supported.
+     */
+    protected init(): void | Promise<any>;
+    private _queryControlsValidator?;
+    private _pagesControlsValidator?;
+    private _getOneControlsValidator?;
+    /** Returns (and memoises) validator for *query* endpoint controls. */
+    protected get queryControlsValidator(): any;
+    /** Returns (and memoises) validator for *pages* endpoint controls. */
+    protected get pagesControlsValidator(): any;
+    /** Returns (and memoises) validator for *one* endpoint controls. */
+    protected get getOneControlsValidator(): any;
+    /**
+     * Validates `$limit`, `$skip`, `$sort`, `$select`, `$count` controls for the
+     * **query** endpoint.
+     *
+     * @param controls - Controls object emitted by `urlql` parser.
+     * @returns Error message string or `undefined` (when valid). Can be async.
+     */
+    protected validateQueryControls(controls: UrlqlQuery['controls']): Promise<string | undefined> | string | undefined;
+    /**
+     * Validates pagination‑specific controls for the **pages** endpoint.
+     *
+     * @param controls - Controls object emitted by `urlql` parser.
+     * @returns Error message string or `undefined` (when valid). Can be async.
+     */
+    protected validatePagesControls(controls: UrlqlQuery['controls']): Promise<string | undefined> | string | undefined;
+    /**
+     * Validates controls for the **one /: id ** endpoint.
+     *
+     * @param controls - Controls object emitted by `urlql` parser.
+     * @returns Error message string or `undefined` (when valid). Can be async.
+     */
+    protected validateGetOneControls(controls: UrlqlQuery['controls']): Promise<string | undefined> | string | undefined;
+    /**
+     * Validates the `insights` section ensuring only known projection fields are used.
+     *
+     * @param insights - Map of insight keys.
+     * @returns Error message string or `undefined` (when valid). Can be async.
+     */
+    protected validateInsights(insights: UrlqlQuery['insights']): Promise<string | undefined> | string | undefined;
+    /**
+     * Runs all validations relevant to current endpoint and returns a ready‑to‑send
+     * `HttpError` instance if something is invalid.
+     *
+     * @param parsed - Full parsed URLQL query.
+     * @param controlsType - Which controls validator to apply.
+     */
+    protected validateUrlql(parsed: UrlqlQuery, controlsType: 'query' | 'pages' | 'getOne'): Promise<HttpError | undefined>;
+    /**
+     * Allows subclasses to translate field projection (e.g. whitelist vs blacklist).
+     *
+     * @param projection - Mongo projection generated by `urlql` `$select` control.
+     * @returns Adjusted projection (may return `Promise`).
+     */
+    protected transformProjection(projection?: Record<string, 0 | 1>): Record<string, 1> | Record<string, 0> | undefined | Promise<Record<string, 1> | Record<string, 0> | undefined>;
+    /**
+     * Builds MongoDB `FindOptions` object out of URLQL controls.
+     *
+     * @param controls - Parsed `controls` object.
+     */
+    protected prepareQueryOptions(controls: UrlqlQuery['controls']): {
+        projection: Record<string, 1> | Record<string, 0> | Promise<Record<string, 1> | Record<string, 0> | undefined> | undefined;
+        sort: Record<string, 1 | -1> | undefined;
+        limit: number | undefined;
+        skip: number | undefined;
+    };
+    /**
+     * **GET /query** – returns an array of documents or a count depending on
+     * presence of `$count` control.
+     *
+     * @param url - Full request URL provided by Moost (includes query string).
+     * @returns Documents array **or** document count number.
+     */
+    query(url: string): Promise<InstanceType<T>[] | number | HttpError>;
+    /**
+     * **GET /pages** – returns paginated documents plus basic pagination meta.
+     *
+     * @param url - Full request URL.
+     * @returns An object with keys: `documents`, `page`, `size`, `totalPages`, `totalDocuments`.
+     */
+    pages(url: string): Promise<{
+        documents: InstanceType<T>[];
+        page: number;
+        size: number;
+        totalPages: number;
+        totalDocuments: number;
+    } | HttpError>;
+    /**
+     * **GET /one/:id** – retrieves a single document. The identifier may be a
+     * Mongo `ObjectId` **or** the value of any `unique` property registered on
+     * the model.
+     *
+     * Filtering is not allowed on this route.
+     *
+     * @param id - Document `_id` or alternate unique key value.
+     * @param url - Full request URL (supports `$select`, `$insights`, etc.).
+     */
+    getOne(id: string, url: string): Promise<InstanceType<T> | HttpError | ValidatorError>;
+    /**
+     * Helper that unwraps a promise returning an array of documents and
+     * guarantees zero‑or‑one semantics expected by **one** endpoint.
+     *
+     * @param result - Promise resolving to an array of documents.
+     * @returns Document, 400 or 404 { @link HttpError }.
+     */
+    protected returnOne(result: Promise<WithId<InstanceType<T>>[]>): Promise<InstanceType<T> | HttpError>;
+    /**
+     * **POST /** – inserts one or many documents.
+     *
+     * @param payload - Raw request body to be inserted.
+     */
+    insert(payload: any): Promise<HttpError | InsertOneResult | InsertManyResult>;
+    /**
+     * **PUT /** – fully replaces a document matched by `_id`.
+     *
+     * @param payload - Object containing `_id` plus full replacement document.
+     */
+    replace(payload: any): Promise<HttpError | UpdateResult<InstanceType<T>>>;
+    /**
+     * **PATCH /** – updates one document using MongoDB update operators.
+     *
+     * @param payload - Update payload produced by `asCollection.prepareUpdate`.
+     */
+    update(payload: any): Promise<HttpError | UpdateResult>;
+    /**
+     * **DELETE /:id** – removes a single document by `_id`.
+     *
+     * @param id - Document identifier.
+     */
+    remove(id: string): Promise<HttpError | DeleteResult>;
+    /**
+     * Intercepts delete operation allowing subclasses to veto or mutate it.
+     *
+     * @param id - Requested document ID.
+     * @param opts - Mutable `DeleteOptions` passed to Mongo driver.
+     * @returns Final ID to be deleted (can be async).
+     */
+    protected onRemove(id: string, opts: DeleteOptions): string | number | Date | ObjectId | undefined | Promise<string | number | Date | ObjectId | undefined>;
+    /**
+     * Generic handler executed right before **every write** (insert/replace/update).
+     *
+     * Override to validate or mutate data, or tweak driver options. Return
+     * `undefined` to abort the write – the endpoint will respond with *500 Not saved*.
+     */
+    protected onWrite(action: 'insert', data: OptionalUnlessRequiredId<InstanceType<T>>, opts: InsertOneOptions): OptionalUnlessRequiredId<InstanceType<T>> | Promise<OptionalUnlessRequiredId<InstanceType<T>> | undefined> | undefined;
+    protected onWrite(action: 'insertMany', data: OptionalUnlessRequiredId<InstanceType<T>>[], opts: BulkWriteOptions): OptionalUnlessRequiredId<InstanceType<T>>[] | Promise<OptionalUnlessRequiredId<InstanceType<T>>[] | undefined> | undefined;
+    protected onWrite(action: 'replace', data: WithoutId<InstanceType<T>>, opts: ReplaceOptions): WithoutId<InstanceType<T>> | Promise<WithoutId<InstanceType<T>> | undefined> | undefined;
+    protected onWrite(action: 'update', data: UpdateFilter<InstanceType<T>>, opts: UpdateOptions): UpdateFilter<InstanceType<T>> | Promise<UpdateFilter<InstanceType<T>> | undefined> | undefined;
+}
+
+/**
+ * DI token under which the AtScript-annotated collection definition
+ * is exposed to the controller’s constructor via `@Inject`.
+ */
+declare const COLLECTION_DEF = "__atscript_mongo_collection_def";
+/**
+ * Combines the boilerplate needed to turn an {@link AsMongoController}
+ * subclass into a fully wired HTTP controller for a given
+ * **@mongo.collection** model.
+ *
+ * Internally applies three decorators:
+ * 1. **Provide** – registers the collection constructor under {@link COLLECTION_DEF}.
+ * 2. **Controller** – registers the class as a Moost HTTP controller
+ *    with an optional route prefix. If the prefix is not set, the collection name used by default
+ * 3. **Inherit** – copies metadata (routes, guards, etc.) from the
+ *    parent class so they stay active in the derived controller.
+ *
+ * @param type   AtScript-annotated constructor produced by `@mongo.collection`.
+ * @param prefix Optional route prefix. Defaults to
+ *               `type.metadata.get("mongo.collection")` or the class name.
+ *
+ * @example
+ * ```ts
+ * ‎@CollectionController(UserModel)
+ * export class UsersController extends AsMongoController<typeof UserModel> {}
+ * ```
+ */
+declare const CollectionController: (type: TAtscriptAnnotatedTypeConstructor, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+
+export { AsMongoController, COLLECTION_DEF, CollectionController };

package/dist/index.mjs

@@ -0,0 +1,434 @@
+import { Body, Delete, Get, HttpError, Patch, Post, Put, Url } from "@moostjs/event-http";
+import { ApplyDecorators, Controller, Inherit, Inject, Moost, Param, Provide } from "moost";
+import { parseUrlql } from "urlql";
+import { ValidatorError, defineAnnotatedType } from "@atscript/typescript";
+import { AsMongo } from "@atscript/mongo";
+
+//#region packages/moost-mongo/src/dto/controls.dto.as.js
+function _define_property$1(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 QueryControlsDto = class {};
+_define_property$1(QueryControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(QueryControlsDto, "type", {});
+_define_property$1(QueryControlsDto, "metadata", new Map());
+var PagesControlsDto = class {};
+_define_property$1(PagesControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(PagesControlsDto, "type", {});
+_define_property$1(PagesControlsDto, "metadata", new Map());
+var GetOneControlsDto = class {};
+_define_property$1(GetOneControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(GetOneControlsDto, "type", {});
+_define_property$1(GetOneControlsDto, "metadata", new Map());
+let SortControlDto = class SortControlDto$1 {};
+_define_property$1(SortControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SortControlDto, "type", {});
+_define_property$1(SortControlDto, "metadata", new Map());
+let SelectControlDto = class SelectControlDto$1 {};
+_define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SelectControlDto, "type", {});
+_define_property$1(SelectControlDto, "metadata", new Map());
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.min", 0).annotate("expect.int", true).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.min", 0).annotate("expect.int", true).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType().refTo(SelectControlDto).optional().$type);
+defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$size", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType().refTo(SelectControlDto).optional().$type);
+defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType().refTo(SelectControlDto).optional().$type);
+defineAnnotatedType("object", SortControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(-1).$type).$type);
+defineAnnotatedType("object", SelectControlDto).propPattern(/./, defineAnnotatedType("union").item(defineAnnotatedType().designType("number").value(1).$type).item(defineAnnotatedType().designType("number").value(0).$type).$type);
+
+//#endregion
+//#region packages/moost-mongo/src/decorators.ts
+const COLLECTION_DEF = "__atscript_mongo_collection_def";
+const CollectionController = (type, prefix) => {
+	return ApplyDecorators(Provide(COLLECTION_DEF, () => type), Controller(prefix || type.metadata.get("mongo.collection") || type.name), Inherit());
+};
+
+//#endregion
+//#region packages/moost-mongo/src/as-mongo.controller.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;
+}
+function _ts_decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+var AsMongoController = class {
+	/**
+	* One‑time initialization hook executed right after the collection is obtained.
+	*
+	* Default behaviour:
+	* * Automatically synchronises MongoDB indexes unless
+	*   `mongo.autoIndexes` metadata flag is set to `false` on the model.
+	*
+	* Override to seed data, register change streams, etc. Both sync and async
+	* return types are supported.
+	*/ init() {
+		if (this.type.metadata.get("mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
+	}
+	/** Returns (and memoises) validator for *query* endpoint controls. */ get queryControlsValidator() {
+		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
+		return this._queryControlsValidator;
+	}
+	/** Returns (and memoises) validator for *pages* endpoint controls. */ get pagesControlsValidator() {
+		if (!this._pagesControlsValidator) this._pagesControlsValidator = PagesControlsDto.validator();
+		return this._pagesControlsValidator;
+	}
+	/** Returns (and memoises) validator for *one* endpoint controls. */ get getOneControlsValidator() {
+		if (!this._getOneControlsValidator) this._getOneControlsValidator = GetOneControlsDto.validator();
+		return this._getOneControlsValidator;
+	}
+	/**
+	* Validates `$limit`, `$skip`, `$sort`, `$select`, `$count` controls for the
+	* **query** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateQueryControls(controls) {
+		this.queryControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates pagination‑specific controls for the **pages** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validatePagesControls(controls) {
+		this.pagesControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates controls for the **one /: id ** endpoint.
+	*
+	* @param controls - Controls object emitted by `urlql` parser.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateGetOneControls(controls) {
+		this.getOneControlsValidator.validate(controls);
+		return undefined;
+	}
+	/**
+	* Validates the `insights` section ensuring only known projection fields are used.
+	*
+	* @param insights - Map of insight keys.
+	* @returns Error message string or `undefined` (when valid). Can be async.
+	*/ validateInsights(insights) {
+		for (const key of insights.keys()) if (!this.asCollection.flatMap.has(key)) return `Unknown field "${key}"`;
+		return undefined;
+	}
+	/**
+	* Runs all validations relevant to current endpoint and returns a ready‑to‑send
+	* `HttpError` instance if something is invalid.
+	*
+	* @param parsed - Full parsed URLQL query.
+	* @param controlsType - Which controls validator to apply.
+	*/ async validateUrlql(parsed, controlsType) {
+		const controlsValidators = {
+			query: this.validateQueryControls.bind(this),
+			pages: this.validatePagesControls.bind(this),
+			getOne: this.validateGetOneControls.bind(this)
+		};
+		try {
+			const error = await controlsValidators[controlsType](parsed.controls);
+			if (error) return new HttpError(400, error);
+		} catch (e) {
+			return new HttpError(400, e.message);
+		}
+		try {
+			const error = await this.validateInsights(parsed.insights);
+			if (error) return new HttpError(400, error);
+		} catch (e) {
+			return new HttpError(400, e.message);
+		}
+	}
+	/**
+	* Allows subclasses to translate field projection (e.g. whitelist vs blacklist).
+	*
+	* @param projection - Mongo projection generated by `urlql` `$select` control.
+	* @returns Adjusted projection (may return `Promise`).
+	*/ transformProjection(projection) {
+		return projection;
+	}
+	/**
+	* Builds MongoDB `FindOptions` object out of URLQL controls.
+	*
+	* @param controls - Parsed `controls` object.
+	*/ prepareQueryOptions(controls) {
+		return {
+			projection: this.transformProjection(controls.$select),
+			sort: controls.$sort,
+			limit: controls.$limit,
+			skip: controls.$skip
+		};
+	}
+	/**
+	* **GET /query** – returns an array of documents or a count depending on
+	* presence of `$count` control.
+	*
+	* @param url - Full request URL provided by Moost (includes query string).
+	* @returns Documents array **or** document count number.
+	*/ async query(url) {
+		const query = url.split("?").slice(1).join("?");
+		const parsed = parseUrlql(query);
+		const error = await this.validateUrlql(parsed, "query");
+		if (error) return error;
+		return parsed.controls.$count ? this.asCollection.collection.countDocuments(parsed.filter) : this.asCollection.collection.find(parsed.filter, this.prepareQueryOptions(parsed.controls)).toArray();
+	}
+	/**
+	* **GET /pages** – returns paginated documents plus basic pagination meta.
+	*
+	* @param url - Full request URL.
+	* @returns An object with keys: `documents`, `page`, `size`, `totalPages`, `totalDocuments`.
+	*/ async pages(url) {
+		const query = url.split("?").slice(1).join("?");
+		const parsed = parseUrlql(query);
+		const error = await this.validateUrlql(parsed, "pages");
+		if (error) return error;
+		const controls = parsed.controls;
+		const page = Math.max(Number(controls.$page || 1), 1);
+		const size = Math.max(Number(controls.$size || 10), 1);
+		const skip = (page - 1) * size;
+		const result = await this.asCollection.collection.aggregate([{ $match: parsed.filter }, { $facet: {
+			documents: [
+				controls.$sort ? { $sort: controls.$sort } : undefined,
+				{ $skip: skip },
+				{ $limit: size },
+				controls.$select ? { $project: controls.$select } : undefined
+			].filter(Boolean),
+			meta: [{ $count: "count" }]
+		} }]).toArray();
+		const totalDocuments = result[0].meta[0].count;
+		return {
+			documents: result[0].documents,
+			page,
+			size,
+			totalPages: Math.ceil(totalDocuments / size),
+			totalDocuments
+		};
+	}
+	/**
+	* **GET /one/:id** – retrieves a single document. The identifier may be a
+	* Mongo `ObjectId` **or** the value of any `unique` property registered on
+	* the model.
+	*
+	* Filtering is not allowed on this route.
+	*
+	* @param id - Document `_id` or alternate unique key value.
+	* @param url - Full request URL (supports `$select`, `$insights`, etc.).
+	*/ async getOne(id, url) {
+		const idValidator = this.asCollection.flatMap.get("_id")?.validator();
+		const query = url.split("?").slice(1).join("?");
+		const parsed = parseUrlql(query);
+		if (Object.keys(parsed.filter).length) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
+		const error = await this.validateUrlql(parsed, "getOne");
+		if (error) return error;
+		if (idValidator?.validate(id, true)) return this.returnOne(this.asCollection.collection.find({ _id: this.asCollection.prepareId(id) }, this.prepareQueryOptions(parsed.controls)).toArray());
+else if (this.asCollection.uniqueProps.size > 0) {
+			const filter = [];
+			for (const prop of this.asCollection.uniqueProps) filter.push({ [prop]: id });
+			return this.returnOne(this.asCollection.collection.find({ $or: filter }, this.prepareQueryOptions(parsed.controls)).toArray());
+		}
+		if (idValidator) return new ValidatorError(idValidator.errors);
+		return new HttpError(500, "Unknown error");
+	}
+	/**
+	* Helper that unwraps a promise returning an array of documents and
+	* guarantees zero‑or‑one semantics expected by **one** endpoint.
+	*
+	* @param result - Promise resolving to an array of documents.
+	* @returns Document, 400 or 404 { @link HttpError }.
+	*/ async returnOne(result) {
+		const items = await result;
+		if (items.length > 1) return new HttpError(400, "Found more than one record");
+else if (items.length === 0) return new HttpError(404);
+else return items[0];
+	}
+	/**
+	* **POST /** – inserts one or many documents.
+	*
+	* @param payload - Raw request body to be inserted.
+	*/ async insert(payload) {
+		const data = this.asCollection.prepareInsert(payload);
+		const opts = {};
+		if (Array.isArray(data)) {
+			const newData = await this.onWrite("insertMany", data, opts);
+			if (newData) return this.asCollection.collection.insertMany(newData, opts);
+else return new HttpError(500, "Not saved");
+		}
+		if (data) {
+			const newData = await this.onWrite("insert", data, opts);
+			if (newData) return this.asCollection.collection.insertOne(newData, opts);
+else return new HttpError(500, "Not saved");
+		}
+		return new HttpError(500, "Not saved");
+	}
+	/**
+	* **PUT /** – fully replaces a document matched by `_id`.
+	*
+	* @param payload - Object containing `_id` plus full replacement document.
+	*/ async replace(payload) {
+		const args = this.asCollection.prepareReplace(payload).toArgs();
+		const newData = await this.onWrite("replace", args[1], args[2]);
+		if (newData) return this.asCollection.collection.replaceOne(args[0], newData, args[2]);
+		return new HttpError(500, "Not saved");
+	}
+	/**
+	* **PATCH /** – updates one document using MongoDB update operators.
+	*
+	* @param payload - Update payload produced by `asCollection.prepareUpdate`.
+	*/ async update(payload) {
+		const args = this.asCollection.prepareUpdate(payload).toArgs();
+		const newData = await this.onWrite("update", args[1], args[2]);
+		if (newData) return this.asCollection.collection.updateOne(args[0], newData, args[2]);
+		return new HttpError(500, "Not saved");
+	}
+	/**
+	* **DELETE /:id** – removes a single document by `_id`.
+	*
+	* @param id - Document identifier.
+	*/ async remove(id) {
+		const opts = {};
+		id = await this.onRemove(id, opts);
+		if (id !== undefined) {
+			const result = await this.asCollection.collection.deleteOne({ _id: this.asCollection.prepareId(id) }, opts);
+			if (result.deletedCount < 1) throw new HttpError(404);
+			return result;
+		}
+		return new HttpError(500, "Not deleted");
+	}
+	/**
+	* Intercepts delete operation allowing subclasses to veto or mutate it.
+	*
+	* @param id - Requested document ID.
+	* @param opts - Mutable `DeleteOptions` passed to Mongo driver.
+	* @returns Final ID to be deleted (can be async).
+	*/ onRemove(id, opts) {
+		return id;
+	}
+	onWrite(action, data, opts) {
+		return data;
+	}
+	/**
+	* Creates a controller instance and resolves the underlying collection.
+	*
+	* > Do **not** perform heavy asynchronous work directly inside the
+	* > constructor – override {@link init} instead.
+	*
+	* @param asMongo - Shared `AsMongo` driver instance.
+	* @param type - AtScript annotated model constructor for the collection.
+	* @param app - The current `Moost` application (used for retrieving a logger).
+	* @throws Rethrows any error emitted from {@link init} to stop controller registration.
+	*/ constructor(asMongo, type, app) {
+		_define_property(this, "asMongo", void 0);
+		_define_property(this, "type", void 0);
+		/** Reference to the lazily created {@link AsCollection}. */ _define_property(this, "asCollection", void 0);
+		/** Application‑scoped logger bound to the collection name. */ _define_property(this, "logger", void 0);
+		_define_property(this, "_queryControlsValidator", void 0);
+		_define_property(this, "_pagesControlsValidator", void 0);
+		_define_property(this, "_getOneControlsValidator", void 0);
+		this.asMongo = asMongo;
+		this.type = type;
+		this.logger = app.getLogger(`mongo [${type.metadata.get("mongo.collection") || ""}]`);
+		this.asCollection = this.asMongo.getCollection(type, this.logger);
+		this.logger.info(`Initializing Collection`);
+		try {
+			const p = this.init();
+			if (p instanceof Promise) p.catch((e) => {
+				this.logger.error(e);
+			});
+		} catch (e) {
+			this.logger.error(e);
+			throw e;
+		}
+	}
+};
+_ts_decorate([
+	Get("query"),
+	_ts_param(0, Url()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "query", null);
+_ts_decorate([
+	Get("pages"),
+	_ts_param(0, Url()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "pages", null);
+_ts_decorate([
+	Get("one/:id"),
+	_ts_param(0, Param("id")),
+	_ts_param(1, Url()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String, String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "getOne", null);
+_ts_decorate([
+	Post(""),
+	_ts_param(0, Body()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "insert", null);
+_ts_decorate([
+	Put(""),
+	_ts_param(0, Body()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "replace", null);
+_ts_decorate([
+	Patch(""),
+	_ts_param(0, Body()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [Object]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "update", null);
+_ts_decorate([
+	Delete(":id"),
+	_ts_param(0, Param("id")),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsMongoController.prototype, "remove", null);
+AsMongoController = _ts_decorate([
+	_ts_param(1, Inject(COLLECTION_DEF)),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [
+		typeof AsMongo === "undefined" ? Object : AsMongo,
+		typeof T === "undefined" ? Object : T,
+		typeof Moost === "undefined" ? Object : Moost
+	])
+], AsMongoController);
+
+//#endregion
+export { AsMongoController, COLLECTION_DEF, CollectionController };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@atscript/moost-mongo",
+  "version": "0.0.18",
+  "description": "Atscript Mongo for Moost.",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "atscript",
+    "annotations",
+    "typescript",
+    "moost",
+    "mongo"
+  ],
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/atscript.git",
+    "directory": "packages/moost-mongo"
+  },
+  "bugs": {
+    "url": "https://github.com/moostjs/atscript/issues"
+  },
+  "homepage": "https://github.com/moostjs/atscript/tree/main/packages/moost-mongo#readme",
+  "license": "ISC",
+  "dependencies": {
+    "urlql": "^0.0.4"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "@moostjs/event-http": "^0.5.30",
+    "mongodb": "^6.17.0",
+    "moost": "^0.5.30",
+    "@atscript/mongo": "^0.0.18",
+    "@atscript/typescript": "^0.0.18"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "before-build": "node ../typescript/cli.cjs -f js",
+    "test": "vitest"
+  }
+}