@jamx-framework/adapter-vercel

Descripción

Adaptador de JAMX Framework para Vercel Edge Functions. Permite ejecutar handlers de JAMX en el entorno serverless de Vercel, proporcionando una API compatible con Vercel que maneja automáticamente la conversión de requests y respuestas, soportando tanto handlers individuales como routers basados en métodos HTTP.

Cómo funciona

El adaptador crea un puente entre el modelo de eventos de Vercel y el sistema de handlers de JAMX:

1. Conversión de Request: Convierte objetos VercelRequest en JamxRequest para procesamiento interno
2. Ejecución del Handler: Ejecuta el handler de JAMX con la request convertida y un ResponseBuilder
3. Construcción de Response: El ResponseBuilder gestiona estado HTTP, headers y cuerpo de la respuesta
4. Conversión de Response: Convierte el builder de respuesta en un objeto compatible con Vercel y lo envía

Componentes principales

• src/adapter.ts: Implementación principal que exporta createVercelHandler y createVercelRouter
• src/response-builder.ts: Clase que implementa JamxResponseBuilder con métodos para gestionar estado, headers y cuerpo
• src/types.ts: Definiciones de tipos compartidos (JamxRequest, JamxResponseBuilder, etc.)
• src/index.ts: Punto de exportación que reúne todos los componentes

Uso básico

// pages/api/hello.ts
import { createVercelHandler } from '@jamx-framework/adapter-vercel';

// Tu handler de JAMX
const jamxHandler = async (req, res) => {
  res.ok({ message: '¡Hola desde JAMX en Vercel!' });
};

// Exporta el handler para Vercel Serverless Functions
export default createVercelHandler(jamxHandler);

Ejemplos

Handler simple

import { createVercelHandler } from '@jamx-framework/adapter-vercel';

export default createVercelHandler(async (req, res) => {
  res.json({ hello: 'world' });
});

Router con múltiples métodos

import { createVercelRouter } from '@jamx-framework/adapter-vercel';

const router = createVercelRouter({
  GET: async (req, res) => {
    res.ok({ path: req.path });
  },
  POST: async (req, res) => {
    res.created({ method: req.method });
  },
  PUT: async (req, res) => {
    res.ok({ updated: true });
  }
});

export default router;

Uso avanzado con middlewares

import { createVercelHandler } from '@jamx-framework/adapter-vercel';

const handler = createVercelHandler(async (req, res) => {
  // Middleware de logging
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
  
  // Middleware de autenticación simple
  if (req.headers['x-api-key'] !== 'mi-clave-secreta') {
    res.unauthorized('API key inválida');
    return;
  }
  
  // Handler principal
  res.ok({ authenticated: true, path: req.path });
});

export default handler;

Flujo interno

1. Conversión de Request: toJamxRequest() transforma VercelRequest en JamxRequest
2. Ejecución del Handler: El handler de JAMX se ejecuta con la request convertida y un ResponseBuilder
3. Construcción de Response: El ResponseBuilder gestiona estado HTTP, headers y cuerpo
4. Conversión de Response: build() crea un objeto JamxResponse con status, headers y body
5. Envío a Vercel: Los métodos de respuesta (status, setHeader, send) actualizan el objeto VercelResponse
6. Finalización: La respuesta final se envía a Vercel mediante end()

API Reference (Resumen)

createVercelHandler

(createHandler: JamxHandler) => (req: VercelRequest, res: VercelResponse) => Promise<void>

Crea un handler de Vercel que ejecuta un handler de JAMX.

createVercelRouter

(handlers: Partial<Record<string, JamxHandler>>) => (req: VercelRequest, res: VercelResponse) => Promise<void>

Crea un router que admite múltiples handlers por método HTTP.

ResponseBuilder

• status(code: number): this
• header(name: string, value: string): this
• json(body: unknown, status?: number): void
• text(body: string, status?: number): void
• send(body: string, status?: number): void
• ok(body: unknown): void
• created(body: unknown): void
• noContent(): void
• notFound(message?: string): void
• build(): JamxResponse

Performance Considerations

• Edge Optimized: Diseñado para ejecutarse en el entorno edge de Vercel con tiempos de inicio rápidos
• Sin Dependencias Externas: No requiere @vercel/node ni otras dependencias pesadas
• Serialización Eficiente: Convierte automáticamente tipos comunes a formatos JSON/texto
• Manejo de Caching: Los headers y estado se gestionan en memoria para minimizar operaciones de I/O

Configuration Options

Este adaptador no requiere configuración adicional. Sin embargo, puedes personalizar el comportamiento mediante:

1. Middlewares: Añade lógica antes/durante/después del handler principal
2. Transformación de Request: Modifica VercelRequest antes de la conversión
3. Transformación de Response: Personaliza la construcción del JamxResponse

Testing

El proyecto incluye tests unitarios en packages/adapter-vercel/tests/unit/adapter.test.ts. Para ejecutarlos:

pnpm test
# o
npm run test

Los tests cubren:

• Conversión básica de request/response
• Manejo de diferentes métodos HTTP
• Respuestas de estado (200, 201, 204, 404, 405, 500)
• Funcionalidad de router con múltiples handlers
• Middleware de autenticación y logging

Compatibility

• Compatible con Vercel Edge Functions y Serverless Functions
• Funciona en Node.js 18+ y TypeScript 5.x
• Soporta todos los métodos HTTP estándar (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
• Compatible con middleware de autenticación y logging

CLI Integration

Este adaptador se integra automáticamente con el CLI de JAMX:

• jamx build: Compila los handlers para Vercel
• jamx dev: Inicia un servidor de desarrollo local que simula el entorno Vercel
• jamx deploy: Despliega automáticamente a Vercel cuando se ejecuta en un proyecto conectado

This adapter provides a seamless bridge between JAMX Framework and Vercel, enabling developers to build scalable, type-safe serverless applications with minimal configuration while maintaining full control over request/response handling.