Comenzando

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

:::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