@hemia/common 0.0.1

package/README.md

@@ -0,0 +1,291 @@
+
+# @hemia/common
+
+Sistema de decoradores y utilidades para crear controladores HTTP con TypeScript usando metadata reflection.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install @hemia/common reflect-metadata
+```
+
+> **Nota:** Este paquete requiere `reflect-metadata` como dependencia peer.
+
+---
+
+## 🚀 Características
+
+- ✨ Decoradores para controladores HTTP estilo Express/NestJS
+- 🎯 Soporte completo para métodos HTTP (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
+- 📝 Decoradores de parámetros para request, response, body, query, params, headers, etc.
+- 🔄 Manejo de redirecciones y headers personalizados
+- 🛡️ Type-safe con TypeScript
+- 📦 Metadata reflection con `reflect-metadata`
+
+---
+
+## 📖 Uso
+
+### Configuración inicial
+
+Asegúrate de importar `reflect-metadata` al inicio de tu aplicación:
+
+```typescript
+import 'reflect-metadata';
+```
+
+También necesitas habilitar los siguientes flags en tu `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+### Ejemplo básico
+
+```typescript
+import { Controller, Get, Post, Body, Param, Query } from '@hemia/common';
+
+@Controller('/users')
+class UserController {
+  @Get('/')
+  getAllUsers(@Query('page') page: string) {
+    // Maneja GET /users?page=1
+    return { users: [], page };
+  }
+
+  @Get('/:id')
+  getUserById(@Param('id') id: string) {
+    // Maneja GET /users/123
+    return { id, name: 'John Doe' };
+  }
+
+  @Post('/')
+  createUser(@Body() userData: any) {
+    // Maneja POST /users
+    return { created: true, data: userData };
+  }
+}
+```
+
+---
+
+## 🎨 API Reference
+
+### Decoradores de Clase
+
+#### `@Controller(basePath?: string)`
+
+Define una clase como controlador HTTP con una ruta base opcional.
+
+```typescript
+@Controller('/api/v1')
+class ApiController {
+  // ...
+}
+```
+
+### Decoradores de Método (HTTP)
+
+Los siguientes decoradores definen rutas y métodos HTTP:
+
+- `@Get(path?: string)` - Método GET
+- `@Post(path?: string)` - Método POST
+- `@Put(path?: string)` - Método PUT
+- `@Delete(path?: string)` - Método DELETE
+- `@Patch(path?: string)` - Método PATCH
+- `@Options(path?: string)` - Método OPTIONS
+- `@Head(path?: string)` - Método HEAD
+
+```typescript
+@Controller('/products')
+class ProductController {
+  @Get('/')
+  findAll() { /* ... */ }
+
+  @Post('/create')
+  create() { /* ... */ }
+
+  @Put('/:id')
+  update() { /* ... */ }
+
+  @Delete('/:id')
+  remove() { /* ... */ }
+}
+```
+
+### Decoradores de Parámetros
+
+Extraen información de la petición HTTP:
+
+#### `@Request()` / `@Req()`
+Inyecta el objeto request completo.
+
+```typescript
+@Get('/')
+handler(@Request() req: any) {
+  // Acceso al request completo
+}
+```
+
+#### `@Response()` / `@Res()`
+Inyecta el objeto response completo.
+
+```typescript
+@Get('/')
+handler(@Response() res: any) {
+  // Acceso al response completo
+}
+```
+
+#### `@Body(key?: string)`
+Extrae el cuerpo de la petición o una propiedad específica.
+
+```typescript
+@Post('/')
+create(@Body() data: any) { /* ... */ }
+
+@Post('/')
+create(@Body('email') email: string) { /* ... */ }
+```
+
+#### `@Param(key?: string)`
+Extrae parámetros de ruta.
+
+```typescript
+@Get('/:id/:name')
+handler(@Param('id') id: string, @Param('name') name: string) { /* ... */ }
+```
+
+#### `@Query(key?: string)`
+Extrae parámetros de query string.
+
+```typescript
+@Get('/')
+search(@Query('q') searchTerm: string, @Query('limit') limit: string) { /* ... */ }
+```
+
+#### `@Headers(key?: string)`
+Extrae headers de la petición.
+
+```typescript
+@Get('/')
+handler(@Headers('authorization') auth: string) { /* ... */ }
+```
+
+#### `@Session()`
+Inyecta el objeto de sesión.
+
+```typescript
+@Get('/profile')
+getProfile(@Session() session: any) { /* ... */ }
+```
+
+#### `@Ip()`
+Obtiene la dirección IP del cliente.
+
+```typescript
+@Get('/')
+handler(@Ip() ip: string) { /* ... */ }
+```
+
+#### `@Host()`
+Obtiene el host de la petición.
+
+```typescript
+@Get('/')
+handler(@Host() host: string) { /* ... */ }
+```
+
+#### `@Next()`
+Inyecta la función next (para middleware).
+
+```typescript
+@Get('/')
+handler(@Next() next: Function) { /* ... */ }
+```
+
+### Decoradores de Respuesta
+
+#### `@Header(name: string, value: string)`
+Define headers personalizados para la respuesta.
+
+```typescript
+@Get('/')
+@Header('X-Custom-Header', 'value')
+@Header('Cache-Control', 'no-cache')
+handler() {
+  return { data: 'example' };
+}
+```
+
+#### `@Redirect(url: string, statusCode?: number)`
+Redirige a una URL específica (código por defecto: 302).
+
+```typescript
+@Get('/old-page')
+@Redirect('/new-page', 301)
+redirectHandler() {
+  // Redirige permanentemente
+}
+
+@Get('/external')
+@Redirect('https://example.com')
+externalRedirect() {
+  // Redirige temporalmente
+}
+```
+---
+
+## 🔍 Metadata Keys
+
+El paquete utiliza las siguientes claves de metadata:
+
+```typescript
+const METADATA_KEYS = {
+  BASE_PATH: 'base_path',      // Ruta base del controlador
+  ROUTES: 'routes',            // Rutas definidas
+  PARAMS: 'params',            // Parámetros del método
+  HEADERS: 'headers',          // Headers personalizados
+  REDIRECT: 'redirect'         // Configuración de redirección
+}
+```
+
+---
+
+## 🧪 Desarrollo
+
+### Scripts disponibles
+
+| Script                | Descripción                           |
+|-----------------------|---------------------------------------|
+| `npm run build`       | Compila el paquete con Rollup        |
+| `npm run test`        | Ejecuta pruebas con Jest             |
+| `npm run test:watch`  | Ejecuta pruebas en modo watch        |
+| `npm run test:coverage` | Genera reporte de cobertura        |
+| `npm run clean`       | Limpia la carpeta `dist/`            |
+
+### Archivos generados
+
+- `dist/hemia-common.js` - Bundle CommonJS
+- `dist/hemia-common.esm.js` - Bundle ES Module
+- `dist/types/` - Declaraciones de TypeScript
+
+---
+
+## 📄 Licencia
+
+ISC
+
+---
+
+## ✨ Generado con Hemia CLI
+
+Este paquete fue generado usando [Hemia CLI](https://www.npmjs.com/package/@hemia/cli).
+    

package/dist/hemia-common.esm.js

@@ -0,0 +1,101 @@
+import 'reflect-metadata';
+
+const METADATA_KEYS = {
+    BASE_PATH: 'base_path',
+    ROUTES: 'routes',
+    PARAMS: 'params',
+    HEADERS: 'headers',
+    REDIRECT: 'redirect'
+};
+
+const Controller = (basePath = '/') => {
+    return (target) => {
+        Reflect.defineMetadata(METADATA_KEYS.BASE_PATH, basePath, target);
+    };
+};
+
+var HttpMethod;
+(function (HttpMethod) {
+    HttpMethod["GET"] = "get";
+    HttpMethod["POST"] = "post";
+    HttpMethod["PUT"] = "put";
+    HttpMethod["DELETE"] = "delete";
+    HttpMethod["PATCH"] = "patch";
+    HttpMethod["OPTIONS"] = "options";
+    HttpMethod["HEAD"] = "head";
+})(HttpMethod || (HttpMethod = {}));
+
+var ParamType;
+(function (ParamType) {
+    ParamType["REQUEST"] = "REQUEST";
+    ParamType["RESPONSE"] = "RESPONSE";
+    ParamType["NEXT"] = "NEXT";
+    ParamType["BODY"] = "BODY";
+    ParamType["QUERY"] = "QUERY";
+    ParamType["PARAM"] = "PARAM";
+    ParamType["HEADERS"] = "HEADERS";
+    ParamType["SESSION"] = "SESSION";
+    ParamType["IP"] = "IP";
+    ParamType["HOST"] = "HOST";
+})(ParamType || (ParamType = {}));
+
+const createMethodDecorator = (method) => {
+    return (path = '/') => {
+        return (target, propertyKey) => {
+            const routes = Reflect.getMetadata(METADATA_KEYS.ROUTES, target.constructor) || [];
+            routes.push({ path, method, methodName: propertyKey });
+            Reflect.defineMetadata(METADATA_KEYS.ROUTES, routes, target.constructor);
+        };
+    };
+};
+const Get = createMethodDecorator(HttpMethod.GET);
+const Post = createMethodDecorator(HttpMethod.POST);
+const Put = createMethodDecorator(HttpMethod.PUT);
+const Delete = createMethodDecorator(HttpMethod.DELETE);
+const Patch = createMethodDecorator(HttpMethod.PATCH);
+const Options = createMethodDecorator(HttpMethod.OPTIONS);
+const Head = createMethodDecorator(HttpMethod.HEAD);
+
+const createParamDecorator = (type) => {
+    return (data) => {
+        return (target, propertyKey, parameterIndex) => {
+            const existingParams = Reflect.getMetadata(METADATA_KEYS.PARAMS, target, propertyKey || '') || [];
+            existingParams.push({ index: parameterIndex, type, data });
+            Reflect.defineMetadata(METADATA_KEYS.PARAMS, existingParams, target, propertyKey || '');
+        };
+    };
+};
+const Request = createParamDecorator(ParamType.REQUEST);
+const Req = createParamDecorator(ParamType.REQUEST);
+const Response = createParamDecorator(ParamType.RESPONSE);
+const Res = createParamDecorator(ParamType.RESPONSE);
+const Next = createParamDecorator(ParamType.NEXT);
+const Session = createParamDecorator(ParamType.SESSION);
+const Ip = createParamDecorator(ParamType.IP);
+const Host = createParamDecorator(ParamType.HOST);
+const Body = createParamDecorator(ParamType.BODY);
+const Query = createParamDecorator(ParamType.QUERY);
+const Param = createParamDecorator(ParamType.PARAM);
+const Headers = createParamDecorator(ParamType.HEADERS);
+
+const Header = (name, value) => {
+    return (target, propertyKey, descriptor) => {
+        const existingHeaders = Reflect.getMetadata(METADATA_KEYS.HEADERS, target.constructor, propertyKey) || [];
+        existingHeaders.push({ name, value });
+        Reflect.defineMetadata(METADATA_KEYS.HEADERS, existingHeaders, target.constructor, propertyKey);
+        return descriptor;
+    };
+};
+const Redirect = (url, statusCode = 302) => {
+    return (target, propertyKey, descriptor) => {
+        const redirectMetadata = { url, statusCode };
+        Reflect.defineMetadata(METADATA_KEYS.REDIRECT, redirectMetadata, target.constructor, propertyKey);
+        return descriptor;
+    };
+};
+
+function isRedirectResponse(value) {
+    return value && typeof value === 'object' && typeof value.url === 'string';
+}
+
+export { Body, Controller, Delete, Get, Head, Header, Headers, Host, HttpMethod, Ip, METADATA_KEYS, Next, Options, Param, ParamType, Patch, Post, Put, Query, Redirect, Req, Request, Res, Response, Session, isRedirectResponse };

package/dist/hemia-common.js

@@ -0,0 +1,126 @@
+'use strict';
+
+require('reflect-metadata');
+
+const METADATA_KEYS = {
+    BASE_PATH: 'base_path',
+    ROUTES: 'routes',
+    PARAMS: 'params',
+    HEADERS: 'headers',
+    REDIRECT: 'redirect'
+};
+
+const Controller = (basePath = '/') => {
+    return (target) => {
+        Reflect.defineMetadata(METADATA_KEYS.BASE_PATH, basePath, target);
+    };
+};
+
+exports.HttpMethod = void 0;
+(function (HttpMethod) {
+    HttpMethod["GET"] = "get";
+    HttpMethod["POST"] = "post";
+    HttpMethod["PUT"] = "put";
+    HttpMethod["DELETE"] = "delete";
+    HttpMethod["PATCH"] = "patch";
+    HttpMethod["OPTIONS"] = "options";
+    HttpMethod["HEAD"] = "head";
+})(exports.HttpMethod || (exports.HttpMethod = {}));
+
+exports.ParamType = void 0;
+(function (ParamType) {
+    ParamType["REQUEST"] = "REQUEST";
+    ParamType["RESPONSE"] = "RESPONSE";
+    ParamType["NEXT"] = "NEXT";
+    ParamType["BODY"] = "BODY";
+    ParamType["QUERY"] = "QUERY";
+    ParamType["PARAM"] = "PARAM";
+    ParamType["HEADERS"] = "HEADERS";
+    ParamType["SESSION"] = "SESSION";
+    ParamType["IP"] = "IP";
+    ParamType["HOST"] = "HOST";
+})(exports.ParamType || (exports.ParamType = {}));
+
+const createMethodDecorator = (method) => {
+    return (path = '/') => {
+        return (target, propertyKey) => {
+            const routes = Reflect.getMetadata(METADATA_KEYS.ROUTES, target.constructor) || [];
+            routes.push({ path, method, methodName: propertyKey });
+            Reflect.defineMetadata(METADATA_KEYS.ROUTES, routes, target.constructor);
+        };
+    };
+};
+const Get = createMethodDecorator(exports.HttpMethod.GET);
+const Post = createMethodDecorator(exports.HttpMethod.POST);
+const Put = createMethodDecorator(exports.HttpMethod.PUT);
+const Delete = createMethodDecorator(exports.HttpMethod.DELETE);
+const Patch = createMethodDecorator(exports.HttpMethod.PATCH);
+const Options = createMethodDecorator(exports.HttpMethod.OPTIONS);
+const Head = createMethodDecorator(exports.HttpMethod.HEAD);
+
+const createParamDecorator = (type) => {
+    return (data) => {
+        return (target, propertyKey, parameterIndex) => {
+            const existingParams = Reflect.getMetadata(METADATA_KEYS.PARAMS, target, propertyKey || '') || [];
+            existingParams.push({ index: parameterIndex, type, data });
+            Reflect.defineMetadata(METADATA_KEYS.PARAMS, existingParams, target, propertyKey || '');
+        };
+    };
+};
+const Request = createParamDecorator(exports.ParamType.REQUEST);
+const Req = createParamDecorator(exports.ParamType.REQUEST);
+const Response = createParamDecorator(exports.ParamType.RESPONSE);
+const Res = createParamDecorator(exports.ParamType.RESPONSE);
+const Next = createParamDecorator(exports.ParamType.NEXT);
+const Session = createParamDecorator(exports.ParamType.SESSION);
+const Ip = createParamDecorator(exports.ParamType.IP);
+const Host = createParamDecorator(exports.ParamType.HOST);
+const Body = createParamDecorator(exports.ParamType.BODY);
+const Query = createParamDecorator(exports.ParamType.QUERY);
+const Param = createParamDecorator(exports.ParamType.PARAM);
+const Headers = createParamDecorator(exports.ParamType.HEADERS);
+
+const Header = (name, value) => {
+    return (target, propertyKey, descriptor) => {
+        const existingHeaders = Reflect.getMetadata(METADATA_KEYS.HEADERS, target.constructor, propertyKey) || [];
+        existingHeaders.push({ name, value });
+        Reflect.defineMetadata(METADATA_KEYS.HEADERS, existingHeaders, target.constructor, propertyKey);
+        return descriptor;
+    };
+};
+const Redirect = (url, statusCode = 302) => {
+    return (target, propertyKey, descriptor) => {
+        const redirectMetadata = { url, statusCode };
+        Reflect.defineMetadata(METADATA_KEYS.REDIRECT, redirectMetadata, target.constructor, propertyKey);
+        return descriptor;
+    };
+};
+
+function isRedirectResponse(value) {
+    return value && typeof value === 'object' && typeof value.url === 'string';
+}
+
+exports.Body = Body;
+exports.Controller = Controller;
+exports.Delete = Delete;
+exports.Get = Get;
+exports.Head = Head;
+exports.Header = Header;
+exports.Headers = Headers;
+exports.Host = Host;
+exports.Ip = Ip;
+exports.METADATA_KEYS = METADATA_KEYS;
+exports.Next = Next;
+exports.Options = Options;
+exports.Param = Param;
+exports.Patch = Patch;
+exports.Post = Post;
+exports.Put = Put;
+exports.Query = Query;
+exports.Redirect = Redirect;
+exports.Req = Req;
+exports.Request = Request;
+exports.Res = Res;
+exports.Response = Response;
+exports.Session = Session;
+exports.isRedirectResponse = isRedirectResponse;

package/dist/types/decorators/controllers/controller.decorator.d.ts

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+export declare const Controller: (basePath?: string) => ClassDecorator;

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

@@ -0,0 +1,4 @@
+export * from "./controller.decorator";
+export * from "./method.decorators";
+export * from "./param.decorators";
+export * from "./response.decorators";

package/dist/types/decorators/controllers/method.decorators.d.ts

@@ -0,0 +1,8 @@
+import 'reflect-metadata';
+export declare const Get: (path?: string) => MethodDecorator;
+export declare const Post: (path?: string) => MethodDecorator;
+export declare const Put: (path?: string) => MethodDecorator;
+export declare const Delete: (path?: string) => MethodDecorator;
+export declare const Patch: (path?: string) => MethodDecorator;
+export declare const Options: (path?: string) => MethodDecorator;
+export declare const Head: (path?: string) => MethodDecorator;

package/dist/types/decorators/controllers/param.decorators.d.ts

@@ -0,0 +1,13 @@
+import 'reflect-metadata';
+export declare const Request: (data?: string) => ParameterDecorator;
+export declare const Req: (data?: string) => ParameterDecorator;
+export declare const Response: (data?: string) => ParameterDecorator;
+export declare const Res: (data?: string) => ParameterDecorator;
+export declare const Next: (data?: string) => ParameterDecorator;
+export declare const Session: (data?: string) => ParameterDecorator;
+export declare const Ip: (data?: string) => ParameterDecorator;
+export declare const Host: (data?: string) => ParameterDecorator;
+export declare const Body: (data?: string) => ParameterDecorator;
+export declare const Query: (data?: string) => ParameterDecorator;
+export declare const Param: (data?: string) => ParameterDecorator;
+export declare const Headers: (data?: string) => ParameterDecorator;

package/dist/types/decorators/controllers/response.decorators.d.ts

@@ -0,0 +1,3 @@
+import 'reflect-metadata';
+export declare const Header: (name: string, value: string) => MethodDecorator;
+export declare const Redirect: (url: string, statusCode?: number) => MethodDecorator;

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

@@ -0,0 +1,2 @@
+export * from "./controllers";
+export * from "./metadata";

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

@@ -0,0 +1,7 @@
+export declare const METADATA_KEYS: {
+    readonly BASE_PATH: "base_path";
+    readonly ROUTES: "routes";
+    readonly PARAMS: "params";
+    readonly HEADERS: "headers";
+    readonly REDIRECT: "redirect";
+};

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

@@ -0,0 +1,2 @@
+export * from './methods.enum';
+export * from './param-type.enum';

package/dist/types/enums/methods.enum.d.ts

@@ -0,0 +1,9 @@
+export declare enum HttpMethod {
+    GET = "get",
+    POST = "post",
+    PUT = "put",
+    DELETE = "delete",
+    PATCH = "patch",
+    OPTIONS = "options",
+    HEAD = "head"
+}

package/dist/types/enums/param-type.enum.d.ts

@@ -0,0 +1,12 @@
+export declare enum ParamType {
+    REQUEST = "REQUEST",
+    RESPONSE = "RESPONSE",
+    NEXT = "NEXT",
+    BODY = "BODY",
+    QUERY = "QUERY",
+    PARAM = "PARAM",
+    HEADERS = "HEADERS",
+    SESSION = "SESSION",
+    IP = "IP",
+    HOST = "HOST"
+}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+export * from "./decorators";
+export * from "./enums";
+export * from "./interfaces";
+export * from "./types";
+export * from "./utils";

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

@@ -0,0 +1,2 @@
+export * from './param.interface';
+export * from './route.interface';

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

@@ -0,0 +1,14 @@
+import { ParamType } from "../enums/param-type.enum";
+export interface ParamMetadata {
+    index: number;
+    type: ParamType;
+    data?: string;
+}
+export interface HeaderMetadata {
+    name: string;
+    value: string;
+}
+export interface RedirectMetadata {
+    url: string;
+    statusCode: number;
+}

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

@@ -0,0 +1,6 @@
+import { HttpMethod } from "../enums/methods.enum";
+export interface RouteMetadata {
+    path: string;
+    method: HttpMethod;
+    methodName: string | symbol;
+}

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

@@ -0,0 +1 @@
+export * from "./redirect.types";

package/dist/types/types/redirect.types.d.ts

@@ -0,0 +1,4 @@
+export interface RedirectResponse {
+    url: string;
+    statusCode?: number;
+}

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

@@ -0,0 +1 @@
+export * from "./type-guards";

package/dist/types/utils/type-guards.d.ts

@@ -0,0 +1,2 @@
+import { RedirectResponse } from '../types';
+export declare function isRedirectResponse(value: any): value is RedirectResponse;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hemia/common",
+  "version": "0.0.1",
+  "description": "Paquete común para proyectos de Hemia",
+  "main": "dist/hemia-common.js",
+  "module": "dist/hemia-common.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",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.5.0",
+    "events": "^3.3.0",
+    "jest": "^29.7.0",
+    "reflect-metadata": "^0.2.2",
+    "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"
+  },
+  "peerDependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "author": "",
+  "license": "ISC",
+  "files": [
+    "dist"
+  ]
+}