@tndhuy/create-app 1.0.0

package/templates/postgres/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/postgres/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/postgres/src/infrastructure/health/prisma.health-indicator.ts

@@ -0,0 +1,19 @@
+import { Injectable } from '@nestjs/common';
+import { HealthIndicator, HealthIndicatorResult, HealthCheckError } from '@nestjs/terminus';
+import { PrismaService } from '../database/prisma.service';
+
+@Injectable()
+export class PrismaHealthIndicator extends HealthIndicator {
+  constructor(private readonly prisma: PrismaService) {
+    super();
+  }
+
+  async isHealthy(key: string): Promise<HealthIndicatorResult> {
+    try {
+      await this.prisma.$queryRaw`SELECT 1`;
+      return this.getStatus(key, true);
+    } catch (error) {
+      throw new HealthCheckError('Database check failed', this.getStatus(key, false));
+    }
+  }
+}

package/templates/postgres/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/postgres/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/postgres/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;

package/templates/postgres/src/main.ts

@@ -0,0 +1,102 @@
+import otelSdk from './instrumentation';
+import { NestFactory, Reflector } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { VersioningType, ValidationPipe } from '@nestjs/common';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { Logger } from 'nestjs-pino';
+import { apiReference } from '@scalar/nestjs-api-reference';
+import basicAuth from 'express-basic-auth';
+import { AppModule } from './app.module';
+import { HttpExceptionFilter } from './common/filters/http-exception.filter';
+import { TransformInterceptor } from './common/interceptors/transform.interceptor';
+import { TimeoutInterceptor } from './common/interceptors/timeout.interceptor';
+import { validationOptions } from './shared/validation-options';
+import { LoggerService } from './shared/logger/logger.service';
+
+async function bootstrap() {
+  otelSdk?.start();
+
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    bufferLogs: true,
+  });
+
+  app.useLogger(app.get(Logger));
+
+  app.set('trust proxy', 1);
+
+  const apiVersion = process.env.API_VERSION ?? '1';
+
+  app.setGlobalPrefix('api', {
+    exclude: ['/health', '/health/ready', '/health/live'],
+  });
+
+  app.enableVersioning({ type: VersioningType.URI, defaultVersion: apiVersion });
+
+  app.useGlobalPipes(new ValidationPipe(validationOptions));
+
+  const reflector = app.get(Reflector);
+  const loggerService = app.get(LoggerService);
+
+  app.useGlobalFilters(new HttpExceptionFilter(loggerService));
+
+  app.useGlobalInterceptors(
+    new TransformInterceptor(reflector),
+    new TimeoutInterceptor(),
+  );
+
+  // Swagger document
+  const documentBuilder = new DocumentBuilder()
+    .setTitle(process.env.APP_NAME ?? 'NestJS Backend Template')
+    .setDescription(process.env.APP_DESCRIPTION ?? 'API Documentation')
+    .setVersion(apiVersion)
+    .addBearerAuth()
+    .build();
+  const document = SwaggerModule.createDocument(app, documentBuilder);
+
+  // Serve raw spec at /docs/json
+  SwaggerModule.setup('docs/json', app, document, {
+    jsonDocumentUrl: '/docs/json',
+  });
+
+  // Basic auth for /docs
+  const docsUser = process.env.DOCS_USER ?? 'admin';
+  const docsPass =
+    process.env.DOCS_PASS ??
+    (process.env.NODE_ENV === 'production' ? undefined : 'admin');
+  if (docsPass) {
+    app.use(
+      '/docs',
+      basicAuth({ users: { [docsUser]: docsPass }, challenge: true }),
+    );
+  }
+
+  // Scalar API reference at /docs
+  app.use(
+    '/docs',
+    apiReference({
+      content: document,
+      spec: { content: document },
+      hiddenClients: ['fetch', 'xhr'],
+      configuration: { agent: { disabled: true } },
+    }),
+  );
+
+  const port = parseInt(process.env.PORT ?? '3000', 10);
+  const httpServer = await app.listen(port);
+
+  process.on('SIGTERM', () => {
+    loggerService.log('SIGTERM signal received: closing HTTP server');
+    setTimeout(() => {
+      void otelSdk?.shutdown().catch(() => undefined);
+      httpServer.close(() => {
+        loggerService.log('HTTP server closed');
+        process.exit(0);
+      });
+    }, 15000);
+  });
+
+  const logger = app.get(Logger);
+  logger.log(`Application running on http://localhost:${port}`);
+}
+
+void bootstrap();

package/templates/postgres/src/modules/example/application/commands/create-item.command.ts

@@ -0,0 +1,3 @@
+export class CreateItemCommand {
+  constructor(public readonly name: string) {}
+}

package/templates/postgres/src/modules/example/application/commands/create-item.handler.spec.ts

@@ -0,0 +1,49 @@
+import { CreateItemHandler } from './create-item.handler';
+import { CreateItemCommand } from './create-item.command';
+import { IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+
+describe('CreateItemHandler', () => {
+  let handler: CreateItemHandler;
+  let mockRepository: jest.Mocked<IItemRepository>;
+
+  beforeEach(() => {
+    mockRepository = {
+      findById: jest.fn(),
+      findAll: jest.fn(),
+      save: jest.fn().mockResolvedValue(undefined),
+      delete: jest.fn(),
+    };
+
+    handler = new CreateItemHandler(mockRepository);
+  });
+
+  it('should call repository.save with an Item constructed from the command name', async () => {
+    const command = new CreateItemCommand('Widget');
+
+    await handler.execute(command);
+
+    expect(mockRepository.save).toHaveBeenCalledTimes(1);
+    const savedItem: Item = mockRepository.save.mock.calls[0][0];
+    expect(savedItem).toBeInstanceOf(Item);
+    expect(savedItem.name.value).toBe('Widget');
+  });
+
+  it('should return a non-empty string id after saving', async () => {
+    const command = new CreateItemCommand('Gadget');
+
+    const result = await handler.execute(command);
+
+    expect(typeof result).toBe('string');
+    expect(result.length).toBeGreaterThan(0);
+  });
+
+  it('should generate a unique id for each execution', async () => {
+    const command = new CreateItemCommand('Widget');
+
+    const id1 = await handler.execute(command);
+    const id2 = await handler.execute(command);
+
+    expect(id1).not.toBe(id2);
+  });
+});

package/templates/postgres/src/modules/example/application/commands/create-item.handler.ts

@@ -0,0 +1,20 @@
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { Inject } from '@nestjs/common';
+import { CreateItemCommand } from './create-item.command';
+import { ITEM_REPOSITORY, IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+import { ItemName } from '../../domain/item-name.value-object';
+
+@CommandHandler(CreateItemCommand)
+export class CreateItemHandler implements ICommandHandler<CreateItemCommand> {
+  constructor(
+    @Inject(ITEM_REPOSITORY) private readonly itemRepository: IItemRepository,
+  ) {}
+
+  async execute(command: CreateItemCommand): Promise<string> {
+    const id = crypto.randomUUID();
+    const item = Item.create(id, ItemName.create(command.name));
+    await this.itemRepository.save(item);
+    return id;
+  }
+}

package/templates/postgres/src/modules/example/application/commands/delete-item.command.ts

@@ -0,0 +1,3 @@
+export class DeleteItemCommand {
+  constructor(public readonly id: string) {}
+}

package/templates/postgres/src/modules/example/application/commands/delete-item.handler.ts

@@ -0,0 +1,15 @@
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { Inject } from '@nestjs/common';
+import { DeleteItemCommand } from './delete-item.command';
+import { ITEM_REPOSITORY, IItemRepository } from '../../domain/item.repository.interface';
+
+@CommandHandler(DeleteItemCommand)
+export class DeleteItemHandler implements ICommandHandler<DeleteItemCommand> {
+  constructor(
+    @Inject(ITEM_REPOSITORY) private readonly itemRepository: IItemRepository,
+  ) {}
+
+  async execute(command: DeleteItemCommand): Promise<void> {
+    await this.itemRepository.delete(command.id);
+  }
+}

package/templates/postgres/src/modules/example/application/dtos/create-item.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+export class CreateItemDto {
+  @ApiProperty({ description: 'The name of the item', example: 'My Item' })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+}

package/templates/postgres/src/modules/example/application/dtos/item.response.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ItemResponseDto {
+  @ApiProperty({ description: 'Unique item identifier', example: '550e8400-e29b-41d4-a716-446655440000' })
+  id: string;
+
+  @ApiProperty({ description: 'The name of the item', example: 'My Item' })
+  name: string;
+}

package/templates/postgres/src/modules/example/application/queries/get-item.handler.spec.ts

@@ -0,0 +1,49 @@
+import { GetItemHandler } from './get-item.handler';
+import { GetItemQuery } from './get-item.query';
+import { IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+import { ItemName } from '../../domain/item-name.value-object';
+
+describe('GetItemHandler', () => {
+  let handler: GetItemHandler;
+  let mockRepository: jest.Mocked<IItemRepository>;
+
+  beforeEach(() => {
+    mockRepository = {
+      findById: jest.fn(),
+      findAll: jest.fn(),
+      save: jest.fn(),
+      delete: jest.fn(),
+    };
+
+    handler = new GetItemHandler(mockRepository);
+  });
+
+  it('should delegate to repository.findById with the query id', async () => {
+    const item = Item.create('item-1', ItemName.create('Widget'));
+    mockRepository.findById.mockResolvedValue(item);
+
+    const query = new GetItemQuery('item-1');
+    await handler.execute(query);
+
+    expect(mockRepository.findById).toHaveBeenCalledTimes(1);
+    expect(mockRepository.findById).toHaveBeenCalledWith('item-1');
+  });
+
+  it('should return the item from the repository when it exists', async () => {
+    const item = Item.create('item-2', ItemName.create('Gadget'));
+    mockRepository.findById.mockResolvedValue(item);
+
+    const result = await handler.execute(new GetItemQuery('item-2'));
+
+    expect(result).toBe(item);
+  });
+
+  it('should return null when the repository returns null', async () => {
+    mockRepository.findById.mockResolvedValue(null);
+
+    const result = await handler.execute(new GetItemQuery('nonexistent'));
+
+    expect(result).toBeNull();
+  });
+});

package/templates/postgres/src/modules/example/application/queries/get-item.handler.ts

@@ -0,0 +1,16 @@
+import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
+import { Inject } from '@nestjs/common';
+import { GetItemQuery } from './get-item.query';
+import { ITEM_REPOSITORY, IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+
+@QueryHandler(GetItemQuery)
+export class GetItemHandler implements IQueryHandler<GetItemQuery> {
+  constructor(
+    @Inject(ITEM_REPOSITORY) private readonly itemRepository: IItemRepository,
+  ) {}
+
+  async execute(query: GetItemQuery): Promise<Item | null> {
+    return this.itemRepository.findById(query.id);
+  }
+}

package/templates/postgres/src/modules/example/application/queries/get-item.query.ts

@@ -0,0 +1,3 @@
+export class GetItemQuery {
+  constructor(public readonly id: string) {}
+}

package/templates/postgres/src/modules/example/application/queries/list-items.handler.ts

@@ -0,0 +1,16 @@
+import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
+import { Inject } from '@nestjs/common';
+import { ListItemsQuery } from './list-items.query';
+import { ITEM_REPOSITORY, IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+
+@QueryHandler(ListItemsQuery)
+export class ListItemsHandler implements IQueryHandler<ListItemsQuery> {
+  constructor(
+    @Inject(ITEM_REPOSITORY) private readonly itemRepository: IItemRepository,
+  ) {}
+
+  async execute(_query: ListItemsQuery): Promise<Item[]> {
+    return this.itemRepository.findAll();
+  }
+}

package/templates/postgres/src/modules/example/application/queries/list-items.query.ts

@@ -0,0 +1,3 @@
+export class ListItemsQuery {
+  constructor() {}
+}

package/templates/postgres/src/modules/example/domain/item-name.value-object.spec.ts

@@ -0,0 +1,49 @@
+import { ItemName } from './item-name.value-object';
+
+describe('ItemName value object', () => {
+  it('should create an ItemName with a valid non-empty string', () => {
+    const name = ItemName.create('Widget');
+
+    expect(name.value).toBe('Widget');
+  });
+
+  it('should trim leading and trailing whitespace on creation', () => {
+    const name = ItemName.create('  Trimmed  ');
+
+    expect(name.value).toBe('Trimmed');
+  });
+
+  it('should throw when given an empty string', () => {
+    expect(() => ItemName.create('')).toThrow('ItemName cannot be empty');
+  });
+
+  it('should throw when given a whitespace-only string', () => {
+    expect(() => ItemName.create('   ')).toThrow('ItemName cannot be empty');
+  });
+
+  it('should be equal to another ItemName with the same trimmed value', () => {
+    const name1 = ItemName.create('Widget');
+    const name2 = ItemName.create('Widget');
+
+    expect(name1.equals(name2)).toBe(true);
+  });
+
+  it('should not be equal to an ItemName with a different value', () => {
+    const name1 = ItemName.create('Widget');
+    const name2 = ItemName.create('Gadget');
+
+    expect(name1.equals(name2)).toBe(false);
+  });
+
+  it('should return false when compared with undefined', () => {
+    const name = ItemName.create('Widget');
+
+    expect(name.equals(undefined)).toBe(false);
+  });
+
+  it('should return true when compared with itself', () => {
+    const name = ItemName.create('Widget');
+
+    expect(name.equals(name)).toBe(true);
+  });
+});

package/templates/postgres/src/modules/example/domain/item-name.value-object.ts

@@ -0,0 +1,18 @@
+import { ValueObject } from '../../../shared/base/value-object';
+
+interface ItemNameProps {
+  value: string;
+}
+
+export class ItemName extends ValueObject<ItemNameProps> {
+  static create(value: string): ItemName {
+    if (!value || value.trim().length === 0) {
+      throw new Error('ItemName cannot be empty');
+    }
+    return new ItemName({ value: value.trim() });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/postgres/src/modules/example/domain/item.entity.spec.ts

@@ -0,0 +1,48 @@
+import { Item } from './item.entity';
+import { ItemName } from './item-name.value-object';
+
+describe('Item entity', () => {
+  it('should create an item via static factory with correct id and name', () => {
+    const name = ItemName.create('Widget');
+    const item = Item.create('item-1', name);
+
+    expect(item.id).toBe('item-1');
+    expect(item.name).toBe(name);
+    expect(item.name.value).toBe('Widget');
+  });
+
+  it('should expose the name value object through the name accessor', () => {
+    const name = ItemName.create('Gadget');
+    const item = Item.create('item-2', name);
+
+    expect(item.name.value).toBe('Gadget');
+  });
+
+  it('should be equal to another item with the same id', () => {
+    const name = ItemName.create('Widget');
+    const item1 = Item.create('same-id', name);
+    const item2 = Item.create('same-id', ItemName.create('DifferentName'));
+
+    expect(item1.equals(item2)).toBe(true);
+  });
+
+  it('should not be equal to an item with a different id', () => {
+    const name = ItemName.create('Widget');
+    const item1 = Item.create('id-a', name);
+    const item2 = Item.create('id-b', name);
+
+    expect(item1.equals(item2)).toBe(false);
+  });
+
+  it('should be equal to itself (reference equality)', () => {
+    const item = Item.create('item-ref', ItemName.create('Test'));
+
+    expect(item.equals(item)).toBe(true);
+  });
+
+  it('should return false when compared with undefined', () => {
+    const item = Item.create('item-undef', ItemName.create('Test'));
+
+    expect(item.equals(undefined)).toBe(false);
+  });
+});

package/templates/postgres/src/modules/example/domain/item.entity.ts

@@ -0,0 +1,19 @@
+import { AggregateRoot } from '../../../shared/base/aggregate-root';
+import { ItemName } from './item-name.value-object';
+
+export class Item extends AggregateRoot<string> {
+  private _name: ItemName;
+
+  private constructor(id: string, name: ItemName) {
+    super(id);
+    this._name = name;
+  }
+
+  static create(id: string, name: ItemName): Item {
+    return new Item(id, name);
+  }
+
+  get name(): ItemName {
+    return this._name;
+  }
+}

package/templates/postgres/src/modules/example/domain/item.repository.interface.ts

@@ -0,0 +1,10 @@
+import { Item } from './item.entity';
+
+export const ITEM_REPOSITORY = Symbol('IItemRepository');
+
+export interface IItemRepository {
+  findById(id: string): Promise<Item | null>;
+  findAll(): Promise<Item[]>;
+  save(item: Item): Promise<void>;
+  delete(id: string): Promise<void>;
+}

package/templates/postgres/src/modules/example/example.module.ts

@@ -0,0 +1,26 @@
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { ItemController } from './presenter/item.controller';
+import { CreateItemHandler } from './application/commands/create-item.handler';
+import { DeleteItemHandler } from './application/commands/delete-item.handler';
+import { GetItemHandler } from './application/queries/get-item.handler';
+import { ListItemsHandler } from './application/queries/list-items.handler';
+import { PrismaItemRepository } from './infrastructure/persistence/prisma-item.repository';
+import { ITEM_REPOSITORY } from './domain/item.repository.interface';
+
+const CommandHandlers = [CreateItemHandler, DeleteItemHandler];
+const QueryHandlers = [GetItemHandler, ListItemsHandler];
+
+@Module({
+  imports: [CqrsModule],
+  controllers: [ItemController],
+  providers: [
+    ...CommandHandlers,
+    ...QueryHandlers,
+    {
+      provide: ITEM_REPOSITORY,
+      useClass: PrismaItemRepository,
+    },
+  ],
+})
+export class ExampleModule {}