@heliosjs/middlewares 10.0.5 → 10.0.8

package/dist/pipe.d.ts

@@ -1,31 +1,32 @@
 import { type Pipe } from '@heliosjs/core/types';
 /**
- * Decorator to register a data transformation pipe.
+ * Registers a transformation pipe on a controller class or a single route method.
+ * Pipes run after guards and before middlewares; each supplied function replaces
+ * the matching part of the request with its return value, so the handler and its
+ * `@Body()` / `@QueryParam()` decorators see the transformed data.
  *
- * Pipes are used to transform incoming request data before it reaches
- * the route handler. They can be applied at the controller level and
- * modify parts of the request such as body, query, params, or headers.
+ * Use pipes for normalization and coercion (trim, lowercase, `Number(...)`,
+ * defaults). For schema validation prefer a DTO on the param decorator or
+ * `@Sanitize`.
  *
- * @param config - Configuration object containing transformation functions
- * for different parts of the request.
+ * @param pipe - An object with any of these keys, each a
+ *   `(value, request) => value` transformer:
+ *   - `body` — `(body, req) => body`. Why: reshape or clean the parsed body.
+ *   - `query` — `(query, req) => query`, where query is
+ *     `Record<string, string | string[]>`. Why: coerce query strings to the
+ *     types the handler expects.
+ *   - `params` — `(params, req) => params`, `Record<string, string>`. Why:
+ *     normalize path segments (case, padding).
+ *   - `headers` — `(headers, req) => headers`. Why: canonicalize header values.
+ *   Omitted keys leave that part untouched.
  *
- * @returns A class decorator that attaches pipe metadata to the target.
+ * @returns A class or method decorator.
  *
  * @example
  * @Pipe({
- *   body: (body) => ({ ...body, name: body.name.trim() }),
- *   query: (query) => ({ ...query, page: Number(query.page) }),
+ *   body: (body) => ({ ...body, name: body.name?.trim() }),
+ *   query: (query) => ({ ...query, page: Number(query.page ?? 1) }),
  * })
  * class MyController {}
- *
- * @remarks
- * Each function in the pipe receives raw data and must return the transformed value.
- * Pipes are executed before controller methods and can be used for:
- * - data normalization
- * - type casting
- * - sanitization
- *
- * Metadata is stored under the CONTROLLER_CONFIGURATION key and later used
- * by the framework during request processing.
  */
-export declare function Pipe(pipe: Pipe): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Pipe(pipe: Pipe): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/pipe.js

@@ -3,38 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Pipe = Pipe;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to register a data transformation pipe.
+ * Registers a transformation pipe on a controller class or a single route method.
+ * Pipes run after guards and before middlewares; each supplied function replaces
+ * the matching part of the request with its return value, so the handler and its
+ * `@Body()` / `@QueryParam()` decorators see the transformed data.
  *
- * Pipes are used to transform incoming request data before it reaches
- * the route handler. They can be applied at the controller level and
- * modify parts of the request such as body, query, params, or headers.
+ * Use pipes for normalization and coercion (trim, lowercase, `Number(...)`,
+ * defaults). For schema validation prefer a DTO on the param decorator or
+ * `@Sanitize`.
  *
- * @param config - Configuration object containing transformation functions
- * for different parts of the request.
+ * @param pipe - An object with any of these keys, each a
+ *   `(value, request) => value` transformer:
+ *   - `body` — `(body, req) => body`. Why: reshape or clean the parsed body.
+ *   - `query` — `(query, req) => query`, where query is
+ *     `Record<string, string | string[]>`. Why: coerce query strings to the
+ *     types the handler expects.
+ *   - `params` — `(params, req) => params`, `Record<string, string>`. Why:
+ *     normalize path segments (case, padding).
+ *   - `headers` — `(headers, req) => headers`. Why: canonicalize header values.
+ *   Omitted keys leave that part untouched.
  *
- * @returns A class decorator that attaches pipe metadata to the target.
+ * @returns A class or method decorator.
  *
  * @example
  * @Pipe({
- *   body: (body) => ({ ...body, name: body.name.trim() }),
- *   query: (query) => ({ ...query, page: Number(query.page) }),
+ *   body: (body) => ({ ...body, name: body.name?.trim() }),
+ *   query: (query) => ({ ...query, page: Number(query.page ?? 1) }),
  * })
  * class MyController {}
- *
- * @remarks
- * Each function in the pipe receives raw data and must return the transformed value.
- * Pipes are executed before controller methods and can be used for:
- * - data normalization
- * - type casting
- * - sanitization
- *
- * Metadata is stored under the CONTROLLER_CONFIGURATION key and later used
- * by the framework during request processing.
  */
 function Pipe(pipe) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const data = [{ pipe }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/pipe.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipe.js","sourceRoot":"","sources":["../src/pipe.ts"],"names":[],"mappings":";;AA+BA,oBAUC;AAxCD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,SAAgB,IAAI,CAAC,IAAU;IAC7B,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAExB,IAAI,UAAU,EAAE,CAAC;YACf,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"pipe.js","sourceRoot":"","sources":["../src/pipe.ts"],"names":[],"mappings":";;AAgCA,oBAUC;AAzCD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,IAAI,CAAC,IAAU;IAC7B,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAExB,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/roles.d.ts

@@ -1,15 +1,25 @@
 import type { GuardFunction } from '@heliosjs/core/types';
+/** Role match policy for `@Roles`: `'any'` (at least one required role) or `'all'` (every required role). */
 export type RoleMode = 'any' | 'all';
+/** Trailing options object accepted by `@Roles`. */
 export interface RolesOptions {
+    /** Match policy. Default `'any'`. */
     mode?: RoleMode;
+    /** Denial message when the check fails. Default `'Insufficient role'`. */
     message?: string;
 }
 type RolesArg = string | string[];
+/**
+ * @internal `true` when `userRoles` satisfies `required` under `mode` (`'all'`:
+ * every required role present; otherwise: at least one).
+ */
 export declare function matchRoles(required: string[], userRoles: string[], mode: RoleMode): boolean;
+/** @internal Splits `@Roles(...)`'s variadic arguments into a flat role list plus the trailing options object, if any. */
 export declare function normalizeArgs(args: (RolesArg | RolesOptions)[]): {
     roles: string[];
     options: RolesOptions;
 };
+/** @internal Builds the `GuardFunction` `@Roles` registers via `@Guard`, using the configured `RolesExtractor`. */
 export declare function createRolesGuard(required: string[], options: RolesOptions): GuardFunction;
 /**
  * Restrict a controller or route to users holding the required role(s).
@@ -26,5 +36,5 @@ export declare function createRolesGuard(required: string[], options: RolesOptio
  * @example
  * @Roles(['admin', 'editor'], { mode: 'all' })  // ALL
  */
-export declare function Roles(...args: (RolesArg | RolesOptions)[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Roles(...args: (RolesArg | RolesOptions)[]): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;
 export {};

package/dist/roles.js

@@ -5,11 +5,16 @@ exports.normalizeArgs = normalizeArgs;
 exports.createRolesGuard = createRolesGuard;
 exports.Roles = Roles;
 const utils_1 = require("@heliosjs/core/utils");
+/**
+ * @internal `true` when `userRoles` satisfies `required` under `mode` (`'all'`:
+ * every required role present; otherwise: at least one).
+ */
 function matchRoles(required, userRoles, mode) {
     return mode === 'all'
         ? required.every((role) => userRoles.includes(role))
         : required.some((role) => userRoles.includes(role));
 }
+/** @internal Splits `@Roles(...)`'s variadic arguments into a flat role list plus the trailing options object, if any. */
 function normalizeArgs(args) {
     let options = {};
     let roleArgs = args;
@@ -28,6 +33,7 @@ function normalizeArgs(args) {
     });
     return { roles, options };
 }
+/** @internal Builds the `GuardFunction` `@Roles` registers via `@Guard`, using the configured `RolesExtractor`. */
 function createRolesGuard(required, options) {
     const mode = options.mode ?? 'any';
     const message = options.message ?? 'Insufficient role';
@@ -59,9 +65,9 @@ function createRolesGuard(required, options) {
 function Roles(...args) {
     const { roles, options } = normalizeArgs(args);
     const guard = createRolesGuard(roles, options);
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const data = [{ guard }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/roles.js.map

@@ -1 +1 @@
-{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"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"}

package/dist/sanitize.d.ts

@@ -1,40 +1,34 @@
 import type { SanitizerConfig } from '@heliosjs/core/types';
 /**
- * Decorator to apply sanitization configurations to a controller or method.
+ * Runs a Joi schema over one part of the request on a controller class or a
+ * single route method. Sanitizers run first in the pipeline (before guards), so
+ * every later stage sees the cleaned/validated data.
  *
- * This decorator accepts one or more sanitization configuration objects which define
- * how incoming request data should be sanitized before processing. It can be applied
- * at the class level to apply sanitization globally to all methods or at the method level
- * for fine-grained control.
+ * Depending on `action` a config either validates (throws on mismatch),
+ * sanitizes (coerces/strips and writes the result back onto the request), or
+ * both. The `SANITIZER` helper from `@heliosjs/core` provides ready-made Joi
+ * builders (`SANITIZER.string.email()`, `SANITIZER.xss()`, …).
  *
- * The sanitization configurations are stored as metadata on the target or method,
- * which can be retrieved by the framework to perform the actual sanitization during
- * request handling.
+ * @param config - One `SanitizerConfig`, or an array applied in order. Each has:
+ *   - `schema` (**required**) — a `Joi.Schema` to run.
+ *   - `type` (**required**) — which request part to target, one of
+ *     `'body'`, `'query'`, `'params'`, `'headers'`.
+ *   - `action` — `'validate'` (reject on error), `'sanitize'` (transform in
+ *     place), or `'both'`. Default `'both'`.
+ *   - `options` — Joi `ValidationOptions` passed through.
+ *   - `stripUnknown` — drop keys not in the schema.
+ *   Why an array: apply different schemas to different request parts on the same
+ *   route.
  *
- * @param {SanitizerConfig | SanitizerConfig[]} sanitizeConfig - A single or array of sanitization configuration objects.
- *
- * @returns {Function} A decorator function that applies the sanitization metadata.
- *
- * @example
- * // Apply sanitization to all methods in a controller
- * @Sanitize({ trim: true, escape: true })
- * class MyController {
- *   // ...
- * }
+ * @returns A class or method decorator.
  *
  * @example
- * // Apply multiple sanitization rules to a specific method
- * @Sanitize([
- *   { trim: true },
- *   { escape: true }
- * ])
- * async myMethod() {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the sanitization configurations is defined by `SANITIZE`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to apply sanitization logic.
+ * @Sanitize({
+ *   type: 'body',
+ *   action: 'both',
+ *   schema: Joi.object({ email: SANITIZER.string.email(), bio: SANITIZER.xss() }),
+ *   stripUnknown: true,
+ * })
+ * class ProfileController {}
  */
-export declare function Sanitize(config: SanitizerConfig | SanitizerConfig[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Sanitize(config: SanitizerConfig | SanitizerConfig[]): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/sanitize.js

@@ -3,48 +3,42 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sanitize = Sanitize;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to apply sanitization configurations to a controller or method.
+ * Runs a Joi schema over one part of the request on a controller class or a
+ * single route method. Sanitizers run first in the pipeline (before guards), so
+ * every later stage sees the cleaned/validated data.
  *
- * This decorator accepts one or more sanitization configuration objects which define
- * how incoming request data should be sanitized before processing. It can be applied
- * at the class level to apply sanitization globally to all methods or at the method level
- * for fine-grained control.
+ * Depending on `action` a config either validates (throws on mismatch),
+ * sanitizes (coerces/strips and writes the result back onto the request), or
+ * both. The `SANITIZER` helper from `@heliosjs/core` provides ready-made Joi
+ * builders (`SANITIZER.string.email()`, `SANITIZER.xss()`, …).
  *
- * The sanitization configurations are stored as metadata on the target or method,
- * which can be retrieved by the framework to perform the actual sanitization during
- * request handling.
+ * @param config - One `SanitizerConfig`, or an array applied in order. Each has:
+ *   - `schema` (**required**) — a `Joi.Schema` to run.
+ *   - `type` (**required**) — which request part to target, one of
+ *     `'body'`, `'query'`, `'params'`, `'headers'`.
+ *   - `action` — `'validate'` (reject on error), `'sanitize'` (transform in
+ *     place), or `'both'`. Default `'both'`.
+ *   - `options` — Joi `ValidationOptions` passed through.
+ *   - `stripUnknown` — drop keys not in the schema.
+ *   Why an array: apply different schemas to different request parts on the same
+ *   route.
  *
- * @param {SanitizerConfig | SanitizerConfig[]} sanitizeConfig - A single or array of sanitization configuration objects.
- *
- * @returns {Function} A decorator function that applies the sanitization metadata.
- *
- * @example
- * // Apply sanitization to all methods in a controller
- * @Sanitize({ trim: true, escape: true })
- * class MyController {
- *   // ...
- * }
+ * @returns A class or method decorator.
  *
  * @example
- * // Apply multiple sanitization rules to a specific method
- * @Sanitize([
- *   { trim: true },
- *   { escape: true }
- * ])
- * async myMethod() {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the sanitization configurations is defined by `SANITIZE`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to apply sanitization logic.
+ * @Sanitize({
+ *   type: 'body',
+ *   action: 'both',
+ *   schema: Joi.object({ email: SANITIZER.string.email(), bio: SANITIZER.xss() }),
+ *   stripUnknown: true,
+ * })
+ * class ProfileController {}
  */
 function Sanitize(config) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const sanitizers = Array.isArray(config) ? config : [config];
         const data = sanitizers.map(sanitizer => ({ sanitizer }));
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/sanitize.js.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":";;AAwCA,4BAWC;AAlDD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,QAAQ,CAAC,MAA2C;IAClE,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAE1D,IAAI,UAAU,EAAE,CAAC;YACf,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":";;AAkCA,4BAWC;AA5CD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,QAAQ,CAAC,MAA2C;IAClE,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAE1D,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/status.d.ts

@@ -1,35 +1,23 @@
 /**
- * Decorator to set the HTTP status code for the response.
+ * Sets the HTTP status code for successful responses from a controller class or a
+ * single route method. Method-level wins over class-level. Without it a
+ * successful handler responds `200` (or the code you set via `res.status`).
  *
- * This decorator can be applied at the method level to specify the HTTP status code
- * that should be returned when the method's response is sent. It can also be applied
- * at the class level to set a default status code for all methods within the class.
+ * This only affects the success path — errors still carry the status of the
+ * thrown `HeliosError`, and an explicit `res.redirect()` keeps its own code.
  *
- * The status code is stored as metadata on the target or method, which can be retrieved
- * by the framework to set the HTTP response status accordingly.
+ * @param status - The HTTP status code to send, e.g. `201` for a create, `202`
+ *   for an accepted async job, `204` for an empty body. Why: express REST
+ *   semantics without touching the `Response` object.
  *
- * @param {number} status - The HTTP status code to set for the response.
- *
- * @returns {Function} A decorator function that applies the status code metadata.
+ * @returns A class or method decorator.
  *
  * @example
- * // Set status code 201 for a specific method
- * @Status(201)
- * async createResource() {
- *   // ...
+ * class UserController {
+ *   @Post('/')
+ *   @Status(201)
+ *   create(@Body() dto: CreateUserDto) {}
  * }
- *
- * @example
- * // Set default status code 204 for all methods in a controller
- * @Status(204)
- * class MyController {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the status code is defined by `OK_METADATA_KEY`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to set the HTTP response status.
  */
 export declare function Status(status: number): (target: any, propertyKey?: string) => void;
 /**

package/dist/status.js

@@ -4,43 +4,34 @@ exports.Ok204 = exports.Ok201 = exports.Ok200 = void 0;
 exports.Status = Status;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to set the HTTP status code for the response.
+ * Sets the HTTP status code for successful responses from a controller class or a
+ * single route method. Method-level wins over class-level. Without it a
+ * successful handler responds `200` (or the code you set via `res.status`).
  *
- * This decorator can be applied at the method level to specify the HTTP status code
- * that should be returned when the method's response is sent. It can also be applied
- * at the class level to set a default status code for all methods within the class.
+ * This only affects the success path — errors still carry the status of the
+ * thrown `HeliosError`, and an explicit `res.redirect()` keeps its own code.
  *
- * The status code is stored as metadata on the target or method, which can be retrieved
- * by the framework to set the HTTP response status accordingly.
+ * @param status - The HTTP status code to send, e.g. `201` for a create, `202`
+ *   for an accepted async job, `204` for an empty body. Why: express REST
+ *   semantics without touching the `Response` object.
  *
- * @param {number} status - The HTTP status code to set for the response.
- *
- * @returns {Function} A decorator function that applies the status code metadata.
- *
- * @example
- * // Set status code 201 for a specific method
- * @Status(201)
- * async createResource() {
- *   // ...
- * }
+ * @returns A class or method decorator.
  *
  * @example
- * // Set default status code 204 for all methods in a controller
- * @Status(204)
- * class MyController {
- *   // ...
+ * class UserController {
+ *   @Post('/')
+ *   @Status(201)
+ *   create(@Body() dto: CreateUserDto) {}
  * }
- *
- * @remarks
- * The metadata key used for storing the status code is defined by `OK_METADATA_KEY`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to set the HTTP response status.
  */
 function Status(status) {
     return function (target, propertyKey) {
         if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)([{ status }], target, propertyKey);
         }
+        else {
+            (0, utils_1.defineMiddlewaresMeta)([{ status }], target);
+        }
     };
 }
 /**

package/dist/status.js.map

@@ -1 +1 @@
-{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":";;;AAkCA,wBAMC;AAxCD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,MAAM,CAAC,MAAc;IACnC,OAAO,UAAU,MAAW,EAAE,WAAoB;QAChD,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB;AAEvC;;;;;;;GAOG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB;AAEvC;;;;;;;;GAQG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB"}
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":";;;AAsBA,wBAQC;AA9BD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,MAAM,CAAC,MAAc;IACnC,OAAO,UAAU,MAAW,EAAE,WAAoB;QAChD,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB;AAEvC;;;;;;;GAOG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB;AAEvC;;;;;;;;GAQG;AACI,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAA1B,QAAA,KAAK,SAAqB"}

package/dist/use.d.ts

@@ -1,46 +1,25 @@
 import type { MiddlewareCB } from '@heliosjs/core/types';
 /**
- * Decorator to register middleware(s) at the controller or method level.
+ * Registers one or more middlewares on a controller class or a single route
+ * method. Middlewares run before the handler, in declaration order, after guards
+ * and pipes in the request pipeline. Calling `next(err)` with an error aborts the
+ * request; not calling `next` still proceeds (the pipeline advances once the
+ * middleware resolves).
  *
- * Middlewares are functions executed before the route handler.
- * They can be used to:
- * - modify request/response
- * - perform logging
- * - handle authentication/authorization
- * - short-circuit request handling
+ * Applied to a class, the middleware covers every route in it (and its child
+ * controllers); applied to a method, only that route.
  *
- * @param middleware - A single middleware function or an array of middleware functions.
+ * @param middleware - A middleware callback `(req, res, next) => void | Promise<void>`,
+ *   or an array of them applied in order. Why: attach auth, logging, request
+ *   shaping, or short-circuit logic without hand-wiring it into each handler.
  *
- * @returns A decorator that attaches middleware metadata to the target
- * (either a class or a method).
+ * @returns A class or method decorator.
  *
  * @example
- * // Single middleware
- * @Use((req, res, next) => {
- *   console.log('Request received');
- *   next();
- * })
- * class MyController {}
- *
- * @example
- * // Multiple middlewares
- * @Use([
- *   authMiddleware,
- *   loggingMiddleware,
- * ])
- * class MyController {}
- *
- * @example
- * // Method-level middleware
+ * @Use([authMiddleware, loggingMiddleware])
  * class MyController {
- *   @Use(authMiddleware)
+ *   @Use(rateLimitMiddleware)
  *   getData() {}
  * }
- *
- * @remarks
- * - Middlewares are executed in the order they are defined.
- * - Can be applied at both class and method levels.
- * - Metadata is stored using the MIDDLEWARES_CONFIG key and used
- *   internally by the framework during request handling.
  */
-export declare function Use(middleware: MiddlewareCB | MiddlewareCB[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+export declare function Use(middleware: MiddlewareCB | MiddlewareCB[]): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => any;

package/dist/use.js

@@ -3,51 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Use = Use;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to register middleware(s) at the controller or method level.
+ * Registers one or more middlewares on a controller class or a single route
+ * method. Middlewares run before the handler, in declaration order, after guards
+ * and pipes in the request pipeline. Calling `next(err)` with an error aborts the
+ * request; not calling `next` still proceeds (the pipeline advances once the
+ * middleware resolves).
  *
- * Middlewares are functions executed before the route handler.
- * They can be used to:
- * - modify request/response
- * - perform logging
- * - handle authentication/authorization
- * - short-circuit request handling
+ * Applied to a class, the middleware covers every route in it (and its child
+ * controllers); applied to a method, only that route.
  *
- * @param middleware - A single middleware function or an array of middleware functions.
+ * @param middleware - A middleware callback `(req, res, next) => void | Promise<void>`,
+ *   or an array of them applied in order. Why: attach auth, logging, request
+ *   shaping, or short-circuit logic without hand-wiring it into each handler.
  *
- * @returns A decorator that attaches middleware metadata to the target
- * (either a class or a method).
+ * @returns A class or method decorator.
  *
  * @example
- * // Single middleware
- * @Use((req, res, next) => {
- *   console.log('Request received');
- *   next();
- * })
- * class MyController {}
- *
- * @example
- * // Multiple middlewares
- * @Use([
- *   authMiddleware,
- *   loggingMiddleware,
- * ])
- * class MyController {}
- *
- * @example
- * // Method-level middleware
+ * @Use([authMiddleware, loggingMiddleware])
  * class MyController {
- *   @Use(authMiddleware)
+ *   @Use(rateLimitMiddleware)
  *   getData() {}
  * }
- *
- * @remarks
- * - Middlewares are executed in the order they are defined.
- * - Can be applied at both class and method levels.
- * - Metadata is stored using the MIDDLEWARES_CONFIG key and used
- *   internally by the framework during request handling.
  */
 function Use(middleware) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const middlewares = Array.isArray(middleware) ? middleware : [middleware];
         const data = middlewares.map((middleware) => ({ middleware }));
         if (propertyKey) {

package/dist/use.js.map

@@ -1 +1 @@
-{"version":3,"file":"use.js","sourceRoot":"","sources":["../src/use.ts"],"names":[],"mappings":";;AA+CA,kBAcC;AA5DD,gDAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,SAAgB,GAAG,CAAC,UAAyC;IAC3D,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAE1E,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAE/D,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"use.js","sourceRoot":"","sources":["../src/use.ts"],"names":[],"mappings":";;AA0BA,kBAcC;AAvCD,gDAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,GAAG,CAAC,UAAyC;IAC3D,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAE1E,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAE/D,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heliosjs/middlewares",
-  "version": "10.0.5",
+  "version": "10.0.8",
   "description": "Middlewares for @heliosjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,7 @@
     "reflect-metadata": "^0.2.2"
   },
   "peerDependencies": {
-    "@heliosjs/core": "^3.2.8",
+    "@heliosjs/core": "^3.2.11",
     "@types/node": ">=20.0.0",
     "reflect-metadata": "^0.2.2",
     "typescript": ">=5.0.0"