Registro de Cambios

Todos los cambios notables de Veloce-TS están documentados en este archivo.

El formato está basado en Keep a Changelog, y este proyecto sigue el Versionado Semántico.

[Unreleased]

[1.2.0] - 2026-06-27

Añadido

CLI — Generación de código

veloce generate controller <nombre> — genera clase @Controller con stubs de rutas CRUD
veloce generate service <nombre> — genera clase de servicio @Injectable()
veloce generate module <nombre> — genera controlador + servicio + DTO + barrel en src/modules/<nombre>/
veloce generate resolver <nombre> — genera clase @Resolver con stubs de @GQLQuery y @GQLMutation
veloce generate dto <nombre> — genera esquema Zod + tipo TypeScript inferido
veloce generate middleware <nombre> — genera skeleton de middleware Hono
veloce generate plugin <nombre> — genera scaffold de clase VelocePlugin

Apagado gradual (Graceful Shutdown)

app.onShutdown(handler) — registra un handler async; se ejecutan en orden inverso al de registro al recibir SIGTERM/SIGINT
app.setShutdownTimeout(ms) — configura el tiempo máximo de espera antes de process.exit(1) (por defecto: 30 000 ms)
app.registerShutdownSignals() — llamado automáticamente por app.compile(); adjunta process.on('SIGTERM') y process.on('SIGINT')

Filtros de excepción

Interfaz ExceptionFilter<T> — implementa catch(error: T, c: Context): Response para producir respuestas de error tipadas
@Catch(...errorClasses) — vincula una clase de filtro a uno o más tipos de error
app.useFilter(filter) — registra un filtro global; se comprueba en orden de registro, gana el primero que coincide
FilterManager — gestor interno; exportado para integraciones personalizadas

Interceptores

Interfaz Interceptor — implementa intercept(ctx: ExecutionContext, next: () => Promise<Response>): Promise<Response>
ExecutionContext — contexto tipado con campos request, controller y handler
@UseInterceptor(...interceptors) — aplica interceptores a un método o clase; se apilan alrededor del handler como middleware
app.useInterceptor(interceptor) — registra un interceptor global; se ejecuta antes de los de clase/método

Respuestas en streaming

@SSE() — marca un handler AsyncGenerator como flujo de Server-Sent Events (text/event-stream)
@Stream(contentType) — marca un handler AsyncGenerator como flujo raw con tipo de contenido personalizado (p. ej. 'text/csv')

Bus de eventos

EventBus — pub/sub en proceso con on, once, off, emit (async, paralelo), emitSync, removeAllListeners, listenerCount
globalEvents — singleton compartido EventBus para comunicación entre módulos sin inyección de dependencias

Decoradores extra

@Throttle(limit, windowMs) — límite de tasa por endpoint que anula la configuración global
@ApiVersion(v) — antepone /v<v> a la ruta del endpoint para APIs versionadas
@ResponseHeader(name, value) — establece una cabecera de respuesta fija para la ruta
@Redirect(url, status?) — devuelve una respuesta de redirección (estado por defecto: 302)
@Deprecated(message?) — marca la ruta como obsoleta en OpenAPI y registra un aviso al arrancar

Aislamiento de tests

isolate() — restablece todo el estado singleton (CacheManager, registros de plugins) entre ejecuciones de test en paralelo
compileTestApp(app) — compila la app y devuelve la instancia Hono; wrapper de conveniencia para tests unitarios

OpenAPI 3.1

Versión de la especificación actualizada de 3.0.x a 3.1.0
Añadido jsonSchemaDialect: 'https://spec.openapis.org/oas/3.1/dialect/base'
nullable: true normalizado a { type: ['x', 'null'] } o { oneOf: [T, { type: 'null' }] } mediante normalizeFor31()

Cambios con ruptura

Ninguno — todos los cambios son aditivos y retrocompatibles con v1.0.1.

[1.0.1] - 2026-06-26

Corregido

Pipeline de decoradores GraphQL: @Resolver/@GQLQuery/@GQLMutation ahora funcionan de extremo a extremo. GraphQLSchemaBuilder leía de los Maps de la instancia de MetadataRegistry que nunca se llenaban (los decoradores escribían con un namespace de símbolos local separado). Ahora lee directamente de reflect-metadata vía getResolverMetadata/getFieldsMetadata.
PermissionManager.revokePermission(): El filtro resourceId ? p.resourceId !== resourceId : true siempre devolvía true cuando no se pasaba resourceId, por lo que nunca se eliminaba nada. Corregido.

Añadido

Opción resolvers en GraphQLPlugin: Pasa las clases resolver directamente — new GraphQLPlugin({ resolvers: [UserResolver] }) — como alternativa a app.include(). Ambas rutas se combinan y deduplicarán automáticamente.
Reconocimiento de resolvers en app.include(): include() detecta ahora las clases decoradas con @Resolver y registra sus metadatos, de modo que app.include(UserResolver) alimenta al constructor del esquema GraphQL automáticamente.

Tests

89 tests nuevos (509 en total): PermissionPlugin (16), HealthCheckPlugin (25), Logger (20), OAuthPlugin (28), decoradores/pipeline GraphQL (8 nuevos, 17 en total en la suite).

[0.4.5] - 2026-03-29

Corregido

CORS en respuestas de error: las respuestas del manejador de errores (401, 422, 500, application/problem+json, etc.) incluyen Access-Control-Allow-Origin y el resto de cabeceras CORS configuradas, alineadas con las respuestas OK (mergeVeloceCorsHeaders, VELOCE_CORS_HEADERS_KEY, VeloceCorsHeadersSnapshot).

Notas

Mismo parche CORS que en 0.4.4; npm no permite republicar una versión tras unpublish, así que 0.4.5 es la versión instalable.

[0.4.4] - 2026-03-28

No usar: el tarball en npm llegó roto (404). Tras unpublish, el registro bloquea reutilizar ese número. Usa 0.4.5 para el arreglo de CORS.

[0.4.3] - 2026-03-27

Añadido

RFC 9457 (Problem Details): errores por defecto con Content-Type: application/problem+json, campos type, title, status, detail, instance y extensiones (violations / details en validación; debug en 500 solo en desarrollo).
VeloceTSConfig.errorResponseFormat: 'rfc9457' (defecto) o 'legacy' para el JSON { error, statusCode, details? } anterior.
Helpers exportados: problemTypeUri, resolveProblemType, resolveProblemTitle, buildProblemInstance, toLegacyErrorBody, sendErrorResponse, PROBLEM_JSON_MEDIA_TYPE, DEFAULT_PROBLEM_TYPE_BASE.
HTTPExceptionOptions: problemType y title opcionales en HTTPException.

Cambiado

Excepciones de auth usan el formato unificado con tipos de problema authentication-error / authorization-error.

Documentación

Cabeceras @module en núcleo, errores, validación, DI, respuestas, logging, middleware, adaptadores, testing y barrels.
Benchmarks actualizados para v0.4.3.

Notas

El cuerpo de error sigue incluyendo error y statusCode junto a los campos RFC 9457. Para application/json en errores, usa errorResponseFormat: 'legacy'.

[0.4.2] - 2026-03-27

Corregido

HealthCheckPlugin: los nombres de los checkers se asignan de forma segura en Bun (Object.defineProperty + respaldo) para que no falle al poner .name en funciones async.
Export @Req: el decorador de parámetro ya se exporta en la entrada principal del paquete (import { Req } from 'veloce-ts').

Documentación

Guías y referencia API actualizadas para @Ctx(), @Req() y la API real de HealthCheckPlugin (array checks, HealthCheckers.database / memory / disk).

[0.4.1] - 2026-03-27

Corregido

include() ya no descarta los campos definidos por decoradores (como statusCode de @HttpCode y responseSchema de @ResponseSchema) al registrar rutas de controladores.

Añadido

Suite de tests completa (53 tests) que cubre: API funcional, rutas con decoradores, validación de body/query, excepciones HTTP y contenedor DI.
Logger de respaldo basado en console: si pino no está instalado, el framework ya no falla al arrancar — usa console automáticamente.

Cambiado

pino, pino-pretty e ioredis movidos a optionalDependencies — ya no se instalan automáticamente (~7 MB menos por defecto). Instálalos explícitamente con bun add pino pino-pretty o bun add ioredis si los necesitas.
winston eliminado de las dependencias (estaba listado pero nunca fue usado por el framework).
Bundle principal reducido de 444 KB → 408 KB (ESM minificado).

Deprecado

Export FastAPITS: usa VeloceTS o el alias corto Veloce en su lugar. FastAPITS será eliminado en v1.0.0.

[0.4.0] - 2026-03-27

Esta versión representa la mayor actualización desde el lanzamiento inicial. Se añadieron más de 25 mejoras distribuidas en tres oleadas de trabajo, cubriendo la cadena completa desde la generación de rutas hasta la documentación OpenAPI, el testing, el ORM y la CLI.

🚀 Nuevos Decoradores

Documentación OpenAPI (shorthand)

Cinco decoradores de una sola línea como alternativa concisa a @ApiDoc({...}):

@Summary(text) — descripción corta visible en la lista de Swagger UI
@Description(text) — texto largo en el panel de detalle de la operación
@Tag(name) — asigna un tag individual; apilable con múltiples @Tag
@Tags(...names) — asigna varios tags en un solo decorador
@Deprecated() — marca la ruta como obsoleta (tachado en Swagger UI)

Control de respuesta

@HttpCode(statusCode) — sobreescribe el código HTTP de respuesta del handler
@ResponseSchema(schema, statusCode?) — valida y sanitiza la respuesta con un esquema Zod; informa el modelo de respuesta al spec de OpenAPI

Middleware declarativo por ruta

@Timeout(ms, message?) — aborta la petición con 408 Request Timeout si el handler supera el límite. Emite el header X-Timeout-Ms
@RateLimit(options) — aplica rate-limiting a nivel de ruta individual. Los headers estándar X-RateLimit-* se envían automáticamente

🛠️ Mejoras al Framework Core

Generador OpenAPI

Auto-tagging: deriva tags automáticamente del primer segmento del path sin necesidad de anotarlos manualmente
Bearer security scheme: añade components.securitySchemes.bearerAuth al spec y aplica security: [{ bearerAuth: [] }] en rutas protegidas automáticamente
401 automático: rutas protegidas reciben una respuesta 401 Unauthorized documentada sin configuración adicional
Soporte de @HttpCode y @ResponseSchema en el spec generado

Sistema de Excepciones HTTP

Seis nuevas clases de excepción:

ConflictException (409), GoneException (410), PayloadTooLargeException (413)
UnprocessableEntityException (422), TooManyRequestsException (429), ServiceUnavailableException (503)

Logger estructurado en ErrorHandler

Errores 5xx se registran con getLogger().error incluyendo path, método, status y stack
Errores 4xx se registran como warn en entorno de desarrollo

🧪 TestClient — API fluida y helpers de autenticación

Reescritura completa de TestClient:

TestResponse con métodos encadenables: expectStatus(), expectOk(), expectCreated(), expectJson(), expectField(), expectHeader(), expectArrayLength()
withToken(token), withHeaders(headers) — instancias inmutables con auth pre-configurada
loginAs(credentials, endpoint?) — hace login y retorna cliente autenticado
registerAndLogin(user, endpoints?) — registra y hace login en una sola llamada
clearAuth() — limpia el token almacenado

🗄️ Drizzle ORM — Integración DI

registerDrizzle(app, db, token?) — registra como singleton en el DIContainer
@InjectDB(token?) — decorador de parámetro, alias de @Depends(DB_TOKEN)
DB_TOKEN — símbolo por defecto para el token de inyección

📊 Paginación mejorada

PaginationMeta incluye from y to (rango 1-based)
createCursorPaginatedResult con nuevo parámetro hadPrevCursor
createMultiCursor y decodeMultiCursor para cursores compuestos
paginate<T>(data, total, page, limit) — helper standalone
parseCursorQuery() y PaginationHelper.parsePaginationQuery() mejorados

🔌 Express Adapter — Compatibilidad ESM

Reescritura completa:

Carga Express de forma lazy usando Function('return require')()
Acepta instancia de Express pre-creada como segundo argumento
Manejo correcto de body raw vs. parseado
Delega errores al pipeline de Express via next(err)

🐛 Bug Fixes

ZodError cross-module: añadido fallback error.name === 'ZodError' para garantizar 422 en todos los casos
Rutas GET marcadas públicas retornaban 401: corregido con app.on(['POST', 'PUT', 'DELETE'], ...)
Cache collision en MetadataCompiler: solucionado con IDs únicos por función vía WeakMap
@Cache / @UseMiddleware perdían metadatos: solucionado actualizando el registro en cada decorador

📋 Mensajes de validación mejorados

La respuesta 422 ahora incluye: field (formato items[0].price), received, expected, minimum/maximum

💥 Breaking Changes

Ninguno — todos los cambios son retrocompatibles.

[0.3.3] - 2025-10-31

🐛 Bug Fixes Críticos

Serialización de Respuestas JSON: Corregido bug crítico de serialización
Resolución de Versión CLI: CLI ahora obtiene correctamente la última versión de npm
Compilación de la Aplicación: Corregida la falta de await app.compile() en plantillas generadas

🔧 Mejoras CLI

Obtención de versión corregida desde el registro npm
Todas las plantillas incluyen await app.compile()

[0.3.2] - 2025-10-31

Lanzamiento de parches con correcciones de build internas. Sin cambios funcionales.

[0.3.1] - 2025-10-31

🛠️ Mejoras CLI

Obtención de Última Versión: CLI obtiene automáticamente la última versión desde npm
Mejor Manejo de Errores: Mensajes más claros y limpieza al fallar la creación de proyectos
Indicadores de Progreso: Indicadores visuales mejorados durante la creación
Plantillas: Todas incluyen la llamada obligatoria a await app.compile()

[0.3.0] - 2025-10-29

🚀 Nuevas Características Principales

Sistema de Caché de Respuestas

Caché en Memoria: Caché LRU rápida con limpieza automática
Caché Redis: Soporte de caché distribuida para despliegues multi-instancia
Decorador @Cache(): Caché de respuestas declarativa con configuración flexible de TTL
Decorador @CacheInvalidate(): Invalidación de caché basada en patrones
Headers X-Cache: Headers automáticos HIT/MISS en respuestas

Contexto de Petición Mejorado

IDs de Petición Automáticos: Generación de UUID para cada petición
Decorador @RequestId(): Inyecta el ID de petición en métodos del controlador
Decorador @AbortSignal(): Soporte de cancelación para operaciones largas
Header X-Request-ID en todas las respuestas

Logging con Pino

Integración automática del ID de petición en todos los logs
Loggers hijo con herencia contextual
Logs JSON estructurados para producción
Pretty printing para desarrollo

🔧 Nuevo Middleware

createRequestContextMiddleware(), createSimpleRequestIdMiddleware()
createCacheMiddleware(), createCacheInvalidationMiddleware()

💥 Breaking Changes

Ninguno — todos los cambios son aditivos y retrocompatibles.

[0.2.6] - 2025-10-15

Corregido

Exportación de Query: Añadida la exportación faltante de Query del índice principal
Decoradores de Parámetro: @Query de HTTP ahora se exporta correctamente junto a los decoradores de GraphQL

[0.2.5] - 2025-10-15

Corregido

Conflicto de Query en GraphQL: Eliminado el alias conflictivo Query de los decoradores GraphQL
Los decoradores GraphQL ahora usan GQLQuery para evitar conflictos

Breaking Changes

Las queries de GraphQL ahora usan @GQLQuery en lugar de @Query

[0.2.4] - 2025-10-15

Corregido

Decorador @Query: Ahora maneja parámetros sin esquemas correctamente
Soporta @Query(), @Query('param') y @Query(Schema)

[0.2.3] - 2025-10-14

Corregido

Exportaciones WebSocket: Corregida la exportación faltante del decorador @WebSocket

[0.2.2] - 2025-10-14

Corregido

Decoradores GraphQL: Añadidos los alias faltantes Query, Mutation y Subscription

[0.2.0] - 2025-10-14

🚀 Características Principales Añadidas

Sistema de Autenticación Completo: JWT con tokens de acceso/refresco
Control de Acceso Basado en Roles (RBAC): Roles jerárquicos con sistema de permisos
Soporte WebSocket en Tiempo Real: Decoradores para WebSocket
Integración GraphQL: Soporte completo con resolvers y suscripciones
Herramienta CLI: Scaffolding de proyectos y generación de código

[0.1.0] - 2025-10-12

Añadido

Lanzamiento inicial del framework veloce-ts
Routing basado en decoradores
Validación automática con Zod
Sistema de inyección de dependencias
Generación automática de documentación OpenAPI
Soporte para WebSocket y GraphQL
CLI para scaffolding de proyectos
Soporte multi-runtime (Bun, Node.js, Deno, Cloudflare Workers)

:::tip Última Versión Recomendamos usar siempre la última versión de Veloce-TS para obtener la mejor experiencia y las últimas funciones. :::

:::note Breaking Changes Los cambios que rompen compatibilidad están claramente marcados en cada lanzamiento. Revisa el registro antes de actualizar a una nueva versión mayor. :::