@hemia/core 0.0.1

package/README.md

@@ -0,0 +1,36 @@
+
+# hemia-core
+
+**@hemia/hemia-core**  
+Paquete generado con [Hemia CLI](https://www.npmjs.com/package/@hemia/cli)
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install @hemia/hemia-core
+```
+
+---
+
+## 🛠️ Scripts disponibles
+
+| Script       | Descripción                      |
+|--------------|----------------------------------|
+| `npm run build`   | Compila el paquete con Rollup     |
+| `npm run test`    | Ejecuta pruebas con Jest         |
+| `npm run clean`   | Limpia la carpeta `dist/`       |
+
+---
+
+## 🔍 Archivos generados
+
+- `dist/hemia-core.js`
+- `dist/hemia-core.esm.js`
+- `dist/types/`
+
+---
+
+## ✨ Generado con Hemia CLI
+    

package/dist/hemia-core.esm.js

@@ -0,0 +1,319 @@
+import 'reflect-metadata';
+import express, { Router } from 'express';
+import { METADATA_KEYS, ParamType, isRedirectResponse, ApiResponse } from '@hemia/common';
+import { TRACE_METADATA_KEY } from '@hemia/trace-manager';
+import { traceMiddleware } from '@hemia/app-context';
+import { plainToInstance } from 'class-transformer';
+import { injectable } from 'inversify';
+
+class GuardsConsumer {
+    /**
+     * Ejecuta una lista de guards secuencialmente.
+     * Lanza error si alguno falla.
+     */
+    static async tryActivate(guards, context, container) {
+        if (!guards || guards.length === 0)
+            return;
+        for (const GuardClass of guards) {
+            let guardInstance;
+            if (container.isBound(GuardClass)) {
+                guardInstance = await container.getAsync(GuardClass);
+            }
+            else {
+                container.bind(GuardClass).toSelf().inTransientScope();
+                guardInstance = await container.getAsync(GuardClass);
+            }
+            const canActivate = await guardInstance.canActivate(context);
+            if (!canActivate) {
+                const error = new Error('Forbidden resource');
+                error.statusCode = 403;
+                throw error;
+            }
+        }
+    }
+}
+
+class HemiaExecutionContext {
+    constructor(args, constructorRef, handler, contextType = 'http') {
+        this.args = args;
+        this.constructorRef = constructorRef;
+        this.handler = handler;
+        this.contextType = contextType;
+    }
+    getType() {
+        return this.contextType;
+    }
+    getArgs() {
+        return this.args;
+    }
+    getArgByIndex(index) {
+        return this.args[index];
+    }
+    switchToHttp() {
+        return {
+            getRequest: () => this.args[0],
+            getResponse: () => this.args[1],
+            getNext: () => this.args[2],
+        };
+    }
+    getClass() {
+        return this.constructorRef;
+    }
+    getHandler() {
+        return this.handler;
+    }
+}
+
+class ResponseSerializer {
+    static transform(entityOrArray, dto) {
+        return plainToInstance(dto, entityOrArray, {
+            excludeExtraneousValues: true,
+            enableImplicitConversion: true,
+        });
+    }
+}
+
+/**
+ * Registra los controladores resolviéndolos desde el contenedor de Inversify.
+ * @param app Instancia de Express
+ * @param container Instancia del Container de Inversify
+ * @param controllerIdentifiers Array de Symbols (o Clases si usas self-binding)
+ */
+async function registerRoutes(app, container, controllerIdentifiers, onTraceFinishCallback) {
+    for (const identifier of controllerIdentifiers) {
+        const instance = await container.getAsync(identifier);
+        const prototype = Object.getPrototypeOf(instance);
+        const ControllerClass = instance.constructor;
+        const basePath = Reflect.getMetadata(METADATA_KEYS.BASE_PATH, ControllerClass) || '/';
+        const routes = Reflect.getMetadata(METADATA_KEYS.ROUTES, ControllerClass) || [];
+        const expressRouter = Router();
+        routes.forEach((route) => {
+            const methodHandler = instance[route.methodName];
+            const traceOptions = Reflect.getMetadata(TRACE_METADATA_KEY, prototype, route.methodName);
+            const handlers = [];
+            if (traceOptions) {
+                handlers.push(traceMiddleware(traceOptions.name || ControllerClass.name || 'UnnamedController', traceOptions.kind || route.methodName, onTraceFinishCallback, undefined, traceOptions.tags));
+            }
+            const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, ControllerClass) || [];
+            const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, methodHandler) || [];
+            const allGuards = [...classGuards, ...methodGuards];
+            const paramsMetadata = Reflect.getMetadata(METADATA_KEYS.PARAMS, instance, route.methodName) || [];
+            // Leer metadata de headers y redirect
+            const headersMetadata = Reflect.getMetadata(METADATA_KEYS.HEADERS, ControllerClass, route.methodName) || [];
+            const redirectMetadata = Reflect.getMetadata(METADATA_KEYS.REDIRECT, ControllerClass, route.methodName);
+            const mainHandler = async (req, res, next) => {
+                try {
+                    const args = [];
+                    const executionContext = new HemiaExecutionContext([req, res, next], ControllerClass, methodHandler);
+                    await GuardsConsumer.tryActivate(allGuards, executionContext, container);
+                    if (paramsMetadata.length === 0) {
+                        args.push(req, res, next);
+                    }
+                    else {
+                        paramsMetadata.sort((a, b) => a.index - b.index);
+                        paramsMetadata.forEach((param) => {
+                            switch (param.type) {
+                                case ParamType.REQUEST:
+                                    args[param.index] = req;
+                                    break;
+                                case ParamType.RESPONSE:
+                                    args[param.index] = res;
+                                    break;
+                                case ParamType.NEXT:
+                                    args[param.index] = next;
+                                    break;
+                                case ParamType.BODY:
+                                    args[param.index] = param.data ? req.body?.[param.data] : req.body;
+                                    break;
+                                case ParamType.QUERY:
+                                    args[param.index] = param.data ? req.query?.[param.data] : req.query;
+                                    break;
+                                case ParamType.PARAM:
+                                    args[param.index] = param.data ? req.params?.[param.data] : req.params;
+                                    break;
+                                case ParamType.HEADERS:
+                                    args[param.index] = param.data ? req.headers?.[param.data.toLowerCase()] : req.headers;
+                                    break;
+                                case ParamType.SESSION:
+                                    args[param.index] = req.session;
+                                    break;
+                                default: args[param.index] = undefined;
+                            }
+                        });
+                    }
+                    const result = await instance[route.methodName](...args);
+                    const serializeDto = Reflect.getMetadata(METADATA_KEYS.SERIALIZE, methodHandler) || Reflect.getMetadata(METADATA_KEYS.SERIALIZE, ControllerClass);
+                    let finalResult = result;
+                    if (serializeDto) {
+                        finalResult = ResponseSerializer.transform(result, serializeDto);
+                    }
+                    if (headersMetadata.length > 0) {
+                        headersMetadata.forEach((header) => {
+                            res.setHeader(header.name, header.value);
+                        });
+                    }
+                    if (isRedirectResponse(result)) {
+                        const statusCode = result.statusCode || redirectMetadata?.statusCode || 302;
+                        return res.redirect(statusCode, result.url);
+                    }
+                    if (redirectMetadata) {
+                        return res.redirect(redirectMetadata.statusCode, redirectMetadata.url);
+                    }
+                    if (!res.headersSent) {
+                        const response = ApiResponse.success(finalResult);
+                        const { status, ...responseData } = response;
+                        res.status(status).json(responseData);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error en ${route.method.toUpperCase()} ${basePath}${route.path}:`, error);
+                    const status = error.statusCode || error.status || 500;
+                    const message = error.message || 'Internal Server Error';
+                    const errorResponse = ApiResponse.error(message, error.stack, status);
+                    const { status: errStatus, ...errorData } = errorResponse;
+                    res.status(errStatus).json(errorData);
+                }
+            };
+            handlers.push(mainHandler);
+            const method = route.method;
+            expressRouter[method](route.path, ...handlers);
+        });
+        app.use(basePath, expressRouter);
+    }
+}
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+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;
+}
+
+function __metadata(metadataKey, metadataValue) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+let Reflector = class Reflector {
+    /**
+     * Obtiene metadata de una clase o un método
+     */
+    get(metadataKey, target) {
+        return Reflect.getMetadata(metadataKey, target);
+    }
+    /**
+     * Obtiene metadata con prioridad: Método > Clase.
+     * Si el método tiene metadata, retorna esa. Si no, busca en la clase.
+     * @param metadataKey La clave de la metadata.
+     * @param targets Tupla con [Handler (Método), Class (Controlador)].
+     */
+    getAllAndOverride(metadataKey, targets) {
+        const [methodHandler, controllerClass] = targets;
+        const methodMetadata = Reflect.getMetadata(metadataKey, methodHandler);
+        if (methodMetadata !== undefined) {
+            return methodMetadata;
+        }
+        return Reflect.getMetadata(metadataKey, controllerClass);
+    }
+    /**
+     * Obtiene metadata combinada (merge) de Método y Clase (opcional, útil para arrays acumulativos)
+     */
+    getAllAndMerge(metadataKey, targets) {
+        const [methodHandler, controllerClass] = targets;
+        const methodMetadata = Reflect.getMetadata(metadataKey, methodHandler) || [];
+        const classMetadata = Reflect.getMetadata(metadataKey, controllerClass) || [];
+        return [...classMetadata, ...methodMetadata];
+    }
+};
+Reflector = __decorate([
+    injectable()
+], Reflector);
+
+class HemiaFactory {
+    /**
+     * Inicializa la aplicación Hemia conectando Express con Inversify.
+     * @param container El contenedor de Inversify con tus servicios ya bindeados.
+     * @param controllers Lista de Clases de Controladores a registrar.
+     * @param options Opciones de configuración.
+     */
+    static async create(container, controllers, options = {}) {
+        const app = express();
+        app.use(express.json());
+        app.use(express.urlencoded({ extended: true }));
+        if (!container.isBound(Reflector)) {
+            container.bind(Reflector).toSelf().inSingletonScope();
+        }
+        controllers.forEach(controllerClass => {
+            if (!container.isBound(controllerClass)) {
+                container.bind(controllerClass).toSelf();
+            }
+        });
+        await registerRoutes(app, container, controllers, options.onTraceFinish || (() => { }));
+        if (options.logger !== false) {
+            console.log(`[Hemia] Application initialized with ${controllers.length} controllers.`);
+        }
+        return app;
+    }
+}
+
+let AuthGuard = class AuthGuard {
+    constructor(reflector) {
+        this.reflector = reflector;
+    }
+    canActivate(context) {
+        const targets = [
+            context.getHandler(),
+            context.getClass()
+        ];
+        const requiredRoles = this.reflector.getAllAndOverride(METADATA_KEYS.ROLES, targets);
+        const requiredPermissions = this.reflector.getAllAndOverride(METADATA_KEYS.PERMISSIONS, targets);
+        if (!requiredRoles && !requiredPermissions) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const user = request.user;
+        if (!user || !user.roles) {
+            return false;
+        }
+        if (requiredRoles) {
+            const userRoleNames = user.roles.map((r) => r.name);
+            const hasRole = requiredRoles.some((role) => userRoleNames.includes(role));
+            if (!hasRole)
+                return false;
+        }
+        if (requiredPermissions) {
+            const userPermissions = user.roles.flatMap((r) => r.permissions || []);
+            const hasPermission = requiredPermissions.some((perm) => userPermissions.includes(perm));
+            if (!hasPermission)
+                return false;
+        }
+        return true;
+    }
+};
+AuthGuard = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [Reflector])
+], AuthGuard);
+
+export { AuthGuard, GuardsConsumer, HemiaExecutionContext, HemiaFactory, Reflector, ResponseSerializer, registerRoutes };

package/dist/hemia-core.js

@@ -0,0 +1,325 @@
+'use strict';
+
+require('reflect-metadata');
+var express = require('express');
+var common = require('@hemia/common');
+var traceManager = require('@hemia/trace-manager');
+var appContext = require('@hemia/app-context');
+var classTransformer = require('class-transformer');
+var inversify = require('inversify');
+
+class GuardsConsumer {
+    /**
+     * Ejecuta una lista de guards secuencialmente.
+     * Lanza error si alguno falla.
+     */
+    static async tryActivate(guards, context, container) {
+        if (!guards || guards.length === 0)
+            return;
+        for (const GuardClass of guards) {
+            let guardInstance;
+            if (container.isBound(GuardClass)) {
+                guardInstance = await container.getAsync(GuardClass);
+            }
+            else {
+                container.bind(GuardClass).toSelf().inTransientScope();
+                guardInstance = await container.getAsync(GuardClass);
+            }
+            const canActivate = await guardInstance.canActivate(context);
+            if (!canActivate) {
+                const error = new Error('Forbidden resource');
+                error.statusCode = 403;
+                throw error;
+            }
+        }
+    }
+}
+
+class HemiaExecutionContext {
+    constructor(args, constructorRef, handler, contextType = 'http') {
+        this.args = args;
+        this.constructorRef = constructorRef;
+        this.handler = handler;
+        this.contextType = contextType;
+    }
+    getType() {
+        return this.contextType;
+    }
+    getArgs() {
+        return this.args;
+    }
+    getArgByIndex(index) {
+        return this.args[index];
+    }
+    switchToHttp() {
+        return {
+            getRequest: () => this.args[0],
+            getResponse: () => this.args[1],
+            getNext: () => this.args[2],
+        };
+    }
+    getClass() {
+        return this.constructorRef;
+    }
+    getHandler() {
+        return this.handler;
+    }
+}
+
+class ResponseSerializer {
+    static transform(entityOrArray, dto) {
+        return classTransformer.plainToInstance(dto, entityOrArray, {
+            excludeExtraneousValues: true,
+            enableImplicitConversion: true,
+        });
+    }
+}
+
+/**
+ * Registra los controladores resolviéndolos desde el contenedor de Inversify.
+ * @param app Instancia de Express
+ * @param container Instancia del Container de Inversify
+ * @param controllerIdentifiers Array de Symbols (o Clases si usas self-binding)
+ */
+async function registerRoutes(app, container, controllerIdentifiers, onTraceFinishCallback) {
+    for (const identifier of controllerIdentifiers) {
+        const instance = await container.getAsync(identifier);
+        const prototype = Object.getPrototypeOf(instance);
+        const ControllerClass = instance.constructor;
+        const basePath = Reflect.getMetadata(common.METADATA_KEYS.BASE_PATH, ControllerClass) || '/';
+        const routes = Reflect.getMetadata(common.METADATA_KEYS.ROUTES, ControllerClass) || [];
+        const expressRouter = express.Router();
+        routes.forEach((route) => {
+            const methodHandler = instance[route.methodName];
+            const traceOptions = Reflect.getMetadata(traceManager.TRACE_METADATA_KEY, prototype, route.methodName);
+            const handlers = [];
+            if (traceOptions) {
+                handlers.push(appContext.traceMiddleware(traceOptions.name || ControllerClass.name || 'UnnamedController', traceOptions.kind || route.methodName, onTraceFinishCallback, undefined, traceOptions.tags));
+            }
+            const classGuards = Reflect.getMetadata(common.METADATA_KEYS.GUARDS, ControllerClass) || [];
+            const methodGuards = Reflect.getMetadata(common.METADATA_KEYS.GUARDS, methodHandler) || [];
+            const allGuards = [...classGuards, ...methodGuards];
+            const paramsMetadata = Reflect.getMetadata(common.METADATA_KEYS.PARAMS, instance, route.methodName) || [];
+            // Leer metadata de headers y redirect
+            const headersMetadata = Reflect.getMetadata(common.METADATA_KEYS.HEADERS, ControllerClass, route.methodName) || [];
+            const redirectMetadata = Reflect.getMetadata(common.METADATA_KEYS.REDIRECT, ControllerClass, route.methodName);
+            const mainHandler = async (req, res, next) => {
+                try {
+                    const args = [];
+                    const executionContext = new HemiaExecutionContext([req, res, next], ControllerClass, methodHandler);
+                    await GuardsConsumer.tryActivate(allGuards, executionContext, container);
+                    if (paramsMetadata.length === 0) {
+                        args.push(req, res, next);
+                    }
+                    else {
+                        paramsMetadata.sort((a, b) => a.index - b.index);
+                        paramsMetadata.forEach((param) => {
+                            switch (param.type) {
+                                case common.ParamType.REQUEST:
+                                    args[param.index] = req;
+                                    break;
+                                case common.ParamType.RESPONSE:
+                                    args[param.index] = res;
+                                    break;
+                                case common.ParamType.NEXT:
+                                    args[param.index] = next;
+                                    break;
+                                case common.ParamType.BODY:
+                                    args[param.index] = param.data ? req.body?.[param.data] : req.body;
+                                    break;
+                                case common.ParamType.QUERY:
+                                    args[param.index] = param.data ? req.query?.[param.data] : req.query;
+                                    break;
+                                case common.ParamType.PARAM:
+                                    args[param.index] = param.data ? req.params?.[param.data] : req.params;
+                                    break;
+                                case common.ParamType.HEADERS:
+                                    args[param.index] = param.data ? req.headers?.[param.data.toLowerCase()] : req.headers;
+                                    break;
+                                case common.ParamType.SESSION:
+                                    args[param.index] = req.session;
+                                    break;
+                                default: args[param.index] = undefined;
+                            }
+                        });
+                    }
+                    const result = await instance[route.methodName](...args);
+                    const serializeDto = Reflect.getMetadata(common.METADATA_KEYS.SERIALIZE, methodHandler) || Reflect.getMetadata(common.METADATA_KEYS.SERIALIZE, ControllerClass);
+                    let finalResult = result;
+                    if (serializeDto) {
+                        finalResult = ResponseSerializer.transform(result, serializeDto);
+                    }
+                    if (headersMetadata.length > 0) {
+                        headersMetadata.forEach((header) => {
+                            res.setHeader(header.name, header.value);
+                        });
+                    }
+                    if (common.isRedirectResponse(result)) {
+                        const statusCode = result.statusCode || redirectMetadata?.statusCode || 302;
+                        return res.redirect(statusCode, result.url);
+                    }
+                    if (redirectMetadata) {
+                        return res.redirect(redirectMetadata.statusCode, redirectMetadata.url);
+                    }
+                    if (!res.headersSent) {
+                        const response = common.ApiResponse.success(finalResult);
+                        const { status, ...responseData } = response;
+                        res.status(status).json(responseData);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error en ${route.method.toUpperCase()} ${basePath}${route.path}:`, error);
+                    const status = error.statusCode || error.status || 500;
+                    const message = error.message || 'Internal Server Error';
+                    const errorResponse = common.ApiResponse.error(message, error.stack, status);
+                    const { status: errStatus, ...errorData } = errorResponse;
+                    res.status(errStatus).json(errorData);
+                }
+            };
+            handlers.push(mainHandler);
+            const method = route.method;
+            expressRouter[method](route.path, ...handlers);
+        });
+        app.use(basePath, expressRouter);
+    }
+}
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+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;
+}
+
+function __metadata(metadataKey, metadataValue) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+exports.Reflector = class Reflector {
+    /**
+     * Obtiene metadata de una clase o un método
+     */
+    get(metadataKey, target) {
+        return Reflect.getMetadata(metadataKey, target);
+    }
+    /**
+     * Obtiene metadata con prioridad: Método > Clase.
+     * Si el método tiene metadata, retorna esa. Si no, busca en la clase.
+     * @param metadataKey La clave de la metadata.
+     * @param targets Tupla con [Handler (Método), Class (Controlador)].
+     */
+    getAllAndOverride(metadataKey, targets) {
+        const [methodHandler, controllerClass] = targets;
+        const methodMetadata = Reflect.getMetadata(metadataKey, methodHandler);
+        if (methodMetadata !== undefined) {
+            return methodMetadata;
+        }
+        return Reflect.getMetadata(metadataKey, controllerClass);
+    }
+    /**
+     * Obtiene metadata combinada (merge) de Método y Clase (opcional, útil para arrays acumulativos)
+     */
+    getAllAndMerge(metadataKey, targets) {
+        const [methodHandler, controllerClass] = targets;
+        const methodMetadata = Reflect.getMetadata(metadataKey, methodHandler) || [];
+        const classMetadata = Reflect.getMetadata(metadataKey, controllerClass) || [];
+        return [...classMetadata, ...methodMetadata];
+    }
+};
+exports.Reflector = __decorate([
+    inversify.injectable()
+], exports.Reflector);
+
+class HemiaFactory {
+    /**
+     * Inicializa la aplicación Hemia conectando Express con Inversify.
+     * @param container El contenedor de Inversify con tus servicios ya bindeados.
+     * @param controllers Lista de Clases de Controladores a registrar.
+     * @param options Opciones de configuración.
+     */
+    static async create(container, controllers, options = {}) {
+        const app = express();
+        app.use(express.json());
+        app.use(express.urlencoded({ extended: true }));
+        if (!container.isBound(exports.Reflector)) {
+            container.bind(exports.Reflector).toSelf().inSingletonScope();
+        }
+        controllers.forEach(controllerClass => {
+            if (!container.isBound(controllerClass)) {
+                container.bind(controllerClass).toSelf();
+            }
+        });
+        await registerRoutes(app, container, controllers, options.onTraceFinish || (() => { }));
+        if (options.logger !== false) {
+            console.log(`[Hemia] Application initialized with ${controllers.length} controllers.`);
+        }
+        return app;
+    }
+}
+
+exports.AuthGuard = class AuthGuard {
+    constructor(reflector) {
+        this.reflector = reflector;
+    }
+    canActivate(context) {
+        const targets = [
+            context.getHandler(),
+            context.getClass()
+        ];
+        const requiredRoles = this.reflector.getAllAndOverride(common.METADATA_KEYS.ROLES, targets);
+        const requiredPermissions = this.reflector.getAllAndOverride(common.METADATA_KEYS.PERMISSIONS, targets);
+        if (!requiredRoles && !requiredPermissions) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const user = request.user;
+        if (!user || !user.roles) {
+            return false;
+        }
+        if (requiredRoles) {
+            const userRoleNames = user.roles.map((r) => r.name);
+            const hasRole = requiredRoles.some((role) => userRoleNames.includes(role));
+            if (!hasRole)
+                return false;
+        }
+        if (requiredPermissions) {
+            const userPermissions = user.roles.flatMap((r) => r.permissions || []);
+            const hasPermission = requiredPermissions.some((perm) => userPermissions.includes(perm));
+            if (!hasPermission)
+                return false;
+        }
+        return true;
+    }
+};
+exports.AuthGuard = __decorate([
+    inversify.injectable(),
+    __metadata("design:paramtypes", [exports.Reflector])
+], exports.AuthGuard);
+
+exports.GuardsConsumer = GuardsConsumer;
+exports.HemiaExecutionContext = HemiaExecutionContext;
+exports.HemiaFactory = HemiaFactory;
+exports.ResponseSerializer = ResponseSerializer;
+exports.registerRoutes = registerRoutes;

package/dist/types/context/execution-context.d.ts

@@ -0,0 +1,14 @@
+import { ExecutionContext, HttpArgumentsHost, Type } from "@hemia/common";
+export declare class HemiaExecutionContext implements ExecutionContext {
+    private readonly args;
+    private readonly constructorRef;
+    private readonly handler;
+    private readonly contextType;
+    constructor(args: any[], constructorRef: Type<any>, handler: Function, contextType?: string);
+    getType<TContext extends string = string>(): TContext;
+    getArgs<T extends Array<any> = any[]>(): T;
+    getArgByIndex<T = any>(index: number): T;
+    switchToHttp(): HttpArgumentsHost;
+    getClass<T = any>(): Type<T>;
+    getHandler(): Function;
+}

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

@@ -0,0 +1 @@
+export * from "./execution-context";

package/dist/types/guards/auth.guard.d.ts

@@ -0,0 +1,7 @@
+import { CanActivate, ExecutionContext } from '@hemia/common';
+import { Reflector } from '../services';
+export declare class AuthGuard implements CanActivate {
+    private reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+}

package/dist/types/guards/guards-consumer.d.ts

@@ -0,0 +1,10 @@
+import { Container } from 'inversify';
+import { CanActivate, Type } from '@hemia/common';
+import { HemiaExecutionContext } from '../context/execution-context';
+export declare class GuardsConsumer {
+    /**
+     * Ejecuta una lista de guards secuencialmente.
+     * Lanza error si alguno falla.
+     */
+    static tryActivate(guards: Type<CanActivate>[], context: HemiaExecutionContext, container: Container): Promise<void>;
+}

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

@@ -0,0 +1,2 @@
+export * from "./auth.guard";
+export * from "./guards-consumer";

package/dist/types/hemia-factory.d.ts

@@ -0,0 +1,17 @@
+import { Container } from "inversify";
+import { TraceFinishCallback } from "./router";
+import { Type } from "@hemia/common";
+import { Express } from "express";
+export interface HemiaFactoryOptions {
+    onTraceFinish?: TraceFinishCallback;
+    logger?: boolean;
+}
+export declare class HemiaFactory {
+    /**
+     * Inicializa la aplicación Hemia conectando Express con Inversify.
+     * @param container El contenedor de Inversify con tus servicios ya bindeados.
+     * @param controllers Lista de Clases de Controladores a registrar.
+     * @param options Opciones de configuración.
+     */
+    static create(container: Container, controllers: Type<any>[], options?: HemiaFactoryOptions): Promise<Express>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+export * from './hemia-factory';
+export * from "./services";
+export * from "./context";
+export * from "./router";
+export * from "./guards";
+export * from "./hemia-factory";

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

@@ -0,0 +1,2 @@
+export * from "./routes-registry";
+export * from "./response-serializer";

package/dist/types/router/response-serializer.d.ts

@@ -0,0 +1,4 @@
+import { Type } from '@hemia/common';
+export declare class ResponseSerializer {
+    static transform(entityOrArray: any, dto: Type<any>): any;
+}

package/dist/types/router/routes-registry.d.ts

@@ -0,0 +1,10 @@
+import { Container } from 'inversify';
+import { Express, Response } from 'express';
+export type TraceFinishCallback = (payloads: any, context: any, res: Response) => void;
+/**
+ * Registra los controladores resolviéndolos desde el contenedor de Inversify.
+ * @param app Instancia de Express
+ * @param container Instancia del Container de Inversify
+ * @param controllerIdentifiers Array de Symbols (o Clases si usas self-binding)
+ */
+export declare function registerRoutes(app: Express, container: Container, controllerIdentifiers: any[], onTraceFinishCallback: TraceFinishCallback): Promise<void>;

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

@@ -0,0 +1 @@
+export * from "./reflector.service";

package/dist/types/services/reflector.service.d.ts

@@ -0,0 +1,19 @@
+import { Type } from '@hemia/common';
+import 'reflect-metadata';
+export declare class Reflector {
+    /**
+     * Obtiene metadata de una clase o un método
+     */
+    get<TResult = any, TKey = any>(metadataKey: TKey, target: Type<any> | Function): TResult;
+    /**
+     * Obtiene metadata con prioridad: Método > Clase.
+     * Si el método tiene metadata, retorna esa. Si no, busca en la clase.
+     * @param metadataKey La clave de la metadata.
+     * @param targets Tupla con [Handler (Método), Class (Controlador)].
+     */
+    getAllAndOverride<TResult = any, TKey = any>(metadataKey: TKey, targets: [Function, Type<any>]): TResult | undefined;
+    /**
+     * Obtiene metadata combinada (merge) de Método y Clase (opcional, útil para arrays acumulativos)
+     */
+    getAllAndMerge<TResult extends any[] = any[], TKey = any>(metadataKey: TKey, targets: [Function, Type<any>]): TResult;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hemia/core",
+  "version": "0.0.1",
+  "description": "Core utilities for Hemia projects",
+  "main": "dist/hemia-core.js",
+  "module": "dist/hemia-core.esm.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "clean": "rimraf dist",
+    "tscBuild": "rollup -c",
+    "build": "npm run clean && npm run tscBuild",
+    "test": "jest --detectOpenHandles",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^26.0.1",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@hemia/common": "^0.0.4",
+    "@hemia/app-context": "^0.0.6",
+    "@hemia/trace-manager": "^0.0.9",
+    "@types/express": "^5.0.5",
+    "express": "^5.1.0",
+    "inversify": "^7.10.4",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.5.0",
+    "class-transformer": "^0.5.1",
+    "events": "^3.3.0",
+    "jest": "^29.7.0",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.20.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^8.9.0",
+    "typescript": "^5.5.4"
+  },
+  "author": "",
+  "license": "ISC",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "class-transformer": "^0.5.1",
+    "express": "^5.0.0",
+    "inversify": "^7.0.0",
+    "reflect-metadata": "^0.1.13"
+  }
+}