@tahminator/sapling 1.5.28 → 2.0.1

package/README.md

@@ -19,6 +19,7 @@ A lightweight Express.js dependency injection & route abstraction library.
   * [Responses](#responses)
   * [Error Handling](#error-handling)
   * [Middleware](#middleware)
+  * [Request Validation](#request-validation)
   * [Redirects](#redirects)
   * [Dependency Injection](#dependency-injection)
   * [Custom Serialization](#custom-serialization)
@@ -142,8 +143,11 @@ Sapling supports the usual suspects:
 - `@DELETE(path?)`
 - `@PATCH(path?)`
 - `@Middleware(path?)` - for middleware
+- `@RequestBody(schema)` - validate & parse the request body
+- `@RequestParam(schema)` - validate & parse route params
+- `@RequestQuery(schema)` - validate & parse the query string
 
-Path defaults to `"/"` if you don't pass one.
+Path defaults to `"/"` if you don't pass one. The request schema decorators accept any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible validator (e.g. Zod, Valibot, ArkType).
 
 ### Responses
 
@@ -234,6 +238,56 @@ app.use(Sapling.resolve(CookieParserMiddleware));
 app.use(cookieParser());
 ```
 
+### Request Validation
+
+Validate and transform request bodies, route params, and query strings at the controller level using `@RequestBody`, `@RequestParam`, and `@RequestQuery`. These decorators accept any [Standard Schema](https://github.com/standard-schema/standard-schema) compatible validator (Zod, Valibot, ArkType, etc.).
+
+If validation fails, a `ParserError` is thrown, which Express handles as a `400 Bad Request` by default:
+
+```typescript
+import { z } from "zod";
+
+const CreateUserSchema = z.object({ name: z.string(), age: z.number() });
+const UserParamsSchema = z.object({ id: z.string() });
+const ListUsersQuerySchema = z.object({ page: z.coerce.number() });
+
+@Controller({ prefix: "/users" })
+class UserController {
+  @RequestBody(CreateUserSchema)
+  @POST()
+  createUser(request: Request): ResponseEntity<User> {
+    // request.body has been fully validated and rewritten. you can safely assert the type!
+    const requestBody = request.body as unknown as z.infer<CreateUserSchema>;
+  
+    const user = this.database.user.create(requestBody.name, requestBody.age)
+
+    return ResponseEntity.ok().body(user);
+  }
+
+  @RequestParam(UserParamsSchema)
+  @GET("/:id")
+  getUser(request: Request): ResponseEntity<z.infer<typeof UserParamsSchema>> {
+    // request.params has been fully validated and rewritten. you can safely assert the type!
+    const params = request.params as unknown as z.infer<typeof UserParamsSchema>;
+
+    const user = this.database.user.findById(params.id);
+
+    return ResponseEntity.ok().body(user);
+  }
+
+  @RequestQuery(ListUsersQuerySchema)
+  @GET()
+  listUsers(request: Request): ResponseEntity<z.infer<typeof ListUsersQuerySchema>> {
+    // request.query has been fully validated and rewritten. you can safely assert the type!
+    const query = request.query as unknown as z.infer<typeof ListUsersQuerySchema>;
+
+    const users = this.database.user.findAll({ page: query.page });
+
+    return ResponseEntity.ok().body(users);
+  }
+}
+```
+
 ### Redirects
 
 ```typescript

package/dist/index.cjs

@@ -221,6 +221,46 @@ var ResponseEntityBuilder = class {
 	}
 };
 //#endregion
+//#region src/helper/error/responsestatus.ts
+/**
+* Ensure that you define a middleware that can handle this error.
+*
+* @see {@link Sapling.loadResponseStatusErrorMiddleware}
+*/
+var ResponseStatusError = class ResponseStatusError extends Error {
+	constructor(status, message) {
+		super(message ?? "Something went wrong.");
+		this.status = status;
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.name = `HttpError(${HttpStatus[status]})`;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, ResponseStatusError);
+	}
+};
+//#endregion
+//#region src/helper/error/parse.ts
+/**
+* This error should be thrown when some data cannot be parsed by a given schema.
+*/
+var ParserError = class ParserError extends ResponseStatusError {
+	constructor(location, issues, vendor) {
+		super(400, ParserError.formatMessage(location, issues, vendor));
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	static formatMessage(location, issues, vendor) {
+		const formatted = issues.map((i) => {
+			const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
+			return path ? `${path}: ${i.message}` : i.message;
+		}).join("; ");
+		return `${vendor} failed to parse ${(() => {
+			switch (location) {
+				case "reqbody": return "request body";
+				case "reqparams": return "request params";
+				case "reqquery": return "request query";
+			}
+		})()}: ${formatted}`;
+	}
+};
+//#endregion
 //#region src/helper/sapling.ts
 const settings = {
 	serialize: JSON.stringify,
@@ -294,34 +334,6 @@ var Sapling = class Sapling {
 		app.use(Sapling.json());
 	}
 	/**
-	* Register a middleware that will handle {@link ResponseStatusError}.
-	*
-	* This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
-	* You may still define middleware to handle all other errors in a separate `app.use` call.
-	*
-	* @example
-	* ```ts
-	* import express from "express";
-	* import { Sapling } from "@tahminator/sapling";
-	*
-	* const app = express();
-	*
-	* Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
-	*   // `err` is guaranteed to be of type ResponseStatusError
-	*   res.status(err.status).json({
-	*     success: false,
-	*     message: err.message,
-	*   });
-	* });
-	* ```
-	*/
-	static loadResponseStatusErrorMiddleware(app, fn) {
-		app.use(((err, req, res, next) => {
-			if (err instanceof ResponseStatusError) fn(err, req, res, next);
-			else next(err);
-		}));
-	}
-	/**
 	* Serialize a value into a JSON string.
 	*
 	* This function is used in {@link ResponseEntity} to serialize the `body`.
@@ -359,22 +371,6 @@ var Sapling = class Sapling {
 	}
 };
 //#endregion
-//#region src/helper/error.ts
-/**
-* Ensure that you define a middleware that can handle this error.
-*
-* @see {@link Sapling.loadResponseStatusErrorMiddleware}
-*/
-var ResponseStatusError = class ResponseStatusError extends Error {
-	constructor(status, message) {
-		super(message ?? "Something went wrong.");
-		this.status = status;
-		Object.setPrototypeOf(this, new.target.prototype);
-		this.name = `HttpError(${HttpStatus[status]})`;
-		if (Error.captureStackTrace) Error.captureStackTrace(this, ResponseStatusError);
-	}
-};
-//#endregion
 //#region src/types.ts
 const methodResolve = {
 	GET: "get",
@@ -507,6 +503,56 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
+//#region src/annotation/request.ts
+const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
+function _getOrCreateRequestSchemaDefinition(ctor, fnName) {
+	const byFn = (() => {
+		const fn = _requestSchemaStore.get(ctor);
+		if (fn) return fn;
+		const newFn = /* @__PURE__ */ new Map();
+		_requestSchemaStore.set(ctor, newFn);
+		return newFn;
+	})();
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+function _setOnce(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
+	};
+}
+function _getRequestSchemas(ctor, fnName) {
+	return _requestSchemaStore.get(ctor)?.get(fnName);
+}
+async function _parseOrThrow(schema, input, kind) {
+	const result = await schema["~standard"].validate(input);
+	if (result.issues) throw new ParserError(kind, result.issues, schema["~standard"].vendor);
+	return result.value;
+}
+//#endregion
 //#region src/annotation/route.ts
 const _routeStore = /* @__PURE__ */ new WeakMap();
 /**
@@ -604,6 +650,14 @@ function Controller({ prefix = "", deps = [] } = {}) {
 		const usedRoutes = /* @__PURE__ */ new Set();
 		_InjectableDeps.set(targetClass, deps);
 		const controllerInstance = _resolve(targetClass);
+		if (routes.reduce((prev, r) => {
+			if (r.method !== "USE") return prev;
+			const fn = controllerInstance[r.fnName];
+			return typeof fn === "function" && fn.length >= 4 ? prev + 1 : prev;
+		}, 0) > 1) throw new Error(`Invalid @MiddlewareClass class "${targetClass.name}":
+Multiple 4-arg @Middleware() error handlers were found.
+Express will not enter routers in error mode, so an error-middleware class must expose exactly one error handler.
+Split these into separate @MiddlewareClass classes, or merge the logic into a single method.`);
 		for (const { method, path, fnName } of routes) {
 			const fn = controllerInstance[fnName];
 			if (typeof fn !== "function") continue;
@@ -612,9 +666,34 @@ function Controller({ prefix = "", deps = [] } = {}) {
 			if (method !== "USE" && usedRoutes.has(routeKey)) throw new Error(`Duplicate route [${method}] "${path instanceof RegExp ? path.source : fp}" detected in controller "${target.name}"`);
 			if (method !== "USE") usedRoutes.add(routeKey);
 			const methodName = methodResolve[method];
+			if (method === "USE" && fn.length >= 4) {
+				const middlewareFn = async (err, request, response, next) => {
+					try {
+						const result = fn.bind(controllerInstance)(err, request, response, next);
+						if (result instanceof ResponseEntity) {
+							response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
+							return;
+						}
+						if (result instanceof RedirectView) {
+							response.redirect(result.getUrl());
+							return;
+						}
+					} catch (e) {
+						console.error(e);
+						next(e);
+					}
+				};
+				_ControllerRegistry.set(targetClass, middlewareFn);
+				return;
+			}
 			router[methodName](fp, async (request, response, next) => {
+				const schemas = _getRequestSchemas(target, fnName);
+				if (schemas) {
+					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "reqbody");
+					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "reqparams");
+					if (schemas.query) request.query = await _parseOrThrow(schemas.query, request.query, "reqquery");
+				}
 				const result = await fn.bind(controllerInstance)(request, response, next);
-				if (method === "USE") return;
 				if (result instanceof ResponseEntity) {
 					response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
 					return;
@@ -623,7 +702,7 @@ function Controller({ prefix = "", deps = [] } = {}) {
 					response.redirect(result.getUrl());
 					return;
 				}
-				if (!response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
+				if (method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
 			});
 		}
 		_ControllerRegistry.set(targetClass, router);
@@ -642,8 +721,47 @@ function MiddlewareClass(...args) {
 	return Controller(...args);
 }
 //#endregion
+//#region \0@oxc-project+runtime@0.127.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;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/middleware/default/base.ts
+let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
+	handle(err, _request, _response, _next) {
+		console.error("[Error]", err);
+		return ResponseEntity.status(500).body({ message: "Internal Server Error" });
+	}
+};
+__decorate([Middleware()], DefaultBaseErrorMiddleware.prototype, "handle", null);
+DefaultBaseErrorMiddleware = __decorate([MiddlewareClass()], DefaultBaseErrorMiddleware);
+//#endregion
+//#region src/middleware/default/responsestatus.ts
+let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddleware {
+	handle(err, _request, _response, _next) {
+		if (err instanceof ResponseStatusError) return ResponseEntity.status(err.status).body({ message: err.message });
+	}
+};
+__decorate([Middleware()], DefaultResponseStatusErrorMiddleware.prototype, "handle", null);
+DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultResponseStatusErrorMiddleware);
+//#endregion
 exports.Controller = Controller;
 exports.DELETE = DELETE;
+Object.defineProperty(exports, "DefaultBaseErrorMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultBaseErrorMiddleware;
+	}
+});
+Object.defineProperty(exports, "DefaultResponseStatusErrorMiddleware", {
+	enumerable: true,
+	get: function() {
+		return DefaultResponseStatusErrorMiddleware;
+	}
+});
 exports.GET = GET;
 exports.HEAD = HEAD;
 exports.Html404ErrorPage = Html404ErrorPage;
@@ -655,7 +773,11 @@ exports.OPTIONS = OPTIONS;
 exports.PATCH = PATCH;
 exports.POST = POST;
 exports.PUT = PUT;
+exports.ParserError = ParserError;
 exports.RedirectView = RedirectView;
+exports.RequestBody = RequestBody;
+exports.RequestParam = RequestParam;
+exports.RequestQuery = RequestQuery;
 exports.ResponseEntity = ResponseEntity;
 exports.ResponseEntityBuilder = ResponseEntityBuilder;
 exports.ResponseStatusError = ResponseStatusError;
@@ -664,6 +786,8 @@ exports._ControllerRegistry = _ControllerRegistry;
 exports._InjectableDeps = _InjectableDeps;
 exports._InjectableRegistry = _InjectableRegistry;
 exports._Route = _Route;
+exports._getRequestSchemas = _getRequestSchemas;
 exports._getRoutes = _getRoutes;
+exports._parseOrThrow = _parseOrThrow;
 exports._resolve = _resolve;
 exports.methodResolve = methodResolve;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import e, { NextFunction, Request, Response, Router } from "express";
+import e, { ErrorRequestHandler, NextFunction, Request, Response, Router } from "express";
 
 //#region src/html/404.d.ts
 /**
@@ -29,7 +29,7 @@ type HttpHeaders = Record<string, string>;
 type ExpressMiddlewareFn = ($1: Request, $2: Response, $3: NextFunction) => void;
 //#endregion
 //#region src/annotation/controller.d.ts
-declare const _ControllerRegistry: WeakMap<Function, Router>;
+declare const _ControllerRegistry: WeakMap<Function, Router | ErrorRequestHandler>;
 type ControllerProps = {
   /**
    * Optional URL prefix applied to all routes in the controller. Defaults to "".
@@ -153,6 +153,84 @@ declare function _getRoutes(ctor: Function): readonly RouteDefinition[];
  */
 declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;
 //#endregion
+//#region node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
 //#region src/helper/redirect.d.ts
 /**
  * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
@@ -308,7 +386,7 @@ declare enum HttpStatus {
   NETWORK_AUTHENTICATION_REQUIRED = 511
 }
 //#endregion
-//#region src/helper/error.d.ts
+//#region src/helper/error/responsestatus.d.ts
 /**
  * Ensure that you define a middleware that can handle this error.
  *
@@ -319,6 +397,16 @@ declare class ResponseStatusError extends Error {
   constructor(status: HttpStatus, message?: string);
 }
 //#endregion
+//#region src/helper/error/parse.d.ts
+type ParserErrorLocation = "reqbody" | "reqparams" | "reqquery";
+/**
+ * This error should be thrown when some data cannot be parsed by a given schema.
+ */
+declare class ParserError extends ResponseStatusError {
+  constructor(location: ParserErrorLocation, issues: readonly StandardSchemaV1.Issue[], vendor: string);
+  private static formatMessage;
+}
+//#endregion
 //#region src/helper/sapling.d.ts
 /**
  * Collection of utility functions which are essential for Sapling to function.
@@ -338,7 +426,7 @@ declare class Sapling {
    * app.use(router);
    * ```
    */
-  static resolve<TClass>(this: void, clazz: Class<TClass>): Router;
+  static resolve<TClass>(this: void, clazz: Class<TClass>): Router | ErrorRequestHandler;
   /**
    * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
    *
@@ -365,29 +453,6 @@ declare class Sapling {
    * ```
    */
   static registerApp(app: e.Express): void;
-  /**
-   * Register a middleware that will handle {@link ResponseStatusError}.
-   *
-   * This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
-   * You may still define middleware to handle all other errors in a separate `app.use` call.
-   *
-   * @example
-   * ```ts
-   * import express from "express";
-   * import { Sapling } from "@tahminator/sapling";
-   *
-   * const app = express();
-   *
-   * Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
-   *   // `err` is guaranteed to be of type ResponseStatusError
-   *   res.status(err.status).json({
-   *     success: false,
-   *     message: err.message,
-   *   });
-   * });
-   * ```
-   */
-  static loadResponseStatusErrorMiddleware(this: void, app: e.Express, fn: (err: ResponseStatusError, request: e.Request, response: e.Response, next: e.NextFunction) => void): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -418,4 +483,35 @@ declare class Sapling {
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
 }
 //#endregion
-export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+//#region src/annotation/request.d.ts
+type RequestSchemaDefinition = {
+  body?: StandardSchemaV1;
+  param?: StandardSchemaV1;
+  query?: StandardSchemaV1;
+};
+declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
+declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
+declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
+//#region src/middleware/default/base.d.ts
+/**
+ * This should be registered last in the middleware chain.
+ *
+ * All exception messages are hidden from the request by default.
+ */
+declare class DefaultBaseErrorMiddleware {
+  handle(err: unknown, _request: Request, _response: Response, _next: NextFunction): ResponseEntity<{
+    message: string;
+  }>;
+}
+//#endregion
+//#region src/middleware/default/responsestatus.d.ts
+declare class DefaultResponseStatusErrorMiddleware {
+  handle(err: unknown, _request: Request, _response: Response, _next: NextFunction): ResponseEntity<{
+    message: string;
+  }> | undefined;
+}
+//#endregion
+export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultResponseStatusErrorMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import e, { NextFunction, Request, Response, Router } from "express";
+import e, { ErrorRequestHandler, NextFunction, Request, Response, Router } from "express";
 
 //#region src/html/404.d.ts
 /**
@@ -29,7 +29,7 @@ type HttpHeaders = Record<string, string>;
 type ExpressMiddlewareFn = ($1: Request, $2: Response, $3: NextFunction) => void;
 //#endregion
 //#region src/annotation/controller.d.ts
-declare const _ControllerRegistry: WeakMap<Function, Router>;
+declare const _ControllerRegistry: WeakMap<Function, Router | ErrorRequestHandler>;
 type ControllerProps = {
   /**
    * Optional URL prefix applied to all routes in the controller. Defaults to "".
@@ -153,6 +153,84 @@ declare function _getRoutes(ctor: Function): readonly RouteDefinition[];
  */
 declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;
 //#endregion
+//#region node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
 //#region src/helper/redirect.d.ts
 /**
  * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
@@ -308,7 +386,7 @@ declare enum HttpStatus {
   NETWORK_AUTHENTICATION_REQUIRED = 511
 }
 //#endregion
-//#region src/helper/error.d.ts
+//#region src/helper/error/responsestatus.d.ts
 /**
  * Ensure that you define a middleware that can handle this error.
  *
@@ -319,6 +397,16 @@ declare class ResponseStatusError extends Error {
   constructor(status: HttpStatus, message?: string);
 }
 //#endregion
+//#region src/helper/error/parse.d.ts
+type ParserErrorLocation = "reqbody" | "reqparams" | "reqquery";
+/**
+ * This error should be thrown when some data cannot be parsed by a given schema.
+ */
+declare class ParserError extends ResponseStatusError {
+  constructor(location: ParserErrorLocation, issues: readonly StandardSchemaV1.Issue[], vendor: string);
+  private static formatMessage;
+}
+//#endregion
 //#region src/helper/sapling.d.ts
 /**
  * Collection of utility functions which are essential for Sapling to function.
@@ -338,7 +426,7 @@ declare class Sapling {
    * app.use(router);
    * ```
    */
-  static resolve<TClass>(this: void, clazz: Class<TClass>): Router;
+  static resolve<TClass>(this: void, clazz: Class<TClass>): Router | ErrorRequestHandler;
   /**
    * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
    *
@@ -365,29 +453,6 @@ declare class Sapling {
    * ```
    */
   static registerApp(app: e.Express): void;
-  /**
-   * Register a middleware that will handle {@link ResponseStatusError}.
-   *
-   * This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
-   * You may still define middleware to handle all other errors in a separate `app.use` call.
-   *
-   * @example
-   * ```ts
-   * import express from "express";
-   * import { Sapling } from "@tahminator/sapling";
-   *
-   * const app = express();
-   *
-   * Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
-   *   // `err` is guaranteed to be of type ResponseStatusError
-   *   res.status(err.status).json({
-   *     success: false,
-   *     message: err.message,
-   *   });
-   * });
-   * ```
-   */
-  static loadResponseStatusErrorMiddleware(this: void, app: e.Express, fn: (err: ResponseStatusError, request: e.Request, response: e.Response, next: e.NextFunction) => void): void;
   /**
    * Serialize a value into a JSON string.
    *
@@ -418,4 +483,35 @@ declare class Sapling {
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
 }
 //#endregion
-export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+//#region src/annotation/request.d.ts
+type RequestSchemaDefinition = {
+  body?: StandardSchemaV1;
+  param?: StandardSchemaV1;
+  query?: StandardSchemaV1;
+};
+declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
+declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
+declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
+//#region src/middleware/default/base.d.ts
+/**
+ * This should be registered last in the middleware chain.
+ *
+ * All exception messages are hidden from the request by default.
+ */
+declare class DefaultBaseErrorMiddleware {
+  handle(err: unknown, _request: Request, _response: Response, _next: NextFunction): ResponseEntity<{
+    message: string;
+  }>;
+}
+//#endregion
+//#region src/middleware/default/responsestatus.d.ts
+declare class DefaultResponseStatusErrorMiddleware {
+  handle(err: unknown, _request: Request, _response: Response, _next: NextFunction): ResponseEntity<{
+    message: string;
+  }> | undefined;
+}
+//#endregion
+export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultResponseStatusErrorMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/dist/index.mjs

@@ -197,6 +197,46 @@ var ResponseEntityBuilder = class {
 	}
 };
 //#endregion
+//#region src/helper/error/responsestatus.ts
+/**
+* Ensure that you define a middleware that can handle this error.
+*
+* @see {@link Sapling.loadResponseStatusErrorMiddleware}
+*/
+var ResponseStatusError = class ResponseStatusError extends Error {
+	constructor(status, message) {
+		super(message ?? "Something went wrong.");
+		this.status = status;
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.name = `HttpError(${HttpStatus[status]})`;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, ResponseStatusError);
+	}
+};
+//#endregion
+//#region src/helper/error/parse.ts
+/**
+* This error should be thrown when some data cannot be parsed by a given schema.
+*/
+var ParserError = class ParserError extends ResponseStatusError {
+	constructor(location, issues, vendor) {
+		super(400, ParserError.formatMessage(location, issues, vendor));
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	static formatMessage(location, issues, vendor) {
+		const formatted = issues.map((i) => {
+			const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
+			return path ? `${path}: ${i.message}` : i.message;
+		}).join("; ");
+		return `${vendor} failed to parse ${(() => {
+			switch (location) {
+				case "reqbody": return "request body";
+				case "reqparams": return "request params";
+				case "reqquery": return "request query";
+			}
+		})()}: ${formatted}`;
+	}
+};
+//#endregion
 //#region src/helper/sapling.ts
 const settings = {
 	serialize: JSON.stringify,
@@ -270,34 +310,6 @@ var Sapling = class Sapling {
 		app.use(Sapling.json());
 	}
 	/**
-	* Register a middleware that will handle {@link ResponseStatusError}.
-	*
-	* This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
-	* You may still define middleware to handle all other errors in a separate `app.use` call.
-	*
-	* @example
-	* ```ts
-	* import express from "express";
-	* import { Sapling } from "@tahminator/sapling";
-	*
-	* const app = express();
-	*
-	* Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
-	*   // `err` is guaranteed to be of type ResponseStatusError
-	*   res.status(err.status).json({
-	*     success: false,
-	*     message: err.message,
-	*   });
-	* });
-	* ```
-	*/
-	static loadResponseStatusErrorMiddleware(app, fn) {
-		app.use(((err, req, res, next) => {
-			if (err instanceof ResponseStatusError) fn(err, req, res, next);
-			else next(err);
-		}));
-	}
-	/**
 	* Serialize a value into a JSON string.
 	*
 	* This function is used in {@link ResponseEntity} to serialize the `body`.
@@ -335,22 +347,6 @@ var Sapling = class Sapling {
 	}
 };
 //#endregion
-//#region src/helper/error.ts
-/**
-* Ensure that you define a middleware that can handle this error.
-*
-* @see {@link Sapling.loadResponseStatusErrorMiddleware}
-*/
-var ResponseStatusError = class ResponseStatusError extends Error {
-	constructor(status, message) {
-		super(message ?? "Something went wrong.");
-		this.status = status;
-		Object.setPrototypeOf(this, new.target.prototype);
-		this.name = `HttpError(${HttpStatus[status]})`;
-		if (Error.captureStackTrace) Error.captureStackTrace(this, ResponseStatusError);
-	}
-};
-//#endregion
 //#region src/types.ts
 const methodResolve = {
 	GET: "get",
@@ -483,6 +479,56 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
+//#region src/annotation/request.ts
+const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
+function _getOrCreateRequestSchemaDefinition(ctor, fnName) {
+	const byFn = (() => {
+		const fn = _requestSchemaStore.get(ctor);
+		if (fn) return fn;
+		const newFn = /* @__PURE__ */ new Map();
+		_requestSchemaStore.set(ctor, newFn);
+		return newFn;
+	})();
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+function _setOnce(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "body", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "param", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateRequestSchemaDefinition(ctor, fnName), "query", schema, fnName);
+	};
+}
+function _getRequestSchemas(ctor, fnName) {
+	return _requestSchemaStore.get(ctor)?.get(fnName);
+}
+async function _parseOrThrow(schema, input, kind) {
+	const result = await schema["~standard"].validate(input);
+	if (result.issues) throw new ParserError(kind, result.issues, schema["~standard"].vendor);
+	return result.value;
+}
+//#endregion
 //#region src/annotation/route.ts
 const _routeStore = /* @__PURE__ */ new WeakMap();
 /**
@@ -580,6 +626,14 @@ function Controller({ prefix = "", deps = [] } = {}) {
 		const usedRoutes = /* @__PURE__ */ new Set();
 		_InjectableDeps.set(targetClass, deps);
 		const controllerInstance = _resolve(targetClass);
+		if (routes.reduce((prev, r) => {
+			if (r.method !== "USE") return prev;
+			const fn = controllerInstance[r.fnName];
+			return typeof fn === "function" && fn.length >= 4 ? prev + 1 : prev;
+		}, 0) > 1) throw new Error(`Invalid @MiddlewareClass class "${targetClass.name}":
+Multiple 4-arg @Middleware() error handlers were found.
+Express will not enter routers in error mode, so an error-middleware class must expose exactly one error handler.
+Split these into separate @MiddlewareClass classes, or merge the logic into a single method.`);
 		for (const { method, path, fnName } of routes) {
 			const fn = controllerInstance[fnName];
 			if (typeof fn !== "function") continue;
@@ -588,9 +642,34 @@ function Controller({ prefix = "", deps = [] } = {}) {
 			if (method !== "USE" && usedRoutes.has(routeKey)) throw new Error(`Duplicate route [${method}] "${path instanceof RegExp ? path.source : fp}" detected in controller "${target.name}"`);
 			if (method !== "USE") usedRoutes.add(routeKey);
 			const methodName = methodResolve[method];
+			if (method === "USE" && fn.length >= 4) {
+				const middlewareFn = async (err, request, response, next) => {
+					try {
+						const result = fn.bind(controllerInstance)(err, request, response, next);
+						if (result instanceof ResponseEntity) {
+							response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
+							return;
+						}
+						if (result instanceof RedirectView) {
+							response.redirect(result.getUrl());
+							return;
+						}
+					} catch (e) {
+						console.error(e);
+						next(e);
+					}
+				};
+				_ControllerRegistry.set(targetClass, middlewareFn);
+				return;
+			}
 			router[methodName](fp, async (request, response, next) => {
+				const schemas = _getRequestSchemas(target, fnName);
+				if (schemas) {
+					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "reqbody");
+					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "reqparams");
+					if (schemas.query) request.query = await _parseOrThrow(schemas.query, request.query, "reqquery");
+				}
 				const result = await fn.bind(controllerInstance)(request, response, next);
-				if (method === "USE") return;
 				if (result instanceof ResponseEntity) {
 					response.contentType("application/json").status(result.getStatusCode()).set(result.getHeaders()).send(Sapling.serialize(result.getBody()));
 					return;
@@ -599,7 +678,7 @@ function Controller({ prefix = "", deps = [] } = {}) {
 					response.redirect(result.getUrl());
 					return;
 				}
-				if (!response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
+				if (method !== "USE" && !response.writableEnded) response.status(404).send(Html404ErrorPage(`Cannot ${methodName.toUpperCase()} ${path instanceof RegExp ? path.source : fp}`));
 			});
 		}
 		_ControllerRegistry.set(targetClass, router);
@@ -618,4 +697,31 @@ function MiddlewareClass(...args) {
 	return Controller(...args);
 }
 //#endregion
-export { Controller, DELETE, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+//#region \0@oxc-project+runtime@0.127.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;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/middleware/default/base.ts
+let DefaultBaseErrorMiddleware = class DefaultBaseErrorMiddleware {
+	handle(err, _request, _response, _next) {
+		console.error("[Error]", err);
+		return ResponseEntity.status(500).body({ message: "Internal Server Error" });
+	}
+};
+__decorate([Middleware()], DefaultBaseErrorMiddleware.prototype, "handle", null);
+DefaultBaseErrorMiddleware = __decorate([MiddlewareClass()], DefaultBaseErrorMiddleware);
+//#endregion
+//#region src/middleware/default/responsestatus.ts
+let DefaultResponseStatusErrorMiddleware = class DefaultResponseStatusErrorMiddleware {
+	handle(err, _request, _response, _next) {
+		if (err instanceof ResponseStatusError) return ResponseEntity.status(err.status).body({ message: err.message });
+	}
+};
+__decorate([Middleware()], DefaultResponseStatusErrorMiddleware.prototype, "handle", null);
+DefaultResponseStatusErrorMiddleware = __decorate([MiddlewareClass()], DefaultResponseStatusErrorMiddleware);
+//#endregion
+export { Controller, DELETE, DefaultBaseErrorMiddleware, DefaultResponseStatusErrorMiddleware, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "1.5.28",
+  "version": "2.0.1",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {
@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@standard-schema/spec": "^1.1.0",
     "@types/express": "^5",
     "@types/supertest": "^7.2.0",
     "@vitest/coverage-istanbul": "^4.1.2",
@@ -55,6 +56,10 @@
     "tsdown": "^0.21.10",
     "typescript-eslint": "^8.57.2",
     "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "zod": "^4.4.3"
+  },
+  "inlinedDependencies": {
+    "@standard-schema/spec": "1.1.0"
   }
 }