@atscript/moost-db 0.1.130 → 0.1.132

package/dist/index.cjs

@@ -5,6 +5,7 @@ let _moostjs_event_http = require("@moostjs/event-http");
 let moost = require("moost");
 let _uniqu_url = require("@uniqu/url");
 let _atscript_db = require("@atscript/db");
+let _uniqu_core = require("@uniqu/core");
 let _atscript_db_memory = require("@atscript/db-memory");
 let _wooksjs_event_core = require("@wooksjs/event-core");
 let _wooksjs_http_body = require("@wooksjs/http-body");
@@ -38,7 +39,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 _atscript_typescript_utils.ValidatorError) reply(errorEnvelope(400, error.message, error.errors));
@@ -630,6 +632,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") {
@@ -823,14 +827,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
@@ -1139,12 +1155,16 @@ function resolveBoundReadable(ctor) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
-const REASON_ADAPTER_FILTER = "adapter cannot filter on this storage type.";
+const ADAPTER_FILTER = "adapter cannot filter on this storage type";
+const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER}.`;
 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_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
 const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
+const REASON_NOT_TIMESTAMP = "not a timestamp field (declare it number.timestamp).";
+const REASON_NOT_DIMENSION = "not a dimension.";
+const REASON_NO_BUCKETS = "adapter has no calendar buckets.";
 /** Sentence subject per op ("Filtering on field …"). */
 const OP_SUBJECT = {
 	filter: "Filtering on",
@@ -1152,7 +1172,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 = {
@@ -1161,7 +1182,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";
@@ -1169,17 +1191,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. */
@@ -1190,9 +1217,32 @@ 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();
+	/**
+	* Declared dimensions when the table is strict (declares dimensions or
+	* measures), else `undefined` — the core rule: a grouping source, a
+	* bucketed field included, must then be a dimension.
+	*/
+	_dimensions;
+	/** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
+	_jsonValueParents;
 	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
 	get leaves() {
 		return this._entries;
@@ -1202,12 +1252,22 @@ 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 = _uniqu_core.BUCKET_UNITS.filter((unit) => units.has(unit));
+		this._dimensions = source.dimensions.length > 0 || source.measures.length > 0 ? new Set(source.dimensions) : void 0;
+		const physicalNames = /* @__PURE__ */ new Set();
+		const jsonValueParents = /* @__PURE__ */ new Set();
+		for (const fd of source.fieldDescriptors) {
+			physicalNames.add(fd.physicalName);
+			if ((0, _atscript_db.isJsonValueField)(fd)) jsonValueParents.add(fd.path);
+		}
+		this.physicalNames = physicalNames;
+		this._jsonValueParents = jsonValueParents;
 		const nav = new Set(source.navFields);
 		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
 		this.navFields = nav;
@@ -1229,7 +1289,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) {
@@ -1249,49 +1309,49 @@ 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 (!(0, _atscript_db.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 ? (0, _atscript_db.narrowerFilterOps)(fd, source) : [];
+		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER}${(0, _atscript_db.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;
+		let bucketReason = physicalReason;
+		const jsonAncestor = (0, _atscript_db.jsonValueAncestor)(fd.path, this._jsonValueParents);
+		if (!bucketReason && jsonAncestor !== void 0) bucketReason = `inside JSON-stored column "${jsonAncestor}".`;
+		if (!bucketReason && !(0, _atscript_db.isBucketableField)(fd)) bucketReason = REASON_NOT_TIMESTAMP;
+		if (!bucketReason && this._dimensions && !this._dimensions.has(fd.path)) bucketReason = REASON_NOT_DIMENSION;
+		if (!bucketReason && this.bucketUnits.length === 0) bucketReason = REASON_NO_BUCKETS;
 		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
 		};
 	}
@@ -1319,8 +1379,11 @@ var FieldCapabilityIndex = class {
 	* 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") {
 		const { kind, parent } = (0, _atscript_db.classifyQueryPath)(this, path);
 		if (kind === "nav") {
 			if (parent === void 0) return {
@@ -1339,14 +1402,21 @@ 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}`
@@ -1420,14 +1490,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). */
@@ -1448,8 +1518,25 @@ 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;
+	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 field-existence check the gate hands to `capabilities.check`. */
 	_exists = (path) => this.hasField(path);
 	_preferredIdSet;
@@ -1471,7 +1558,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 ?? []);
@@ -1518,19 +1604,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 = (0, _atscript_db.collectQueryPaths)(parsed);
 		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, (0, _atscript_db.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 = (0, _atscript_db.checkHavingKeys)(refs);
@@ -1538,6 +1628,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 {
+			(0, _atscript_db.resolveCalendarBuckets)(controls, {
+				flatMap: this.readable.flatMap,
+				physicalNames: capabilities.physicalNames,
+				navFields: capabilities.navFields
+			});
+		} catch (error) {
+			if (!(error instanceof _atscript_db.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
@@ -1553,8 +1668,10 @@ 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;
@@ -2026,6 +2143,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			const insightsError = this.validateInsights(parsed.insights);
 			if (insightsError) return new _moostjs_event_http.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)]);
@@ -2158,16 +2277,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 {
@@ -2182,7 +2304,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() {