Requerimientos básicos

• NestJS Starter
• Node.js v22.21.1 or higher (Download)
• YARN >= 1.22.22 o NPM >= 11.6.4
• NestJS v11.1.11 or higher (Documentación)
• Lerna

Arquitectura y configuración centralizada

Todos los paquetes de este toolkit siguen un patrón de configuración centralizada: en lugar de que cada módulo reciba su configuración de forma independiente, todos leen desde un único ConfigService de NestJS bajo la clave 'config'.

Cómo funciona

1. La aplicación host registra una función de configuración usando registerAs de @nestjs/config:

// configuration.ts
import { registerAs } from '@nestjs/config';
import { Typings } from '@tresdoce-nestjs-toolkit/core';

export default registerAs('config', (): Typings.AppConfig => ({
  project: { ... },
  server: { ... },
  swagger: { ... },
  redis: { ... },    // leído por @tresdoce-nestjs-toolkit/redis
  mailer: { ... },   // leído por @tresdoce-nestjs-toolkit/mailer
  // ...demás secciones opcionales
}));

2. Cada paquete de este toolkit inyecta ConfigService y accede únicamente a su propia sección del objeto config:

// Ejemplo interno de RedisModule
@Injectable()
export class RedisService {
  constructor(private readonly configService: ConfigService) {}

  getOptions() {
    return this.configService.get<Typings.AppConfig>('config').redis;
  }
}

3. La interfaz AppConfig (exportada por @tresdoce-nestjs-toolkit/core bajo el namespace Typings) es el contrato central que garantiza la coherencia de tipos entre todos los paquetes.

Ventajas del patrón

• Un solo punto de verdad: toda la configuración vive en configuration.ts.
• Tipado end-to-end: AppConfig valida en tiempo de compilación que cada sección tenga la forma correcta.
• Modularidad real: agregar o quitar un módulo equivale a agregar o quitar una clave del objeto de configuración.
• Compatible con schematics: los paquetes están diseñados para instalarse mediante ng add / schematics del NestJS Starter.

Interfaz AppConfig

La siguiente interfaz, definida en packages/core/src/typings/index.ts y exportada como Typings.AppConfig, es el contrato que une a todos los paquetes del toolkit.

// @tresdoce-nestjs-toolkit/core — Typings.AppConfig
interface AppConfig {
  // REQUERIDO — metadatos de la aplicación (leídos del package.json del proyecto host)
  project: {
    apiPrefix: string;
    name: string;
    version: string;
    description: string;
    author: { name: string; email: string; url: string };
    repository: { type: string; url: string };
    bugs: { url: string };
    homepage: string;
    [key: string]: any;
  };

  // REQUERIDO — configuración de runtime del servidor
  server: {
    isProd: boolean;
    appStage: 'local' | 'test' | 'snd' | 'dev' | 'qa' | 'homo' | 'prod';
    port: number;
    context: string;
    origins: string[] | string;
    propagateHeaders?: string[]; // -> response-parser
    exposedHeaders?: string;
    allowedHeaders: string;
    allowedMethods: string;
    corsEnabled: boolean;
    corsCredentials: boolean;
    csrf?: CsrfCookieOptions; // -> @tresdoce-nestjs-toolkit/core
    rateLimits?: ThrottlerModuleOptions; // -> @tresdoce-nestjs-toolkit/rate-limit
  };

  // REQUERIDO — configuración de Swagger/OpenAPI
  swagger: {
    path: string;
    enabled: boolean;
  };

  // OPCIONAL — configuración de health checks
  // -> @tresdoce-nestjs-toolkit/health
  health?: {
    skipChecks?: ('storage' | 'memory' | 'elasticsearch' | 'camunda' | 'typeorm' | 'redis')[];
    storage?: DiskHealthIndicatorOptions;
    memory?: { heap: number; rss: number };
  };

  // OPCIONAL — servicios externos para health checks de conectividad HTTP
  // -> @tresdoce-nestjs-toolkit/health
  services?: Record<
    string,
    {
      url: string;
      timeout?: number;
      healthPath?: string;
      [key: string]: any;
    }
  >;

  // OPCIONAL — configuración del cliente HTTP (Axios + axios-retry)
  // -> @tresdoce-nestjs-toolkit/http-client
  httpClient?: {
    httpOptions?: HttpModuleOptions;
    propagateHeaders?: string[];
  };

  // OPCIONAL — configuración de base de datos relacional vía TypeORM
  // -> @tresdoce-nestjs-toolkit/typeorm
  database?: {
    typeorm?: TypeOrmModuleOptions;
  };

  // OPCIONAL — configuración de Redis para cache
  // -> @tresdoce-nestjs-toolkit/redis
  redis?: RedisOptions;

  // OPCIONAL — configuración del mailer (nodemailer)
  // -> @tresdoce-nestjs-toolkit/mailer
  mailer?: MailerOptions;

  // OPCIONAL — configuración de Camunda (BPMN)
  // -> @tresdoce-nestjs-toolkit/camunda
  camunda?: CamundaOptions;

  // OPCIONAL — configuración de Elasticsearch
  // -> @tresdoce-nestjs-toolkit/elk
  elasticsearch?: ElasticsearchOptions;

  // OPCIONAL — configuración de trazabilidad distribuida (OpenTelemetry)
  // -> @tresdoce-nestjs-toolkit/tracing
  tracing?: TracingOptions;

  // OPCIONAL — configuración de redacción de campos sensibles en logs
  // -> @tresdoce-nestjs-toolkit/utils (RedactModule)
  redact?: RedactOptions;

  // OPCIONAL — configuración de hashing con bcrypt
  // -> @tresdoce-nestjs-toolkit/utils (BcryptModule)
  bcrypt?: BcryptOptions;

  // OPCIONAL — configuración de generación de IDs únicos tipo Snowflake
  // -> @tresdoce-nestjs-toolkit/snowflake-uid
  snowflakeUID?: SnowFlakeOptions;

  // OPCIONAL — configuración de AWS Simple Queue Service
  // -> @tresdoce-nestjs-toolkit/aws-sqs
  sqs?: AwsSqsModuleOptions;

  // OPCIONAL — parámetros personalizados de la aplicación
  params?: Record<string, any>;

  [key: string]: any;
}

Grafo de dependencias entre paquetes

El siguiente diagrama muestra las dependencias internas entre los paquetes del toolkit (dependencias hacia paquetes externos de npm no se muestran).

graph TD
  core["core\n(tipos base, decoradores, CSRF)"]
  utils["utils\n(Redact, Format, Bcrypt)"]
  filters["filters\n(ExceptionsFilter)"]
  tracing["tracing\n(OpenTelemetry)"]
  elk["elk\n(Elasticsearch)"]
  health["health\n(liveness/readiness)"]
  archetype["archetype\n(endpoint /info)"]
  httpClient["http-client\n(Axios wrapper)"]
  responseParser["response-parser\n(ResponseInterceptor)"]
  paas["paas\n(umbrella cross)"]
  rateLimits["rate-limit\n(ThrottlerModule)"]

  filters --> core
  tracing --> utils
  elk --> utils
  elk --> filters
  health --> core
  health --> tracing
  archetype --> core
  httpClient --> core
  responseParser --> filters
  paas --> core
  paas --> filters
  paas --> health
  paas --> responseParser
  paas --> tracing
  paas --> utils
  paas --> rateLimits

Paquetes standalone (sin dependencias internas entre si): aws-sqs, camunda, commons, dynamoose, mailer, qrcode, rate-limit, redis, snowflake-uid, typeorm, test-utils.

Scripts

Instalar Lerna

npm i -g lerna

Instalar dependencias del monorepo

yarn install

Crear paquetes

yarn plop

Transpilar paquetes

yarn build

Test paquetes

yarn test

Toolkit

Los módulos de la siguiente lista están pensados para ser consumidos por el NestJS Starter, siguiendo los lineamientos de schematics.

Es recomendable utilizar las versiones estables, ya que las versiones beta están pensadas para ser utilizadas a modo de testing y pueden generar conflictos en el código.

Commits

Para los mensajes de commits se toma como referencia conventional commits.

<type>[optional scope]: <description>

[optional body]

[optional footer]

• type: chore, docs, feat, fix, refactor, test (más comunes)
• scope: indica la página, componente, funcionalidad
• description: comienza en minúsculas y no debe superar los 72 caracteres.

Ejemplo Commit

git commit -m "docs(core): add documentantion to readme core module"

Commit Breaking Change

git commit -am 'feat!: changes in application'