@atscript/moost-validator 0.1.88 → 0.1.90

package/dist/index.cjs

@@ -1,30 +1,7 @@
-"use strict";
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
-const __atscript_typescript_utils = __toESM(require("@atscript/typescript/utils"));
-const moost = __toESM(require("moost"));
-const __moostjs_event_http = __toESM(require("@moostjs/event-http"));
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
+let moost = require("moost");
+let _moostjs_event_http = require("@moostjs/event-http");
 
 //#region packages/moost-validator/src/as-coercion.pipe.ts
 /**
@@ -36,20 +13,63 @@ const __moostjs_event_http = __toESM(require("@moostjs/event-http"));
 	"QUERY",
 	"QUERY_ITEM"
 ];
-const coercionPipe = (opts) => {
+/**
+* **coercionPipe** ─ Creates a Moost *pipe* that coerces string-transport
+* input (route params, query strings) toward the parameter's declared type
+* before validation runs.
+*
+* For atscript-annotated types it delegates to `coerceForType` from
+* `@atscript/typescript/utils` (scalars, unions, `@Query()` DTOs, arrays).
+* For plain design types (`offset: number`, `flag: boolean`, `since: Date`)
+* it falls back to direct constructor-based coercion — this also covers
+* scalar `.as` aliases under tsc's `emitDecoratorMetadata`, where the alias
+* identity collapses to `Number`.
+*
+* Coercion never throws and never validates — unparsable input passes
+* through unchanged for {@link validatorPipe} to report. The pipe is
+* registered at {@link TPipePriority.TRANSFORM}, so it composes ahead of
+* `validatorPipe` (VALIDATE):
+*
+* @example
+* ```ts
+* const app = new Moost()
+* app.applyGlobalPipes(coercionPipe(), validatorPipe())
+*
+* // KafkaOffset: @expect.int @expect.min 0 → export type KafkaOffset = number
+* ‎@Get('topics/:topic')
+* read(@Param('offset') offset: KafkaOffset) {
+*   // offset is a validated number — no manual Number.parseInt
+* }
+* ```
+*
+* @param opts {@link TCoercionOptions}.
+* @returns A ready‑to‑use `PipeFn` instance.
+*/ const coercionPipe = (opts) => {
 	const sources = new Set(opts?.sources ?? DEFAULT_SOURCES);
 	return (0, moost.definePipeFn)((value, metas) => {
 		const source = metas?.targetMeta?.paramSource;
 		if (!source || !sources.has(source)) return value;
 		const t = metas?.targetMeta?.type;
-		if ((0, __atscript_typescript_utils.isAnnotatedType)(t)) return (0, __atscript_typescript_utils.coerceForType)(t, value);
-		if (t === Number) return (0, __atscript_typescript_utils.coerceScalar)("number", value);
-		if (t === Boolean) return (0, __atscript_typescript_utils.coerceScalar)("boolean", value);
+		if ((0, _atscript_typescript_utils.isAnnotatedType)(t)) return (0, _atscript_typescript_utils.coerceForType)(t, value);
+		if (t === Number) return (0, _atscript_typescript_utils.coerceScalar)("number", value);
+		if (t === Boolean) return (0, _atscript_typescript_utils.coerceScalar)("boolean", value);
 		if (t === Date) return coerceDate(value);
 		return value;
 	}, moost.TPipePriority.TRANSFORM);
 };
-const UseCoercionPipe = (opts) => (0, moost.Pipe)(coercionPipe(opts));
+/**
+* Syntactic sugar decorator that applies {@link coercionPipe} to a handler or
+* an entire controller class.
+*
+* @param opts {@link TCoercionOptions}.
+*
+* @example
+* ```ts
+* ‎@Get('items')
+* ‎@UseCoercionPipe()
+* list(@Query() query: SearchQuery) {}
+* ```
+*/ const UseCoercionPipe = (opts) => (0, moost.Pipe)(coercionPipe(opts));
 function coerceDate(value) {
 	if (typeof value !== "string" || value.trim().length === 0) return value;
 	const parsed = new Date(value);
@@ -58,19 +78,67 @@ function coerceDate(value) {
 
 //#endregion
 //#region packages/moost-validator/src/as-validator.pipe.ts
-const validatorPipe = (opts) => (0, moost.definePipeFn)((value, metas, level) => {
-	if (metas?.targetMeta?.optional && (value === undefined || value === null)) return value;
-	if ((0, __atscript_typescript_utils.isAnnotatedType)(metas?.targetMeta?.type) && typeof metas.targetMeta.type.validator === "function") {
-		const validator = metas.targetMeta.type.validator(opts);
-		validator.validate(value);
-	}
+/**
+* **validatorPipe** ─ Creates a Moost *pipe* that runs atscript validation on
+* handler parameters (body, params, query, etc.).
+*
+* The pipe inspects the runtime metadata supplied by Moost; when the target
+* parameter type is an atscript‑annotated class or interface it calls
+* `type.validator(opts).validate(value)` to perform synchronous validation.
+*
+* The pipe is registered at {@link TPipePriority.VALIDATE}, ensuring it fires
+* before any transformation pipes and long before business logic executes.
+*
+* @param opts {@link TValidatorOptions}.
+* @returns A ready‑to‑use `PipeFn` instance.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@Pipe(validatorPipe())
+* async create(@Body() dto: CreateUserDto) {}
+*
+* // or globally:
+* const app = new Moost();
+* app.applyGlobalPipes(validatorPipe());
+* ```
+*/ const validatorPipe = (opts) => (0, moost.definePipeFn)((value, metas, level) => {
+	if (metas?.targetMeta?.optional && (value === void 0 || value === null)) return value;
+	if ((0, _atscript_typescript_utils.isAnnotatedType)(metas?.targetMeta?.type) && typeof metas.targetMeta.type.validator === "function") metas.targetMeta.type.validator(opts).validate(value);
 	return value;
 }, moost.TPipePriority.VALIDATE);
-const UseValidatorPipe = (opts) => (0, moost.Pipe)(validatorPipe(opts));
+/**
+* Syntactic sugar decorator that applies {@link validatorPipe} to a handler or
+* an entire controller class.
+*
+* @param opts {@link TValidatorOptions}.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@UseValidatorPipe()
+* async create(@Body() dto: CreateUserDto) {}
+* ```
+*/ const UseValidatorPipe = (opts) => (0, moost.Pipe)(validatorPipe(opts));
 
 //#endregion
 //#region packages/moost-validator/src/error-transform.ts
-const validationErrorTransform = () => (0, moost.defineInterceptor)({
+/**
+* **validationErrorTransform** ─ Moost interceptor that catches
+* {@link ValidatorError}s thrown by {@link validatorPipe} (or manually) and
+* converts them into a structured `HttpError(400)`
+*
+* Applied at {@link TInterceptorPriority.CATCH_ERROR}
+*
+* @example
+* ```ts
+* // apply globally
+* const app = new Moost();
+* app.applyGlobalInterceptors(validationErrorTransform());
+* ```
+*/ const validationErrorTransform = () => (0, moost.defineInterceptor)({
 	after: transformValidationError,
 	error: transformValidationError
 }, moost.TInterceptorPriority.CATCH_ERROR);
@@ -78,18 +146,27 @@ const validationErrorTransform = () => (0, moost.defineInterceptor)({
 * Internal helper that performs the actual conversion: wraps a
 * `ValidatorError` into {@link HttpError} and passes it to Moost's `reply`.
 */ function transformValidationError(error, reply) {
-	if (error instanceof __atscript_typescript_utils.ValidatorError) reply(new __moostjs_event_http.HttpError(400, {
+	if (error instanceof _atscript_typescript_utils.ValidatorError) reply(new _moostjs_event_http.HttpError(400, {
 		message: error.message,
 		statusCode: 400,
 		_body: error.errors
 	}));
 }
-const UseValidationErrorTransform = () => (0, moost.Intercept)(validationErrorTransform());
+/**
+* Decorator that registers {@link validationErrorTransform} on a controller or
+* route handler.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@UseValidationErrorTransform()
+*/ const UseValidationErrorTransform = () => (0, moost.Intercept)(validationErrorTransform());
 
 //#endregion
-exports.UseCoercionPipe = UseCoercionPipe
-exports.UseValidationErrorTransform = UseValidationErrorTransform
-exports.UseValidatorPipe = UseValidatorPipe
-exports.coercionPipe = coercionPipe
-exports.validationErrorTransform = validationErrorTransform
-exports.validatorPipe = validatorPipe
+exports.UseCoercionPipe = UseCoercionPipe;
+exports.UseValidationErrorTransform = UseValidationErrorTransform;
+exports.UseValidatorPipe = UseValidatorPipe;
+exports.coercionPipe = coercionPipe;
+exports.validationErrorTransform = validationErrorTransform;
+exports.validatorPipe = validatorPipe;

package/dist/index.mjs

@@ -12,7 +12,38 @@ import { HttpError } from "@moostjs/event-http";
 	"QUERY",
 	"QUERY_ITEM"
 ];
-const coercionPipe = (opts) => {
+/**
+* **coercionPipe** ─ Creates a Moost *pipe* that coerces string-transport
+* input (route params, query strings) toward the parameter's declared type
+* before validation runs.
+*
+* For atscript-annotated types it delegates to `coerceForType` from
+* `@atscript/typescript/utils` (scalars, unions, `@Query()` DTOs, arrays).
+* For plain design types (`offset: number`, `flag: boolean`, `since: Date`)
+* it falls back to direct constructor-based coercion — this also covers
+* scalar `.as` aliases under tsc's `emitDecoratorMetadata`, where the alias
+* identity collapses to `Number`.
+*
+* Coercion never throws and never validates — unparsable input passes
+* through unchanged for {@link validatorPipe} to report. The pipe is
+* registered at {@link TPipePriority.TRANSFORM}, so it composes ahead of
+* `validatorPipe` (VALIDATE):
+*
+* @example
+* ```ts
+* const app = new Moost()
+* app.applyGlobalPipes(coercionPipe(), validatorPipe())
+*
+* // KafkaOffset: @expect.int @expect.min 0 → export type KafkaOffset = number
+* ‎@Get('topics/:topic')
+* read(@Param('offset') offset: KafkaOffset) {
+*   // offset is a validated number — no manual Number.parseInt
+* }
+* ```
+*
+* @param opts {@link TCoercionOptions}.
+* @returns A ready‑to‑use `PipeFn` instance.
+*/ const coercionPipe = (opts) => {
 	const sources = new Set(opts?.sources ?? DEFAULT_SOURCES);
 	return definePipeFn((value, metas) => {
 		const source = metas?.targetMeta?.paramSource;
@@ -25,7 +56,19 @@ const coercionPipe = (opts) => {
 		return value;
 	}, TPipePriority.TRANSFORM);
 };
-const UseCoercionPipe = (opts) => Pipe(coercionPipe(opts));
+/**
+* Syntactic sugar decorator that applies {@link coercionPipe} to a handler or
+* an entire controller class.
+*
+* @param opts {@link TCoercionOptions}.
+*
+* @example
+* ```ts
+* ‎@Get('items')
+* ‎@UseCoercionPipe()
+* list(@Query() query: SearchQuery) {}
+* ```
+*/ const UseCoercionPipe = (opts) => Pipe(coercionPipe(opts));
 function coerceDate(value) {
 	if (typeof value !== "string" || value.trim().length === 0) return value;
 	const parsed = new Date(value);
@@ -34,19 +77,67 @@ function coerceDate(value) {
 
 //#endregion
 //#region packages/moost-validator/src/as-validator.pipe.ts
-const validatorPipe = (opts) => definePipeFn((value, metas, level) => {
-	if (metas?.targetMeta?.optional && (value === undefined || value === null)) return value;
-	if (isAnnotatedType(metas?.targetMeta?.type) && typeof metas.targetMeta.type.validator === "function") {
-		const validator = metas.targetMeta.type.validator(opts);
-		validator.validate(value);
-	}
+/**
+* **validatorPipe** ─ Creates a Moost *pipe* that runs atscript validation on
+* handler parameters (body, params, query, etc.).
+*
+* The pipe inspects the runtime metadata supplied by Moost; when the target
+* parameter type is an atscript‑annotated class or interface it calls
+* `type.validator(opts).validate(value)` to perform synchronous validation.
+*
+* The pipe is registered at {@link TPipePriority.VALIDATE}, ensuring it fires
+* before any transformation pipes and long before business logic executes.
+*
+* @param opts {@link TValidatorOptions}.
+* @returns A ready‑to‑use `PipeFn` instance.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@Pipe(validatorPipe())
+* async create(@Body() dto: CreateUserDto) {}
+*
+* // or globally:
+* const app = new Moost();
+* app.applyGlobalPipes(validatorPipe());
+* ```
+*/ const validatorPipe = (opts) => definePipeFn((value, metas, level) => {
+	if (metas?.targetMeta?.optional && (value === void 0 || value === null)) return value;
+	if (isAnnotatedType(metas?.targetMeta?.type) && typeof metas.targetMeta.type.validator === "function") metas.targetMeta.type.validator(opts).validate(value);
 	return value;
 }, TPipePriority.VALIDATE);
-const UseValidatorPipe = (opts) => Pipe(validatorPipe(opts));
+/**
+* Syntactic sugar decorator that applies {@link validatorPipe} to a handler or
+* an entire controller class.
+*
+* @param opts {@link TValidatorOptions}.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@UseValidatorPipe()
+* async create(@Body() dto: CreateUserDto) {}
+* ```
+*/ const UseValidatorPipe = (opts) => Pipe(validatorPipe(opts));
 
 //#endregion
 //#region packages/moost-validator/src/error-transform.ts
-const validationErrorTransform = () => defineInterceptor({
+/**
+* **validationErrorTransform** ─ Moost interceptor that catches
+* {@link ValidatorError}s thrown by {@link validatorPipe} (or manually) and
+* converts them into a structured `HttpError(400)`
+*
+* Applied at {@link TInterceptorPriority.CATCH_ERROR}
+*
+* @example
+* ```ts
+* // apply globally
+* const app = new Moost();
+* app.applyGlobalInterceptors(validationErrorTransform());
+* ```
+*/ const validationErrorTransform = () => defineInterceptor({
 	after: transformValidationError,
 	error: transformValidationError
 }, TInterceptorPriority.CATCH_ERROR);
@@ -60,7 +151,16 @@ const validationErrorTransform = () => defineInterceptor({
 		_body: error.errors
 	}));
 }
-const UseValidationErrorTransform = () => Intercept(validationErrorTransform());
+/**
+* Decorator that registers {@link validationErrorTransform} on a controller or
+* route handler.
+*
+* @example
+* ```ts
+* // for method:
+* ‎@Post()
+* ‎@UseValidationErrorTransform()
+*/ const UseValidationErrorTransform = () => Intercept(validationErrorTransform());
 
 //#endregion
 export { UseCoercionPipe, UseValidationErrorTransform, UseValidatorPipe, coercionPipe, validationErrorTransform, validatorPipe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-validator",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "description": "Validator pipe and utils for Moost.",
   "keywords": [
     "annotations",
@@ -36,15 +36,15 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@moostjs/event-http": "^0.6.35",
-    "moost": "^0.6.35",
+    "@moostjs/event-http": "^0.6.36",
+    "moost": "^0.6.36",
     "vitest": "3.2.7"
   },
   "peerDependencies": {
-    "@moostjs/event-http": "^0.6.35",
-    "moost": "^0.6.35",
-    "@atscript/core": "^0.1.88",
-    "@atscript/typescript": "^0.1.88"
+    "@moostjs/event-http": "^0.6.36",
+    "moost": "^0.6.36",
+    "@atscript/core": "^0.1.90",
+    "@atscript/typescript": "^0.1.90"
   },
   "scripts": {
     "pub": "pnpm publish --access public",