Comenzando

¡Bienvenido a Veloce-TS! Esta guía te ayudará a empezar rápidamente con las últimas funciones.

:::danger ¿Vienes de v2.x? Tus guards de ruta no se estaban aplicando En todas las versiones 2.x, @Auth(), @Session(), @RequireCSRF() y la familia @CanAccess no se aplicaban, en silencio. Los tres plugins que los respaldan instalaban su guard reemplazando app.compile, desde dentro de una llamada que compile() ya había iniciado, así que el reemplazo nunca corría. Una ruta marcada con @Auth() y sin parámetro @CurrentUser() respondía 200 a peticiones anónimas.

@Roles() nunca se vio afectado: RBACPlugin era el único plugin bien conectado.

Tras actualizar, peticiones que antes funcionaban pueden empezar a recibir 401 o 403. Eso es el arreglo funcionando. Además:

SessionConfig.secret ahora es obligatorio y firma la cookie de sesión. Las sesiones emitidas por 2.x se rechazan, así que esos usuarios vuelven a iniciar sesión.
El cuerpo de las peticiones se limita a 1 MiB. Si aceptas subidas, súbelo: new Veloce({ bodyLimit: 25 * 1024 * 1024 }).
docs vale true por defecto y ahora sí monta /openapi.json y /docs.
Response ahora es VeloceResponse (el nombre anterior ensombrecía el Response global).
Se requiere Node 20+.

Lista completa: MIGRATION.md. :::

:::danger ¿Vienes de v1.x? Dos cambios incompatibles 1. Los métodos de verificación y revocación de JWTProvider ahora son async (verifyAccessToken, verifyRefreshToken, refreshAccessToken, blacklistToken, isBlacklisted, cleanupBlacklist). Olvidar el await es peor que un error de tipos: la Promise devuelta siempre es truthy, así que un chequeo viejo como if (verifyAccessToken(token)) ahora pasa con cualquier string. Ver Autenticación.

2. Los controladores con decoradores ahora usan scope singleton por defecto, no una instancia nueva por petición. El estado por petición guardado en campos de instancia ahora se comparte entre peticiones concurrentes. Puedes optar por lo anterior con @Controller('/x', { scope: 'transient' }).

Diff completo: MIGRATION.md. :::

:::tip Novedades en v2.0.0 Si despliegas en Node.js, actualiza. La v1.2.0 publicada estaba genuinamente rota ahí — cuatro bugs de empaquetado distintos, todos corregidos:

veloce-ts/adapters/* apuntaba a una ruta que el build nunca generaba, así que ese import fallaba por completo
el bundle ESM emitía import.meta.require, un global exclusivo de Bun que lanza bajo Node
dist/cjs se interpretaba como ESM, porque el package.json raíz declara "type": "module"
las dependencias de runtime se empaquetaban dentro de dist, enviando una copia duplicada de Zod — lo que rompía las comprobaciones de identidad contra los schemas que tú creas — y dejando el regex de semver inválido, lo que lanzaba al hacer require

Seguridad — un refresh token podía reutilizarse como access token; los algoritmos asimétricos RS256/384/512 firmaban en silencio con el secreto HMAC compartido; el rate limiting confiaba en el X-Forwarded-For enviado por el cliente (ahora se activa con trustProxy); los fallos de @ResponseSchema se tragaban en lugar de reportarse.

Rendimiento — el dispatch de peticiones mejoró bastante respecto a v0.4.18 al sacar del camino por petición la resolución de controladores, la búsqueda de interceptores y el orden de parámetros. El paquete publicado bajó de 3.82 MB a 1.33 MB (y a 0.42 MB en 3.1.2).

Las notas de v2.0.0 también afirmaban que Veloce-TS superaba a Hono crudo en parseo de body y validación Zod. Eso era ruido de medición y ya está corregido: una capa construida sobre Hono no puede ser más rápida que Hono haciendo el mismo trabajo. Las cifras actuales, con su metodología, están en BENCHMARKS.md.

GraphQL ahora sí funciona. Los resolvers estaban conectados a una forma que graphql-js nunca lee, así que toda query devolvía null, y todos los campos se tipaban como String. Los tipos de objeto y de entrada ahora se derivan de tus schemas Zod.

APIs nuevas — rutas funcionales tipadas (los argumentos del handler se infieren del conjunto de schemas Zod), @Controller(prefix, { scope }), RedisTokenBlacklist para revocación entre réplicas, hooks de ciclo de vida Plugin.onStart/onStop, app.getFetchHandler() para Cloudflare Workers, límites de heartbeat/inactividad/tamaño de mensaje en WebSocket, y CacheManager.destroy().

Tooling — el CLI corre bajo Node puro (antes requería Bun), CI ganó una matriz multi-runtime real, y los fallos de generación de .d.ts ahora son fatales en builds de producción. :::

:::tip Novedades en v1.2.0

CLI scaffolding — veloce generate controller/service/module/resolver/dto/middleware/plugin <nombre> genera boilerplate tipado al instante
Apagado gradual — app.onShutdown(handler) + manejo automático de SIGTERM/SIGINT; timeout configurable
Filtros de excepción — @Catch(ErrorClass) + app.useFilter() para respuestas de error centralizadas y tipadas
Interceptores — @UseInterceptor() + app.useInterceptor() para logging AOP, caché y transformaciones
Streaming — @SSE() y @Stream(contentType) en handlers AsyncGenerator para SSE y exportaciones CSV
Bus de eventos — EventBus y singleton globalEvents para pub/sub en proceso sin Redis
Decoradores extra — @Throttle, @ApiVersion, @ResponseHeader, @Redirect, @Deprecated
Aislamiento de tests — isolate() y compileTestApp() para tests paralelos sin flakiness
OpenAPI 3.1 — jsonSchemaDialect, nullable → type: ['x','null'] :::

:::tip Novedades en v1.0.1

Pipeline de decoradores GraphQL corregido — @Resolver, @GQLQuery, @GQLMutation y @Arg funcionan de extremo a extremo. Pasa las clases resolver con resolvers: [...] en el plugin o con app.include().
PermissionManager.revokePermission() corregido — los permisos ahora se eliminan correctamente cuando no se especifica resourceId.
509 tests — 89 tests nuevos que cubren PermissionPlugin, HealthCheckPlugin, Logger, OAuthPlugin y GraphQL. :::

:::tip Novedades en v0.4.0

Nuevos decoradores OpenAPI — @Summary, @Description, @Tag, @Tags, @Deprecated para documentar rutas de forma concisa
Decoradores de control de respuesta — @HttpCode(statusCode) y @ResponseSchema(schema) para controlar y documentar respuestas
Middleware declarativo por ruta — @Timeout(ms) y @RateLimit(options) aplicados declarativamente
TestClient fluente — nueva TestResponse con aserciones encadenables (expectOk(), expectJson(), expectField())
Integración DI con Drizzle ORM — registerDrizzle() y @InjectDB() para inyección limpia de base de datos
6 nuevas clases de excepción HTTP — ConflictException, GoneException, PayloadTooLargeException, UnprocessableEntityException, TooManyRequestsException, ServiceUnavailableException
Auto-tagging y seguridad Bearer en el generador OpenAPI
Respuestas de validación mejoradas — field, received, expected, minimum/maximum estructurados en errores 422 :::

Instalación

Instala Veloce usando tu gestor de paquetes preferido:

# Usando Bun (recomendado)
bun add veloce-ts zod

# Usando npm
npm install veloce-ts zod

# Usando pnpm
pnpm add veloce-ts zod

Inicio Rápido

Crea tu primera API en minutos:

import { Veloce, Controller, Get, Post, Body } from 'veloce-ts';
import { z } from 'zod';

// Define un esquema
const UserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

// Crea un controlador
@Controller('/users')
class UserController {
  @Get('/')
  async getUsers() {
    return [
      { id: 1, name: 'John Doe', email: 'john@example.com' },
      { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
    ];
  }

  @Post('/')
  async createUser(@Body(UserSchema) user: z.infer<typeof UserSchema>) {
    return { id: 3, ...user };
  }
}

// Crea e inicia la aplicación
const app = new Veloce();
app.include(UserController);
app.listen(3000);

console.log('Servidor ejecutándose en http://localhost:3000');

Configuración de TypeScript

Agrega estas configuraciones a tu tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Estructura del Proyecto

Una estructura típica de proyecto Veloce-TS:

my-api/
├── src/
│   ├── controllers/
│   │   └── user.controller.ts
│   ├── services/
│   │   └── user.service.ts
│   ├── schemas/
│   │   └── user.schema.ts
│   └── index.ts
├── package.json
└── tsconfig.json

Usando el CLI

Veloce-TS incluye una potente CLI para creación de proyectos y generación de código:

# Crear un nuevo proyecto
veloce new my-api

# Generar un módulo completo (controlador + servicio + DTO + barrel)
veloce generate module users

# Generar piezas individuales
veloce generate controller products
veloce generate service products
veloce generate dto create-product
veloce generate resolver user
veloce generate middleware auth
veloce generate plugin analytics

Consulta la guía CLI para todas las opciones.

Próximos Pasos

Guía CLI — referencia de generación de código
Filtros de Excepción — manejo centralizado de errores
Interceptores — logging AOP y caché
Streaming — SSE y respuestas en streaming
Bus de Eventos — pub/sub en proceso
Decoradores — referencia completa de decoradores
Inyección de Dependencias
Plugins
Referencia API