Configuración

Referencia completa de configuración para aplicaciones YasuiJS usando yasui.createServer() y yasui.createApp().

Descripción General

YasuiJS proporciona dos formas principales de crear tu aplicación:

• yasui.createServer(config) - Crea e inicia un servidor automáticamente
• yasui.createApp(config) - Devuelve un manejador fetch para configuración manual del servidor

Ambos métodos aceptan el mismo objeto de configuración con las siguientes opciones.

Opciones de Configuración

Opciones Requeridas

controllers

Tipo: Array<Constructor>
Descripción: Array de clases controladoras para registrar en tu aplicación.

import yasui from 'yasui';

yasui.createServer({
  controllers: [UserController, ProductController]
});

Opciones Opcionales

middlewares

Array de middlewares globales para aplicar a todas las solicitudes. Deben ser clases middleware de YasuiJS decoradas con @Middleware().

• Tipo: Array<Constructor>
• Por defecto: []
• Valor de ejemplo: [LoggingMiddleware, AuthMiddleware]
• Nota: Los middlewares de Express (como cors(), helmet()) no son compatibles con YasuiJS 4.x

globalPipes

Array de pipes globales para aplicar a todos los parámetros de ruta. Ver Pipes para detalles.

• Tipo: Array<Constructor<IPipeTransform>>
• Por defecto: []
• Valor de ejemplo: [ValidationPipe, TrimPipe]

environment

Nombre del entorno para tu aplicación.

• Tipo: string
• Por defecto: undefined
• Valor de ejemplo: production

port

Número de puerto para el servidor. Solo se usa con createServer().

• Tipo: number | string
• Por defecto: 3000

hostname

Nombre del host al cual vincular el servidor.

• Tipo: string | undefined
• Por defecto: 'localhost' en desarrollo, undefined en producción

maxBodySize

Tamaño máximo del cuerpo de solicitud en bytes. Las solicitudes que excedan este límite serán rechazadas con 413 Payload Too Large.

• Tipo: number
• Por defecto: 10485760 (10MB)
• Nota: Esta es una verificación a nivel de aplicación que funciona en todos los runtimes (Node.js, Deno, Bun)

maxHeaderSize

Tamaño total máximo de encabezados en bytes. Las solicitudes que excedan este límite serán rechazadas con 413 Payload Too Large.

• Tipo: number
• Por defecto: 16384 (16KB)
• Nota: Esta es una verificación a nivel de aplicación que funciona en todos los runtimes.

tls

Configuración TLS/HTTPS. Cuando se proporciona, el servidor usa HTTPS automáticamente. Los tipos se extraen de srvx.

• Tipo: TLSConfig | undefined
• Por defecto: undefined (HTTP)
• Valor de ejemplo:

{
  cert: './path/to/cert.pem',  // o string PEM
  key: './path/to/key.pem',    // o string PEM
  passphrase: 'optional'       // frase de contraseña opcional de la clave
}

runtimeOptions

Opciones de configuración del servidor específicas del runtime. Se pasan directamente al servidor subyacente (srvx), que luego las pasa al runtime respectivo. Los tipos se extraen de ServerOptions de srvx para seguridad de tipos.

• Tipo: RuntimeOptions | undefined
• Por defecto: undefined
• Runtimes soportados: node, bun, deno, serviceWorker

Opciones disponibles por runtime:

• node: Acepta todas las Node.js HTTP ServerOptions, HTTPS ServerOptions, HTTP/2 ServerOptions, y ListenOptions, además de:

  • http2?: boolean - Habilitar HTTP/2 (por defecto: true con TLS)

• bun: Acepta todas las Bun.Serve.Options (excepto fetch)

• deno: Acepta todas las Deno.ServeOptions

• serviceWorker: Acepta configuración de service worker (ver docs de srvx)

Ejemplo:

yasui.createServer({
  controllers: [UserController],
  runtimeOptions: {
    node: {
      http2: true,
      maxHeadersize: 16384,
      ipv6Only: false
    }
  }
});

Nota: Para límites consistentes de tamaño de encabezados/cuerpo en todos los runtimes, usa las opciones de nivel raíz maxHeaderSize y maxBodySize. Las opciones específicas del runtime proporcionan defensa adicional en profundidad donde sea compatible.

debug

Habilitar modo debug con logging adicional y rastreo de solicitudes.

• Tipo: boolean
• Por defecto: false

injections

Tokens de inyección personalizados para inyección de dependencias. Ver Inyección de Dependencias para detalles.

• Tipo: Array<Injection>
• Por defecto: []

Donde Injection es:

{ token: string; provide: any } | // Valor directo
{ token: string; factory: () => Promise<any>; deferred?: boolean } // Factory

• Valores de ejemplo:

[
  // Valor directo
  { token: 'API_KEY', provide: 'value' },

  // Factory asíncrona (construida antes de que el servidor inicie)
  {
    token: 'DATABASE',
    factory: async () => {
      const db = new Database();
      await db.connect();
      return db;
    }
  },
  // Factory no bloqueante (el servidor inicia sin ella y acepta errores)
  {
    token: 'ANALYTICS',
    deferred: true,
    factory: async () => {
      const analytics = new AnalyticsClient();
      await analytics.connect();
      return analytics;
    },
  }
]

swagger

Configuración de documentación Swagger. Ver Swagger para detalles.

• Tipo: SwaggerConfig | undefined
• Por defecto: undefined
• Valor de ejemplo:

{
  enabled: true,
  path: '/api-docs',
  info: {
    title: 'Mi API',
    version: '1.0.0',
    description: 'Documentación de la API'
  }
}

enableDecoratorValidation

Habilitar validación de decoradores al inicio para detectar errores de configuración.

• Tipo: boolean
• Por defecto: true

strictValidation

Habilitar validación estricta de conversión de tipos y análisis JSON. Cuando está habilitado, lanza HttpError(400) en lugar de devolver valores inválidos (NaN, Invalid Date, null) o body indefinido.

• Tipo: boolean
• Por defecto: false
• Ver: Modo de Validación Estricta para comportamiento detallado y ejemplos

requestTimeout

Duración máxima de solicitud en milisegundos. Las solicitudes que excedan esta duración serán terminadas con 408 Request Timeout.

• Tipo: number
• Por defecto: 30000 (30 segundos)
• Nota: Previene que solicitudes de larga duración agoten los recursos del servidor. Establece en 0 para deshabilitar el timeout.

compression

Habilita la compresión gzip automática para las respuestas basándose en el encabezado Accept-Encoding del cliente.

• Tipo: boolean
• Por defecto: false
• Comportamiento:
  • Solo comprime cuando el cliente envía el encabezado Accept-Encoding: gzip
  • Solo comprime tipos de contenido basados en texto (JSON, HTML, CSS, JavaScript, XML)
  • Omite la compresión para formatos binarios (imágenes, videos, archivos)
  • Los navegadores y clientes HTTP (curl, Postman, fetch) descomprimen automáticamente las respuestas
• Ejemplo:

yasui.createServer({
  controllers: [UserController],
  compression: true  // Habilitar compresión gzip
});

• Nota: Requiere la API CompressionStream de Web Standards (Node.js 18+, Deno, Bun). Si no está disponible, la compresión se omitirá silenciosamente con una advertencia al inicio. Proporciona una reducción de ancho de banda del 70%+ para respuestas JSON/texto con mínima sobrecarga de CPU cuando está disponible.

createServer() vs createApp()

createServer()

Crea un servidor y comienza a escuchar automáticamente:

import yasui from 'yasui';

yasui.createServer({
  controllers: [UserController],
  port: 3000,
  debug: true
});

Usar cuando:

• Quieres iniciar tu servidor inmediatamente
• Estás construyendo una API estándar
• No necesitas configuración personalizada del servidor

createApp()

Devuelve un manejador fetch compatible con cualquier servidor o plataforma basada en Web Standards:

import yasui from 'yasui';

const app = yasui.createApp({
  controllers: [UserController]
});

// app.fetch es un manejador fetch estándar - usar con CUALQUIER servidor compatible

// Opción 1: SRVX (multi-runtime)
import { serve } from 'srvx';
serve({
  fetch: app.fetch,
  port: 3000
});

// Opción 2: Deno Nativo
Deno.serve({ port: 3000 }, app.fetch);

// Opción 3: Bun Nativo
Bun.serve({
  port: 3000,
  fetch: app.fetch
});

// Opción 4: Cloudflare Workers
export default {
  fetch: app.fetch
};

// Opción 5: Vercel Edge Functions
export const GET = app.fetch;
export const POST = app.fetch;

// Opción 6: Servidor http de Node.js
import { createServer } from 'http';
createServer(async (req, res) => {
  const response = await app.fetch(req);
  // Convertir Response a respuesta de Node.js
});

Usar cuando:

• Necesitas configuración personalizada del servidor
• Quieres más control sobre el inicio del servidor
• Estás desplegando en runtimes edge (Cloudflare Workers, Vercel Edge, Netlify Edge, Deno Deploy)
• Estás desplegando en plataformas serverless
• Estás integrando con características específicas de la plataforma

Despliegue en Runtime Edge

Para runtimes edge, usa createApp() para obtener un manejador fetch estándar:

const app = yasui.createApp({
  controllers: [UserController],
  middlewares: [CorsMiddleware]
});

// Desplegar en Cloudflare Workers
export default { fetch: app.fetch };

// Desplegar en Vercel Edge
export const GET = app.fetch;
export const POST = app.fetch;

// Desplegar en Deno Deploy
Deno.serve(app.fetch);

Modo Debug

Habilita el modo debug para ver información detallada:

yasui.createServer({
  controllers: [UserController],
  debug: true
});

El modo debug proporciona:

• Logging de solicitudes/respuestas
• Detalles de inyección de dependencias
• Información de registro de rutas
• Trazas de pila de errores

Environment

YasuiJS proporciona acceso a variables de entorno que es independiente del runtime. Úsalo en lugar de process.env para asegurar compatibilidad en Node.js, Deno y Bun.

• getEnv(name: string, fallback?: string): string - Leer variable de entorno con valor de respaldo opcional

import { getEnv, Injectable } from 'yasui';

@Injectable()
export class DatabaseService {
  private readonly dbUrl = getEnv('DATABASE_URL', 'localhost');
  private readonly port = getEnv('DB_PORT', '5432');

  connect() {
    console.log(`Conectando a ${this.dbUrl}:${this.port}`);
  }
}