@atscript/moost-db 0.1.32

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/dist/index.cjs

@@ -0,0 +1,427 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __atscript_typescript_utils = __toESM(require("@atscript/typescript/utils"));
+const __moostjs_event_http = __toESM(require("@moostjs/event-http"));
+const moost = __toESM(require("moost"));
+const __uniqu_url = __toESM(require("@uniqu/url"));
+
+//#region packages/moost-db/src/decorators.ts
+const TABLE_DEF = "__atscript_db_table_def";
+const TableController = (table, prefix) => (0, moost.ApplyDecorators)((0, moost.Provide)(TABLE_DEF, () => table), (0, moost.Controller)(prefix || table.tableName), (0, moost.Inherit)());
+
+//#endregion
+//#region packages/moost-db/src/validation-interceptor.ts
+function transformValidationError(error, reply) {
+	if (error instanceof __atscript_typescript_utils.ValidatorError) reply(new __moostjs_event_http.HttpError(400, {
+		message: error.message,
+		statusCode: 400,
+		errors: error.errors
+	}));
+}
+const validationErrorTransform = () => (0, moost.defineInterceptor)({ error: transformValidationError }, moost.TInterceptorPriority.CATCH_ERROR);
+const UseValidationErrorTransform = () => (0, moost.Intercept)(validationErrorTransform());
+
+//#endregion
+//#region packages/moost-db/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 {
+	static toJsonSchema() {
+		(0, __atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(QueryControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(QueryControlsDto, "type", {});
+_define_property$1(QueryControlsDto, "metadata", new Map());
+_define_property$1(QueryControlsDto, "id", "QueryControlsDto");
+var PagesControlsDto = class {
+	static toJsonSchema() {
+		(0, __atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(PagesControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(PagesControlsDto, "type", {});
+_define_property$1(PagesControlsDto, "metadata", new Map());
+_define_property$1(PagesControlsDto, "id", "PagesControlsDto");
+var GetOneControlsDto = class {
+	static toJsonSchema() {
+		(0, __atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(GetOneControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(GetOneControlsDto, "type", {});
+_define_property$1(GetOneControlsDto, "metadata", new Map());
+_define_property$1(GetOneControlsDto, "id", "GetOneControlsDto");
+let SortControlDto = class SortControlDto$1 {
+	static toJsonSchema() {
+		(0, __atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(SortControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SortControlDto, "type", {});
+_define_property$1(SortControlDto, "metadata", new Map());
+_define_property$1(SortControlDto, "id", "SortControlDto");
+let SelectControlDto = class SelectControlDto$1 {
+	static toJsonSchema() {
+		(0, __atscript_typescript_utils.throwFeatureDisabled)("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SelectControlDto, "type", {});
+_define_property$1(SelectControlDto, "metadata", new Map());
+_define_property$1(SelectControlDto, "id", "SelectControlDto");
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript_utils.defineAnnotatedType)("union").item((0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, __atscript_typescript_utils.defineAnnotatedType)("array").of((0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type);
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", PagesControlsDto).prop("$page", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$size", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
+	pattern: "^\\d+$",
+	flags: "u",
+	message: "Expected positive number"
+}, true).optional().$type).prop("$sort", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript_utils.defineAnnotatedType)("union").item((0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, __atscript_typescript_utils.defineAnnotatedType)("array").of((0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type).prop("$search", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type);
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", GetOneControlsDto).prop("$select", (0, __atscript_typescript_utils.defineAnnotatedType)("union").item((0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).$type).item((0, __atscript_typescript_utils.defineAnnotatedType)("array").of((0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").$type).$type).optional().$type);
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", SortControlDto).propPattern(/./, (0, __atscript_typescript_utils.defineAnnotatedType)("union").item((0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").value(1).$type).item((0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").value(-1).$type).$type);
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", SelectControlDto).propPattern(/./, (0, __atscript_typescript_utils.defineAnnotatedType)("union").item((0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").value(1).$type).item((0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").value(0).$type).$type);
+
+//#endregion
+//#region packages/moost-db/src/as-db.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 AsDbController = class {
+	/**
+	* One-time initialization hook. Override to seed data, register watchers, etc.
+	*/ init() {}
+	get queryControlsValidator() {
+		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
+		return this._queryControlsValidator;
+	}
+	get pagesControlsValidator() {
+		if (!this._pagesControlsValidator) this._pagesControlsValidator = PagesControlsDto.validator();
+		return this._pagesControlsValidator;
+	}
+	get getOneControlsValidator() {
+		if (!this._getOneControlsValidator) this._getOneControlsValidator = GetOneControlsDto.validator();
+		return this._getOneControlsValidator;
+	}
+	validateControls(controls, type) {
+		const v = type === "query" ? this.queryControlsValidator : type === "pages" ? this.pagesControlsValidator : this.getOneControlsValidator;
+		if (!v.validate(controls, true)) return v.errors[0]?.message || "Invalid controls";
+		return undefined;
+	}
+	validateInsights(insights) {
+		for (const key of insights.keys()) if (!this.table.flatMap.has(key)) return `Unknown field "${key}"`;
+		return undefined;
+	}
+	validateParsed(parsed, type) {
+		const controlsError = this.validateControls(parsed.controls, type);
+		if (controlsError) return new __moostjs_event_http.HttpError(400, controlsError);
+		if (parsed.insights) {
+			const insightsError = this.validateInsights(parsed.insights);
+			if (insightsError) return new __moostjs_event_http.HttpError(400, insightsError);
+		}
+		return undefined;
+	}
+	/**
+	* Transform filter before querying. Override to add tenant filtering, etc.
+	*/ transformFilter(filter) {
+		return filter;
+	}
+	/**
+	* Transform projection before querying.
+	*/ transformProjection(projection) {
+		return projection;
+	}
+	/**
+	* Intercepts write operations. Return `undefined` to abort.
+	*/ onWrite(action, data) {
+		return data;
+	}
+	/**
+	* Intercepts delete operations. Return `undefined` to abort.
+	*/ onRemove(id) {
+		return id;
+	}
+	parseQueryString(url) {
+		const idx = url.indexOf("?");
+		return (0, __uniqu_url.parseUrl)(idx >= 0 ? url.slice(idx + 1) : "");
+	}
+	async returnOne(result) {
+		const item = await result;
+		if (!item) return new __moostjs_event_http.HttpError(404);
+		return item;
+	}
+	/**
+	* **GET /query** — returns an array of records or a count.
+	*/ async query(url) {
+		const parsed = this.parseQueryString(url);
+		const error = this.validateParsed(parsed, "query");
+		if (error) return error;
+		const controls = parsed.controls;
+		const filter = this.transformFilter(parsed.filter);
+		const select = this.transformProjection(controls.$select);
+		if (controls.$count) return this.table.count({
+			filter,
+			controls: {
+				...controls,
+				$select: select
+			}
+		});
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		if (searchTerm && this.table.isSearchable()) return this.table.search(searchTerm, {
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$limit: controls.$limit || 1e3
+			}
+		}, indexName);
+		return this.table.findMany({
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$limit: controls.$limit || 1e3
+			}
+		});
+	}
+	/**
+	* **GET /pages** — returns paginated records with metadata.
+	*/ async pages(url) {
+		const parsed = this.parseQueryString(url);
+		const error = this.validateParsed(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 filter = this.transformFilter(parsed.filter);
+		const select = this.transformProjection(controls.$select);
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		const query = {
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$skip: skip,
+				$limit: size
+			}
+		};
+		let result;
+		if (searchTerm && this.table.isSearchable()) result = await this.table.searchWithCount(searchTerm, query, indexName);
+else result = await this.table.findManyWithCount(query);
+		return {
+			data: result.data,
+			page,
+			itemsPerPage: size,
+			pages: Math.ceil(result.count / size),
+			count: result.count
+		};
+	}
+	/**
+	* **GET /one/:id** — retrieves a single record by ID or unique property.
+	*/ async getOne(id, url) {
+		const parsed = this.parseQueryString(url);
+		if (Object.keys(parsed.filter).length > 0) return new __moostjs_event_http.HttpError(400, "Filtering is not allowed for \"one\" endpoint");
+		const error = this.validateParsed(parsed, "getOne");
+		if (error) return error;
+		const select = this.transformProjection(parsed.controls.$select);
+		return this.returnOne(this.table.findById(id, { $select: select }));
+	}
+	/**
+	* **POST /** — inserts one or many records.
+	*/ async insert(payload) {
+		const arr = Array.isArray(payload) ? payload : [payload];
+		if (arr.length === 1) {
+			const data$1 = await this.onWrite("insert", arr[0]);
+			if (data$1 === undefined) return new __moostjs_event_http.HttpError(500, "Not saved");
+			return await this.table.insertOne(data$1);
+		}
+		const data = await this.onWrite("insertMany", arr);
+		if (data === undefined) return new __moostjs_event_http.HttpError(500, "Not saved");
+		return await this.table.insertMany(data);
+	}
+	/**
+	* **PUT /** — fully replaces a record matched by primary key.
+	*/ async replace(payload) {
+		const data = await this.onWrite("replace", payload);
+		if (data === undefined) return new __moostjs_event_http.HttpError(500, "Not saved");
+		return await this.table.replaceOne(data);
+	}
+	/**
+	* **PATCH /** — partially updates a record matched by primary key.
+	*/ async update(payload) {
+		const data = await this.onWrite("update", payload);
+		if (data === undefined) return new __moostjs_event_http.HttpError(500, "Not saved");
+		return await this.table.updateOne(data);
+	}
+	/**
+	* **DELETE /:id** — removes a single record by primary key.
+	*/ async remove(id) {
+		const resolvedId = await this.onRemove(id);
+		if (resolvedId === undefined) return new __moostjs_event_http.HttpError(500, "Not deleted");
+		const result = await this.table.deleteOne(resolvedId);
+		if (result.deletedCount < 1) return new __moostjs_event_http.HttpError(404);
+		return result;
+	}
+	/**
+	* **GET /meta** — returns table metadata for UI.
+	*/ meta() {
+		return {
+			searchable: this.table.isSearchable(),
+			searchIndexes: this._searchIndexes,
+			type: this._serializedType
+		};
+	}
+	constructor(table, app) {
+		/** Reference to the underlying table. */ _define_property(this, "table", void 0);
+		/** Application-scoped logger. */ _define_property(this, "logger", void 0);
+		/** Cached serialized type definition (static, computed once). */ _define_property(this, "_serializedType", void 0);
+		/** Cached search index list (static, computed once). */ _define_property(this, "_searchIndexes", void 0);
+		_define_property(this, "_queryControlsValidator", void 0);
+		_define_property(this, "_pagesControlsValidator", void 0);
+		_define_property(this, "_getOneControlsValidator", void 0);
+		this.table = table;
+		this._serializedType = (0, __atscript_typescript_utils.serializeAnnotatedType)(table.type);
+		this._searchIndexes = table.getSearchIndexes();
+		this.logger = app.getLogger(`db [${table.tableName}]`);
+		this.logger.info("Initializing table controller");
+		try {
+			const p = this.init();
+			if (p instanceof Promise) p.catch((error) => {
+				this.logger.error(error);
+			});
+		} catch (error) {
+			this.logger.error(error);
+			throw error;
+		}
+	}
+};
+_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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.prototype, "remove", null);
+_ts_decorate([
+	(0, __moostjs_event_http.Get)("meta"),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", []),
+	_ts_metadata("design:returntype", void 0)
+], AsDbController.prototype, "meta", null);
+AsDbController = _ts_decorate([
+	UseValidationErrorTransform(),
+	_ts_param(0, (0, moost.Inject)(TABLE_DEF)),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [typeof AtscriptDbTable === "undefined" ? Object : AtscriptDbTable, typeof moost.Moost === "undefined" ? Object : moost.Moost])
+], AsDbController);
+
+//#endregion
+Object.defineProperty(exports, 'AsDbController', {
+  enumerable: true,
+  get: function () {
+    return AsDbController;
+  }
+});
+exports.TABLE_DEF = TABLE_DEF
+exports.TableController = TableController
+exports.UseValidationErrorTransform = UseValidationErrorTransform
+exports.validationErrorTransform = validationErrorTransform

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import * as _atscript_typescript_serialize from '@atscript/typescript/serialize';
+import * as _atscript_utils_db from '@atscript/utils-db';
+import { AtscriptDbTable, Uniquery, FilterExpr, UniqueryControls } from '@atscript/utils-db';
+import * as _uniqu_url from '@uniqu/url';
+import { TAtscriptAnnotatedType, TAtscriptDataType, Validator } from '@atscript/typescript/utils';
+import { HttpError } from '@moostjs/event-http';
+import * as moost from 'moost';
+import { TConsoleBase, Moost } from 'moost';
+
+/**
+ * Generic database controller for Moost that works with any `AtscriptDbTable` +
+ * `BaseDbAdapter`. All CRUD routes through the generic table layer — no
+ * adapter-specific imports.
+ *
+ * Subclass and provide the table via DI:
+ * ```ts
+ * ‎@Provide(TABLE_DEF, () => driver.getTable(MyType))
+ * ‎@TableController(MyType)
+ * export class MyController extends AsDbController<typeof MyType> {}
+ * ```
+ */
+declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+    /** Reference to the underlying table. */
+    protected table: AtscriptDbTable<T>;
+    /** Application-scoped logger. */
+    protected logger: TConsoleBase;
+    /** Cached serialized type definition (static, computed once). */
+    private _serializedType;
+    /** Cached search index list (static, computed once). */
+    private _searchIndexes;
+    constructor(table: AtscriptDbTable<T>, app: Moost);
+    /**
+     * One-time initialization hook. Override to seed data, register watchers, etc.
+     */
+    protected init(): void | Promise<void>;
+    private _queryControlsValidator?;
+    private _pagesControlsValidator?;
+    private _getOneControlsValidator?;
+    protected get queryControlsValidator(): Validator<any, unknown>;
+    protected get pagesControlsValidator(): Validator<any, unknown>;
+    protected get getOneControlsValidator(): Validator<any, unknown>;
+    protected validateControls(controls: Record<string, unknown>, type: 'query' | 'pages' | 'getOne'): string | undefined;
+    protected validateInsights(insights: Map<string, unknown>): string | undefined;
+    protected validateParsed(parsed: Uniquery, type: 'query' | 'pages' | 'getOne'): HttpError | undefined;
+    /**
+     * Transform filter before querying. Override to add tenant filtering, etc.
+     */
+    protected transformFilter(filter: FilterExpr): FilterExpr;
+    /**
+     * Transform projection before querying.
+     */
+    protected transformProjection(projection?: UniqueryControls['$select']): UniqueryControls['$select'] | undefined;
+    /**
+     * Intercepts write operations. Return `undefined` to abort.
+     */
+    protected onWrite(action: 'insert' | 'insertMany' | 'replace' | 'update', data: unknown): unknown | Promise<unknown | undefined>;
+    /**
+     * Intercepts delete operations. Return `undefined` to abort.
+     */
+    protected onRemove(id: unknown): unknown | Promise<unknown | undefined>;
+    protected parseQueryString(url: string): _uniqu_url.UrlQuery;
+    protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
+    /**
+     * **GET /query** — returns an array of records or a count.
+     */
+    query(url: string): Promise<DataType[] | number | HttpError>;
+    /**
+     * **GET /pages** — returns paginated records with metadata.
+     */
+    pages(url: string): Promise<{
+        data: DataType[];
+        page: number;
+        itemsPerPage: number;
+        pages: number;
+        count: number;
+    } | HttpError>;
+    /**
+     * **GET /one/:id** — retrieves a single record by ID or unique property.
+     */
+    getOne(id: string, url: string): Promise<DataType | HttpError>;
+    /**
+     * **POST /** — inserts one or many records.
+     */
+    insert(payload: unknown): Promise<HttpError | unknown>;
+    /**
+     * **PUT /** — fully replaces a record matched by primary key.
+     */
+    replace(payload: unknown): Promise<HttpError | unknown>;
+    /**
+     * **PATCH /** — partially updates a record matched by primary key.
+     */
+    update(payload: unknown): Promise<HttpError | unknown>;
+    /**
+     * **DELETE /:id** — removes a single record by primary key.
+     */
+    remove(id: string): Promise<HttpError | unknown>;
+    /**
+     * **GET /meta** — returns table metadata for UI.
+     */
+    meta(): {
+        searchable: boolean;
+        searchIndexes: _atscript_utils_db.TSearchIndexInfo[];
+        type: _atscript_typescript_serialize.TSerializedAnnotatedType;
+    };
+}
+
+/**
+ * DI token under which the {@link AtscriptDbTable} instance
+ * is exposed to the controller's constructor via `@Inject`.
+ */
+declare const TABLE_DEF = "__atscript_db_table_def";
+/**
+ * Combines the boilerplate needed to turn an {@link AsDbController}
+ * subclass into a fully wired HTTP controller for a given `@db.table` model.
+ *
+ * Internally applies three decorators:
+ * 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
+ * 2. **Controller** — registers the class as a Moost HTTP controller
+ *    with an optional route prefix. Defaults to `table.tableName`.
+ * 3. **Inherit** — copies metadata (routes, guards, etc.) from the
+ *    parent class so they stay active in the derived controller.
+ *
+ * @param table  The {@link AtscriptDbTable} instance for this controller.
+ * @param prefix Optional route prefix. Defaults to `table.tableName`.
+ *
+ * @example
+ * ```ts
+ * ‎@TableController(usersTable)
+ * export class UsersController extends AsDbController<typeof UserModel> {}
+ * ```
+ */
+declare const TableController: (table: AtscriptDbTable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+
+declare const validationErrorTransform: () => moost.TInterceptorDef;
+declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
+
+export { AsDbController, TABLE_DEF, TableController, UseValidationErrorTransform, validationErrorTransform };

package/dist/index.mjs

@@ -0,0 +1,394 @@
+import { ValidatorError, defineAnnotatedType, serializeAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
+import { Body, Delete, Get, HttpError, Patch, Post, Put, Url } from "@moostjs/event-http";
+import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, TInterceptorPriority, defineInterceptor } from "moost";
+import { parseUrl } from "@uniqu/url";
+
+//#region packages/moost-db/src/decorators.ts
+const TABLE_DEF = "__atscript_db_table_def";
+const TableController = (table, prefix) => ApplyDecorators(Provide(TABLE_DEF, () => table), Controller(prefix || table.tableName), Inherit());
+
+//#endregion
+//#region packages/moost-db/src/validation-interceptor.ts
+function transformValidationError(error, reply) {
+	if (error instanceof ValidatorError) reply(new HttpError(400, {
+		message: error.message,
+		statusCode: 400,
+		errors: error.errors
+	}));
+}
+const validationErrorTransform = () => defineInterceptor({ error: transformValidationError }, TInterceptorPriority.CATCH_ERROR);
+const UseValidationErrorTransform = () => Intercept(validationErrorTransform());
+
+//#endregion
+//#region packages/moost-db/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 {
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(QueryControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(QueryControlsDto, "type", {});
+_define_property$1(QueryControlsDto, "metadata", new Map());
+_define_property$1(QueryControlsDto, "id", "QueryControlsDto");
+var PagesControlsDto = class {
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(PagesControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(PagesControlsDto, "type", {});
+_define_property$1(PagesControlsDto, "metadata", new Map());
+_define_property$1(PagesControlsDto, "id", "PagesControlsDto");
+var GetOneControlsDto = class {
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(GetOneControlsDto, "__is_atscript_annotated_type", true);
+_define_property$1(GetOneControlsDto, "type", {});
+_define_property$1(GetOneControlsDto, "metadata", new Map());
+_define_property$1(GetOneControlsDto, "id", "GetOneControlsDto");
+let SortControlDto = class SortControlDto$1 {
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(SortControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SortControlDto, "type", {});
+_define_property$1(SortControlDto, "metadata", new Map());
+_define_property$1(SortControlDto, "id", "SortControlDto");
+let SelectControlDto = class SelectControlDto$1 {
+	static toJsonSchema() {
+		throwFeatureDisabled("JSON Schema", "jsonSchema", "emit.jsonSchema");
+	}
+};
+_define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
+_define_property$1(SelectControlDto, "type", {});
+_define_property$1(SelectControlDto, "metadata", new Map());
+_define_property$1(SelectControlDto, "id", "SelectControlDto");
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").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("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type);
+defineAnnotatedType("object", GetOneControlsDto).prop("$select", defineAnnotatedType("union").item(defineAnnotatedType().refTo(SelectControlDto).$type).item(defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).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-db/src/as-db.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 AsDbController = class {
+	/**
+	* One-time initialization hook. Override to seed data, register watchers, etc.
+	*/ init() {}
+	get queryControlsValidator() {
+		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
+		return this._queryControlsValidator;
+	}
+	get pagesControlsValidator() {
+		if (!this._pagesControlsValidator) this._pagesControlsValidator = PagesControlsDto.validator();
+		return this._pagesControlsValidator;
+	}
+	get getOneControlsValidator() {
+		if (!this._getOneControlsValidator) this._getOneControlsValidator = GetOneControlsDto.validator();
+		return this._getOneControlsValidator;
+	}
+	validateControls(controls, type) {
+		const v = type === "query" ? this.queryControlsValidator : type === "pages" ? this.pagesControlsValidator : this.getOneControlsValidator;
+		if (!v.validate(controls, true)) return v.errors[0]?.message || "Invalid controls";
+		return undefined;
+	}
+	validateInsights(insights) {
+		for (const key of insights.keys()) if (!this.table.flatMap.has(key)) return `Unknown field "${key}"`;
+		return undefined;
+	}
+	validateParsed(parsed, type) {
+		const controlsError = this.validateControls(parsed.controls, type);
+		if (controlsError) return new HttpError(400, controlsError);
+		if (parsed.insights) {
+			const insightsError = this.validateInsights(parsed.insights);
+			if (insightsError) return new HttpError(400, insightsError);
+		}
+		return undefined;
+	}
+	/**
+	* Transform filter before querying. Override to add tenant filtering, etc.
+	*/ transformFilter(filter) {
+		return filter;
+	}
+	/**
+	* Transform projection before querying.
+	*/ transformProjection(projection) {
+		return projection;
+	}
+	/**
+	* Intercepts write operations. Return `undefined` to abort.
+	*/ onWrite(action, data) {
+		return data;
+	}
+	/**
+	* Intercepts delete operations. Return `undefined` to abort.
+	*/ onRemove(id) {
+		return id;
+	}
+	parseQueryString(url) {
+		const idx = url.indexOf("?");
+		return parseUrl(idx >= 0 ? url.slice(idx + 1) : "");
+	}
+	async returnOne(result) {
+		const item = await result;
+		if (!item) return new HttpError(404);
+		return item;
+	}
+	/**
+	* **GET /query** — returns an array of records or a count.
+	*/ async query(url) {
+		const parsed = this.parseQueryString(url);
+		const error = this.validateParsed(parsed, "query");
+		if (error) return error;
+		const controls = parsed.controls;
+		const filter = this.transformFilter(parsed.filter);
+		const select = this.transformProjection(controls.$select);
+		if (controls.$count) return this.table.count({
+			filter,
+			controls: {
+				...controls,
+				$select: select
+			}
+		});
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		if (searchTerm && this.table.isSearchable()) return this.table.search(searchTerm, {
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$limit: controls.$limit || 1e3
+			}
+		}, indexName);
+		return this.table.findMany({
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$limit: controls.$limit || 1e3
+			}
+		});
+	}
+	/**
+	* **GET /pages** — returns paginated records with metadata.
+	*/ async pages(url) {
+		const parsed = this.parseQueryString(url);
+		const error = this.validateParsed(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 filter = this.transformFilter(parsed.filter);
+		const select = this.transformProjection(controls.$select);
+		const searchTerm = controls.$search;
+		const indexName = controls.$index;
+		const query = {
+			filter,
+			controls: {
+				...controls,
+				$select: select,
+				$skip: skip,
+				$limit: size
+			}
+		};
+		let result;
+		if (searchTerm && this.table.isSearchable()) result = await this.table.searchWithCount(searchTerm, query, indexName);
+else result = await this.table.findManyWithCount(query);
+		return {
+			data: result.data,
+			page,
+			itemsPerPage: size,
+			pages: Math.ceil(result.count / size),
+			count: result.count
+		};
+	}
+	/**
+	* **GET /one/:id** — retrieves a single record by ID or unique property.
+	*/ async getOne(id, url) {
+		const parsed = this.parseQueryString(url);
+		if (Object.keys(parsed.filter).length > 0) return new HttpError(400, "Filtering is not allowed for \"one\" endpoint");
+		const error = this.validateParsed(parsed, "getOne");
+		if (error) return error;
+		const select = this.transformProjection(parsed.controls.$select);
+		return this.returnOne(this.table.findById(id, { $select: select }));
+	}
+	/**
+	* **POST /** — inserts one or many records.
+	*/ async insert(payload) {
+		const arr = Array.isArray(payload) ? payload : [payload];
+		if (arr.length === 1) {
+			const data$1 = await this.onWrite("insert", arr[0]);
+			if (data$1 === undefined) return new HttpError(500, "Not saved");
+			return await this.table.insertOne(data$1);
+		}
+		const data = await this.onWrite("insertMany", arr);
+		if (data === undefined) return new HttpError(500, "Not saved");
+		return await this.table.insertMany(data);
+	}
+	/**
+	* **PUT /** — fully replaces a record matched by primary key.
+	*/ async replace(payload) {
+		const data = await this.onWrite("replace", payload);
+		if (data === undefined) return new HttpError(500, "Not saved");
+		return await this.table.replaceOne(data);
+	}
+	/**
+	* **PATCH /** — partially updates a record matched by primary key.
+	*/ async update(payload) {
+		const data = await this.onWrite("update", payload);
+		if (data === undefined) return new HttpError(500, "Not saved");
+		return await this.table.updateOne(data);
+	}
+	/**
+	* **DELETE /:id** — removes a single record by primary key.
+	*/ async remove(id) {
+		const resolvedId = await this.onRemove(id);
+		if (resolvedId === undefined) return new HttpError(500, "Not deleted");
+		const result = await this.table.deleteOne(resolvedId);
+		if (result.deletedCount < 1) return new HttpError(404);
+		return result;
+	}
+	/**
+	* **GET /meta** — returns table metadata for UI.
+	*/ meta() {
+		return {
+			searchable: this.table.isSearchable(),
+			searchIndexes: this._searchIndexes,
+			type: this._serializedType
+		};
+	}
+	constructor(table, app) {
+		/** Reference to the underlying table. */ _define_property(this, "table", void 0);
+		/** Application-scoped logger. */ _define_property(this, "logger", void 0);
+		/** Cached serialized type definition (static, computed once). */ _define_property(this, "_serializedType", void 0);
+		/** Cached search index list (static, computed once). */ _define_property(this, "_searchIndexes", void 0);
+		_define_property(this, "_queryControlsValidator", void 0);
+		_define_property(this, "_pagesControlsValidator", void 0);
+		_define_property(this, "_getOneControlsValidator", void 0);
+		this.table = table;
+		this._serializedType = serializeAnnotatedType(table.type);
+		this._searchIndexes = table.getSearchIndexes();
+		this.logger = app.getLogger(`db [${table.tableName}]`);
+		this.logger.info("Initializing table controller");
+		try {
+			const p = this.init();
+			if (p instanceof Promise) p.catch((error) => {
+				this.logger.error(error);
+			});
+		} catch (error) {
+			this.logger.error(error);
+			throw error;
+		}
+	}
+};
+_ts_decorate([
+	Get("query"),
+	_ts_param(0, Url()),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [String]),
+	_ts_metadata("design:returntype", Promise)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.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)
+], AsDbController.prototype, "remove", null);
+_ts_decorate([
+	Get("meta"),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", []),
+	_ts_metadata("design:returntype", void 0)
+], AsDbController.prototype, "meta", null);
+AsDbController = _ts_decorate([
+	UseValidationErrorTransform(),
+	_ts_param(0, Inject(TABLE_DEF)),
+	_ts_metadata("design:type", Function),
+	_ts_metadata("design:paramtypes", [typeof AtscriptDbTable === "undefined" ? Object : AtscriptDbTable, typeof Moost === "undefined" ? Object : Moost])
+], AsDbController);
+
+//#endregion
+export { AsDbController, TABLE_DEF, TableController, UseValidationErrorTransform, validationErrorTransform };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@atscript/moost-db",
+  "version": "0.1.32",
+  "description": "Generic database controller for Moost with Atscript.",
+  "keywords": [
+    "annotations",
+    "atscript",
+    "database",
+    "moost",
+    "typescript"
+  ],
+  "homepage": "https://github.com/moostjs/atscript/tree/main/packages/moost-db#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/atscript/issues"
+  },
+  "license": "ISC",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/atscript.git",
+    "directory": "packages/moost-db"
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+  },
+  "dependencies": {
+    "@uniqu/url": "^0.0.1"
+  },
+  "devDependencies": {
+    "@moostjs/event-http": "^0.6.2",
+    "moost": "^0.6.2",
+    "vitest": "3.2.4",
+    "@atscript/core": "^0.1.32"
+  },
+  "peerDependencies": {
+    "@moostjs/event-http": "^0.6.2",
+    "moost": "^0.6.2",
+    "@uniqu/core": "^0.0.2",
+    "@atscript/utils-db": "^0.1.32",
+    "@atscript/typescript": "^0.1.32"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "before-build": "node ../typescript/cli.cjs -f js",
+    "test": "vitest"
+  }
+}