Limitaciones y hoja de ruta

Limitaciones y hoja de ruta

Esta página es deliberadamente clara: qué aún no está redondo y hacia dónde apuntamos. No es un plan con fechas: el orden y los tiempos pueden cambiar. Para lo ya publicado, revisa el Registro de cambios.

Limitaciones actuales

Área	Qué esperar
Schema stitching de GraphQL	Las queries, las mutaciones y —desde v3.4.0— las suscripciones se ejecutan todas. El schema stitching sigue sin estar endurecido; compón los esquemas en el gateway en lugar de apoyarte en el plugin para eso.
Integraciones ORM	Drizzle tiene ayudas de primer nivel en el DI (registerDrizzle, @InjectDB). Prisma y TypeORM aún no están al mismo nivel de integración documentada en el core; puedes usarlos directamente en tus servicios. Los tres proveen count/updateMany/deleteMany nativos; un repositorio propio debe sobrescribirlos (las implementaciones base ahora lanzan NotImplementedError en lugar de escanear toda la tabla en silencio).
Cobertura de tests	La cobertura de líneas sobre src/ es de ~57%, con el gate de CI en 55% para evitar regresiones. Lo más delgado que queda, medido: los middlewares de caché y de contexto de petición (~3%), el middleware de logging y el plugin de health (~5%), el plugin de WebSocket (~7%), y los ayudantes de OAuth y permisos junto a los decoradores RBAC (~10–21%). Trata esos caminos con más cautela que el núcleo de enrutamiento/validación.

Qué se publicó en v3.4.0

• ✅ Las suscripciones GraphQL se ejecutan — el hueco más grande que quedaba. Solo se generaban en el SDL y nada más; no había transporte de ejecución, así que suscribirse no hacía nada. GraphQLPlugin las sirve ahora sobre graphql-transport-ws (el subprotocolo que hablan Apollo Client, urql, GraphiQL y el cliente graphql-ws) en Bun, Deno y Node, con un PubSub construido sobre el bus de eventos, autenticación por conexión vía connectionParams y contrapresión acotada. El protocolo es propio del framework, así que CI lo corre contra el cliente oficial graphql-ws en vez de dar por hecha la interoperabilidad. Ver GraphQL → Suscripciones.
• ✅ app.listen(0) informa el puerto que obtuvo — devolvía el puerto solicitado, así que pedirle uno libre al sistema te dejaba con 0.
• ✅ Un gateway de WebSocketPlugin y el endpoint de suscripciones conviven en Node — cada uno creaba su propia instancia de @hono/node-ws, y cada instancia termina cualquier upgrade para el que no encuentra dueño, así que los dos se destruían las conexiones mutuamente.

Qué se publicó en v3.3.0

• ✅ El decorador @On('event') — listeners declarativos, registrados con app.include() y resueltos por el contenedor de DI, así que un listener inyecta los mismos servicios que un controlador. Las suscripciones se enganchan en compile() y se sueltan en shutdown(), lo que importa sobre el globalEvents del proceso: sin eso, cada app construida en una suite de tests responde al mismo evento. new VeloceTS({ eventBus }) acepta un bus propio. Ver Event Bus.

Qué se publicó en v3.2.0

• ✅ WebSockets en Node.js — la limitación más antigua del framework. El upgrade en Node pasa ahora por la peer dependency opcional @hono/node-ws; los decoradores y la API de WebSocketConnection son idénticos en Bun, Deno y Node. El plugin se engancha en onStart(), así que la app debe servirse con app.listen(). Los cuatro templates de la CLI, websocket y fullstack incluidos, ya arrancan bajo Node en CI. Ver WebSockets.
• ✅ El paquete publicado bajó 72% — de 1.5 MB a 0.41 MB empaquetado, quitando los sourcemaps de JS y 351 KB de mapas de declaración que apuntaban a un src/ que el paquete no publica.
• ✅ Las declaraciones funcionan con node16/nodenext — antes los tipos publicados solo resolvían con moduleResolution: bundler.

Qué se publicó en v3.1.0

• ✅ La CLI funciona en Node — veloce dev y veloce build detectan el runtime y aceptan --runtime auto|bun|node; los caminos de Node usan tsx y tsc
• ✅ Los proyectos generados corren en Node — antes emitían una config de CORS que el framework rechaza (así que la app reventaba al arrancar), imports sin extensión que el cargador ESM de Node no resuelve, y scripts que fijaban bun
• ✅ Smoke test de templates en CI — cada template se genera, instala, compila, construye y arranca con Node en cada ejecución

Siguen siendo solo Bun/Deno: los templates websocket y fullstack, porque WebSocketPlugin todavía no tiene camino de upgrade en Node. veloce new avisa de esto al generarlos.

Qué se publicó en v3.0.0

Los guards de ruta no se aplicaban antes de v3.0.0

@Auth(), @Session(), @RequireCSRF() y la familia @CanAccess no hacían nada en ninguna versión 2.x: los 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 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.

• ✅ Guards que sí se aplican — los tres plugins afectados inyectan su guard durante install()
• ✅ Cookies de sesión firmadas — SessionConfig.secret es obligatorio y la cookie va firmada con HMAC; antes llevaba el id de sesión en crudo
• ✅ Rotación atómica de refresh tokens — dos refrescos concurrentes con el mismo token ya no tienen éxito los dos
• ✅ Límite de cuerpo de petición — bodyLimit, 1 MiB por defecto
• ✅ Claves de caché por llamante — varyByHeaders / keyGenerator en @Cache(), más un aviso al compilar cuando se cachea una ruta por usuario con clave compartida
• ✅ El listen() de Node funciona de verdad — usaba require() dentro del bundle ESM, así que siempre lanzaba
• ✅ Los filtros de excepción ven errores de validación y DI; @UseInterceptor a nivel de clase se ejecuta; el contenedor DI ya no reporta ciclos falsos con concurrencia
• ✅ Rate limiting distribuido — RedisRateLimitStore
• ✅ Variables de contexto tipadas — c.get('auth.user') viene tipado

Qué se publicó en v2.0.0

GraphQL estaba roto antes de v2.0.0

Las versiones anteriores — incluida la v1.0.1 que esta misma página anunciaba como “funcionando” — conectaban los resolvers en una forma de rootValue que graphql-js nunca lee, así que toda query resolvía a null, y el tipo de retorno de cada campo estaba fijado a String, lo que significa que los tipos de objeto nunca se emitían. Ambas cosas están corregidas: los resolvers se adjuntan directamente a los campos del schema, y los tipos de objeto/entrada se derivan de tus schemas Zod.

• ✅ Seguridad — los refresh tokens ya no pueden reutilizarse como access tokens; RS256/384/512 firman de verdad de forma asimétrica (antes usaban el secreto HMAC compartido); el rate limiting ya no confía en el X-Forwarded-For del cliente salvo que se active trustProxy
• ✅ El soporte de Node.js ahora sí funciona — la 1.2.0 publicada tenía cuatro bugs de empaquetado que la rompían para consumidores de Node, incluida una copia duplicada de Zod que rompía en silencio las comprobaciones instanceof contra tus propios schemas
• ✅ Rendimiento — el dispatch de peticiones mejoró bastante respecto a v0.4.18; el paquete pesa 1.33 MB, contra 3.82 MB
• ✅ API funcional tipada — los argumentos del handler se infieren del conjunto de schemas Zod declarado
• ✅ Revocación distribuida de tokens — RedisTokenBlacklist propaga el logout entre réplicas
• ✅ Ciclo de vida de plugins — hooks onStart / onStop
• ✅ Cloudflare Workers — app.getFetchHandler() es la vía soportada para desplegar
• ✅ Endurecimiento de WebSocket (Bun/Deno) — heartbeat, timeout de inactividad, tamaño máximo de mensaje
• ✅ El CLI corre bajo Node puro — antes requería Bun

Qué se publicó en v1.2.0

Todos los elementos P0 y P1 de la hoja de ruta están ahora disponibles:

• ✅ CLI scaffolding — veloce generate module/controller/service/resolver/dto/middleware/plugin
• ✅ Apagado gradual — app.onShutdown(), SIGTERM/SIGINT, timeout configurable
• ✅ Filtros de excepción — @Catch(), app.useFilter(), FilterManager
• ✅ Interceptores — @UseInterceptor(), app.useInterceptor(), ExecutionContext
• ✅ Respuestas en streaming — @SSE(), @Stream(contentType) en handlers AsyncGenerator
• ✅ Bus de eventos — EventBus, singleton globalEvents
• ✅ Decoradores extra — @Throttle, @ApiVersion, @ResponseHeader, @Redirect, @Deprecated
• ✅ Aislamiento de tests — isolate(), compileTestApp()
• ✅ OpenAPI 3.1 — jsonSchemaDialect, normalización de nullable

Próximas actualizaciones (dirección)

Prioridades del equipo; no es promesa de orden ni de fecha.

1. Elegir ORM — Que Drizzle, Prisma y TypeORM sean opciones prácticas y documentadas para que cada proyecto elija su ORM sin fricción con el framework.
2. Schema stitching de GraphQL — Las suscripciones se ejecutan desde v3.4.0; componer esquemas entre servicios es la parte que sigue sin estar endurecida.
3. Subir el piso de cobertura — El gate de CI está en 55% para bloquear regresiones; la meta es elevarlo conforme se cubran las áreas delgadas de arriba.

Ya publicado: una suite de benchmarks reproducible que compara Veloce-TS contra Hono, Express y Fastify (BENCHMARKS.md, bun run benchmark). Resumen honesto: Veloce-TS cuesta entre 2% y 11% sobre Hono crudo — el precio de la capa de decoradores, más amplio en una ruta trivial /hello y más estrecho en validación Zod, donde Zod domina el coste de ambos lados — y es aproximadamente 1.8× más rápido que Express 4 y 1.3–1.4× más rápido que Fastify 5 bajo Bun. Elysia y NestJS no están incluidos todavía.

Ediciones anteriores afirmaban que Veloce-TS superaba a Hono crudo en dos escenarios. Esas cifras venían de mediciones de una sola pasada cuyo resultado se invertía entre corridas; el harness ahora repite cada medición y reporta una mediana con su dispersión.

Cómo aportar o debatir

• Cambios ya publicados: Registro de cambios y el repositorio en GitHub.
• Ideas y propuestas: GitHub Discussions.