@atscript/moost-db 0.1.131 → 0.1.133

package/dist/index.mjs

@@ -3,7 +3,8 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { DbError, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isPlainObject, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
+import { ADAPTER_FILTER_REASON, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, unsupportedOperatorMessage } from "@atscript/db";
+import { BUCKET_UNITS } from "@uniqu/core";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
@@ -37,7 +38,8 @@ function badRequest(path, message, top = message) {
 const dbErrorCodeToStatus = {
 	CONFLICT: 409,
 	CAS_MISMATCH: 409,
-	TX_WAIT_TIMEOUT: 503
+	TX_WAIT_TIMEOUT: 503,
+	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
 	if (error instanceof ValidatorError) reply(errorEnvelope(400, error.message, error.errors));
@@ -629,6 +631,8 @@ let AsReadableController = class AsReadableController {
 	_serializedType;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
+	/** {@link metaCacheKey} the cached response was built for. */
+	_metaResponseKey;
 	/** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
 	_formSchemas = /* @__PURE__ */ new Map();
 	constructor(boundType, controllerName, app, kindTag = "readable") {
@@ -822,14 +826,26 @@ let AsReadableController = class AsReadableController {
 	}
 	/**
 	* **GET /meta** — returns the bound interface's metadata envelope. The
-	* static envelope is cached; {@link applyMetaOverlay} runs per request so
-	* subclasses can prune the response by principal.
+	* static envelope is cached (rebuilt when {@link metaCacheKey} changes);
+	* {@link applyMetaOverlay} runs per request so subclasses can prune the
+	* response by principal.
 	*/
 	async meta() {
-		if (!this._metaResponse) this._metaResponse = this.buildMetaResponse();
+		const key = this.metaCacheKey();
+		if (!this._metaResponse || key !== this._metaResponseKey) {
+			this._metaResponse = this.buildMetaResponse();
+			this._metaResponseKey = key;
+		}
 		return this.applyMetaOverlay(this._metaResponse);
 	}
 	/**
+	* Identity of the inputs the cached `/meta` envelope is built from — a new
+	* value rebuilds it. Default: constant (built once). The DB readable
+	* controller returns its capability index, which is rebuilt when the
+	* adapter's capabilities change (since 0.1.132).
+	*/
+	metaCacheKey() {}
+	/**
 	* **GET /meta/form/:name** — returns the serialized schema of a form
 	* referenced by an action's `inputForm` field. The form name is the
 	* compiled `.as` class's `.name`, registered when an action's parameter is
@@ -1138,10 +1154,10 @@ function resolveBoundReadable(ctor) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
-const REASON_ADAPTER_FILTER = "adapter cannot filter on this storage type.";
+const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER_REASON}.`;
 const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
 const REASON_WRITE_ONLY = "field is @db.writeOnly.";
-const REASON_ENCRYPTED = "field is @db.encrypted (ciphertext cannot be compared or ordered).";
+const REASON_ENCRYPTED = `${ENCRYPTED_REASON}.`;
 const REASON_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
 const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
 /** Sentence subject per op ("Filtering on field …"). */
@@ -1151,7 +1167,8 @@ const OP_SUBJECT = {
 	select: "Selecting",
 	groupBy: "Grouping by",
 	having: "Filtering ($having) on",
-	aggregate: "Aggregating over"
+	aggregate: "Aggregating over",
+	bucket: "Bucketing"
 };
 /** Lower-case verb per op ("… cannot filter JSON paths"). */
 const OP_VERB = {
@@ -1160,7 +1177,8 @@ const OP_VERB = {
 	select: "select",
 	groupBy: "group by",
 	having: "filter ($having) on",
-	aggregate: "aggregate over"
+	aggregate: "aggregate over",
+	bucket: "bucket"
 };
 function leafHint(leaves) {
 	if (leaves.length === 0) return "no leaf fields";
@@ -1168,17 +1186,22 @@ function leafHint(leaves) {
 	return leaves.length > 5 ? `${shown}, …` : shown;
 }
 /**
-* Capability index of one readable, built once per controller.
+* Capability index of one readable.
 *
 * - {@link entries} feeds `/meta.fields` (listed leaves in descriptor order);
 * - {@link check} is the request gate: same inputs, same answer.
 *
+* Built from the adapter's capabilities as they are NOW. Some are only known
+* after schema sync (PostgreSQL learns PostGIS there), so owners rebuild the
+* index when {@link adapterSignature} changes (see `AsDbReadableController`'s
+* `capabilities` getter) instead of keeping a constructor-time snapshot.
+*
 * Paths outside the index are classified by the core's `classifyQueryPath`
 * (the same rules the core backstop applies) — navigation path, nested-object
 * parent, JSON descendant (relational adapters), encrypted descendant,
 * unknown — so the 400 names the storage reason and the alternative.
 */
-var FieldCapabilityIndex = class {
+var FieldCapabilityIndex = class FieldCapabilityIndex {
 	filterableManual;
 	sortableManual;
 	/** Navigation relations (`@db.rel.to/from/via`), incl. nested ones. */
@@ -1189,9 +1212,26 @@ var FieldCapabilityIndex = class {
 	jsonParents;
 	/** Descriptors carrying `@db.encrypted` (the ciphertext column on relational adapters). */
 	encryptedFields;
+	/** Every field descriptor's `physicalName` — names a calendar-bucket alias may not take. */
+	physicalNames;
+	/** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
+	bucketUnits;
+	/** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
+	signature;
+	/**
+	* The adapter-level capabilities that can change after construction (geo
+	* support, calendar-bucket units): an index whose {@link signature}
+	* differs from this is stale. Any new adapter-level input the index reads
+	* must be added here.
+	*/
+	static adapterSignature(source) {
+		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}`;
+	}
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
 	_objectParents = /* @__PURE__ */ new Map();
+	/** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+	_bucketTable;
 	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
 	get leaves() {
 		return this._entries;
@@ -1201,12 +1241,25 @@ var FieldCapabilityIndex = class {
 		return this._objectParents;
 	}
 	constructor(source, writeOnly) {
-		const canFilter = (fd) => source.canFilterField(fd);
-		const canSort = (fd) => source.canSortField(fd);
 		const tableMeta = source.type.metadata;
 		this.filterableManual = tableMeta.get("db.table.filterable") === "manual";
 		this.sortableManual = tableMeta.get("db.table.sortable") === "manual";
 		this.writeOnly = writeOnly;
+		this.signature = FieldCapabilityIndex.adapterSignature(source);
+		const units = source.calendarBucketUnits();
+		this.bucketUnits = BUCKET_UNITS.filter((unit) => units.has(unit));
+		const physicalNames = /* @__PURE__ */ new Set();
+		const jsonValueParents = /* @__PURE__ */ new Set();
+		for (const fd of source.fieldDescriptors) {
+			physicalNames.add(fd.physicalName);
+			if (isJsonValueField(fd)) jsonValueParents.add(fd.path);
+		}
+		this.physicalNames = physicalNames;
+		this._bucketTable = {
+			jsonValueParents,
+			dimensions: source.dimensions,
+			measures: source.measures
+		};
 		const nav = new Set(source.navFields);
 		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
 		this.navFields = nav;
@@ -1228,7 +1281,7 @@ var FieldCapabilityIndex = class {
 				this._objectParents.set(fd.path, []);
 				continue;
 			}
-			this._entries.set(fd.path, this._buildEntry(fd, canFilter, canSort, annotated));
+			this._entries.set(fd.path, this._buildEntry(fd, source, annotated));
 		}
 		const ignored = source.ignoredFields;
 		for (const [path, entry] of flatMap) {
@@ -1248,49 +1301,45 @@ var FieldCapabilityIndex = class {
 		this.jsonParents = jsonParents;
 		this.encryptedFields = encrypted;
 	}
-	_buildEntry(fd, canFilter, canSort, annotated) {
-		const physicalFilter = canFilter(fd);
-		const physicalSort = canSort(fd);
+	_buildEntry(fd, source, annotated) {
 		const isWriteOnly = this.writeOnly.has(fd.path);
-		let filterable = physicalFilter;
-		let sortable = physicalSort;
-		let filterReason = physicalFilter ? void 0 : REASON_ADAPTER_FILTER;
-		let sortReason = physicalSort ? void 0 : REASON_ADAPTER_SORT;
-		let physicalReason = physicalFilter ? void 0 : REASON_ADAPTER_FILTER;
-		if (fd.encrypted) {
-			filterable = false;
-			sortable = false;
-			filterReason = REASON_ENCRYPTED;
-			sortReason = REASON_ENCRYPTED;
-			physicalReason = REASON_ENCRYPTED;
-		}
-		if (isWriteOnly) {
-			filterable = false;
-			sortable = false;
-			filterReason = REASON_WRITE_ONLY;
-			sortReason = REASON_WRITE_ONLY;
-			physicalReason = REASON_WRITE_ONLY;
-		}
-		if (filterable && this.filterableManual && !annotated(fd, "db.column.filterable")) {
-			filterable = false;
-			filterReason = REASON_ANNOTATION_FILTER;
-		}
-		if (sortable && this.sortableManual && !annotated(fd, "db.column.sortable")) {
-			sortable = false;
-			sortReason = REASON_ANNOTATION_SORT;
-		}
+		const filterPolicyBlocked = this.filterableManual && !annotated(fd, "db.column.filterable");
+		const verdict = (predicate, policy) => {
+			if (isWriteOnly) return REASON_WRITE_ONLY;
+			if (fd.encrypted) return REASON_ENCRYPTED;
+			if (!canFilterLeaf(fd, predicate, source)) return REASON_ADAPTER_FILTER;
+			if (policy && filterPolicyBlocked) return REASON_ANNOTATION_FILTER;
+		};
+		const filterBy = {
+			compare: verdict("compare", true),
+			exists: verdict("exists", true),
+			geo: verdict("geo", true)
+		};
+		const filterOps = filterBy.compare === REASON_ADAPTER_FILTER && !filterPolicyBlocked ? narrowerFilterOps(fd, source) : [];
+		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER_REASON}${acceptedOperatorsHint(filterOps)}.`;
+		const physicalReason = verdict("compare", false);
+		let sortReason = source.canSortField(fd) ? void 0 : REASON_ADAPTER_SORT;
+		if (fd.encrypted) sortReason = REASON_ENCRYPTED;
+		if (isWriteOnly) sortReason = REASON_WRITE_ONLY;
+		if (!sortReason && this.sortableManual && !annotated(fd, "db.column.sortable")) sortReason = REASON_ANNOTATION_SORT;
+		const bucket = isWriteOnly ? void 0 : bucketSourceVerdict(fd, this._bucketTable, source);
+		const bucketReason = !bucket ? REASON_WRITE_ONLY : bucket.ok ? void 0 : `${bucket.reason}.`;
 		const cap = {
-			filterable,
-			sortable,
+			filterable: filterBy.compare === void 0,
+			sortable: sortReason === void 0,
 			selectable: true,
-			indexed: fd.isIndexed === true
+			indexed: fd.isIndexed === true,
+			bucketable: bucketReason === void 0
 		};
-		if (filterReason) cap.filterReason = filterReason;
+		if (filterOps.length > 0) cap.filterOps = filterOps;
+		if (filterBy.compare) cap.filterReason = filterBy.compare;
 		if (sortReason) cap.sortReason = sortReason;
+		if (bucketReason) cap.bucketReason = bucketReason;
 		return {
 			fd,
 			cap,
-			physicalFilterable: physicalFilter && !isWriteOnly && !fd.encrypted,
+			filterBy,
+			physicalFilterable: physicalReason === void 0,
 			physicalReason
 		};
 	}
@@ -1308,18 +1357,32 @@ var FieldCapabilityIndex = class {
 	}
 	/**
 	* Gate check for one path in one position. Returns `undefined` when the
-	* path is accepted. Order: navigation paths first (a nav path "exists" on
-	* the target table but is never a column here), then a listed leaf's
-	* capability (no existence lookup needed — every listed leaf is a real
-	* field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-	* that exist but are not leaves, the storage classification.
+	* path is accepted.
+	*
+	* `exists` runs FIRST, for every path (since 0.1.133): it is the
+	* controller's `hasField`, the visibility hook subclasses narrow per
+	* request (e.g. a projection-scoped viewer). A path it rejects answers
+	* `Unknown field "x"` exactly like a nonexistent one — never a capability
+	* or navigation hint, which would reveal the field and let a filter or
+	* sort on it act as a value oracle. Before 0.1.133 listed leaves and
+	* navigation paths skipped it.
+	*
+	* Then: navigation paths (a nav path exists on the target table but is
+	* never a column here), a listed leaf's capability, and for other paths
+	* the storage classification. Existence also runs BEFORE the JSON /
+	* encrypted classification: an untyped descendant of a JSON column
+	* (`address.nope`) is reported as `Unknown field`, not as "inside
+	* JSON-stored column" — clients pin that wording, so do not "align" it
+	* with the core backstop's text.
 	*
-	* Existence deliberately runs BEFORE the JSON / encrypted classification:
-	* an untyped descendant of a JSON column (`address.nope`) is reported as
-	* `Unknown field`, not as "inside JSON-stored column" — clients pin that
-	* wording, so do not "align" it with the core backstop's text.
+	* `predicate` is a filter entry's class (`collectQueryPaths` records it per
+	* occurrence); it only matters for `op === "filter"` on a listed leaf.
 	*/
-	check(path, op, exists) {
+	check(path, op, exists, predicate = "compare") {
+		if (!exists(path)) return {
+			path,
+			message: `Unknown field "${path}"`
+		};
 		const { kind, parent } = classifyQueryPath(this, path);
 		if (kind === "nav") {
 			if (parent === void 0) return {
@@ -1338,24 +1401,27 @@ var FieldCapabilityIndex = class {
 					path,
 					message: `Selecting field "${path}" is not permitted.`
 				};
-				case "filter": return entry.cap.filterable ? void 0 : {
-					path,
-					message: `Filtering on field "${path}" is not permitted — ${entry.cap.filterReason}`
-				};
+				case "filter": {
+					const reason = entry.filterBy[predicate];
+					return reason === void 0 ? void 0 : {
+						path,
+						message: `Filtering on field "${path}" is not permitted — ${reason}`
+					};
+				}
 				case "sort": return entry.cap.sortable ? void 0 : {
 					path,
 					message: `Sorting on field "${path}" is not permitted — ${entry.cap.sortReason}`
 				};
+				case "bucket": return entry.cap.bucketable ? void 0 : {
+					path,
+					message: `Bucketing field "${path}" is not permitted — ${entry.cap.bucketReason}`
+				};
 				default: return entry.physicalFilterable ? void 0 : {
 					path,
 					message: `${OP_SUBJECT[op]} field "${path}" is not permitted — ${entry.physicalReason}`
 				};
 			}
 		}
-		if (!exists(path)) return {
-			path,
-			message: `Unknown field "${path}"`
-		};
 		switch (kind) {
 			case "objectParent":
 				if (op === "select") return void 0;
@@ -1419,14 +1485,14 @@ const GEO_CONTROLS = [
 ];
 //#endregion
 //#region src/as-db-readable.controller.ts
-/** The gate positions in check order; `refs[op]` are the paths collected for each. */
-const OPS = [
-	"filter",
+/** Gate positions checked after the filter entries, in order; `refs[op]` are their paths. */
+const PATH_OPS = [
 	"sort",
 	"select",
 	"groupBy",
 	"having",
-	"aggregate"
+	"aggregate",
+	"bucket"
 ];
 let AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
@@ -1447,9 +1513,26 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	* Per-path capability index (since 0.1.128): the ONE input both `/meta.fields`
 	* and the request gate ({@link checkCapabilities}) are computed from, so
 	* metadata and runtime can never diverge.
+	*
+	* Built on first use and rebuilt whenever the adapter-level capabilities
+	* change (`FieldCapabilityIndex.adapterSignature`: geo support, calendar
+	* buckets) — PostgreSQL learns PostGIS only during schema sync, which may
+	* run after this controller is constructed, so a constructor-time snapshot
+	* would keep advertising (and gating) the pre-sync answer (since 0.1.132).
 	*/
-	capabilities;
-	/** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+	get capabilities() {
+		const current = this._capabilities;
+		if (current && current.signature === FieldCapabilityIndex.adapterSignature(this.readable)) return current;
+		const index = new FieldCapabilityIndex(this.readable, this._writeOnlySet);
+		this._capabilities = index;
+		return index;
+	}
+	_capabilities;
+	/** `/meta` is a projection of {@link capabilities}: a rebuilt index rebuilds the cached envelope. */
+	metaCacheKey() {
+		return this.capabilities;
+	}
+	/** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
 	_exists = (path) => this.hasField(path);
 	_preferredIdSet;
 	_overlayIsNoOp;
@@ -1470,7 +1553,6 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
 		this.readable = resolved;
 		this._writeOnlySet = this._collectAnnotated("db.writeOnly");
-		this.capabilities = new FieldCapabilityIndex(resolved, this._writeOnlySet);
 		this._invertibleFields = this._collectInvertibleFields();
 		this._searchFallbackFields = this._collectSearchFallbackFields();
 		this._preferredIdSet = new Set(resolved.preferredId ?? []);
@@ -1503,6 +1585,20 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
+	/**
+	* THE field-visibility hook: every gated path consults it before any
+	* capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+	* `$not`, existence predicates included), `$sort`, `$select`,
+	* `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+	* `$with` relation names and sub-query paths, and the `$search` fallback
+	* fields. A path it rejects is answered exactly like a nonexistent one
+	* (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+	* fields per request (read scopes). The default accepts every real path
+	* (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+	* there with `applyMetaOverlay`. Native text search and vector search
+	* (`$vector` names an index) run inside the engine over its indexes, out of
+	* this hook's reach — keep hidden fields out of those indexes.
+	*/
 	hasField(path) {
 		if (typeof this.readable.isValidFieldPath === "function") return this.readable.isValidFieldPath(path);
 		return this.readable.flatMap.has(path);
@@ -1517,19 +1613,23 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	*
 	* Rejections use the structured envelope `{ message, statusCode: 400,
 	* errors: [{ path, message }] }` — `path` is the offending logical path.
-	* After the per-path checks the core `$having` rule runs (`checkHavingKeys`:
-	* aliases or `$groupBy` fields only), so a readable mock and a real table
-	* answer alike.
+	*
+	* Expects normalized `$select` computed entries ({@link checkComputedSelect}
+	* ran first); a bucket's source is checked like any other path (op
+	* `bucket`). After the per-path checks the core `$having` rule runs
+	* (`checkHavingKeys`: aliases or `$groupBy` fields only), so a readable mock
+	* and a real table answer alike.
 	*/
 	checkCapabilities(parsed) {
+		const capabilities = this.capabilities;
 		const refs = collectQueryPaths$1(parsed);
 		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
-		for (const op of OPS) for (const path of refs[op]) {
-			const verdict = this.capabilities.check(path, op, this._exists);
+		for (const { path, predicate } of refs.filter) {
+			const verdict = capabilities.check(path, "filter", this._exists, predicate);
 			if (verdict) return badRequest(verdict.path, verdict.message);
 		}
-		for (const path of refs.geoFilter) {
-			const verdict = this.capabilities.check(path, "filter", this._exists);
+		for (const op of PATH_OPS) for (const path of refs[op]) {
+			const verdict = capabilities.check(path, op, this._exists);
 			if (verdict) return badRequest(verdict.path, verdict.message);
 		}
 		const having = checkHavingKeys(refs);
@@ -1537,6 +1637,31 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		return this.checkGates(parsed);
 	}
 	/**
+	* The core's shared normalizer of `$select` computed entries
+	* (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+	* (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
+	* week start / alias, "grouped queries only", "must also appear in
+	* $groupBy", alias collisions with this table's fields. Runs once per
+	* request, before {@link checkCapabilities}: at the head of
+	* {@link validateParsed} — ahead of the controls DTO, which would otherwise
+	* answer a bucket in a non-grouped query with a generic type mismatch — or
+	* explicitly on the endpoint that skips it (`geo`).
+	*/
+	checkComputedSelect(controls) {
+		const capabilities = this.capabilities;
+		try {
+			resolveCalendarBuckets(controls, {
+				flatMap: this.readable.flatMap,
+				physicalNames: capabilities.physicalNames,
+				navFields: capabilities.navFields
+			});
+		} catch (error) {
+			if (!(error instanceof DbError)) throw error;
+			const [issue] = error.errors;
+			return badRequest(issue.path, issue.message);
+		}
+	}
+	/**
 	* Root-path existence moved into {@link checkCapabilities}; the insights map
 	* only serves `$with` sub-controls here — the URL parser flattens
 	* `$with=assignee($select=name)` into the insight `assignee.name`, which is
@@ -1552,14 +1677,22 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			if (!this.hasField(key)) return `Unknown field "${key}"`;
 		}
 	}
-	/** Validates $with relations against the readable. */
+	/** {@link checkComputedSelect} (before the controls DTO), then $with relations against the readable. */
 	validateParsed(parsed, type) {
+		const computedError = this.checkComputedSelect(parsed.controls);
+		if (computedError) return computedError;
 		const baseError = super.validateParsed(parsed, type);
 		if (baseError) return baseError;
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
-			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
+			for (const rel of withRelations) {
+				const dot = rel.name.indexOf(".");
+				if (!(dot === -1 ? relations.has(rel.name) && this.hasField(rel.name) : this.hasField(rel.name.slice(0, dot)))) {
+					const visible = [...relations.keys()].filter((name) => this.hasField(name));
+					return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+				}
+			}
 		}
 	}
 	/**
@@ -1796,10 +1929,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
 	_findWriteOnlyInAggregate(groupBy, select) {
 		if (this._writeOnlySet.size === 0) return void 0;
-		for (const f of groupBy) if (this._writeOnlySet.has(f)) return f;
+		const sealed = (f) => this._writeOnlySet.has(f) && this.hasField(f);
+		for (const f of groupBy) if (sealed(f)) return f;
 		if (Array.isArray(select)) for (const item of select) {
 			const field = typeof item === "string" ? item : item.$field;
-			if (field && this._writeOnlySet.has(field)) return field;
+			if (field && sealed(field)) return field;
 		}
 	}
 	/**
@@ -1811,9 +1945,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
 		if (!term || controls.$vector !== void 0) return filter;
-		if (this.readable.isSearchable() || this._searchFallbackFields.length === 0) return filter;
+		if (this.readable.isSearchable()) return filter;
+		const fields = this._searchFallbackFields.filter((f) => this.hasField(f));
+		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
-		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
 		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
 	}
 	/**
@@ -2025,6 +2161,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			const insightsError = this.validateInsights(parsed.insights);
 			if (insightsError) return new HttpError(400, insightsError);
 		}
+		const computedError = this.checkComputedSelect(controls);
+		if (computedError) return computedError;
 		const gateError = this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const [filter, transformedSelect] = await Promise.all([this.transformFilter(parsed.filter), this.transformProjection(controls.$select)]);
@@ -2157,16 +2295,19 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		if (this.readable.indexes instanceof Map) {
 			for (const index of this.readable.indexes.values()) if (index.type === "geo") for (const f of index.fields) geoIndexedPhysical.add(f.name);
 		}
+		const capabilities = this.capabilities;
 		const fields = {};
-		for (const [path, cap, fd] of this.capabilities.entries()) {
+		for (const [path, cap, fd] of capabilities.entries()) {
 			const entry = {
 				sortable: cap.sortable,
 				filterable: cap.filterable
 			};
+			if (cap.filterOps) entry.filterOps = [...cap.filterOps];
 			if (cap.indexed) entry.indexed = true;
 			if (fd.encrypted) entry.encrypted = true;
 			if (geoIndexedPhysical.has(fd.physicalName)) entry.geo = true;
 			if (this._writeOnlySet.has(path)) entry.writeOnly = true;
+			if (cap.bucketable) entry.bucketable = true;
 			fields[path] = entry;
 		}
 		return {
@@ -2181,7 +2322,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			type: this.getSerializedType(),
 			actions: this.buildActions(),
 			crud: this.buildCrud(),
-			versionColumn: this.readable.versionColumn
+			versionColumn: this.readable.versionColumn,
+			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] }
 		};
 	}
 	buildCrud() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -43,14 +43,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/url": "^0.1.8",
-    "@atscript/db-memory": "^0.1.131"
+    "@uniqu/url": "^0.1.10",
+    "@atscript/db-memory": "^0.1.133"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.10",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/event-http": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
@@ -60,11 +60,11 @@
   "peerDependencies": {
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.10",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
     "moost": "^0.6.37",
-    "@atscript/db": "^0.1.131"
+    "@atscript/db": "^0.1.133"
   },
   "scripts": {
     "postinstall": "asc -f dts",