@tndhuy/create-app 1.0.0

package/templates/mongo/src/common/middleware/correlation-id.middleware.ts

@@ -0,0 +1,26 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { NextFunction, Request, Response } from 'express';
+import { AsyncLocalStorage } from 'async_hooks';
+
+export const REQUEST_ID_HEADER = 'X-Request-Id';
+export const requestIdStorage = new AsyncLocalStorage<string>();
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction): void {
+    const requestId =
+      (req.headers[REQUEST_ID_HEADER.toLowerCase()] as string) || 
+      (req.headers['x-correlation-id'] as string) || 
+      randomUUID();
+
+    // Ensure it's in headers for downstream and logs
+    req.headers[REQUEST_ID_HEADER.toLowerCase()] = requestId;
+    res.setHeader(REQUEST_ID_HEADER, requestId);
+
+    // Wrap in AsyncLocalStorage so it's accessible everywhere
+    requestIdStorage.run(requestId, () => {
+      next();
+    });
+  }
+}

package/templates/mongo/src/infrastructure/cache/inject-redis.decorator.ts

@@ -0,0 +1,4 @@
+import { Inject } from '@nestjs/common';
+import { RedisService } from './redis.service';
+
+export const InjectRedis = () => Inject(RedisService);

package/templates/mongo/src/infrastructure/cache/redis.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { RedisService } from './redis.service';
+
+@Global()
+@Module({
+  providers: [RedisService],
+  exports: [RedisService],
+})
+export class CacheModule {}

package/templates/mongo/src/infrastructure/cache/redis.service.spec.ts

@@ -0,0 +1,174 @@
+import { RedisService } from './redis.service';
+import { trace } from '@opentelemetry/api';
+
+// ---- ioredis mock ----
+const mockRedisOn = jest.fn();
+const mockGet = jest.fn();
+const mockSet = jest.fn();
+const mockDel = jest.fn();
+const mockExpire = jest.fn();
+const mockQuit = jest.fn().mockResolvedValue('OK');
+
+const mockRedisInstance = {
+  on: mockRedisOn,
+  get: mockGet,
+  set: mockSet,
+  del: mockDel,
+  expire: mockExpire,
+  quit: mockQuit,
+};
+
+jest.mock('ioredis', () => {
+  return jest.fn().mockImplementation(() => mockRedisInstance);
+});
+
+// ---- cockatiel mock ----
+// circuitBreaker returns a policy whose execute() just calls the fn directly
+const mockPolicyExecute = jest.fn((fn: () => Promise<unknown>) => fn());
+
+jest.mock('cockatiel', () => ({
+  circuitBreaker: jest.fn(() => ({ execute: mockPolicyExecute })),
+  ConsecutiveBreaker: jest.fn(),
+  handleAll: {},
+}));
+
+describe('RedisService', () => {
+  let service: RedisService;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Re-establish required mock implementations after clearAllMocks()
+    mockQuit.mockResolvedValue('OK');
+    mockPolicyExecute.mockImplementation((fn: () => Promise<unknown>) => fn());
+    process.env.REDIS_URL = 'redis://localhost:6379';
+    service = new RedisService();
+  });
+
+  afterEach(async () => {
+    await service.onModuleDestroy();
+  });
+
+  describe('constructor', () => {
+    it('should initialise the Redis client immediately in the constructor', () => {
+      // The Redis constructor mock should have been called once
+      const RedisMock = require('ioredis');
+      expect(RedisMock).toHaveBeenCalledWith(
+        process.env.REDIS_URL,
+        expect.objectContaining({ enableOfflineQueue: false }),
+      );
+    });
+
+    it('should register connect and error event listeners on the client', () => {
+      expect(mockRedisOn).toHaveBeenCalledWith('connect', expect.any(Function));
+      expect(mockRedisOn).toHaveBeenCalledWith('error', expect.any(Function));
+    });
+  });
+
+  describe('get', () => {
+    it('should return the cached value for a key', async () => {
+      mockGet.mockResolvedValue('cached-value');
+      const result = await service.get('some-key');
+      expect(mockGet).toHaveBeenCalledWith('some-key');
+      expect(result).toBe('cached-value');
+    });
+
+    it('should return null when key does not exist', async () => {
+      mockGet.mockResolvedValue(null);
+      const result = await service.get('missing-key');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('set', () => {
+    it('should set a key-value pair without TTL', async () => {
+      mockSet.mockResolvedValue('OK');
+      await service.set('key', 'value');
+      expect(mockSet).toHaveBeenCalledWith('key', 'value');
+    });
+
+    it('should set a key-value pair with TTL in seconds', async () => {
+      mockSet.mockResolvedValue('OK');
+      await service.set('key', 'value', 60);
+      expect(mockSet).toHaveBeenCalledWith('key', 'value', 'EX', 60);
+    });
+  });
+
+  describe('del', () => {
+    it('should delete a key from the cache', async () => {
+      mockDel.mockResolvedValue(1);
+      await service.del('key-to-delete');
+      expect(mockDel).toHaveBeenCalledWith('key-to-delete');
+    });
+  });
+
+  describe('expire', () => {
+    it('should set an expiry time on an existing key', async () => {
+      mockExpire.mockResolvedValue(1);
+      await service.expire('some-key', 300);
+      expect(mockExpire).toHaveBeenCalledWith('some-key', 300);
+    });
+  });
+
+  describe('execute (circuit breaker)', () => {
+    it('should delegate operations through the circuit breaker policy', async () => {
+      mockGet.mockResolvedValue('value');
+      await service.get('test');
+      expect(mockPolicyExecute).toHaveBeenCalled();
+    });
+
+    it('should propagate errors when the circuit breaker is open', async () => {
+      const circuitOpenError = new Error('Circuit breaker is open');
+      mockPolicyExecute.mockRejectedValueOnce(circuitOpenError);
+      await expect(service.get('any-key')).rejects.toThrow(
+        'Circuit breaker is open',
+      );
+    });
+  });
+
+  describe('getClient', () => {
+    it('should return the underlying Redis client instance', () => {
+      const client = service.getClient();
+      expect(client).toBe(mockRedisInstance);
+    });
+  });
+
+  describe('onModuleDestroy', () => {
+    it('should quit the Redis client on module destroy', async () => {
+      await service.onModuleDestroy();
+      expect(mockQuit).toHaveBeenCalled();
+    });
+  });
+
+  describe('OTel tracing', () => {
+    it('should expose the OTel trace API (smoke test)', () => {
+      // When OTel SDK is not initialized, getTracer returns a no-op tracer
+      const t = trace.getTracer('test');
+      expect(t).toBeDefined();
+    });
+
+    it('get() should still resolve correctly with OTel no-op spans', async () => {
+      mockGet.mockResolvedValue('traced-value');
+      const result = await service.get('otel-key');
+      expect(result).toBe('traced-value');
+      expect(mockGet).toHaveBeenCalledWith('otel-key');
+    });
+
+    it('set() should still resolve correctly with OTel no-op spans', async () => {
+      mockSet.mockResolvedValue('OK');
+      await service.set('otel-key', 'otel-value', 30);
+      expect(mockSet).toHaveBeenCalledWith('otel-key', 'otel-value', 'EX', 30);
+    });
+
+    it('del() should still resolve correctly with OTel no-op spans', async () => {
+      mockDel.mockResolvedValue(1);
+      await service.del('otel-key');
+      expect(mockDel).toHaveBeenCalledWith('otel-key');
+    });
+
+    it('expire() should still resolve correctly with OTel no-op spans', async () => {
+      mockExpire.mockResolvedValue(1);
+      await service.expire('otel-key', 120);
+      expect(mockExpire).toHaveBeenCalledWith('otel-key', 120);
+    });
+  });
+});

package/templates/mongo/src/infrastructure/cache/redis.service.ts

@@ -0,0 +1,121 @@
+import { Injectable, OnModuleDestroy, Logger } from '@nestjs/common';
+import Redis from 'ioredis';
+import { circuitBreaker, ConsecutiveBreaker, CircuitBreakerPolicy, handleAll } from 'cockatiel';
+import { trace } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('redis-service');
+
+@Injectable()
+export class RedisService implements OnModuleDestroy {
+  private readonly client: Redis;
+  private readonly logger = new Logger(RedisService.name);
+  private readonly policy: CircuitBreakerPolicy;
+
+  constructor() {
+    // Initialize circuit breaker
+    this.policy = circuitBreaker(handleAll, {
+      halfOpenAfter: 10_000,
+      breaker: new ConsecutiveBreaker(5),
+    });
+
+    // Initialize Redis client in constructor — NOT onModuleInit.
+    // ConfigModule validates REDIS_URL at startup (fail-fast),
+    // so it is guaranteed available when CacheModule loads.
+    this.client = new Redis(process.env.REDIS_URL!, {
+      commandTimeout: 5000,
+      connectTimeout: 5000,
+      enableOfflineQueue: false,
+      maxRetriesPerRequest: 3,
+    });
+
+    this.client.on('connect', () => this.logger.log('Redis connected'));
+    this.client.on('error', (err) => this.logger.error('Redis error', err.message));
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.client?.quit();
+    this.logger.log('Redis disconnected');
+  }
+
+  getClient(): Redis {
+    return this.client;
+  }
+
+  async execute<T>(fn: (client: Redis) => Promise<T>): Promise<T> {
+    return this.policy.execute(() => fn(this.client));
+  }
+
+  async get(key: string): Promise<string | null> {
+    return tracer.startActiveSpan('redis.get', async (span) => {
+      try {
+        span.setAttribute('db.system', 'redis');
+        span.setAttribute('db.operation', 'get');
+        span.setAttribute('db.redis.key', key);
+        return await this.execute((c) => c.get(key));
+      } catch (error) {
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    return tracer.startActiveSpan('redis.set', async (span) => {
+      try {
+        span.setAttribute('db.system', 'redis');
+        span.setAttribute('db.operation', 'set');
+        span.setAttribute('db.redis.key', key);
+        if (ttlSeconds !== undefined) {
+          span.setAttribute('db.redis.ttl', ttlSeconds);
+        }
+        await this.execute(async (c) => {
+          if (ttlSeconds) {
+            await c.set(key, value, 'EX', ttlSeconds);
+          } else {
+            await c.set(key, value);
+          }
+        });
+      } catch (error) {
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  async del(key: string): Promise<void> {
+    return tracer.startActiveSpan('redis.del', async (span) => {
+      try {
+        span.setAttribute('db.system', 'redis');
+        span.setAttribute('db.operation', 'del');
+        span.setAttribute('db.redis.key', key);
+        await this.execute((c) => c.del(key).then(() => undefined));
+      } catch (error) {
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  async expire(key: string, ttlSeconds: number): Promise<void> {
+    return tracer.startActiveSpan('redis.expire', async (span) => {
+      try {
+        span.setAttribute('db.system', 'redis');
+        span.setAttribute('db.operation', 'expire');
+        span.setAttribute('db.redis.key', key);
+        span.setAttribute('db.redis.ttl', ttlSeconds);
+        await this.execute((c) => c.expire(key, ttlSeconds).then(() => undefined));
+      } catch (error) {
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+}

package/templates/mongo/src/infrastructure/config/config.module.ts

@@ -0,0 +1,36 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule as NestConfigModule } from '@nestjs/config';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { EnvironmentVariables } from './environment.validation';
+
+function validate(config: Record<string, unknown>) {
+  const validatedConfig = plainToInstance(EnvironmentVariables, config, {
+    enableImplicitConversion: true,
+  });
+
+  const errors = validateSync(validatedConfig, {
+    skipMissingProperties: false,
+  });
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Environment validation failed:\n${errors
+        .map((e) => Object.values(e.constraints ?? {}).join(', '))
+        .join('\n')}`,
+    );
+  }
+
+  return validatedConfig;
+}
+
+@Module({
+  imports: [
+    NestConfigModule.forRoot({
+      isGlobal: true,
+      validate,
+    }),
+  ],
+  exports: [NestConfigModule],
+})
+export class AppConfigModule {}

package/templates/mongo/src/infrastructure/config/environment.validation.spec.ts

@@ -0,0 +1,100 @@
+import 'reflect-metadata';
+import { validateSync } from 'class-validator';
+import { plainToInstance } from 'class-transformer';
+import { EnvironmentVariables } from './environment.validation';
+
+function buildConfig(overrides: Record<string, unknown> = {}): EnvironmentVariables {
+  return plainToInstance(
+    EnvironmentVariables,
+    {
+      DATABASE_URL: 'mongodb://localhost:27017/app',
+      REDIS_URL: 'redis://localhost:6379',
+      ...overrides,
+    },
+    { enableImplicitConversion: true },
+  );
+}
+
+describe('EnvironmentVariables', () => {
+  describe('valid configuration', () => {
+    it('should pass validation with all required fields provided', () => {
+      const config = buildConfig();
+      const errors = validateSync(config, { skipMissingProperties: false });
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should use default PORT of 3000 when PORT is not provided', () => {
+      const config = buildConfig();
+      expect(config.PORT).toBe(3000);
+    });
+
+    it('should use default NODE_ENV of development when NODE_ENV is not provided', () => {
+      const config = buildConfig();
+      expect(config.NODE_ENV).toBe('development');
+    });
+
+    it('should accept PORT within valid range (1–65535)', () => {
+      const config = buildConfig({ PORT: '8080' });
+      const errors = validateSync(config, { skipMissingProperties: false });
+      expect(errors).toHaveLength(0);
+      expect(config.PORT).toBe(8080);
+    });
+
+    it('should accept all valid NODE_ENV values', () => {
+      for (const env of ['development', 'production', 'test']) {
+        const config = buildConfig({ NODE_ENV: env });
+        const errors = validateSync(config, { skipMissingProperties: false });
+        expect(errors).toHaveLength(0);
+      }
+    });
+  });
+
+  describe('missing required fields', () => {
+    it('should fail validation when DATABASE_URL is missing', () => {
+      const config = plainToInstance(
+        EnvironmentVariables,
+        { REDIS_URL: 'redis://localhost:6379' },
+        { enableImplicitConversion: true },
+      );
+      const errors = validateSync(config, { skipMissingProperties: false });
+      const fieldNames = errors.map((e) => e.property);
+      expect(fieldNames).toContain('DATABASE_URL');
+    });
+
+    it('should fail validation when REDIS_URL is missing', () => {
+      const config = plainToInstance(
+        EnvironmentVariables,
+        { DATABASE_URL: 'mongodb://localhost:27017/app' },
+        { enableImplicitConversion: true },
+      );
+      const errors = validateSync(config, { skipMissingProperties: false });
+      const fieldNames = errors.map((e) => e.property);
+      expect(fieldNames).toContain('REDIS_URL');
+    });
+  });
+
+  describe('PORT validation', () => {
+    it('should fail validation when PORT is below 1', () => {
+      const config = buildConfig({ PORT: '0' });
+      const errors = validateSync(config, { skipMissingProperties: false });
+      const portErrors = errors.filter((e) => e.property === 'PORT');
+      expect(portErrors.length).toBeGreaterThan(0);
+    });
+
+    it('should fail validation when PORT exceeds 65535', () => {
+      const config = buildConfig({ PORT: '65536' });
+      const errors = validateSync(config, { skipMissingProperties: false });
+      const portErrors = errors.filter((e) => e.property === 'PORT');
+      expect(portErrors.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('NODE_ENV whitelist', () => {
+    it('should fail validation when NODE_ENV is not in the allowed list', () => {
+      const config = buildConfig({ NODE_ENV: 'staging' });
+      const errors = validateSync(config, { skipMissingProperties: false });
+      const nodeEnvErrors = errors.filter((e) => e.property === 'NODE_ENV');
+      expect(nodeEnvErrors.length).toBeGreaterThan(0);
+    });
+  });
+});

package/templates/mongo/src/infrastructure/config/environment.validation.ts

@@ -0,0 +1,21 @@
+import { IsString, IsInt, IsIn, IsOptional, Min, Max } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+export class EnvironmentVariables {
+  @IsString()
+  DATABASE_URL: string;
+
+  @IsString()
+  REDIS_URL: string;
+
+  @IsOptional()
+  @Transform(({ value }) => parseInt(value, 10))
+  @IsInt()
+  @Min(1)
+  @Max(65535)
+  PORT: number = 3000;
+
+  @IsOptional()
+  @IsIn(['development', 'production', 'test'])
+  NODE_ENV: string = 'development';
+}

package/templates/mongo/src/infrastructure/database/mongodb.module.ts

@@ -0,0 +1,17 @@
+import { Global, Module } from '@nestjs/common';
+import { MongooseModule } from '@nestjs/mongoose';
+import { ConfigService } from '@nestjs/config';
+
+@Global()
+@Module({
+  imports: [
+    MongooseModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        uri: config.get<string>('DATABASE_URL'),
+      }),
+    }),
+  ],
+  exports: [MongooseModule],
+})
+export class MongoDBModule {}

package/templates/mongo/src/infrastructure/health/health.controller.ts

@@ -0,0 +1,46 @@
+import { Controller, Get } from '@nestjs/common';
+import { HealthCheck, HealthCheckService } from '@nestjs/terminus';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import { PrismaHealthIndicator } from './prisma.health-indicator';
+import { RedisHealthIndicator } from './redis.health-indicator';
+import { RawResponse } from '../../common';
+
+@ApiTags('health')
+@Controller('health')
+export class HealthController {
+  constructor(
+    private health: HealthCheckService,
+    private db: PrismaHealthIndicator,
+    private redis: RedisHealthIndicator,
+  ) {}
+
+  @Get()
+  @HealthCheck()
+  @RawResponse()
+  @ApiOperation({ summary: 'Overall health check' })
+  check() {
+    return this.health.check([
+      () => this.db.isHealthy('database'),
+      () => this.redis.isHealthy('redis'),
+    ]);
+  }
+
+  @Get('ready')
+  @HealthCheck()
+  @RawResponse()
+  @ApiOperation({ summary: 'Readiness probe' })
+  ready() {
+    return this.health.check([
+      () => this.db.isHealthy('database'),
+      () => this.redis.isHealthy('redis'),
+    ]);
+  }
+
+  @Get('live')
+  @HealthCheck()
+  @RawResponse()
+  @ApiOperation({ summary: 'Liveness probe' })
+  live() {
+    return this.health.check([]);
+  }
+}

package/templates/mongo/src/infrastructure/health/health.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { HealthController } from './health.controller';
+import { PrismaHealthIndicator } from './prisma.health-indicator';
+import { RedisHealthIndicator } from './redis.health-indicator';
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+  providers: [PrismaHealthIndicator, RedisHealthIndicator],
+})
+export class HealthModule {}

package/templates/mongo/src/infrastructure/health/redis.health-indicator.ts

@@ -0,0 +1,20 @@
+import { Injectable } from '@nestjs/common';
+import { HealthIndicator, HealthIndicatorResult, HealthCheckError } from '@nestjs/terminus';
+import { RedisService } from '../cache/redis.service';
+
+@Injectable()
+export class RedisHealthIndicator extends HealthIndicator {
+  constructor(private readonly redis: RedisService) {
+    super();
+  }
+
+  async isHealthy(key: string): Promise<HealthIndicatorResult> {
+    try {
+      const result = await this.redis.getClient().ping();
+      const isUp = result === 'PONG';
+      return this.getStatus(key, isUp);
+    } catch (error) {
+      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
+    }
+  }
+}

package/templates/mongo/src/instrumentation.spec.ts

@@ -0,0 +1,24 @@
+describe('instrumentation.ts feature flag', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('should export null when OTEL_ENABLED is not set', async () => {
+    delete process.env.OTEL_ENABLED;
+    const mod = await import('./instrumentation');
+    expect(mod.default).toBeNull();
+  });
+
+  it('should export null when OTEL_ENABLED is "false"', async () => {
+    process.env.OTEL_ENABLED = 'false';
+    const mod = await import('./instrumentation');
+    expect(mod.default).toBeNull();
+  });
+});

package/templates/mongo/src/instrumentation.ts

@@ -0,0 +1,44 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+
+let sdk: NodeSDK | null = null;
+
+if (process.env.OTEL_ENABLED === 'true') {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { resourceFromAttributes } = require('@opentelemetry/resources');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-base');
+
+    const serviceName = process.env.OTEL_SERVICE_NAME ?? 'nestjs-backend-template';
+    const prometheusPort = parseInt(process.env.OTEL_PROMETHEUS_PORT ?? '9464', 10);
+
+    const prometheusExporter = new PrometheusExporter({ port: prometheusPort });
+
+    const traceExporter = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+      ? new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT })
+      : new ConsoleSpanExporter();
+
+    const instrumentations = getNodeAutoInstrumentations({
+      '@opentelemetry/instrumentation-dns': { enabled: false },
+      '@opentelemetry/instrumentation-fs': { enabled: false },
+    });
+
+    sdk = new NodeSDK({
+      resource: resourceFromAttributes({ 'service.name': serviceName }),
+      metricReader: prometheusExporter,
+      traceExporter,
+      instrumentations,
+    });
+  } catch (err) {
+    console.error('[OTel] Failed to initialize OpenTelemetry SDK:', err);
+    sdk = null;
+  }
+}
+
+export default sdk;