@tndhuy/create-app 1.0.0

package/templates/postgres/src/common/interceptors/transform.interceptor.spec.ts

@@ -0,0 +1,52 @@
+import { Reflector } from '@nestjs/core';
+import { of } from 'rxjs';
+import { RAW_RESPONSE_KEY, TransformInterceptor } from './transform.interceptor';
+
+function createMockContext(isRaw: boolean) {
+  const reflector = new Reflector();
+  jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(isRaw);
+  const context = {
+    getHandler: () => jest.fn(),
+    getClass: () => jest.fn(),
+  } as any;
+  return { reflector, context };
+}
+
+describe('TransformInterceptor', () => {
+  it('should wrap controller return value in { success: true, data }', (done) => {
+    const { reflector, context } = createMockContext(false);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of({ id: '1', name: 'test' }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ success: true, data: { id: '1', name: 'test' } });
+      done();
+    });
+  });
+
+  it('should NOT wrap when @RawResponse() is used', (done) => {
+    const { reflector, context } = createMockContext(true);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of({ status: 'ok' }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ status: 'ok' });
+      done();
+    });
+  });
+
+  it('should wrap null return value in { success: true, data: null }', (done) => {
+    const { reflector, context } = createMockContext(false);
+    const interceptor = new TransformInterceptor(reflector);
+    const next = { handle: () => of(null) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ success: true, data: null });
+      done();
+    });
+  });
+
+  it('should use RAW_RESPONSE_KEY constant', () => {
+    expect(RAW_RESPONSE_KEY).toBe('raw_response');
+  });
+});

package/templates/postgres/src/common/interceptors/transform.interceptor.ts

@@ -0,0 +1,25 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { PUBLIC_API_KEY } from '../decorators/public-api.decorator';
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, unknown> {
+  constructor(private readonly reflector: Reflector) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(PUBLIC_API_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    // Internal first: If not explicitly marked as Public API, return RAW data
+    if (!isPublic) {
+      return next.handle();
+    }
+
+    // Public API: Wrap response in a standardized success object
+    return next.handle().pipe(map((data) => ({ success: true, data })));
+  }
+}

package/templates/postgres/src/common/middleware/correlation-id.middleware.spec.ts

@@ -0,0 +1,69 @@
+import { CORRELATION_ID_HEADER, CorrelationIdMiddleware } from './correlation-id.middleware';
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function createMockReq(headers: Record<string, string> = {}): any {
+  return { headers: { ...headers } };
+}
+
+function createMockRes(): any {
+  const headers: Record<string, string> = {};
+  return {
+    setHeader: (name: string, value: string) => {
+      headers[name] = value;
+    },
+    _headers: headers,
+  };
+}
+
+describe('CorrelationIdMiddleware', () => {
+  let middleware: CorrelationIdMiddleware;
+
+  beforeEach(() => {
+    middleware = new CorrelationIdMiddleware();
+  });
+
+  it('should generate UUID v4 when X-Correlation-ID header is absent', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    const correlationId = req.headers[CORRELATION_ID_HEADER.toLowerCase()];
+    expect(correlationId).toMatch(UUID_PATTERN);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should preserve existing X-Correlation-ID header', () => {
+    const req = createMockReq({ 'x-correlation-id': 'abc-123' });
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(req.headers['x-correlation-id']).toBe('abc-123');
+    expect(res._headers[CORRELATION_ID_HEADER]).toBe('abc-123');
+  });
+
+  it('should always set X-Correlation-ID on the response header', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(res._headers[CORRELATION_ID_HEADER]).toBeDefined();
+    expect(res._headers[CORRELATION_ID_HEADER]).toMatch(UUID_PATTERN);
+  });
+
+  it('should call next()', () => {
+    const req = createMockReq();
+    const res = createMockRes();
+    const next = jest.fn();
+
+    middleware.use(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/templates/postgres/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/postgres/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/postgres/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/postgres/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/postgres/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/postgres/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/postgres/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: 'postgresql://user:pass@localhost:5432/db',
+      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: 'postgresql://user:pass@localhost:5432/db' },
+        { 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/postgres/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/postgres/src/infrastructure/database/inject-prisma.decorator.ts

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

package/templates/postgres/src/infrastructure/database/prisma.module.ts

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

package/templates/postgres/src/infrastructure/database/prisma.service.ts

@@ -0,0 +1,21 @@
+import { Injectable, OnModuleInit, OnModuleDestroy, Logger } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(PrismaService.name);
+
+  constructor() {
+    super();
+  }
+
+  async onModuleInit(): Promise<void> {
+    await this.$connect();
+    this.logger.log('Prisma connected to database');
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.$disconnect();
+    this.logger.log('Prisma disconnected from database');
+  }
+}