@hemia/common 0.0.2 → 0.0.4

package/dist/hemia-common.esm.js

@@ -5,7 +5,13 @@ const METADATA_KEYS = {
     ROUTES: 'routes',
     PARAMS: 'params',
     HEADERS: 'headers',
-    REDIRECT: 'redirect'
+    REDIRECT: 'redirect',
+    GUARDS: 'hemia:guards',
+    INTERCEPTORS: 'hemia:interceptors',
+    CUSTOM: 'hemia:custom',
+    SERIALIZE: 'hemia:serialize',
+    ROLES: 'hemia:roles',
+    PERMISSIONS: 'hemia:permissions'
 };
 
 const Controller = (basePath = '/') => {
@@ -94,6 +100,87 @@ const Redirect = (url, statusCode = 302) => {
     };
 };
 
+function extendArrayMetadata(key, metadata, target) {
+    const previousValue = Reflect.getMetadata(key, target) || [];
+    const value = [...previousValue, ...metadata];
+    Reflect.defineMetadata(key, value, target);
+}
+
+/**
+ * Decorador que vincula Guards al controlador o método.
+ * @param guards Una lista de clases Guard o instancias de Guard.
+ */
+function UseGuards(...guards) {
+    return (target, key, descriptor) => {
+        guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.GUARDS, guards, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.GUARDS, guards, target);
+        return target;
+    };
+}
+
+/**
+ * Decorador que vincula Interceptores al controlador o método.
+ * @param interceptors Una lista de clases Interceptor o instancias.
+ */
+function UseInterceptors(...interceptors) {
+    return (target, key, descriptor) => {
+        const validInterceptors = interceptors.filter(i => i && (typeof i === 'function' || typeof i === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, target);
+        return target;
+    };
+}
+
+/**
+ * Decorador que asigna metadata personalizada a una clase o método.
+ * @param metadataKey La clave para guardar la metadata (string, symbol, etc.)
+ * @param metadataValue El valor a guardar (objeto, array, primitivo, etc.)
+ */
+const SetMetadata = (metadataKey, metadataValue) => {
+    return (target, key, descriptor) => {
+        if (descriptor) {
+            Reflect.defineMetadata(metadataKey, metadataValue, descriptor.value);
+            return descriptor;
+        }
+        Reflect.defineMetadata(metadataKey, metadataValue, target);
+        return target;
+    };
+};
+
+/**
+ * Decorador que transforma la respuesta saliente a una instancia del DTO proporcionado.
+ * @param dto La clase DTO a la que quieres convertir la respuesta.
+ */
+function Serialize(dto) {
+    return SetMetadata(METADATA_KEYS.SERIALIZE, dto);
+}
+
+class ApiResponse {
+    static success(data, message = 'OK', status = 200) {
+        return {
+            success: true,
+            message,
+            data,
+            status,
+        };
+    }
+    static error(message, error = null, status = 500) {
+        return {
+            success: false,
+            message,
+            error,
+            status,
+        };
+    }
+}
+
 function isRedirectResponse(value) {
     return value && typeof value === 'object' && typeof value.url === 'string';
 }
@@ -163,4 +250,4 @@ class HttpErrorWithDetails extends HttpError {
     }
 }
 
-export { BadRequestError, Body, ConflictError, Controller, CustomHttpError, Delete, ForbiddenError, GatewayTimeoutError, Get, Head, Header, Headers, Host, HttpError, HttpErrorWithDetails, HttpMethod, InternalServerError, Ip, METADATA_KEYS, Next, NotFoundError, Options, Param, ParamType, Patch, Post, Put, Query, Redirect, Req, Request, Res, Response, ServiceUnavailableError, Session, UnauthorizedError, UnprocessableEntityError, isRedirectResponse };
+export { ApiResponse, BadRequestError, Body, ConflictError, Controller, CustomHttpError, Delete, ForbiddenError, GatewayTimeoutError, Get, Head, Header, Headers, Host, HttpError, HttpErrorWithDetails, HttpMethod, InternalServerError, Ip, METADATA_KEYS, Next, NotFoundError, Options, Param, ParamType, Patch, Post, Put, Query, Redirect, Req, Request, Res, Response, Serialize, ServiceUnavailableError, Session, SetMetadata, UnauthorizedError, UnprocessableEntityError, UseGuards, UseInterceptors, isRedirectResponse };

package/dist/hemia-common.js

@@ -7,7 +7,13 @@ const METADATA_KEYS = {
     ROUTES: 'routes',
     PARAMS: 'params',
     HEADERS: 'headers',
-    REDIRECT: 'redirect'
+    REDIRECT: 'redirect',
+    GUARDS: 'hemia:guards',
+    INTERCEPTORS: 'hemia:interceptors',
+    CUSTOM: 'hemia:custom',
+    SERIALIZE: 'hemia:serialize',
+    ROLES: 'hemia:roles',
+    PERMISSIONS: 'hemia:permissions'
 };
 
 const Controller = (basePath = '/') => {
@@ -96,6 +102,87 @@ const Redirect = (url, statusCode = 302) => {
     };
 };
 
+function extendArrayMetadata(key, metadata, target) {
+    const previousValue = Reflect.getMetadata(key, target) || [];
+    const value = [...previousValue, ...metadata];
+    Reflect.defineMetadata(key, value, target);
+}
+
+/**
+ * Decorador que vincula Guards al controlador o método.
+ * @param guards Una lista de clases Guard o instancias de Guard.
+ */
+function UseGuards(...guards) {
+    return (target, key, descriptor) => {
+        guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.GUARDS, guards, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.GUARDS, guards, target);
+        return target;
+    };
+}
+
+/**
+ * Decorador que vincula Interceptores al controlador o método.
+ * @param interceptors Una lista de clases Interceptor o instancias.
+ */
+function UseInterceptors(...interceptors) {
+    return (target, key, descriptor) => {
+        const validInterceptors = interceptors.filter(i => i && (typeof i === 'function' || typeof i === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, target);
+        return target;
+    };
+}
+
+/**
+ * Decorador que asigna metadata personalizada a una clase o método.
+ * @param metadataKey La clave para guardar la metadata (string, symbol, etc.)
+ * @param metadataValue El valor a guardar (objeto, array, primitivo, etc.)
+ */
+const SetMetadata = (metadataKey, metadataValue) => {
+    return (target, key, descriptor) => {
+        if (descriptor) {
+            Reflect.defineMetadata(metadataKey, metadataValue, descriptor.value);
+            return descriptor;
+        }
+        Reflect.defineMetadata(metadataKey, metadataValue, target);
+        return target;
+    };
+};
+
+/**
+ * Decorador que transforma la respuesta saliente a una instancia del DTO proporcionado.
+ * @param dto La clase DTO a la que quieres convertir la respuesta.
+ */
+function Serialize(dto) {
+    return SetMetadata(METADATA_KEYS.SERIALIZE, dto);
+}
+
+class ApiResponse {
+    static success(data, message = 'OK', status = 200) {
+        return {
+            success: true,
+            message,
+            data,
+            status,
+        };
+    }
+    static error(message, error = null, status = 500) {
+        return {
+            success: false,
+            message,
+            error,
+            status,
+        };
+    }
+}
+
 function isRedirectResponse(value) {
     return value && typeof value === 'object' && typeof value.url === 'string';
 }
@@ -165,6 +252,7 @@ class HttpErrorWithDetails extends HttpError {
     }
 }
 
+exports.ApiResponse = ApiResponse;
 exports.BadRequestError = BadRequestError;
 exports.Body = Body;
 exports.ConflictError = ConflictError;
@@ -196,8 +284,12 @@ exports.Req = Req;
 exports.Request = Request;
 exports.Res = Res;
 exports.Response = Response;
+exports.Serialize = Serialize;
 exports.ServiceUnavailableError = ServiceUnavailableError;
 exports.Session = Session;
+exports.SetMetadata = SetMetadata;
 exports.UnauthorizedError = UnauthorizedError;
 exports.UnprocessableEntityError = UnprocessableEntityError;
+exports.UseGuards = UseGuards;
+exports.UseInterceptors = UseInterceptors;
 exports.isRedirectResponse = isRedirectResponse;

package/dist/types/decorators/auth/index.d.ts

@@ -0,0 +1,2 @@
+export * from './roles.decorator';
+export * from './permissions.decorator';

package/dist/types/decorators/auth/permissions.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Define los permisos específicos requeridos para acceder a un recurso.
+ * @param permissions Lista de permisos (ej: 'read:users', 'write:posts')
+ */
+export declare const Permissions: (...permissions: string[]) => (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/auth/roles.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Define los roles requeridos para acceder a un recurso.
+ * @param roles Lista de roles (ej: 'admin', 'user')
+ */
+export declare const Roles: (...roles: string[]) => (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./use-guards.decorator";
+export * from "./use-interceptors.decorator";
+export * from "./set-metadata.decorator";
+export * from "./serialize.decorator";

package/dist/types/decorators/core/serialize.decorator.d.ts

@@ -0,0 +1,9 @@
+import { Type } from "../../interfaces";
+export interface SerializeOptions {
+    excludeExtraneousValues?: boolean;
+}
+/**
+ * Decorador que transforma la respuesta saliente a una instancia del DTO proporcionado.
+ * @param dto La clase DTO a la que quieres convertir la respuesta.
+ */
+export declare function Serialize(dto: Type<any>): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/core/set-metadata.decorator.d.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+/**
+ * Decorador que asigna metadata personalizada a una clase o método.
+ * @param metadataKey La clave para guardar la metadata (string, symbol, etc.)
+ * @param metadataValue El valor a guardar (objeto, array, primitivo, etc.)
+ */
+export declare const SetMetadata: <K = string | symbol, V = any>(metadataKey: K, metadataValue: V) => (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/core/use-guards.decorator.d.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+import { CanActivate, Type } from '../../interfaces';
+/**
+ * Decorador que vincula Guards al controlador o método.
+ * @param guards Una lista de clases Guard o instancias de Guard.
+ */
+export declare function UseGuards(...guards: (Type<CanActivate> | CanActivate | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/core/use-interceptors.decorator.d.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+import { HemiaInterceptor, Type } from '../../interfaces';
+/**
+ * Decorador que vincula Interceptores al controlador o método.
+ * @param interceptors Una lista de clases Interceptor o instancias.
+ */
+export declare function UseInterceptors(...interceptors: (Type<HemiaInterceptor> | HemiaInterceptor | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;

package/dist/types/decorators/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./controllers";
+export * from "./http";
 export * from "./metadata";
+export * from "./core";

package/dist/types/decorators/metadata.d.ts

@@ -4,4 +4,10 @@ export declare const METADATA_KEYS: {
     readonly PARAMS: "params";
     readonly HEADERS: "headers";
     readonly REDIRECT: "redirect";
+    readonly GUARDS: "hemia:guards";
+    readonly INTERCEPTORS: "hemia:interceptors";
+    readonly CUSTOM: "hemia:custom";
+    readonly SERIALIZE: "hemia:serialize";
+    readonly ROLES: "hemia:roles";
+    readonly PERMISSIONS: "hemia:permissions";
 };

package/dist/types/decorators/utils/extend-metadata.util.d.ts

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+export declare function extendArrayMetadata<T>(key: string, metadata: T[], target: object | Function): void;

package/dist/types/interfaces/activate.interface.d.ts

@@ -0,0 +1,4 @@
+import { ExecutionContext } from "./features/execution-context.interface";
+export interface CanActivate {
+    canActivate(context: ExecutionContext): boolean | Promise<boolean>;
+}

package/dist/types/interfaces/api-response.interface.d.ts

@@ -0,0 +1,13 @@
+export interface IResponseData<T> {
+    success: boolean;
+    data?: T;
+    message: string;
+    error?: any;
+}
+export interface IApiResponse<T> extends IResponseData<T> {
+    status: number;
+}
+export declare class ApiResponse {
+    static success<T>(data: T, message?: string, status?: number): IApiResponse<T>;
+    static error(message: string, error?: any, status?: number): IApiResponse<null>;
+}

package/dist/types/interfaces/features/arguments-host.interface.d.ts

@@ -0,0 +1,18 @@
+export interface HttpArgumentsHost {
+    /** Retorna el objeto Request nativo (Express) */
+    getRequest<T = any>(): T;
+    /** Retorna el objeto Response nativo (Express) */
+    getResponse<T = any>(): T;
+    /** Retorna la función Next nativa (Express) */
+    getNext<T = any>(): T;
+}
+export interface ArgumentsHost {
+    /** Retorna el array de argumentos original [req, res, next] */
+    getArgs<T extends Array<any> = any[]>(): T;
+    /** Retorna un argumento específico por índice */
+    getArgByIndex<T = any>(index: number): T;
+    /** Cambia el contexto a HTTP para obtener métodos tipados */
+    switchToHttp(): HttpArgumentsHost;
+    /** Retorna el tipo de contexto actual (ej: 'http') */
+    getType<TContext extends string = string>(): TContext;
+}

package/dist/types/interfaces/features/execution-context.interface.d.ts

@@ -0,0 +1,14 @@
+import { Type } from "../type.interface";
+import { ArgumentsHost } from "./arguments-host.interface";
+export interface ExecutionContext extends ArgumentsHost {
+    /**
+     * Retorna la CLASE (Constructor) del controlador que se está ejecutando.
+     * Útil para leer metadata a nivel de clase (ej. @Roles('admin') sobre la clase)
+     */
+    getClass<T = any>(): Type<T>;
+    /**
+     * Retorna la FUNCIÓN (Método) del handler que se está ejecutando.
+     * Útil para leer metadata a nivel de método (ej. @Public() sobre el método)
+     */
+    getHandler(): Function;
+}

package/dist/types/interfaces/handler.interface.d.ts

@@ -0,0 +1,3 @@
+export interface CallHandler<T = any> {
+    handle(): Promise<T>;
+}

package/dist/types/interfaces/index.d.ts

@@ -1,2 +1,9 @@
 export * from './param.interface';
 export * from './route.interface';
+export * from './api-response.interface';
+export * from './activate.interface';
+export * from './features/execution-context.interface';
+export * from "./features/arguments-host.interface";
+export * from './type.interface';
+export * from './handler.interface';
+export * from './interceptor.interface';

package/dist/types/interfaces/interceptor.interface.d.ts

@@ -0,0 +1,5 @@
+import { ExecutionContext } from "./features/execution-context.interface";
+import { CallHandler } from "./handler.interface";
+export interface HemiaInterceptor<T = any, R = any> {
+    intercept(context: ExecutionContext, next: CallHandler<T>): Promise<R>;
+}

package/dist/types/interfaces/type.interface.d.ts

@@ -0,0 +1 @@
+export type Type<T = any> = new (...args: any[]) => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hemia/common",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Paquete común para proyectos de Hemia",
   "main": "dist/hemia-common.js",
   "module": "dist/hemia-common.esm.js",