@heliosjs/middlewares 10.0.5 → 10.0.8

package/dist/catch.d.ts

@@ -1,29 +1,30 @@
 import type { ErrorHandler } from '@heliosjs/core/types';
 /**
- * Decorator to register a global or controller-level error handler.
+ * Registers an error handler on a controller class or a single route method. It
+ * fires when a guard, pipe, middleware, handler, or interceptor throws.
  *
- * This decorator accepts an error handling callback function which will be invoked
- * whenever an error occurs within the decorated target's scope (e.g., controller or service).
- * It attaches the handler as metadata on the target class, allowing the framework to
- * retrieve and execute the error handler appropriately during runtime.
+ * Handlers run newest-first (method-level before controller-level). The first one
+ * that **returns a non-Error value** stops the chain and that value becomes the
+ * response body; a handler that returns an `Error` or re-throws passes control to
+ * the next handler, and if none resolves the error it propagates to the adapter's
+ * default error response.
  *
- * @param {ErrorHandler} handler - The error callback function to handle errors.
+ * Declaring `@Catch` also opts the route into handling the "self-resolving" error
+ * codes (`FORBIDDEN`, `NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `UNAUTHORIZED`) that
+ * otherwise bypass error handlers.
  *
- * @returns {Function} A class decorator function that defines the error handler metadata.
+ * @param handler - `(error, req, res) => unknown`. `error` is the thrown value
+ *   (often a `HeliosError` subclass with `.code` / `.status`). Return a value to
+ *   answer the request, or return/throw an `Error` to defer. May be async. Why:
+ *   map domain errors to response shapes in one place.
+ *
+ * @returns A class or method decorator.
  *
  * @example
- * // Register a global error handler for a controller
- * @Catch(async (error, context) => {
- *   console.error('Error caught:', error);
- *   // Custom error handling logic
+ * @Catch((err, req, res) => {
+ *   if (err instanceof NotFoundError) return { error: 'not found', path: req.path };
+ *   throw err; // let the framework handle everything else
  * })
- * class MyController {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the error handler is defined by `CATCH`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to invoke the registered error handler when errors occur.
+ * class MyController {}
  */
-export declare function Catch(handler: ErrorHandler): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Catch(handler: ErrorHandler): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/catch.js

@@ -3,36 +3,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Catch = Catch;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to register a global or controller-level error handler.
+ * Registers an error handler on a controller class or a single route method. It
+ * fires when a guard, pipe, middleware, handler, or interceptor throws.
  *
- * This decorator accepts an error handling callback function which will be invoked
- * whenever an error occurs within the decorated target's scope (e.g., controller or service).
- * It attaches the handler as metadata on the target class, allowing the framework to
- * retrieve and execute the error handler appropriately during runtime.
+ * Handlers run newest-first (method-level before controller-level). The first one
+ * that **returns a non-Error value** stops the chain and that value becomes the
+ * response body; a handler that returns an `Error` or re-throws passes control to
+ * the next handler, and if none resolves the error it propagates to the adapter's
+ * default error response.
  *
- * @param {ErrorHandler} handler - The error callback function to handle errors.
+ * Declaring `@Catch` also opts the route into handling the "self-resolving" error
+ * codes (`FORBIDDEN`, `NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `UNAUTHORIZED`) that
+ * otherwise bypass error handlers.
  *
- * @returns {Function} A class decorator function that defines the error handler metadata.
+ * @param handler - `(error, req, res) => unknown`. `error` is the thrown value
+ *   (often a `HeliosError` subclass with `.code` / `.status`). Return a value to
+ *   answer the request, or return/throw an `Error` to defer. May be async. Why:
+ *   map domain errors to response shapes in one place.
+ *
+ * @returns A class or method decorator.
  *
  * @example
- * // Register a global error handler for a controller
- * @Catch(async (error, context) => {
- *   console.error('Error caught:', error);
- *   // Custom error handling logic
+ * @Catch((err, req, res) => {
+ *   if (err instanceof NotFoundError) return { error: 'not found', path: req.path };
+ *   throw err; // let the framework handle everything else
  * })
- * class MyController {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the error handler is defined by `CATCH`.
- * This metadata is accessible via Reflect API and used internally by the framework
- * to invoke the registered error handler when errors occur.
+ * class MyController {}
  */
 function Catch(handler) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const data = [{ errorHandler: handler }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/catch.js.map

@@ -1 +1 @@
-{"version":3,"file":"catch.js","sourceRoot":"","sources":["../src/catch.ts"],"names":[],"mappings":";;AA6BA,sBAUC;AAtCD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,KAAK,CAAC,OAAqB;IACzC,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,IAAI,GAAG,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;QAEzC,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":"catch.js","sourceRoot":"","sources":["../src/catch.ts"],"names":[],"mappings":";;AA8BA,sBAUC;AAvCD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,KAAK,CAAC,OAAqB;IACzC,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;QAEzC,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/cors.d.ts

@@ -1,37 +1,40 @@
 import type { CORSConfig } from '@heliosjs/core/types';
 /**
- * Decorator to configure Cross-Origin Resource Sharing (CORS) settings for HTTP controllers or methods.
+ * Configures Cross-Origin Resource Sharing for a controller class or a single
+ * route method. On a preflight (`OPTIONS`) request the response is answered
+ * directly with the negotiated CORS headers and `optionsSuccessStatus`; on a
+ * real request a disallowed origin is rejected with HTTP 403.
  *
- * This decorator allows you to specify CORS policies such as allowed origins, HTTP methods, and
- * the status code to return for successful OPTIONS requests. It can be applied at the class level
- * to affect all endpoints within a controller or at the method level to customize CORS for specific endpoints.
+ * Unspecified keys fall back to: `origin: '*'`, `optionsSuccessStatus: 204`,
+ * `methods:` every HTTP method Helios knows.
  *
- * When applied, the decorator defines metadata on the target (class prototype or method) which can be
- * later retrieved by the framework to enforce CORS policies during request handling.
+ * @param config - CORS options (all optional):
+ *   - `origin` — `string`, `string[]`, or `(origin) => boolean`. `'*'` allows
+ *     any origin; a list allows exact matches; a function decides per request.
+ *     Why: the allow-list is the core of the policy.
+ *   - `methods` — allowed methods for `Access-Control-Allow-Methods`, e.g.
+ *     `['GET', 'POST']`. Why: advertise only what the route group supports.
+ *   - `allowedHeaders` — value for `Access-Control-Allow-Headers` (request
+ *     headers the browser may send). Why: without this, custom headers like
+ *     `Authorization` are blocked on cross-origin calls.
+ *   - `exposedHeaders` — response headers JS may read
+ *     (`Access-Control-Expose-Headers`). Why: e.g. expose `X-Total-Count`.
+ *   - `credentials` — when `true`, sets `Access-Control-Allow-Credentials: true`
+ *     so cookies / `Authorization` are sent. Why: required for cookie auth;
+ *     cannot be combined with `origin: '*'` per the spec.
+ *   - `maxAge` — seconds a browser may cache the preflight result. Why: fewer
+ *     `OPTIONS` round-trips.
+ *   - `optionsSuccessStatus` — status for a successful preflight (default `204`;
+ *     use `200` for legacy browsers that choke on 204).
  *
- * @param {CORSConfig} [config={}] - Configuration object for CORS settings.
- * @param {string|string[]} [config.origin='*'] - Specifies the allowed origin(s) for CORS requests. Defaults to '*'.
- * @param {number} [config.optionsSuccessStatus=204] - HTTP status code to return for successful OPTIONS requests.
- * @param {string[]} [config.methods=Object.keys(HTTP_METHODS)] - Array of allowed HTTP methods for CORS.
- *
- * @returns {Function} A decorator function that applies the CORS configuration metadata.
- *
- * @example
- * // Apply CORS with default settings to all endpoints in a controller
- * @Cors()
- * class MyController {
- *   // ...
- * }
+ * @returns A class or method decorator.
  *
  * @example
- * // Apply CORS with custom settings to a specific method
- * @Cors({ origin: 'https://example.com', methods: ['GET', 'POST'] })
- * async myMethod() {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the CORS configuration is defined by `CORS_METADATA`.
- * This metadata is accessible via Reflect API and used internally by the framework to enforce CORS.
+ * @Cors({
+ *   origin: ['https://app.example.com'],
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ * })
+ * class ApiController {}
  */
-export declare function Cors(config?: CORSConfig): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Cors(config?: CORSConfig): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/cors.js

@@ -4,42 +4,45 @@ exports.Cors = Cors;
 const types_1 = require("@heliosjs/core/types");
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to configure Cross-Origin Resource Sharing (CORS) settings for HTTP controllers or methods.
+ * Configures Cross-Origin Resource Sharing for a controller class or a single
+ * route method. On a preflight (`OPTIONS`) request the response is answered
+ * directly with the negotiated CORS headers and `optionsSuccessStatus`; on a
+ * real request a disallowed origin is rejected with HTTP 403.
  *
- * This decorator allows you to specify CORS policies such as allowed origins, HTTP methods, and
- * the status code to return for successful OPTIONS requests. It can be applied at the class level
- * to affect all endpoints within a controller or at the method level to customize CORS for specific endpoints.
+ * Unspecified keys fall back to: `origin: '*'`, `optionsSuccessStatus: 204`,
+ * `methods:` every HTTP method Helios knows.
  *
- * When applied, the decorator defines metadata on the target (class prototype or method) which can be
- * later retrieved by the framework to enforce CORS policies during request handling.
+ * @param config - CORS options (all optional):
+ *   - `origin` — `string`, `string[]`, or `(origin) => boolean`. `'*'` allows
+ *     any origin; a list allows exact matches; a function decides per request.
+ *     Why: the allow-list is the core of the policy.
+ *   - `methods` — allowed methods for `Access-Control-Allow-Methods`, e.g.
+ *     `['GET', 'POST']`. Why: advertise only what the route group supports.
+ *   - `allowedHeaders` — value for `Access-Control-Allow-Headers` (request
+ *     headers the browser may send). Why: without this, custom headers like
+ *     `Authorization` are blocked on cross-origin calls.
+ *   - `exposedHeaders` — response headers JS may read
+ *     (`Access-Control-Expose-Headers`). Why: e.g. expose `X-Total-Count`.
+ *   - `credentials` — when `true`, sets `Access-Control-Allow-Credentials: true`
+ *     so cookies / `Authorization` are sent. Why: required for cookie auth;
+ *     cannot be combined with `origin: '*'` per the spec.
+ *   - `maxAge` — seconds a browser may cache the preflight result. Why: fewer
+ *     `OPTIONS` round-trips.
+ *   - `optionsSuccessStatus` — status for a successful preflight (default `204`;
+ *     use `200` for legacy browsers that choke on 204).
  *
- * @param {CORSConfig} [config={}] - Configuration object for CORS settings.
- * @param {string|string[]} [config.origin='*'] - Specifies the allowed origin(s) for CORS requests. Defaults to '*'.
- * @param {number} [config.optionsSuccessStatus=204] - HTTP status code to return for successful OPTIONS requests.
- * @param {string[]} [config.methods=Object.keys(HTTP_METHODS)] - Array of allowed HTTP methods for CORS.
- *
- * @returns {Function} A decorator function that applies the CORS configuration metadata.
- *
- * @example
- * // Apply CORS with default settings to all endpoints in a controller
- * @Cors()
- * class MyController {
- *   // ...
- * }
+ * @returns A class or method decorator.
  *
  * @example
- * // Apply CORS with custom settings to a specific method
- * @Cors({ origin: 'https://example.com', methods: ['GET', 'POST'] })
- * async myMethod() {
- *   // ...
- * }
- *
- * @remarks
- * The metadata key used for storing the CORS configuration is defined by `CORS_METADATA`.
- * This metadata is accessible via Reflect API and used internally by the framework to enforce CORS.
+ * @Cors({
+ *   origin: ['https://app.example.com'],
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ * })
+ * class ApiController {}
  */
 function Cors(config = {}) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const defaultConfig = {
             origin: '*',
             optionsSuccessStatus: 204,
@@ -47,7 +50,7 @@ function Cors(config = {}) {
         };
         const finalConfig = { ...defaultConfig, ...config };
         const data = [{ cors: finalConfig }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/cors.js.map

@@ -1 +1 @@
-{"version":3,"file":"cors.js","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":";;AAsCA,oBAkBC;AAvDD,gDAAoD;AACpD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,SAAgB,IAAI,CAAC,SAAqB,EAAE;IAC1C,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,aAAa,GAAe;YAChC,MAAM,EAAE,GAAG;YACX,oBAAoB,EAAE,GAAG;YACzB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,oBAAY,CAAC;SACnC,CAAC;QAEF,MAAM,WAAW,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;QAEpD,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QAErC,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":"cors.js","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":";;AAyCA,oBAkBC;AA1DD,gDAAoD;AACpD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,IAAI,CAAC,SAAqB,EAAE;IAC1C,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,aAAa,GAAe;YAChC,MAAM,EAAE,GAAG;YACX,oBAAoB,EAAE,GAAG;YACzB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,oBAAY,CAAC;SACnC,CAAC;QAEF,MAAM,WAAW,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;QAEpD,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QAErC,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/fingerprint.d.ts

@@ -1,5 +1,7 @@
 import type { FingerprintComponent } from '@heliosjs/core/types';
+/** Options for `@UseFingerprint`. */
 export interface UseFingerprintOptions {
+    /** Component set to hash for this scope, overriding the configured/default set. See {@link FingerprintComponent}. */
     components?: FingerprintComponent[];
 }
 /**

package/dist/fingerprint.js.map

@@ -1 +1 @@
-{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":";;AAoBA,wCAeC;AA/BD,gDAAsF;AAMtF;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,UAAU,GAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACnD,IAAA,+BAAuB,EAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACjD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9B,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;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":";;AAsBA,wCAeC;AAjCD,gDAAsF;AAQtF;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,UAAU,GAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACnD,IAAA,+BAAuB,EAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACjD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9B,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;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/guard.d.ts

@@ -1,45 +1,40 @@
 import type { GuardFunction, GuardInstance } from '@heliosjs/core/types';
 import { type GuardClass } from '@heliosjs/core/types';
 /**
- * Decorator to register a guard.
- *
- * Guards are used to control access to a controller by validating
- * incoming requests before they reach route handlers. If a guard
- * returns `false`, the request is blocked.
- *
- * @param guard - A guard class or function used to determine whether
- * the request is allowed to proceed.
- *
- * @returns A class decorator that attaches guard metadata to the target.
+ * Registers a guard on a controller class or a single route method. Guards run
+ * before pipes, middlewares, and the handler; use them for authentication and
+ * authorization checks.
+ *
+ * A guard grants access by returning `true` and denies by returning `false` or a
+ * `string`. On denial the request is rejected with `ForbiddenError` (HTTP 403);
+ * a returned string becomes the error message (falling back to
+ * `guard.message`, then `"Forbidden"`). Guards may be async.
+ *
+ * @param guard - One of:
+ *   - a **function** `(req, res) => boolean | string | Promise<boolean | string>`;
+ *   - a **class** with a `canActivate(req, res)` method (instantiated per request,
+ *     may expose a `message` property for the denial text);
+ *   - an already-constructed **instance** with `canActivate` (and optional
+ *     `message`).
+ *   Why: pick the lightest form — a closure for simple checks, a class when the
+ *   guard needs its own dependencies.
+ *
+ * @returns A class or method decorator.
  *
  * @example
- * // Using function guard
- * @GuardClass((req, res) => {
- *   return !!req.headers.authorization;
- * })
- * class MyController {}
+ * @Guard((req) => !!req.getHeader('authorization') || 'Missing token')
+ * class SecureController {}
  *
- * @example
- * // Using class-based guard
- * class AuthGuard {
- *   canActivate(req: Request, res: Response) {
- *     return !!req.headers.authorization;
+ * class RoleGuard {
+ *   message = 'Admins only';
+ *   canActivate(req: Request) {
+ *     return req.getState('role') === 'admin';
  *   }
  * }
  *
- * @GuardClass(AuthGuard)
- * class MyController {}
- *
- * @remarks
- * Guards are executed before controller methods.
- * They can be used for:
- * - authentication
- * - authorization
- * - request validation
- *
- * If any guard returns `false`, the request handling is stopped.
- *
- * Metadata is stored under the CONTROLLER_CONFIGURATION key and used
- * internally by the framework during request processing.
+ * class AdminController {
+ *   @Guard(RoleGuard)
+ *   deleteEverything() {}
+ * }
  */
-export declare function Guard(guard: GuardClass | GuardFunction | GuardInstance): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Guard(guard: GuardClass | GuardFunction | GuardInstance): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/guard.js

@@ -3,51 +3,46 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Guard = Guard;
 const utils_1 = require("@heliosjs/core/utils");
 /**
- * Decorator to register a guard.
- *
- * Guards are used to control access to a controller by validating
- * incoming requests before they reach route handlers. If a guard
- * returns `false`, the request is blocked.
- *
- * @param guard - A guard class or function used to determine whether
- * the request is allowed to proceed.
- *
- * @returns A class decorator that attaches guard metadata to the target.
+ * Registers a guard on a controller class or a single route method. Guards run
+ * before pipes, middlewares, and the handler; use them for authentication and
+ * authorization checks.
+ *
+ * A guard grants access by returning `true` and denies by returning `false` or a
+ * `string`. On denial the request is rejected with `ForbiddenError` (HTTP 403);
+ * a returned string becomes the error message (falling back to
+ * `guard.message`, then `"Forbidden"`). Guards may be async.
+ *
+ * @param guard - One of:
+ *   - a **function** `(req, res) => boolean | string | Promise<boolean | string>`;
+ *   - a **class** with a `canActivate(req, res)` method (instantiated per request,
+ *     may expose a `message` property for the denial text);
+ *   - an already-constructed **instance** with `canActivate` (and optional
+ *     `message`).
+ *   Why: pick the lightest form — a closure for simple checks, a class when the
+ *   guard needs its own dependencies.
+ *
+ * @returns A class or method decorator.
  *
  * @example
- * // Using function guard
- * @GuardClass((req, res) => {
- *   return !!req.headers.authorization;
- * })
- * class MyController {}
+ * @Guard((req) => !!req.getHeader('authorization') || 'Missing token')
+ * class SecureController {}
  *
- * @example
- * // Using class-based guard
- * class AuthGuard {
- *   canActivate(req: Request, res: Response) {
- *     return !!req.headers.authorization;
+ * class RoleGuard {
+ *   message = 'Admins only';
+ *   canActivate(req: Request) {
+ *     return req.getState('role') === 'admin';
  *   }
  * }
  *
- * @GuardClass(AuthGuard)
- * class MyController {}
- *
- * @remarks
- * Guards are executed before controller methods.
- * They can be used for:
- * - authentication
- * - authorization
- * - request validation
- *
- * If any guard returns `false`, the request handling is stopped.
- *
- * Metadata is stored under the CONTROLLER_CONFIGURATION key and used
- * internally by the framework during request processing.
+ * class AdminController {
+ *   @Guard(RoleGuard)
+ *   deleteEverything() {}
+ * }
  */
 function Guard(guard) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const data = [{ guard: guard }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":";;AA6CA,sBAUC;AArDD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,KAAK,CAAC,KAAiD;IACrE,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAEhC,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":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":";;AAwCA,sBAUC;AAhDD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,SAAgB,KAAK,CAAC,KAAiD;IACrE,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAEhC,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/interceptor.d.ts

@@ -2,37 +2,33 @@ import type { InterceptorCB } from '@heliosjs/core/types';
 /**
  * Decorator to register an interceptor at the controller or method level.
  *
- * Interceptors are functions that wrap the execution of a route handler.
- * They can run logic before after the handler is executed, allowing
- * you to modify  responses, or handle cross-cutting concerns.
+ * An interceptor runs *after* the route handler. It receives the value the
+ * handler returned and whatever it returns becomes the new response payload,
+ * so it is the place for response shaping, wrapping, or caching.
  *
- * @param handler - Interceptor callback function.
+ * Signature: `(data, req, res) => newData` (may be async). Interceptors run
+ * regardless of whether the handler returned a value, including `undefined`.
+ *
+ * @param interceptor - `(data, req, res) => newData` callback.
  *
  * @returns A decorator that attaches interceptor metadata to the target
  * (either a class or a method).
  *
  * @example
- * // Logging interceptor
- * @Intercept(async (ctx, next) => {
- *   console.log('Before');
- *   const result = await next();
- *   console.log('After');
- *   return result;
- * })
+ * // Wrap every response body
+ * @Intercept((data) => ({ data, timestamp: Date.now() }))
  * class MyController {}
  *
  * @example
  * // Method-level interceptor
  * class MyController {
- *   @Intercept(async (ctx, next) => {
- *     return next();
- *   })
+ *   @Intercept(async (data, req) => ({ ...data, path: req.path }))
  *   getData() {}
  * }
  *
  * @remarks
- * - Interceptors can modify the result returned by the handler.
- * - They are executed in the order they are applied.
+ * - Interceptors replace the result returned by the handler.
+ * - Multiple interceptors run in reverse order (the one nearest the handler first).
  * - Can be used for:
  *   - logging
  *   - response transformation
@@ -42,4 +38,4 @@ import type { InterceptorCB } from '@heliosjs/core/types';
  * Metadata is stored using the MIDDLEWARES_CONFIG key and
  * used internally by the framework during request processing.
  */
-export declare function Intercept(interceptor: InterceptorCB): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Intercept(interceptor: InterceptorCB): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => void;

package/dist/interceptor.js

@@ -5,37 +5,33 @@ const utils_1 = require("@heliosjs/core/utils");
 /**
  * Decorator to register an interceptor at the controller or method level.
  *
- * Interceptors are functions that wrap the execution of a route handler.
- * They can run logic before after the handler is executed, allowing
- * you to modify  responses, or handle cross-cutting concerns.
+ * An interceptor runs *after* the route handler. It receives the value the
+ * handler returned and whatever it returns becomes the new response payload,
+ * so it is the place for response shaping, wrapping, or caching.
  *
- * @param handler - Interceptor callback function.
+ * Signature: `(data, req, res) => newData` (may be async). Interceptors run
+ * regardless of whether the handler returned a value, including `undefined`.
+ *
+ * @param interceptor - `(data, req, res) => newData` callback.
  *
  * @returns A decorator that attaches interceptor metadata to the target
  * (either a class or a method).
  *
  * @example
- * // Logging interceptor
- * @Intercept(async (ctx, next) => {
- *   console.log('Before');
- *   const result = await next();
- *   console.log('After');
- *   return result;
- * })
+ * // Wrap every response body
+ * @Intercept((data) => ({ data, timestamp: Date.now() }))
  * class MyController {}
  *
  * @example
  * // Method-level interceptor
  * class MyController {
- *   @Intercept(async (ctx, next) => {
- *     return next();
- *   })
+ *   @Intercept(async (data, req) => ({ ...data, path: req.path }))
  *   getData() {}
  * }
  *
  * @remarks
- * - Interceptors can modify the result returned by the handler.
- * - They are executed in the order they are applied.
+ * - Interceptors replace the result returned by the handler.
+ * - Multiple interceptors run in reverse order (the one nearest the handler first).
  * - Can be used for:
  *   - logging
  *   - response transformation
@@ -46,9 +42,9 @@ const utils_1 = require("@heliosjs/core/utils");
  * used internally by the framework during request processing.
  */
 function Intercept(interceptor) {
-    return function (target, propertyKey, descriptor) {
+    return function (target, propertyKey, _descriptor) {
         const data = [{ interceptor }];
-        if (descriptor) {
+        if (propertyKey) {
             (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
         }
         else {

package/dist/interceptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.js","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":";;AA6CA,8BAUC;AAtDD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,SAAgB,SAAS,CAAC,WAA0B;IAClD,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,UAA+B;QACjF,MAAM,IAAI,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAE/B,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":"interceptor.js","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":";;AAyCA,8BAUC;AAlDD,gDAA6D;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,SAAS,CAAC,WAA0B;IAClD,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAE/B,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"}