@atscript/moost-db 0.1.55 → 0.1.56

package/README.md

@@ -22,7 +22,9 @@ Generic database controller for the [Moost](https://moost.org) framework. Expose
 pnpm add @atscript/moost-db
 ```
 
-Peer dependencies: `moost`, `@moostjs/event-http`, `@atscript/db`, `@atscript/typescript`.
+Peer dependencies: `moost`, `@moostjs/event-http`, `@wooksjs/http-body`, `@atscript/db`, `@atscript/typescript`.
+
+`@wooksjs/http-body` is required by the `@DbActionPK` / `@DbActionPKs` parameter resolvers (used by the action layer) to read the parsed JSON request body.
 
 ## Quick Start
 

package/dist/index.cjs

@@ -4,6 +4,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 _wooksjs_http_body = require("@wooksjs/http-body");
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = { CONFLICT: 409 };
 function transformValidationError(error, reply) {
@@ -180,6 +181,196 @@ function findSortOffender(sort, isAllowed) {
 	}
 }
 //#endregion
+//#region src/actions/keys.ts
+/** Method-level metadata key — written by `@DbAction(name, opts)`. */
+const MOOST_DB_ACTION = "atscript_db_action";
+/** Class-level metadata key — written by `@DbActions` and the level-pinned shortcuts. Stored as an array; decorators accumulate. */
+const MOOST_DB_ACTIONS = "atscript_db_actions";
+/** Param-level metadata key — written by `@DbActionPK()` / `@DbActionPKs()`. Drives level inference. */
+const MOOST_DB_ACTION_PARAM = "atscript_db_action_param";
+/**
+* Shared method-decorator update used by `@DbAction` and `@DbActionDefault`:
+* read the existing `MOOST_DB_ACTION` slot, merge the patch (later-applied
+* fields win), and write it back. `name` is empty until `@DbAction` provides
+* one — `discoverActions` warns and drops actions with no name.
+*/
+function mergeActionMeta(current, patch) {
+	const existing = current[MOOST_DB_ACTION];
+	return {
+		name: patch.name ?? existing?.name ?? "",
+		opts: {
+			...existing?.opts,
+			...patch.opts
+		}
+	};
+}
+//#endregion
+//#region src/actions/discover.ts
+/** Optional fields shared between method opts and class-level entries. */
+const OPTIONAL_FIELDS = [
+	"icon",
+	"intent",
+	"description",
+	"order",
+	"default",
+	"promptText"
+];
+const WARN_PREFIX = "[moost-db actions]";
+const actionsCache = /* @__PURE__ */ new WeakMap();
+/**
+* Discover all actions declared on a controller and produce the `/meta` array.
+* Reads class + method metadata via `getMoostMate()` and resolves bound POST
+* paths through the Moost controller overview.
+*
+* Result is memoized per controller constructor — discovery walks every
+* handler entry and reads decorator metadata, which is wasted work to repeat
+* across instances.
+*/
+function discoverActions(controllerCtor, app, logger) {
+	const cached = actionsCache.get(controllerCtor);
+	if (cached) return cached;
+	const overview = app.getControllersOverview?.()?.find((o) => o.type === controllerCtor);
+	const out = [];
+	collectMethodActions(controllerCtor, overview, logger, out);
+	collectClassActions(controllerCtor, logger, out);
+	applyDefaultPerLevel(out, logger);
+	actionsCache.set(controllerCtor, out);
+	return out;
+}
+function collectMethodActions(ctor, overview, logger, out) {
+	if (!overview) return;
+	const byMethod = /* @__PURE__ */ new Map();
+	for (const h of overview.handlers) {
+		const list = byMethod.get(h.method);
+		if (list) list.push(h);
+		else byMethod.set(h.method, [h]);
+	}
+	for (const [methodName, handlers] of byMethod) {
+		const methodMeta = handlers[0].meta;
+		const action = methodMeta[MOOST_DB_ACTION];
+		if (!action) continue;
+		if (!action.name) {
+			logger.warn(`${WARN_PREFIX} method "${methodName}" has @DbActionDefault() but no @DbAction(name) — dropping`);
+			continue;
+		}
+		const levelInfer = inferMethodLevel(methodMeta.params ?? [], action.name, logger);
+		if (!levelInfer) continue;
+		if (levelInfer.bodyConflict) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" cannot mix @DbActionPK*/@DbActionPKs with @Body() — dropping`);
+			continue;
+		}
+		const postEntry = handlers.find((h) => h.handler.type === "HTTP" && h.handler.method === "POST");
+		if (!postEntry) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" requires @Post(...); no POST handler bound to ${methodName} — dropping`);
+			continue;
+		}
+		const path = postEntry.registeredAs[0]?.path;
+		if (!path) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" — POST handler ${methodName} has no registered path — dropping`);
+			continue;
+		}
+		const label = action.opts.label ?? methodMeta.label;
+		if (!label) {
+			logger.warn(`${WARN_PREFIX} action "${action.name}" requires a label (opts.label or @Label) — dropping`);
+			continue;
+		}
+		const info = {
+			name: action.name,
+			label,
+			level: levelInfer.level,
+			processor: "backend",
+			value: path
+		};
+		copyOptionalFields(info, action.opts);
+		out.push(info);
+	}
+}
+function inferMethodLevel(params, actionName, logger) {
+	let hasPk = false;
+	let hasPks = false;
+	let hasBody = false;
+	for (const p of params) {
+		const kind = p[MOOST_DB_ACTION_PARAM];
+		if (kind === "pk") hasPk = true;
+		else if (kind === "pks") hasPks = true;
+		if (p.paramSource === "BODY") hasBody = true;
+	}
+	if (hasPk && hasPks) {
+		logger.warn(`${WARN_PREFIX} action "${actionName}" has both @DbActionPK and @DbActionPKs — dropping`);
+		return null;
+	}
+	const level = hasPk ? "row" : hasPks ? "rows" : "table";
+	return {
+		level,
+		bodyConflict: hasBody && level !== "table"
+	};
+}
+function collectClassActions(ctor, logger, out) {
+	const list = (0, moost.getMoostMate)().read(ctor)?.[MOOST_DB_ACTIONS];
+	if (!list) return;
+	for (const { name, entry, forcedLevel } of list) {
+		const built = buildClassEntry(name, entry, forcedLevel, logger);
+		if (built) out.push(built);
+	}
+}
+function buildClassEntry(name, entry, forcedLevel, logger) {
+	const level = forcedLevel ?? entry.level;
+	if (!level) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a level — dropping. Use @DbTableActions/@DbRowActions/@DbRowsActions or set "level" explicitly.`);
+		return null;
+	}
+	if (!entry.label) {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a label — dropping`);
+		return null;
+	}
+	const processor = entry.processor;
+	let value;
+	if (processor === "navigate" || processor === "backend") {
+		const v = entry.value;
+		if (typeof v !== "string" || v === "") {
+			logger.warn(`${WARN_PREFIX} class-level action "${name}" with processor "${processor}" requires a non-empty "value" — dropping`);
+			return null;
+		}
+		value = v;
+	} else if (processor === "custom") {
+		const v = entry.value;
+		if (v !== void 0 && v !== null) {
+			logger.warn(`${WARN_PREFIX} class-level action "${name}" with processor "custom" forbids "value" (always derived from the dict key) — dropping`);
+			return null;
+		}
+		value = name;
+	} else {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" has unknown processor "${String(processor)}" — dropping`);
+		return null;
+	}
+	const info = {
+		name,
+		label: entry.label,
+		level,
+		processor,
+		value
+	};
+	copyOptionalFields(info, entry);
+	return info;
+}
+function applyDefaultPerLevel(actions, logger) {
+	const winners = /* @__PURE__ */ new Map();
+	for (const a of actions) {
+		if (!a.default) continue;
+		const existing = winners.get(a.level);
+		if (existing) {
+			a.default = false;
+			logger.warn(`${WARN_PREFIX} duplicate default action at level "${a.level}": "${existing}" wins, "${a.name}" demoted`);
+		} else winners.set(a.level, a.name);
+	}
+}
+function copyOptionalFields(info, source) {
+	for (const key of OPTIONAL_FIELDS) {
+		const value = source[key];
+		if (value !== void 0) info[key] = value;
+	}
+}
+//#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);
@@ -365,6 +556,8 @@ let AsReadableController = class AsReadableController {
 	* 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.
+	* Subclasses that fully replace the envelope must call {@link buildActions}
+	* directly so `@DbAction*` decorators still surface.
 	*/
 	async buildMetaResponse() {
 		return {
@@ -375,9 +568,18 @@ let AsReadableController = class AsReadableController {
 			readOnly: this._isReadOnly(),
 			relations: [],
 			fields: {},
-			type: this.getSerializedType()
+			type: this.getSerializedType(),
+			actions: this.buildActions()
 		};
 	}
+	/**
+	* Discovers `@DbAction*` and `@DbActions`-style class metadata on this
+	* controller and produces the `actions` array. Returns `[]` for value-help
+	* controllers — see {@link AsValueHelpController#buildMetaResponse}.
+	*/
+	buildActions() {
+		return discoverActions(this.constructor, this.app, this.logger);
+	}
 };
 __decorate([
 	(0, _moostjs_event_http.Get)("meta"),
@@ -733,7 +935,8 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			readOnly: this._isReadOnly(),
 			relations,
 			fields,
-			type: this.getSerializedType()
+			type: this.getSerializedType(),
+			actions: this.buildActions()
 		};
 	}
 };
@@ -1015,9 +1218,13 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 			readOnly: this._isReadOnly(),
 			relations: [],
 			fields,
-			type: this.getSerializedType()
+			type: this.getSerializedType(),
+			actions: []
 		};
 	}
+	buildActions() {
+		return [];
+	}
 };
 __decorate([
 	(0, _moostjs_event_http.Get)("query"),
@@ -1212,6 +1419,254 @@ function applySelect(rows, select) {
 	});
 }
 //#endregion
+//#region src/actions/db-action.decorator.ts
+/**
+* Mark a controller method as a database action surfaced via `/meta`.
+*
+* Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
+* meta builder reads this metadata plus the bound POST path lazily and
+* emits the action with `processor: 'backend'`. Order vs.
+* `@DbActionDefault()` does not matter — both merge into the same slot.
+*
+* @example
+* ```ts
+* @Post('actions/block')
+* @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
+* async blockUser(@DbActionPK() id: string) { ... }
+* ```
+*/
+function DbAction(name, opts = {}) {
+	return (0, moost.getMoostMate)().decorate((current) => {
+		const meta = current;
+		return {
+			...current,
+			[MOOST_DB_ACTION]: mergeActionMeta(meta, {
+				name,
+				opts
+			})
+		};
+	});
+}
+//#endregion
+//#region src/actions/db-action-default.decorator.ts
+/**
+* Sugar that flips `default: true` on the same method's `@DbAction` metadata.
+* Equivalent to passing `opts.default = true`. Decorator order does not matter.
+*/
+function DbActionDefault() {
+	return (0, moost.getMoostMate)().decorate((current) => {
+		const meta = current;
+		return {
+			...current,
+			[MOOST_DB_ACTION]: mergeActionMeta(meta, { opts: { default: true } })
+		};
+	});
+}
+//#endregion
+//#region src/actions/pk-source.ts
+/**
+* Extract the PK validation source from a controller instance. Looks for
+* `readable` (set by {@link AsDbReadableController}) or `table` (set by
+* {@link AsDbController}).
+*
+* If the controller has no typed table attached (e.g. a value-help
+* controller, or a plain Moost controller without `@TableController`),
+* throws an HTTP 500 — this is a **server misconfiguration**, not a client
+* error. The body parser has nothing to validate against, so the request
+* cannot proceed. Use `@Body()` and parse the PK manually if you need to
+* accept PK-shaped bodies on a controller without an attached table.
+*/
+function resolvePkSource(controller) {
+	const c = controller;
+	const candidate = c.readable ?? c.table;
+	if (!isPkValidationSource(candidate)) throw new _moostjs_event_http.HttpError(500, "@DbActionPK/@DbActionPKs requires a controller with an attached table (via @TableController / @ReadableController). Use @Body() instead if your controller has no typed table.");
+	return candidate;
+}
+function isPkValidationSource(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return Array.isArray(v.primaryKeys) && Array.isArray(v.fieldDescriptors);
+}
+/**
+* Build a parameter decorator that parses the JSON request body, validates
+* it against the bound table's PK schema with `validate`, and tags the param
+* so {@link discoverActions} can infer the action's `level`.
+*/
+function createPkParamDecorator(kind, validate, resolverName) {
+	return (0, moost.ApplyDecorators)((0, moost.getMoostMate)().decorate(MOOST_DB_ACTION_PARAM, kind), (0, moost.Resolve)(async () => {
+		const body = await (0, _wooksjs_http_body.useBody)().parseBody();
+		validate(body, resolvePkSource((0, moost.useControllerContext)().getController()));
+		return body;
+	}, resolverName));
+}
+//#endregion
+//#region src/actions/pk-validation.ts
+/**
+* Validate a JSON-decoded body against a single-row PK shape (scalar or
+* composite). Throws {@link ValidatorError} with structured `errors` so the
+* existing validation interceptor returns HTTP 400.
+*/
+function validateSinglePk(body, source, path = "") {
+	const errors = collectPkErrors(body, source, path);
+	if (errors.length > 0) throw new _atscript_typescript_utils.ValidatorError(errors);
+}
+/**
+* Validate a JSON-decoded body against an array of PK shapes (`@DbActionPKs`).
+* The body MUST be an array; each element is validated against the PK schema.
+*/
+function validateMultiPk(body, source) {
+	if (!Array.isArray(body)) throw new _atscript_typescript_utils.ValidatorError([{
+		path: "",
+		message: "Expected JSON array of primary keys",
+		details: []
+	}]);
+	const errors = [];
+	for (let i = 0; i < body.length; i++) errors.push(...collectPkErrors(body[i], source, `[${i}]`));
+	if (errors.length > 0) throw new _atscript_typescript_utils.ValidatorError(errors);
+}
+function collectPkErrors(value, source, pathPrefix) {
+	const pkFields = source.primaryKeys;
+	if (pkFields.length === 0) return [{
+		path: pathPrefix,
+		message: "Table has no primary key configured",
+		details: []
+	}];
+	const errors = [];
+	if (pkFields.length === 1) {
+		const err = checkScalar(value, findFieldDescriptor(source, pkFields[0]), pathPrefix);
+		if (err) errors.push(err);
+		return errors;
+	}
+	if (!isPlainObject(value)) {
+		errors.push({
+			path: pathPrefix,
+			message: "Expected JSON object for composite primary key",
+			details: []
+		});
+		return errors;
+	}
+	for (const fieldName of pkFields) {
+		const sub = pathPrefix ? `${pathPrefix}.${fieldName}` : fieldName;
+		if (!(fieldName in value)) {
+			errors.push({
+				path: sub,
+				message: `Missing primary-key field "${fieldName}"`,
+				details: []
+			});
+			continue;
+		}
+		const fd = findFieldDescriptor(source, fieldName);
+		const err = checkScalar(value[fieldName], fd, sub);
+		if (err) errors.push(err);
+	}
+	return errors;
+}
+function findFieldDescriptor(source, name) {
+	for (const fd of source.fieldDescriptors) if (fd.path === name) return fd;
+}
+function checkScalar(value, fd, path) {
+	const expected = fd?.designType ?? "string";
+	if (expected === "string" && typeof value !== "string") return scalarMismatch(path, expected, value);
+	if (expected === "number" && typeof value !== "number") return scalarMismatch(path, expected, value);
+	if (expected === "boolean" && typeof value !== "boolean") return scalarMismatch(path, expected, value);
+}
+function scalarMismatch(path, expected, value) {
+	return {
+		path,
+		message: `Expected primary-key value to be ${expected}, got ${describe(value)}`,
+		details: []
+	};
+}
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/actions/db-action-pk.decorator.ts
+/**
+* Parameter resolver that reads the primary key from the JSON request body
+* and validates it against the bound table's PK schema.
+*
+* - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
+* - Composite PK → JSON object with all PK fields.
+*
+* Validation is strict — no type coercion. Mismatches throw a
+* `ValidatorError` which the existing validation interceptor surfaces as
+* HTTP 400 with the same envelope as DTO failures.
+*
+* Marks the param so {@link discoverActions} can infer the action's `level`
+* as `'row'`.
+*/
+function DbActionPK() {
+	return createPkParamDecorator("pk", validateSinglePk, "dbActionPk");
+}
+//#endregion
+//#region src/actions/db-action-pks.decorator.ts
+/**
+* Parameter resolver that reads a JSON array of primary keys from the request
+* body and validates each entry against the bound table's PK schema.
+*
+* - Scalar PK → JSON array of scalars (`["a","b","c"]`).
+* - Composite PK → JSON array of objects.
+*
+* Validation is strict — no type coercion. Marks the param so
+* {@link discoverActions} can infer the action's `level` as `'rows'`.
+*/
+function DbActionPKs() {
+	return createPkParamDecorator("pks", validateMultiPk, "dbActionPks");
+}
+//#endregion
+//#region src/actions/db-actions.decorator.ts
+/**
+* Declare class-level actions on a controller. Entries are flat dicts with
+* `processor: 'navigate' | 'custom' | 'backend'` matching the `/meta` wire
+* shape (see {@link TDbActionsEntry}). Each entry MUST specify `level`. Use
+* the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
+* `@DbRowsActions`) to avoid repeating `level`.
+*
+* The dictionary key serves as the action `name`. Entries do NOT bind any
+* HTTP route — the meta builder surfaces them in `/meta` only. For
+* `processor: 'backend'`, the dev-supplied `value` MUST point to a real
+* `@Post`-bound endpoint accepting the level-determined body shape.
+*
+* Multiple `@DbActions` (and shortcut) decorators on the same class
+* accumulate.
+*/
+function DbActions(dict) {
+	return classLevelActions(dict);
+}
+/** Sugar for `@DbActions` with `level: 'table'` injected into each entry. */
+function DbTableActions(dict) {
+	return classLevelActions(dict, "table");
+}
+/** Sugar for `@DbActions` with `level: 'row'` injected into each entry. */
+function DbRowActions(dict) {
+	return classLevelActions(dict, "row");
+}
+/** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
+function DbRowsActions(dict) {
+	return classLevelActions(dict, "rows");
+}
+function classLevelActions(dict, forcedLevel) {
+	const entries = [];
+	for (const [name, entry] of Object.entries(dict)) entries.push({
+		name,
+		entry,
+		forcedLevel
+	});
+	return (0, moost.getMoostMate)().decorate((current) => {
+		const existing = current["atscript_db_actions"] ?? [];
+		return {
+			...current,
+			[MOOST_DB_ACTIONS]: [...existing, ...entries]
+		};
+	});
+}
+//#endregion
 Object.defineProperty(exports, "AsDbController", {
 	enumerable: true,
 	get: function() {
@@ -1242,10 +1697,19 @@ Object.defineProperty(exports, "AsValueHelpController", {
 		return AsValueHelpController;
 	}
 });
+exports.DbAction = DbAction;
+exports.DbActionDefault = DbActionDefault;
+exports.DbActionPK = DbActionPK;
+exports.DbActionPKs = DbActionPKs;
+exports.DbActions = DbActions;
+exports.DbRowActions = DbRowActions;
+exports.DbRowsActions = DbRowsActions;
+exports.DbTableActions = DbTableActions;
 exports.READABLE_DEF = READABLE_DEF;
 exports.ReadableController = ReadableController;
 exports.TABLE_DEF = TABLE_DEF;
 exports.TableController = TableController;
 exports.UseValidationErrorTransform = UseValidationErrorTransform;
 exports.ViewController = ViewController;
+exports.discoverActions = discoverActions;
 exports.validationErrorTransform = validationErrorTransform;