xTaskjs 1.0 ya está disponible: cuentas por rol, documentación y una interfaz personalizable.

EN ES
Iniciar sesión Registrarse

Ejemplos

Aplicaciones de ejemplo oficiales para core, adaptadores, persistencia, cache, scheduling y queues.

Usa las aplicaciones de ejemplo como la ruta más corta hacia el framework. Muestran las combinaciones principales del runtime publicadas en el monorepo original, incluidos ejemplos centrados en mailer, cache, scheduler y queues, y los endpoints que expone cada una.

Ver ejemplos Abrir arquitectura

25 ejemplos de referencia documentados

Empieza pequeño

Usa 01-new_app para entender el arranque mínimo con node-http y el flujo de registro de rutas.

Cambia adaptadores

Compara los ejemplos de Express y Fastify para ver cómo los controladores permanecen estables mientras cambia el servidor.

Añade integraciones

Pasa a los ejemplos de TypeORM, security, mailer, cache, scheduler y queues cuando necesites persistencia, rutas protegidas, trabajo en segundo plano o flujos de entrega asíncrona.

Catálogo

Aplicaciones de referencia incluidas en el monorepo

samples/01-new_app

01-new_app

La aplicación más pequeña posible. Demuestra que core puede arrancar un servidor y enrutar un endpoint de salud sin adaptador externo.

node-http + core

Endpoints

  • GET /health

Flujo habitual

  1. Instala las dependencias dentro de la carpeta del ejemplo.
  2. Ejecuta npm start para arrancar CreateApplication() con node-http.
  3. Llama a /health para comprobar el registro del controlador y la configuración del logger.

samples/02-express_app

02-express_app

Muestra cómo una app Express existente se envuelve con ExpressAdapter mientras los controladores siguen devolviendo valores nativos del framework.

core + express-http

Endpoints

  • GET /
  • GET /health

Flujo habitual

  1. Crea una instancia de Express y habilita por tu cuenta body parsing u otros middlewares.
  2. Pasa la instancia a new ExpressAdapter(expressApp).
  3. Renderiza una home basada en plantillas y expone un endpoint JSON de salud.

samples/03-fastify_app

03-fastify_app

Demuestra la portabilidad del adaptador: el mismo estilo de controlador funciona sobre Fastify sin cambiar la lógica de negocio.

core + fastify-http

Endpoints

  • GET /
  • GET /health

Flujo habitual

  1. Crea una instancia de Fastify con sus propias opciones de logger/runtime.
  2. Envuélvela con FastifyAdapter.
  3. Reutiliza las mismas convenciones de controlador usadas por Express y node-http.

samples/04-typeorm_app

04-typeorm_app

Añade estado persistente sobre el adaptador de Fastify. El ejemplo siembra usuarios y demuestra el registro del ciclo de vida del datasource.

fastify-http + typeorm

Endpoints

  • GET /users/
  • POST /users/seed
  • GET /health/

Flujo habitual

  1. Decora una clase de configuración del datasource con TypeOrmDataSource().
  2. Arranca la aplicación con FastifyAdapter.
  3. Usa repositorios o datasources inyectados dentro de servicios para consultar y mutar el estado.

samples/06-security_app

06-security_app

Demuestra flujos JWT y JWE sin un adaptador web completo, centrándose en el registro de estrategias y controladores protegidos.

node-http + security

Endpoints

  • GET /health/
  • GET /auth/jwt/admin
  • GET /me/
  • GET /admin/
  • GET /encrypted/

Flujo habitual

  1. Registra estrategias JWT y JWE antes de CreateApplication().
  2. Emite un token de demostración desde /auth/jwt/admin.
  3. Usa Authorization: Bearer <token> contra /me/ y /admin/.

samples/07-security_express_app

07-security_express_app

Combina la integración de Express con decoradores de security y el módulo mailer, mostrando endpoints de perfil autenticado además de correos transaccionales y notificaciones protegidas.

express-http + security + mailer

Endpoints

  • GET /health/
  • GET /auth/jwt/admin
  • GET /me/
  • POST /me/notify
  • GET /admin/
  • GET /encrypted/

Flujo habitual

  1. Crea una app Express, registra estrategias JWT y JWE, y después registra transports y plantillas de correo durante el arranque.
  2. Obtén un token de demostración desde /auth/jwt/admin y llama a /me/ con Authorization: Bearer <token>.
  3. Haz POST a /me/notify para renderizar plantillas de correo del perfil y enviarlas mediante los transports default y notifications.

samples/08-email_express_app

08-email_express_app

Ejemplo dedicado a mailer que muestra transports con nombre, plantillas de correo basadas en EJS y servicios gestionados por DI que envían mensajes de bienvenida y campaña.

express-http + mailer

Endpoints

  • GET /health/
  • GET /email/
  • POST /email/welcome
  • POST /email/campaign

Flujo habitual

  1. Registra los transports default y notifications, y después conecta el renderer ejs-file y las plantillas de correo.
  2. Inicia la app Express mediante CreateApplication() e inspecciona /email/ para ver el contrato del ejemplo.
  3. Haz POST a /email/welcome o /email/campaign para renderizar plantillas y enviarlas a través del transporter configurado.

samples/09-internationalization_app

09-internationalization_app

Muestra resolución de locale por petición, helpers de traducción, formatters personalizados y carga diferida de namespaces sobre el adaptador node-http por defecto.

node-http + internationalization

Endpoints

  • GET /health
  • GET /i18n
  • GET /i18n?locale=es-ES&name=ada&items=3&amount=1499.95
  • GET /i18n/checkout?locale=en-US&items=2&amount=249.5

Flujo habitual

  1. Configura el locale por defecto, el fallback de locale y los formatters integrados antes de CreateApplication().
  2. Abre /i18n para inspeccionar mensajes traducidos, el estado del locale y los namespaces cargados.
  3. Accede a /i18n/checkout para activar la carga diferida de namespaces y el formateo localizado de números, moneda y fecha-hora.

samples/10-internationalization_express_app

10-internationalization_express_app

Combina renderizado de páginas localizadas con el adaptador de Express, incluyendo cambio de locale por query, soporte de Accept-Language y traducciones diferidas para checkout.

express-http + internationalization

Endpoints

  • GET /?locale=en-US&name=ada&items=3&amount=1499.95
  • GET /?locale=es-ES&name=ada&items=3&amount=1499.95
  • GET /checkout?locale=es-ES&name=ada&items=2&amount=249.5
  • GET /health

Flujo habitual

  1. Configura catálogos de locale y formatters personalizados, y después arranca una app Express mediante ExpressAdapter.
  2. Abre la página principal localizada y cambia entre en-US y es-ES mediante parámetros de consulta o Accept-Language.
  3. Sigue la ruta de checkout para probar la carga diferida de namespaces con vistas renderizadas en el servidor.

samples/11-scheduler_app

11-scheduler_app

Demuestra trabajos programados integrados con el ciclo de vida de xtask, incluyendo ejecución en arranque, grupos con nombre, reintentos y endpoints de inspección en tiempo de ejecución.

node-http + scheduler

Endpoints

  • GET /health
  • GET /scheduler/status
  • GET /scheduler/groups
  • GET /scheduler/run-maintenance

Flujo habitual

  1. Inicia el ejemplo para que CreateApplication() descubra los métodos programados después de que arranque el contenedor.
  2. Abre /scheduler/status para inspeccionar metadata de trabajos, contadores, fallos y eventos recientes.
  3. Llama a /scheduler/run-maintenance para disparar manualmente un grupo de trabajos con nombre y observar el comportamiento de reintento.

samples/12-cache_app

12-cache_app

Introduces cache models, method decorators, repository injection, and the built-in cache management controller on the default node-http adapter.

node-http + cache

Endpoints

  • GET /cache/products/:id
  • GET /cache/products/:id/inspect
  • GET /cache/products/:id/refresh
  • GET /cache/products/:id/evict
  • GET /ops/cache/models

Flujo habitual

  1. Configure the cache package with memory storage defaults and register a ProductCacheModel before CreateApplication().
  2. Call the product, refresh, and evict endpoints to observe Cacheable, CachePut, and CacheEvict behavior.
  3. Inspect /ops/cache/models and /cache/products/:id/inspect to verify repository state and generated admin metadata.

samples/13-cache_redis_app

13-cache_redis_app

Switches the same caching model to Redis so the decorators and repository APIs stay the same while storage moves out of process.

node-http + cache + redis

Endpoints

  • GET /cache/products/:id
  • GET /cache/products/:id/inspect
  • GET /cache/products/:id/refresh
  • GET /cache/products/:id/evict
  • GET /ops/cache/models

Flujo habitual

  1. Configure a Redis-backed cache model or client factory before boot so the lifecycle manager can open the store.
  2. Reuse the same service decorators and repository injection patterns from the memory sample.
  3. Use the inspect and admin endpoints to confirm Redis-backed entries, TTL behavior, and explicit eviction paths.

samples/14-http_cache_web_app

14-http_cache_web_app

Shows browser-facing cache policies on rendered pages and JSON endpoints, including ETag, Last-Modified, stale-while-revalidate, and preview no-store behavior.

express-http + cache

Endpoints

  • GET /
  • GET /articles/:slug
  • GET /api/articles/:slug
  • GET /preview
  • GET /ops/cache/http/routes

Flujo habitual

  1. Define package-wide httpCacheDefaults and then override them per route with CacheView, BrowserCache, and NoStore decorators.
  2. Request the same pages with conditional headers to observe ETag and Last-Modified handling on cached responses.
  3. Inspect /ops/cache/http/routes to verify the effective Cache-Control policy and validators resolved for each route.

samples/15-fastify_http_cache_web_app

15-fastify_http_cache_web_app

Ports the browser cache sample to Fastify to show that the same cache decorators and admin controller work across adapters.

fastify-http + cache

Endpoints

  • GET /
  • GET /articles/:slug
  • GET /api/articles/:slug
  • GET /preview
  • GET /ops/cache/http/routes

Flujo habitual

  1. Boot the app through FastifyAdapter while keeping the same CacheView, BrowserCache, NoStore, and management-controller setup.
  2. Compare the page and API endpoints with the Express version to confirm adapter-portable HTTP cache behavior.
  3. Use the admin routes to inspect merged cache policy, validators, and route metadata under Fastify as well.

samples/16-queues_memory_app

16-queues_memory_app

Introduce el paquete queues con el transporte integrado en memoria, consumidores decorados, listeners por patrones y flujos de publicación al devolver resultados.

node-http + queues

Endpoints

  • GET /queues/
  • GET /queues/status
  • POST /queues/orders
  • POST /queues/orders/:id/complete

Flujo habitual

  1. Configura configureQueues() con un transporte memory explícito y registerInMemoryQueueTransport() antes de CreateApplication().
  2. Haz POST a /queues/orders para publicar un mensaje y ver cómo los consumidores QueueHandler y QueuePattern actualizan el registro de eventos en memoria.
  3. Haz POST a /queues/orders/:id/complete para probar PublishToQueue() y observar flujos locales de colas encadenados.

samples/17-queues_rabbitmq_app

17-queues_rabbitmq_app

Traslada el mismo modelo de colas a RabbitMQ, añadiendo routing por topics, consumidores en competencia, reintentos y gestión de dead-letter mediante la utilidad del broker.

node-http + queues + rabbitmq

Endpoints

  • GET /health
  • GET /queues/
  • GET /queues/status
  • POST /queues/orders
  • POST /queues/orders/:id/fail
  • POST /queues/orders/:id/complete

Flujo habitual

  1. Configura el transporte por defecto con createRabbitMqTransport() y registerQueueTransport() antes de CreateApplication().
  2. Publica pedidos mediante /queues/orders y /queues/orders/:id/fail para inspeccionar reintentos, listeners de auditoría y el dead-letter routing.
  3. Abre /queues/status para inspeccionar consumidores iniciados, metadata de transports, grupos, ajustes de reintento y eventos recientes.

samples/19-cqrs_app

19-cqrs_app

Shows a full CQRS flow with separate SQLite write and read databases, injected buses, idempotent commands, event-driven projections, and projection rebuild support.

node-http + typeorm + cqrs

Endpoints

  • GET /cqrs/
  • GET /cqrs/users
  • GET /cqrs/debug/state
  • POST /cqrs/users
  • POST /cqrs/users/:id/onboard
  • POST /cqrs/projections/rebuild

Flujo habitual

  1. Register two TypeORM datasources and bind them to @Cqrs(...) as write-db and read-db before CreateApplication().
  2. Use CommandBus and QueryBus from the controller to create users, inspect read models, and trigger onboarding commands.
  3. Inspect /cqrs/debug/state and POST /cqrs/projections/rebuild to verify projection handlers, rebuilders, and read-model synchronization.

samples/20-cqrs_postgres_replication_app

20-cqrs_postgres_replication_app

Extends the CQRS sample to Postgres master and replica datasources so writes stay on the primary, reads come from the replica, and projection rebuild tooling remains part of the same lifecycle.

node-http + typeorm + cqrs + postgres

Endpoints

  • GET /cqrs/
  • GET /cqrs/users
  • GET /cqrs/debug/state
  • POST /cqrs/users
  • POST /cqrs/users/:id/rename
  • POST /cqrs/projections/rebuild

Flujo habitual

  1. Configure @xtaskjs/typeorm datasources for pg-master and pg-slave, then point @Cqrs(...) at those aliases before bootstrap.
  2. Route write-side commands through CommandBus while query handlers and injected read repositories use the replica datasource.
  3. Use the debug and rebuild endpoints to inspect replication-aware state, registered projection rebuilders, and lifecycle-managed read-model recovery.

samples/21-event_source_rabbitmq_app

21-event_source_rabbitmq_app

Demonstrates event-sourced aggregate writes backed by a SQLite event store, in-process projection updates, and RabbitMQ publication of stored domain events.

node-http + event-source + typeorm + queues + rabbitmq

Endpoints

  • GET /health
  • GET /event-source/
  • GET /event-source/users
  • GET /event-source/streams/:id
  • GET /event-source/status
  • POST /event-source/users
  • POST /event-source/users/:id/verify-email

Flujo habitual

  1. Configure @EventSource(...) with createTypeOrmEventStore() and createQueueEventPublisher(), then register a RabbitMQ transport before CreateApplication().
  2. Create and evolve aggregates through the POST endpoints, then inspect /event-source/streams/:id to verify replayed state and persisted event history.
  3. Open /event-source/status to inspect projection counts, started queue consumers, registered transports, and broker audit information.

samples/22-event_source_cqrs_app

22-event_source_cqrs_app

Shows the package boundary where event-source owns aggregate writes and stream persistence while CQRS builds and queries a separate read model.

node-http + event-source + typeorm + cqrs

Endpoints

  • GET /health
  • GET /interop/
  • GET /interop/users
  • GET /interop/state
  • GET /interop/streams/:id
  • POST /interop/users
  • POST /interop/users/:id/verify-email

Flujo habitual

  1. Register the event-store datasource and the separate read datasource, then bind event-source and CQRS to those aliases before bootstrap.
  2. Create users through the event-source endpoints and inspect /interop/streams/:id to confirm aggregate replay and stored event history.
  3. Query /interop/users and /interop/state to verify CQRS projections, runtime state, and the read-side model fed from persisted domain events.

samples/23-socket_io_express_app

23-socket_io_express_app

Aplicación de ejemplo con Express que usa gateways Socket.IO decorados, uniones a salas, acknowledgements automáticos y broadcasts disparados por HTTP.

express-http + socket-io

Endpoints

  • GET /
  • GET /health
  • GET /socket/
  • GET /socket/status
  • GET /socket/announce/:message

Flujo habitual

  1. Arranca Express mediante ExpressAdapter y deja que @xtaskjs/socket-io se conecte al servidor HTTP activo durante listen().
  2. Abre la página de demostración, únete al lobby del namespace /chat y emite eventos chat.join y chat.message desde el cliente del navegador.
  3. Llama a /socket/announce/:message para publicar un evento server.announcement desde un controlador HTTP mediante InjectSocketService().

samples/24-throttler_app

24-throttler_app

node-http application demonstrating global and per-endpoint rate limiting using configureThrottler and @Throttle decorators with memory storage.

node-http + throttler

Endpoints

  • GET /health
  • GET /items (throttled: 10 req / 30s)
  • GET /items/heavy (throttled: 2 req / 1m)
  • GET /items/open (no throttle)

Flujo habitual

  1. configureThrottler() registers global 100 req/min default with memory driver.
  2. Request arrives at a throttled endpoint.
  3. Throttler extracts the key (IP by default) and checks the counter in the store.
  4. Within limit: request proceeds normally to the controller handler.
  5. Over limit: 429 Too Many Requests is returned with a Retry-After header.

samples/25-testing_app

25-testing_app

Demonstrates isolated testing modules, DI overrides, lifecycle hooks, and in-memory test containers powered by @xtaskjs/testing.

node-http + testing

Endpoints

  • GET /health
  • GET /tests/status
  • POST /tests/run

Flujo habitual

  1. Build a testing module with Test.createTestingModule() and override providers for deterministic tests.
  2. Run controller and service-level assertions without booting a full production runtime.
  3. Close module references after each test to release lifecycle hooks and avoid shared state leaks.

samples/26-bots_app

26-bots_app

Unified bots sample using Telegram, Slack, and WhatsApp adapters with decorated gateway handlers in one runtime.

node-http + bots

Endpoints

  • GET /health
  • GET /bots/status
  • POST /bots/dispatch

Flujo habitual

  1. Register BotsModule adapters and decorate gateway handlers with command, message, and callback decorators.
  2. Dispatch messages through the unified runtime to keep platform-specific logic behind adapter boundaries.
  3. Inspect status endpoints to validate active adapters, handler groups, and dispatch diagnostics.

samples/27-bots_webhook_security_app

27-bots_webhook_security_app

Webhook-first bots sample with Slack and Telegram signature verification plus JWT-protected audit routes.

express-http + bots + security

Endpoints

  • GET /health
  • POST /webhooks/slack
  • POST /webhooks/telegram
  • GET /audit/events

Flujo habitual

  1. Configure webhook secrets and JWT validation through ConfigModule before startup.
  2. Receive signed webhook events, validate signatures, and dispatch bot handlers through @xtaskjs/bots.
  3. Expose protected audit endpoints using @xtaskjs/security to review webhook processing and runtime events.