npm package: @jamx-framework/adapter-vercel
Description: JAMX Framework â€” Vercel Edge adapter
Author: Stiven-21
Latest version: 1.0.0

# @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
```typescript
// 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
```typescript
import { createVercelHandler } from '@jamx-framework/adapter-vercel';

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

### Router con múltiples métodos
```typescript
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
```typescript
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
```typescript
(createHandler: JamxHandler) => (req: VercelRequest, res: VercelResponse) => Promise<void>
```
Crea un handler de Vercel que ejecuta un handler de JAMX.

### createVercelRouter
```typescript
(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:

```bash
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.