@atscript/moost-db 0.1.53 → 0.1.55

package/dist/index.mjs

@@ -1,72 +1,8 @@
 import { ValidatorError, defineAnnotatedType, serializeAnnotatedType, throwFeatureDisabled } from "@atscript/typescript/utils";
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
-import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, TInterceptorPriority, defineInterceptor } from "moost";
+import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Param, Provide, TInterceptorPriority, defineInterceptor, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
 import { DbError } from "@atscript/db";
-//#region src/decorators.ts
-/**
-* DI token under which the {@link AtscriptDbReadable} instance
-* is exposed to the readable controller's constructor via `@Inject`.
-*/
-const READABLE_DEF = "__atscript_db_readable_def";
-/**
-* DI token under which the {@link AtscriptDbTable} instance
-* is exposed to the controller's constructor via `@Inject`.
-* Points to the same token as READABLE_DEF for backward compatibility.
-*/
-const TABLE_DEF = READABLE_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> {}
-* ```
-*/
-const TableController = (table, prefix) => {
-	const resolvedPath = prefix || table.type.metadata.get("db.http.path");
-	return ApplyDecorators(Provide(TABLE_DEF, () => table), Controller(resolvedPath || table.tableName), Inherit());
-};
-/**
-* Combines the boilerplate needed to turn an {@link AsDbReadableController}
-* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
-*
-* @param readable  The {@link AtscriptDbReadable} instance (table or view).
-* @param prefix    Optional route prefix. Defaults to `readable.tableName`.
-*
-* @example
-* ```ts
-* ‎@ReadableController(activeTasksView)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ReadableController = (readable, prefix) => {
-	const resolvedPath = prefix || readable.type.metadata.get("db.http.path");
-	return ApplyDecorators(Provide(READABLE_DEF, () => readable), Controller(resolvedPath || readable.tableName), Inherit());
-};
-/**
-* Alias for {@link ReadableController} — use with view-backed controllers.
-*
-* @example
-* ```ts
-* ‎@ViewController(activeTasksView)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ViewController = ReadableController;
-//#endregion
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = { CONFLICT: 409 };
 function transformValidationError(error, reply) {
@@ -177,18 +113,77 @@ defineAnnotatedType("object", WithFilterDto).propPattern(/./, defineAnnotatedTyp
 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 src/gate-utils.ts
+/**
+* Walks a Uniquery filter expression and returns the first field name that
+* fails the `isAllowed` predicate, or `undefined` if every leaf field is
+* allowed. Logical combinators (`$and`, `$or`, `$nor`, `$not`) are traversed;
+* other `$`-prefixed keys are skipped.
+*
+* Shared by the DB readable's `@db.column.filterable` gate and the value-help
+* controller's `@ui.dict.filterable` gate — only the predicate differs.
+*/
+function findFilterOffender(filter, isAllowed) {
+	if (!filter || typeof filter !== "object") return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or" || key === "$nor") {
+			if (Array.isArray(value)) for (const sub of value) {
+				const inner = findFilterOffender(sub, isAllowed);
+				if (inner) return inner;
+			}
+			continue;
+		}
+		if (key === "$not") {
+			const inner = findFilterOffender(value, isAllowed);
+			if (inner) return inner;
+			continue;
+		}
+		if (key.startsWith("$")) continue;
+		if (!isAllowed(key)) return key;
+	}
+}
+/**
+* Walks a Uniquery `$sort` control (accepts string, string[], object, or
+* array-of-{field: dir}) and returns the first field name that fails the
+* `isAllowed` predicate, or `undefined` if every sort key is allowed.
+*
+* Shared by the DB readable's `@db.column.sortable` gate and the value-help
+* controller's `@ui.dict.sortable` gate.
+*/
+function findSortOffender(sort, isAllowed) {
+	if (!sort) return void 0;
+	const check = (name) => isAllowed(name) ? void 0 : name;
+	if (typeof sort === "string") {
+		for (const part of sort.split(",")) {
+			const name = part.trim().replace(/^[-+]/, "").split(":")[0];
+			if (name) {
+				const bad = check(name);
+				if (bad) return bad;
+			}
+		}
+		return;
+	}
+	if (Array.isArray(sort)) {
+		for (const entry of sort) if (typeof entry === "string") {
+			const bad = check(entry.replace(/^[-+]/, ""));
+			if (bad) return bad;
+		} else if (entry && typeof entry === "object") for (const name of Object.keys(entry)) {
+			const bad = check(name);
+			if (bad) return bad;
+		}
+		return;
+	}
+	if (typeof sort === "object") for (const name of Object.keys(sort)) {
+		const bad = check(name);
+		if (bad) return bad;
+	}
+}
+//#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
-function __decorateParam(paramIndex, decorator) {
-	return function(target, key) {
-		decorator(target, key, paramIndex);
-	};
-}
-//#endregion
 //#region \0@oxc-project+runtime@0.120.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -197,24 +192,27 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#endregion
-//#region src/as-db-readable.controller.ts
-var _ref$1, _ref2$1;
-let AsDbReadableController = class AsDbReadableController {
-	/** Reference to the underlying readable (table or view). */
-	readable;
+//#region src/as-readable.controller.ts
+var _ref$4;
+let AsReadableController = class AsReadableController {
+	/** The Atscript interface this controller serves. */
+	boundType;
+	/** Short human-readable name for logging (usually the table/source name). */
+	controllerName;
 	/** Application-scoped logger. */
 	logger;
-	/** Cached serialized type definition (lazy, computed on first access). */
-	_serializedType;
 	/** Moost application instance. */
 	app;
+	/** Cached serialized type definition (lazy, computed on first access). */
+	_serializedType;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
-	constructor(readable, app) {
-		this.readable = readable;
+	constructor(boundType, controllerName, app, kindTag = "readable") {
+		this.boundType = boundType;
+		this.controllerName = controllerName;
 		this.app = app;
-		this.logger = app.getLogger(`db [${readable.tableName}]`);
-		this.logger.info(`Initializing ${readable.isView ? "view" : "table"} controller`);
+		this.logger = app.getLogger(`db [${controllerName}]`);
+		this.logger.info(`Initializing ${kindTag} controller`);
 		this._resolveHttpPath();
 		try {
 			const p = this.init();
@@ -228,12 +226,19 @@ let AsDbReadableController = class AsDbReadableController {
 	}
 	/** Sets @db.http.path on the type metadata from the controller's computed prefix. */
 	_resolveHttpPath() {
-		const overview = this.app.getControllersOverview?.()?.find((o) => o.type === this.constructor);
-		if (overview?.computedPrefix) this.readable.type.metadata.set("db.http.path", overview.computedPrefix);
+		let prefix;
+		try {
+			prefix = useControllerContext().getPrefix();
+		} catch {}
+		if (!prefix) prefix = (this.app.getControllersOverview?.()?.find((o) => o.type === this.constructor))?.computedPrefix;
+		if (prefix) {
+			if (!prefix.startsWith("/")) prefix = `/${prefix}`;
+			this.boundType.metadata.set("db.http.path", prefix);
+		}
 	}
-	/** Lazily serializes the type (after all controllers have set their @db.http.path). */
+	/** Lazily serializes the bound type (after all controllers have set @db.http.path). */
 	getSerializedType() {
-		if (!this._serializedType) this._serializedType = serializeAnnotatedType(this.readable.type, this.getSerializeOptions());
+		if (!this._serializedType) this._serializedType = serializeAnnotatedType(this.boundType, this.getSerializeOptions());
 		return this._serializedType;
 	}
 	/**
@@ -242,13 +247,23 @@ let AsDbReadableController = class AsDbReadableController {
 	init() {}
 	/**
 	* Returns serialization options for the `/meta` endpoint's type field.
-	* Default: whitelist — keeps `meta.*`, `expect.*`, and `db.rel.*` annotations,
-	* strips all other `db.*` annotations (table, column, index, default, etc.).
-	* Override in subclass to customise what annotations are exposed to clients.
+	*
+	* `refDepth: 0.5` is intentionally static — independent of `@db.depth.limit`
+	* (which is a security guard on nested writes, not a serialization policy).
+	* The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
+	* which carries the target's `db.http.path` so clients can resolve value-help
+	* URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
+	* props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
+	* and always expand fully regardless of `refDepth` — the write-payload shape
+	* clients need is unaffected.
+	*
+	* Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
+	* other `db.*` (table, column, index, default, etc.). Override in subclass
+	* to customise.
 	*/
 	getSerializeOptions() {
 		return {
-			refDepth: 1,
+			refDepth: .5,
 			processAnnotation: ({ key, value }) => {
 				if (key.startsWith("meta.") || key.startsWith("expect.") || key.startsWith("db.rel.")) return {
 					key,
@@ -268,7 +283,7 @@ let AsDbReadableController = class AsDbReadableController {
 	}
 	/**
 	* Whether this controller is read-only (no write endpoints).
-	* Returns `true` for readable/view controllers, overridden to `false` in AsDbController.
+	* Returns `true` by default; {@link AsDbController} overrides to `false`.
 	*/
 	_isReadOnly() {
 		return true;
@@ -295,7 +310,7 @@ let AsDbReadableController = class AsDbReadableController {
 	validateInsights(insights) {
 		for (const [key] of insights) {
 			if (key === "*") continue;
-			if (!this.readable.flatMap.has(key)) return `Unknown field "${key}"`;
+			if (!this.hasField(key)) return `Unknown field "${key}"`;
 		}
 	}
 	validateParsed(parsed, type) {
@@ -305,6 +320,190 @@ let AsDbReadableController = class AsDbReadableController {
 			const insightsError = this.validateInsights(parsed.insights);
 			if (insightsError) return new HttpError(400, insightsError);
 		}
+	}
+	/**
+	* Shared filter/sort/search gate check. Subclasses assemble a {@link ReadableGates}
+	* config per request (or once in the constructor when static) and call this to
+	* get a uniform HTTP 400 response for any offending field/control.
+	*/
+	checkGates(filter, controls, gates) {
+		if (gates.filter) {
+			const bad = findFilterOffender(filter, gates.filter.predicate);
+			if (bad) return new HttpError(400, `Filtering on field "${bad}" is not permitted — add ${gates.filter.annotation} to enable.`);
+		}
+		if (gates.sort) {
+			const bad = findSortOffender(controls.$sort, gates.sort.predicate);
+			if (bad) return new HttpError(400, `Sorting on field "${bad}" is not permitted — add ${gates.sort.annotation} to enable.`);
+		}
+		if (gates.search && controls.$search && !gates.search.allowed) return new HttpError(400, gates.search.rejectionMessage);
+	}
+	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 /meta** — returns the bound interface's metadata envelope.
+	*
+	* Base implementation delegates to {@link buildMetaResponse}, which subclasses
+	* override to add source-specific fields (relations, searchable flags, etc.).
+	* The response is cached on the instance; async overrides must cache any
+	* extra enrichment themselves.
+	*/
+	async meta() {
+		if (this._metaResponse) return this._metaResponse;
+		const response = await this.buildMetaResponse();
+		this._metaResponse = response;
+		return response;
+	}
+	/**
+	* Builds the `/meta` payload. Override in subclasses to populate source-specific
+	* fields. Defaults return a minimal envelope with the serialized type and the
+	* read-only flag; value-help dicts populate their capability hints here.
+	*/
+	async buildMetaResponse() {
+		return {
+			searchable: false,
+			vectorSearchable: false,
+			searchIndexes: [],
+			primaryKeys: [],
+			readOnly: this._isReadOnly(),
+			relations: [],
+			fields: {},
+			type: this.getSerializedType()
+		};
+	}
+};
+__decorate([
+	Get("meta"),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Promise)
+], AsReadableController.prototype, "meta", null);
+AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
+	Object,
+	String,
+	typeof (_ref$4 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$4 : Object,
+	Object
+])], AsReadableController);
+//#endregion
+//#region src/decorators.ts
+/**
+* DI token under which the {@link AtscriptDbReadable} instance
+* is exposed to the readable controller's constructor via `@Inject`.
+*/
+const READABLE_DEF = "__atscript_db_readable_def";
+/**
+* DI token under which the {@link AtscriptDbTable} instance
+* is exposed to the controller's constructor via `@Inject`.
+* Points to the same token as READABLE_DEF for backward compatibility.
+*/
+const TABLE_DEF = READABLE_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> {}
+* ```
+*/
+const TableController = (table, prefix) => {
+	const resolvedPath = prefix || table.type.metadata.get("db.http.path");
+	return ApplyDecorators(Provide(TABLE_DEF, () => table), Controller(resolvedPath || table.tableName), Inherit());
+};
+/**
+* Combines the boilerplate needed to turn an {@link AsDbReadableController}
+* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
+*
+* @param readable  The {@link AtscriptDbReadable} instance (table or view).
+* @param prefix    Optional route prefix. Defaults to `readable.tableName`.
+*
+* @example
+* ```ts
+* ‎@ReadableController(activeTasksView)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ReadableController = (readable, prefix) => {
+	const resolvedPath = prefix || readable.type.metadata.get("db.http.path");
+	return ApplyDecorators(Provide(READABLE_DEF, () => readable), Controller(resolvedPath || readable.tableName), Inherit());
+};
+/**
+* Alias for {@link ReadableController} — use with view-backed controllers.
+*
+* @example
+* ```ts
+* ‎@ViewController(activeTasksView)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ViewController = ReadableController;
+//#endregion
+//#region \0@oxc-project+runtime@0.120.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region src/as-db-readable.controller.ts
+var _ref$3, _ref2$2;
+let AsDbReadableController = class AsDbReadableController extends AsReadableController {
+	/** Reference to the underlying readable (table or view). */
+	readable;
+	_gates;
+	constructor(readable, app) {
+		super(readable.type, readable.tableName, app, readable.isView ? "view" : "table");
+		this.readable = readable;
+		this._gates = this._buildGates();
+	}
+	_buildGates() {
+		const meta = this.readable.type.metadata;
+		const gates = {};
+		if (meta.get("db.table.filterable") === "manual") {
+			const allowed = this._collectAnnotated("db.column.filterable");
+			gates.filter = {
+				predicate: (f) => allowed.has(f),
+				annotation: "@db.column.filterable"
+			};
+		}
+		if (meta.get("db.table.sortable") === "manual") {
+			const allowed = this._collectAnnotated("db.column.sortable");
+			gates.sort = {
+				predicate: (f) => allowed.has(f),
+				annotation: "@db.column.sortable"
+			};
+		}
+		return gates;
+	}
+	_collectAnnotated(annotation) {
+		const out = /* @__PURE__ */ new Set();
+		for (const [path, entry] of this.readable.flatMap) if (entry.metadata.has(annotation)) out.add(path);
+		return out;
+	}
+	hasField(path) {
+		return this.readable.flatMap.has(path);
+	}
+	/** Validates $with relations against the readable. */
+	validateParsed(parsed, type) {
+		const baseError = super.validateParsed(parsed, type);
+		if (baseError) return baseError;
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
@@ -340,15 +539,6 @@ let AsDbReadableController = class AsDbReadableController {
 	transformProjection(projection) {
 		return projection;
 	}
-	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;
-	}
 	/**
 	* Extracts a composite identifier object from query params.
 	* Tries composite primary key first, then compound unique indexes.
@@ -403,6 +593,8 @@ let AsDbReadableController = class AsDbReadableController {
 		}
 		const error = this.validateParsed(parsed, "query");
 		if (error) return error;
+		const gateError = this.checkGates(parsed.filter, controls, this._gates);
+		if (gateError) return gateError;
 		const [filter, select] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
 		if (controls.$count) return this.readable.count({
 			filter,
@@ -440,6 +632,8 @@ let AsDbReadableController = class AsDbReadableController {
 		const error = this.validateParsed(parsed, "pages");
 		if (error) return error;
 		const controls = parsed.controls;
+		const gateError = this.checkGates(parsed.filter, controls, this._gates);
+		if (gateError) return gateError;
 		const page = Math.max(Number(controls.$page || 1), 1);
 		const size = Math.max(Number(controls.$size || 10), 1);
 		const skip = (page - 1) * size;
@@ -506,28 +700,31 @@ let AsDbReadableController = class AsDbReadableController {
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
 	*
-	* The return type includes `Promise<...>` so subclasses can override with an
-	* async implementation (e.g. to enrich the payload from an external source).
-	* The base cache only covers the base payload — async overrides must cache
-	* their own enrichment if needed.
+	* Overrides the base's minimal envelope to add relations, searchable flags,
+	* vector-searchable flags, field-descriptor-derived filter/sort hints, and
+	* the configured primary keys.
 	*/
-	meta() {
-		if (this._metaResponse) return this._metaResponse;
+	async buildMetaResponse() {
 		const relations = [];
 		for (const [name, rel] of this.readable.relations) relations.push({
 			name,
 			direction: rel.direction,
 			isArray: rel.isArray
 		});
+		const filterableMode = this.readable.type.metadata.get("db.table.filterable") === "manual";
+		const sortableMode = this.readable.type.metadata.get("db.table.sortable") === "manual";
 		const fields = {};
 		for (const fd of this.readable.fieldDescriptors) {
 			if (fd.ignored) continue;
+			const annotations = fd.type?.metadata;
+			const annotatedFilterable = annotations?.has("db.column.filterable") ?? false;
+			const annotatedSortable = annotations?.has("db.column.sortable") ?? false;
 			fields[fd.path] = {
-				sortable: !!fd.isIndexed,
-				filterable: true
+				sortable: sortableMode ? annotatedSortable : !!fd.isIndexed,
+				filterable: filterableMode ? annotatedFilterable : true
 			};
 		}
-		const response = {
+		return {
 			searchable: this.readable.isSearchable(),
 			vectorSearchable: this.readable.isVectorSearchable(),
 			searchIndexes: this.readable.getSearchIndexes(),
@@ -537,8 +734,6 @@ let AsDbReadableController = class AsDbReadableController {
 			fields,
 			type: this.getSerializedType()
 		};
-		this._metaResponse = response;
-		return response;
 	}
 };
 __decorate([
@@ -568,23 +763,17 @@ __decorate([
 	__decorateParam(0, Query()),
 	__decorateParam(1, Url()),
 	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", [typeof (_ref2$1 = typeof Record !== "undefined" && Record) === "function" ? _ref2$1 : Object, String]),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2$2 = typeof Record !== "undefined" && Record) === "function" ? _ref2$2 : Object, String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbReadableController.prototype, "getOneComposite", null);
-__decorate([
-	Get("meta"),
-	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", []),
-	__decorateMetadata("design:returntype", Object)
-], AsDbReadableController.prototype, "meta", null);
 AsDbReadableController = __decorate([
-	UseValidationErrorTransform(),
+	Inherit(),
 	__decorateParam(0, Inject(READABLE_DEF)),
-	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$1 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$1 : Object])
+	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$3 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$3 : Object])
 ], AsDbReadableController);
 //#endregion
 //#region src/as-db.controller.ts
-var _ref, _ref2;
+var _ref$2, _ref2$1;
 let AsDbController = class AsDbController extends AsDbReadableController {
 	/** Reference to the underlying table (typed for write access). */
 	get table() {
@@ -705,13 +894,321 @@ __decorate([
 	Delete(""),
 	__decorateParam(0, Query()),
 	__decorateMetadata("design:type", Function),
-	__decorateMetadata("design:paramtypes", [typeof (_ref2 = typeof Record !== "undefined" && Record) === "function" ? _ref2 : Object]),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2$1 = typeof Record !== "undefined" && Record) === "function" ? _ref2$1 : Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbController.prototype, "removeComposite", null);
 AsDbController = __decorate([
 	Inherit(),
 	__decorateParam(0, Inject(TABLE_DEF)),
-	__decorateMetadata("design:paramtypes", [Object, typeof (_ref = typeof Moost !== "undefined" && Moost) === "function" ? _ref : Object])
+	__decorateMetadata("design:paramtypes", [Object, typeof (_ref$2 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$2 : Object])
 ], AsDbController);
 //#endregion
-export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };
+//#region src/as-value-help.controller.ts
+var _ref$1, _ref2;
+let AsValueHelpController = class AsValueHelpController extends AsReadableController {
+	/** Per-prop metadata map of the bound interface; eagerly built once. */
+	fieldMeta;
+	/**
+	* Fields that participate in `$search` by default. Populated from
+	* `@ui.dict.searchable`:
+	* - If any prop carries `@ui.dict.searchable`, only those props are here.
+	* - Else if the interface carries `@ui.dict.searchable`, every `string`-typed prop is here.
+	* - Else every `string`-typed prop is here (hint is absent — default to all strings).
+	*/
+	searchableFields;
+	/** The `@meta.id` field name on the bound interface, if any. */
+	primaryKey;
+	constructor(boundType, controllerName, app) {
+		super(boundType, controllerName, app, "value-help");
+		const fieldMeta = /* @__PURE__ */ new Map();
+		const explicitlySearchable = [];
+		const stringProps = [];
+		let primaryKey;
+		const interfaceSearchable = boundType.metadata.has("ui.dict.searchable");
+		const asObj = boundType.type;
+		if (asObj?.props) for (const [name, prop] of asObj.props) {
+			const meta = prop.metadata;
+			fieldMeta.set(name, meta);
+			if (!primaryKey && meta.has("meta.id")) primaryKey = name;
+			if (prop.type.designType === "string") stringProps.push(name);
+			if (meta.has("ui.dict.searchable")) explicitlySearchable.push(name);
+		}
+		this.fieldMeta = fieldMeta;
+		this.primaryKey = primaryKey;
+		this.searchableFields = explicitlySearchable.length > 0 ? explicitlySearchable : interfaceSearchable ? stringProps : stringProps;
+	}
+	hasField(path) {
+		return this.fieldMeta.has(path);
+	}
+	/**
+	* **GET /query** — returns an array of matched rows (up to `$limit`).
+	*/
+	async runQuery(url) {
+		const parsed = this.parseQueryString(url);
+		const validateError = this.validateParsed(parsed, "query");
+		if (validateError) return validateError;
+		return (await this.query({
+			filter: parsed.filter,
+			controls: parsed.controls
+		})).data;
+	}
+	/**
+	* **GET /pages** — paginated row window plus total count.
+	*/
+	async runPages(url) {
+		const parsed = this.parseQueryString(url);
+		const validateError = this.validateParsed(parsed, "pages");
+		if (validateError) return validateError;
+		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.query({
+			filter: parsed.filter,
+			controls: {
+				...controls,
+				$skip: skip,
+				$limit: size
+			}
+		});
+		return {
+			data: result.data,
+			page,
+			itemsPerPage: size,
+			pages: Math.ceil(result.count / size),
+			count: result.count
+		};
+	}
+	/**
+	* **GET /one/:id** — retrieves a single row by primary key.
+	*/
+	async runGetOne(id) {
+		return this.returnOne(this.getOne(id));
+	}
+	/**
+	* **GET /one?<pk>=<val>** — retrieves a single row by PK query param (fallback).
+	*/
+	async runGetOneComposite(query) {
+		const pk = this.primaryKey;
+		if (!pk) return new HttpError(400, "No primary key (@meta.id) on value-help interface");
+		const id = query[pk];
+		if (id === void 0) return new HttpError(400, `Missing PK field "${pk}"`);
+		return this.returnOne(this.getOne(id));
+	}
+	/**
+	* Meta response surfaces `@ui.dict.*` annotations as **hints** for the
+	* client picker UI (which controls to render); the server does not enforce
+	* these flags at request time.
+	*/
+	async buildMetaResponse() {
+		const fields = {};
+		for (const [path, meta] of this.fieldMeta) fields[path] = {
+			sortable: meta.has("ui.dict.sortable"),
+			filterable: meta.has("ui.dict.filterable")
+		};
+		return {
+			searchable: this.searchableFields.length > 0,
+			vectorSearchable: false,
+			searchIndexes: [],
+			primaryKeys: this.primaryKey ? [this.primaryKey] : [],
+			readOnly: this._isReadOnly(),
+			relations: [],
+			fields,
+			type: this.getSerializedType()
+		};
+	}
+};
+__decorate([
+	Get("query"),
+	__decorateParam(0, Url()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runQuery", null);
+__decorate([
+	Get("pages"),
+	__decorateParam(0, Url()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runPages", null);
+__decorate([
+	Get("one/:id"),
+	__decorateParam(0, Param("id")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [String]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runGetOne", null);
+__decorate([
+	Get("one"),
+	__decorateParam(0, Query()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [typeof (_ref2 = typeof Record !== "undefined" && Record) === "function" ? _ref2 : Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AsValueHelpController.prototype, "runGetOneComposite", null);
+AsValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
+	Object,
+	String,
+	typeof (_ref$1 = typeof Moost !== "undefined" && Moost) === "function" ? _ref$1 : Object
+])], AsValueHelpController);
+//#endregion
+//#region src/as-json-value-help.controller.ts
+var _ref;
+let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueHelpController {
+	rows;
+	_pkIndex;
+	constructor(boundType, rows, app, controllerName) {
+		const name = controllerName || boundType.metadata.get("db.table") || "value-help";
+		super(boundType, name, app);
+		this.rows = rows;
+		if (this.primaryKey) {
+			const pk = this.primaryKey;
+			const index = /* @__PURE__ */ new Map();
+			for (const row of rows) index.set(String(row[pk]), row);
+			this._pkIndex = index;
+		}
+	}
+	async query(controls) {
+		let rows = this.rows;
+		if (controls.filter && Object.keys(controls.filter).length > 0) rows = rows.filter((row) => matchFilter(row, controls.filter));
+		const search = controls.controls.$search;
+		if (search) {
+			const needle = search.toLowerCase();
+			const fields = this.searchableFields;
+			rows = rows.filter((row) => {
+				for (const field of fields) {
+					const v = row[field];
+					if (typeof v === "string" && v.toLowerCase().includes(needle)) return true;
+				}
+				return false;
+			});
+		}
+		if (controls.controls.$sort) rows = sortRows(rows, controls.controls.$sort);
+		const total = rows.length;
+		const skip = Math.max(0, Number(controls.controls.$skip ?? 0));
+		const limit = Math.max(0, Number(controls.controls.$limit ?? total - skip));
+		return {
+			data: applySelect(rows.slice(skip, skip + limit), controls.controls.$select),
+			count: total
+		};
+	}
+	async getOne(id) {
+		return this._pkIndex?.get(String(id)) ?? null;
+	}
+};
+AsJsonValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
+	Object,
+	Array,
+	typeof (_ref = typeof Moost !== "undefined" && Moost) === "function" ? _ref : Object,
+	String
+])], AsJsonValueHelpController);
+function matchFilter(row, filter) {
+	if (!filter || typeof filter !== "object") return true;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and") {
+			if (!Array.isArray(value)) continue;
+			if (!value.every((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$or") {
+			if (!Array.isArray(value)) continue;
+			if (!value.some((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$nor") {
+			if (!Array.isArray(value)) continue;
+			if (value.some((clause) => matchFilter(row, clause))) return false;
+			continue;
+		}
+		if (key === "$not") {
+			if (matchFilter(row, value)) return false;
+			continue;
+		}
+		if (key.startsWith("$")) continue;
+		const fieldValue = row[key];
+		if (!matchFieldPredicate(fieldValue, value)) return false;
+	}
+	return true;
+}
+function matchFieldPredicate(fieldValue, predicate) {
+	if (predicate === null || typeof predicate !== "object" || Array.isArray(predicate)) return fieldValue === predicate;
+	for (const [op, operand] of Object.entries(predicate)) switch (op) {
+		case "$eq":
+			if (fieldValue !== operand) return false;
+			break;
+		case "$ne":
+			if (fieldValue === operand) return false;
+			break;
+		case "$in":
+			if (!Array.isArray(operand) || !operand.includes(fieldValue)) return false;
+			break;
+		case "$nin":
+			if (!Array.isArray(operand) || operand.includes(fieldValue)) return false;
+			break;
+		case "$gt":
+			if (!(fieldValue > operand)) return false;
+			break;
+		case "$gte":
+			if (!(fieldValue >= operand)) return false;
+			break;
+		case "$lt":
+			if (!(fieldValue < operand)) return false;
+			break;
+		case "$lte":
+			if (!(fieldValue <= operand)) return false;
+			break;
+		case "$regex": {
+			const re = operand instanceof RegExp ? operand : new RegExp(String(operand));
+			if (typeof fieldValue !== "string" || !re.test(fieldValue)) return false;
+			break;
+		}
+		default: if (fieldValue !== operand) return false;
+	}
+	return true;
+}
+function sortRows(rows, sort) {
+	const keys = [];
+	const push = (name, explicit) => {
+		const clean = name.replace(/^[-+]/, "");
+		const dir = explicit ?? (name.startsWith("-") ? -1 : 1);
+		if (clean) keys.push({
+			name: clean,
+			dir
+		});
+	};
+	if (typeof sort === "string") for (const part of sort.split(",")) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+		const [name, dir] = trimmed.split(":");
+		push(name, dir === "desc" ? -1 : dir === "asc" ? 1 : void 0);
+	}
+	else if (Array.isArray(sort)) {
+		for (const entry of sort) if (typeof entry === "string") push(entry);
+		else if (entry && typeof entry === "object") for (const [name, d] of Object.entries(entry)) push(name, d === "desc" || d === -1 ? -1 : 1);
+	} else if (sort && typeof sort === "object") for (const [name, d] of Object.entries(sort)) push(name, d === "desc" || d === -1 ? -1 : 1);
+	if (keys.length === 0) return rows;
+	const out = rows.slice();
+	out.sort((a, b) => {
+		for (const { name, dir } of keys) {
+			const av = a[name];
+			const bv = b[name];
+			if (av === bv) continue;
+			if (av === void 0 || av === null) return -1 * dir;
+			if (bv === void 0 || bv === null) return 1 * dir;
+			if (av < bv) return -1 * dir;
+			if (av > bv) return 1 * dir;
+		}
+		return 0;
+	});
+	return out;
+}
+function applySelect(rows, select) {
+	if (!select?.length) return rows;
+	return rows.map((row) => {
+		const out = {};
+		for (const key of select) out[key] = row[key];
+		return out;
+	});
+}
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };