@tndhuy/create-app 1.0.0

package/templates/postgres/src/modules/example/infrastructure/persistence/prisma-item.repository.ts

@@ -0,0 +1,34 @@
+import { Injectable } from '@nestjs/common';
+import { InjectPrisma } from '../../../../infrastructure/database/inject-prisma.decorator';
+import { PrismaService } from '../../../../infrastructure/database/prisma.service';
+import { IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+import { ItemName } from '../../domain/item-name.value-object';
+
+@Injectable()
+export class PrismaItemRepository implements IItemRepository {
+  constructor(@InjectPrisma() private readonly prisma: PrismaService) {}
+
+  async findById(id: string): Promise<Item | null> {
+    const record = await this.prisma.item.findUnique({ where: { id } });
+    if (!record) return null;
+    return Item.create(record.id, ItemName.create(record.name));
+  }
+
+  async findAll(): Promise<Item[]> {
+    const records = await this.prisma.item.findMany();
+    return records.map((r) => Item.create(r.id, ItemName.create(r.name)));
+  }
+
+  async save(item: Item): Promise<void> {
+    await this.prisma.item.upsert({
+      where: { id: item.id },
+      update: { name: item.name.value },
+      create: { id: item.id, name: item.name.value },
+    });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.item.delete({ where: { id } });
+  }
+}

package/templates/postgres/src/modules/example/presenter/item.controller.ts

@@ -0,0 +1,52 @@
+import { Body, Controller, Delete, Get, Param, Post, Query } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse, ApiParam } from '@nestjs/swagger';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import { CreateItemDto } from '../application/dtos/create-item.dto';
+import { ItemResponseDto } from '../application/dtos/item.response.dto';
+import { CreateItemCommand } from '../application/commands/create-item.command';
+import { DeleteItemCommand } from '../application/commands/delete-item.command';
+import { GetItemQuery } from '../application/queries/get-item.query';
+import { ListItemsQuery } from '../application/queries/list-items.query';
+import { PaginationDto } from '../../../shared';
+
+@ApiTags('example')
+@Controller('items')
+export class ItemController {
+  constructor(
+    private readonly commandBus: CommandBus,
+    private readonly queryBus: QueryBus,
+  ) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Create a new item' })
+  @ApiResponse({ status: 201, description: 'Item created successfully', type: ItemResponseDto })
+  @ApiResponse({ status: 400, description: 'Validation failed' })
+  create(@Body() dto: CreateItemDto) {
+    return this.commandBus.execute(new CreateItemCommand(dto.name));
+  }
+
+  @Delete(':id')
+  @ApiOperation({ summary: 'Delete an item by ID' })
+  @ApiParam({ name: 'id', description: 'Item UUID' })
+  @ApiResponse({ status: 200, description: 'Item deleted successfully' })
+  @ApiResponse({ status: 404, description: 'Item not found' })
+  delete(@Param('id') id: string) {
+    return this.commandBus.execute(new DeleteItemCommand(id));
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get an item by ID' })
+  @ApiParam({ name: 'id', description: 'Item UUID' })
+  @ApiResponse({ status: 200, description: 'Item found', type: ItemResponseDto })
+  @ApiResponse({ status: 404, description: 'Item not found' })
+  findOne(@Param('id') id: string) {
+    return this.queryBus.execute(new GetItemQuery(id));
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'List all items with pagination' })
+  @ApiResponse({ status: 200, description: 'List of items', type: [ItemResponseDto] })
+  findAll(@Query() pagination: PaginationDto) {
+    return this.queryBus.execute(new ListItemsQuery());
+  }
+}

package/templates/postgres/src/shared/base/aggregate-root.spec.ts

@@ -0,0 +1,44 @@
+import { AggregateRoot } from './aggregate-root';
+import { DomainEvent } from './domain-event';
+
+class TestEvent extends DomainEvent {
+  constructor() {
+    super();
+  }
+}
+
+class TestAggregate extends AggregateRoot<string> {
+  constructor(id: string) {
+    super(id);
+  }
+}
+
+describe('AggregateRoot', () => {
+  it('should extend Entity and return the id', () => {
+    const aggregate = new TestAggregate('agg-1');
+    expect(aggregate.id).toBe('agg-1');
+  });
+
+  it('should collect a domain event via addDomainEvent', () => {
+    const aggregate = new TestAggregate('agg-1');
+    const event = new TestEvent();
+    aggregate.addDomainEvent(event);
+    const events = aggregate.pullDomainEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toBe(event);
+  });
+
+  it('should clear domain events after pullDomainEvents', () => {
+    const aggregate = new TestAggregate('agg-1');
+    aggregate.addDomainEvent(new TestEvent());
+    aggregate.pullDomainEvents();
+    const secondPull = aggregate.pullDomainEvents();
+    expect(secondPull).toHaveLength(0);
+  });
+
+  it('should support equals comparison via inherited Entity method', () => {
+    const a1 = new TestAggregate('agg-1');
+    const a2 = new TestAggregate('agg-1');
+    expect(a1.equals(a2)).toBe(true);
+  });
+});

package/templates/postgres/src/shared/base/aggregate-root.ts

@@ -0,0 +1,20 @@
+import { Entity } from './entity';
+import { DomainEvent } from './domain-event';
+
+export abstract class AggregateRoot<TId> extends Entity<TId> {
+  private readonly domainEvents: DomainEvent[] = [];
+
+  protected constructor(id: TId) {
+    super(id);
+  }
+
+  addDomainEvent(event: DomainEvent): void {
+    this.domainEvents.push(event);
+  }
+
+  pullDomainEvents(): DomainEvent[] {
+    const events = [...this.domainEvents];
+    this.domainEvents.length = 0;
+    return events;
+  }
+}

package/templates/postgres/src/shared/base/domain-event.ts

@@ -0,0 +1,6 @@
+export abstract class DomainEvent {
+  readonly occurredAt: Date;
+  protected constructor() {
+    this.occurredAt = new Date();
+  }
+}

package/templates/postgres/src/shared/base/entity.spec.ts

@@ -0,0 +1,36 @@
+import { Entity } from './entity';
+
+class TestEntity extends Entity<string> {
+  constructor(id: string) {
+    super(id);
+  }
+}
+
+describe('Entity', () => {
+  it('should store and return the id', () => {
+    const entity = new TestEntity('abc');
+    expect(entity.id).toBe('abc');
+  });
+
+  it('should be equal to another entity with the same id', () => {
+    const e1 = new TestEntity('abc');
+    const e2 = new TestEntity('abc');
+    expect(e1.equals(e2)).toBe(true);
+  });
+
+  it('should not be equal to another entity with a different id', () => {
+    const e1 = new TestEntity('abc');
+    const e2 = new TestEntity('xyz');
+    expect(e1.equals(e2)).toBe(false);
+  });
+
+  it('should return false when comparing with undefined', () => {
+    const entity = new TestEntity('abc');
+    expect(entity.equals(undefined)).toBe(false);
+  });
+
+  it('should return true when comparing with itself (reference equality)', () => {
+    const entity = new TestEntity('abc');
+    expect(entity.equals(entity)).toBe(true);
+  });
+});

package/templates/postgres/src/shared/base/entity.ts

@@ -0,0 +1,13 @@
+export abstract class Entity<TId> {
+  readonly id: TId;
+
+  protected constructor(id: TId) {
+    this.id = id;
+  }
+
+  equals(other?: Entity<TId>): boolean {
+    if (!other) return false;
+    if (other === this) return true;
+    return this.id === other.id;
+  }
+}

package/templates/postgres/src/shared/base/index.ts

@@ -0,0 +1,5 @@
+export { Entity } from './entity';
+export { AggregateRoot } from './aggregate-root';
+export { ValueObject } from './value-object';
+export { DomainEvent } from './domain-event';
+export { Repository } from './repository.interface';

package/templates/postgres/src/shared/base/repository.interface.ts

@@ -0,0 +1,6 @@
+export interface Repository<T, TId> {
+  findById(id: TId): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  save(entity: T): Promise<void>;
+  delete(id: TId): Promise<void>;
+}

package/templates/postgres/src/shared/base/value-object.spec.ts

@@ -0,0 +1,39 @@
+import { ValueObject } from './value-object';
+
+class TestVO extends ValueObject<{ value: string }> {
+  constructor(props: { value: string }) {
+    super(props);
+  }
+}
+
+describe('ValueObject', () => {
+  it('should be equal to another VO with the same props', () => {
+    const vo1 = new TestVO({ value: 'hello' });
+    const vo2 = new TestVO({ value: 'hello' });
+    expect(vo1.equals(vo2)).toBe(true);
+  });
+
+  it('should not be equal to a VO with different props', () => {
+    const vo1 = new TestVO({ value: 'hello' });
+    const vo2 = new TestVO({ value: 'world' });
+    expect(vo1.equals(vo2)).toBe(false);
+  });
+
+  it('should return false when comparing with undefined', () => {
+    const vo = new TestVO({ value: 'hello' });
+    expect(vo.equals(undefined)).toBe(false);
+  });
+
+  it('should return true when comparing with itself (reference equality)', () => {
+    const vo = new TestVO({ value: 'hello' });
+    expect(vo.equals(vo)).toBe(true);
+  });
+
+  it('should be immutable — mutation attempt does not change value', () => {
+    const vo = new TestVO({ value: 'original' });
+    expect(() => {
+      (vo as any).props.value = 'mutated';
+    }).toThrow();
+    expect(vo.equals(new TestVO({ value: 'original' }))).toBe(true);
+  });
+});

package/templates/postgres/src/shared/base/value-object.ts

@@ -0,0 +1,13 @@
+export abstract class ValueObject<TProps> {
+  protected readonly props: TProps;
+
+  protected constructor(props: TProps) {
+    this.props = Object.freeze({ ...props });
+  }
+
+  equals(other?: ValueObject<TProps>): boolean {
+    if (!other) return false;
+    if (other === this) return true;
+    return JSON.stringify(this.props) === JSON.stringify(other.props);
+  }
+}

package/templates/postgres/src/shared/dto/pagination.dto.spec.ts

@@ -0,0 +1,49 @@
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { PaginationDto } from './pagination.dto';
+
+async function validateDto(plain: Record<string, unknown>) {
+  const dto = plainToInstance(PaginationDto, plain);
+  const errors = await validate(dto);
+  return { dto, errors };
+}
+
+describe('PaginationDto', () => {
+  it('should have defaults: page=1, limit=20, order=asc', async () => {
+    const { dto } = await validateDto({});
+    expect(dto.page).toBe(1);
+    expect(dto.limit).toBe(20);
+    expect(dto.order).toBe('asc');
+  });
+
+  it('should pass with valid page=2, limit=50, sort=name, order=desc', async () => {
+    const { errors } = await validateDto({ page: 2, limit: 50, sort: 'name', order: 'desc' });
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should fail when page < 1', async () => {
+    const { errors } = await validateDto({ page: 0 });
+    expect(errors.length).toBeGreaterThan(0);
+    const pageError = errors.find((e) => e.property === 'page');
+    expect(pageError).toBeDefined();
+  });
+
+  it('should fail when limit > 100', async () => {
+    const { errors } = await validateDto({ limit: 101 });
+    expect(errors.length).toBeGreaterThan(0);
+    const limitError = errors.find((e) => e.property === 'limit');
+    expect(limitError).toBeDefined();
+  });
+
+  it('should fail when order is not asc or desc', async () => {
+    const { errors } = await validateDto({ order: 'random' });
+    expect(errors.length).toBeGreaterThan(0);
+    const orderError = errors.find((e) => e.property === 'order');
+    expect(orderError).toBeDefined();
+  });
+
+  it('should fail when limit < 1', async () => {
+    const { errors } = await validateDto({ limit: 0 });
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/templates/postgres/src/shared/dto/pagination.dto.ts

@@ -0,0 +1,37 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsIn, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+
+export class PaginationDto {
+  @ApiPropertyOptional({ description: 'Page number (1-based)', default: 1, minimum: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({ description: 'Items per page', default: 20, minimum: 1, maximum: 100 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  @ApiPropertyOptional({ description: 'Sort field' })
+  @IsOptional()
+  @IsString()
+  sort?: string;
+
+  @ApiPropertyOptional({ description: 'Sort direction', enum: ['asc', 'desc'], default: 'asc' })
+  @IsOptional()
+  @IsIn(['asc', 'desc'])
+  order?: 'asc' | 'desc' = 'asc';
+}
+
+export interface PaginationMeta {
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}

package/templates/postgres/src/shared/dto/response.dto.ts

@@ -0,0 +1,13 @@
+import { PaginationMeta } from './pagination.dto';
+
+export interface ResponseEnvelope<T = unknown> {
+  success: boolean;
+  data?: T;
+  meta?: PaginationMeta;
+  error?: {
+    code: string;
+    message: string;
+    statusCode: number;
+    details?: unknown;
+  };
+}

package/templates/postgres/src/shared/exceptions/app.exception.spec.ts

@@ -0,0 +1,59 @@
+import { HttpException } from '@nestjs/common';
+import { AppException } from './app.exception';
+import { ErrorCodes } from './error-codes';
+
+describe('AppException', () => {
+  it('should set code, message, statusCode from payload', () => {
+    const exception = new AppException({
+      code: ErrorCodes.NOT_FOUND,
+      message: 'Item not found',
+      statusCode: 404,
+    });
+
+    expect(exception.code).toBe('NOT_FOUND');
+    expect(exception.message).toBe('Item not found');
+    expect(exception.getStatus()).toBe(404);
+  });
+
+  it('should set details from payload', () => {
+    const details = [{ field: 'email', constraints: { isEmail: 'must be email' } }];
+    const exception = new AppException({
+      code: ErrorCodes.VALIDATION_FAILED,
+      message: 'Validation failed',
+      statusCode: 400,
+      details,
+    });
+
+    expect(exception.details).toEqual(details);
+  });
+
+  it('should default details to undefined when not provided', () => {
+    const exception = new AppException({
+      code: ErrorCodes.INTERNAL_ERROR,
+      message: 'Something went wrong',
+      statusCode: 500,
+    });
+
+    expect(exception.details).toBeUndefined();
+  });
+
+  it('should be instanceof HttpException', () => {
+    const exception = new AppException({
+      code: ErrorCodes.UNAUTHORIZED,
+      message: 'Unauthorized',
+      statusCode: 401,
+    });
+
+    expect(exception).toBeInstanceOf(HttpException);
+  });
+
+  it('should return the correct statusCode via getStatus()', () => {
+    const exception = new AppException({
+      code: ErrorCodes.FORBIDDEN,
+      message: 'Forbidden',
+      statusCode: 403,
+    });
+
+    expect(exception.getStatus()).toBe(403);
+  });
+});

package/templates/postgres/src/shared/exceptions/app.exception.ts

@@ -0,0 +1,19 @@
+import { HttpException } from '@nestjs/common';
+
+export interface AppExceptionPayload {
+  code: string;
+  message: string;
+  statusCode: number;
+  details?: unknown;
+}
+
+export class AppException extends HttpException {
+  public readonly code: string;
+  public readonly details?: unknown;
+
+  constructor(payload: AppExceptionPayload) {
+    super(payload, payload.statusCode);
+    this.code = payload.code;
+    this.details = payload.details;
+  }
+}

package/templates/postgres/src/shared/exceptions/error-codes.ts

@@ -0,0 +1,9 @@
+export const ErrorCodes = {
+  VALIDATION_FAILED: 'VALIDATION_FAILED',
+  NOT_FOUND: 'NOT_FOUND',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/templates/postgres/src/shared/index.ts

@@ -0,0 +1,7 @@
+export * from './base';
+export * from './valueobjects';
+export * from './dto/pagination.dto';
+export * from './dto/response.dto';
+export * from './exceptions/app.exception';
+export * from './exceptions/error-codes';
+export * from './validation-options';

package/templates/postgres/src/shared/logger/logger.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { LoggerModule as PinoLoggerModule } from 'nestjs-pino';
+import { pinoConfig } from './pino.config';
+import { LoggerService } from './logger.service';
+
+@Global()
+@Module({
+  imports: [PinoLoggerModule.forRoot(pinoConfig)],
+  providers: [LoggerService],
+  exports: [PinoLoggerModule, LoggerService],
+})
+export class LoggerModule {}

package/templates/postgres/src/shared/logger/logger.service.ts

@@ -0,0 +1,48 @@
+import { Injectable } from '@nestjs/common';
+import { InjectPinoLogger, PinoLogger } from 'nestjs-pino';
+
+@Injectable()
+export class LoggerService {
+  private context: string = LoggerService.name;
+
+  constructor(
+    @InjectPinoLogger(LoggerService.name)
+    private readonly logger: PinoLogger,
+  ) {}
+
+  log(message: string, contextOrMetadata?: string | Record<string, unknown>): void {
+    const metadata = this.normalizeMetadata(contextOrMetadata);
+    this.logger.info(metadata, message);
+  }
+
+  error(message: string, traceOrMetadata?: string | Record<string, unknown>, context?: string): void {
+    let metadata: Record<string, unknown>;
+    if (typeof traceOrMetadata === 'string') {
+      metadata = { trace: traceOrMetadata, context: context || this.context };
+    } else {
+      metadata = this.normalizeMetadata(traceOrMetadata);
+    }
+    this.logger.error(metadata, message);
+  }
+
+  warn(message: string, contextOrMetadata?: string | Record<string, unknown>): void {
+    const metadata = this.normalizeMetadata(contextOrMetadata);
+    this.logger.warn(metadata, message);
+  }
+
+  debug(message: string, contextOrMetadata?: string | Record<string, unknown>): void {
+    const metadata = this.normalizeMetadata(contextOrMetadata);
+    this.logger.debug(metadata, message);
+  }
+
+  setContext(context: string): this {
+    this.context = context;
+    return this;
+  }
+
+  private normalizeMetadata(contextOrMetadata?: string | Record<string, unknown>): Record<string, unknown> {
+    if (!contextOrMetadata) return { context: this.context };
+    if (typeof contextOrMetadata === 'string') return { context: contextOrMetadata };
+    return { context: this.context, ...contextOrMetadata };
+  }
+}

package/templates/postgres/src/shared/logger/pino.config.ts

@@ -0,0 +1,86 @@
+import { join } from 'path';
+import type { Params } from 'nestjs-pino';
+import { trace, context, isSpanContextValid } from '@opentelemetry/api';
+
+const isDev = process.env.NODE_ENV !== 'production';
+const LOG_DIR = join(process.cwd(), 'logs');
+const LOG_MAX_SIZE = '10M';
+
+export const pinoConfig: Params = {
+  pinoHttp: {
+    level: isDev ? 'debug' : 'info',
+    // Inject Trace context into every log line
+    mixin() {
+      const activeSpan = trace.getSpan(context.active());
+      if (activeSpan) {
+        const spanContext = activeSpan.spanContext();
+        if (isSpanContextValid(spanContext)) {
+          return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: `0${spanContext.traceFlags.toString(16)}`,
+          };
+        }
+      }
+      return {};
+    },
+    // Standardize on X-Request-Id as the primary req.id
+    genReqId: (req) => (req.headers['x-request-id'] as string) || (req.headers['x-correlation-id'] as string),
+    transport: {
+      targets: [
+        // Daily rotating file for production-like environments
+        {
+          target: 'pino-roll',
+          options: {
+            file: join(LOG_DIR, 'application'),
+            frequency: 'daily',
+            size: LOG_MAX_SIZE,
+            mkdir: true,
+            extension: '.log',
+          },
+          level: 'info',
+        },
+        // Dedicated error log
+        {
+          target: 'pino/file',
+          options: {
+            destination: join(LOG_DIR, 'error.log'),
+            mkdir: true,
+          },
+          level: 'error',
+        },
+        // Console output (pretty in Dev, JSON in Prod)
+        ...(isDev
+          ? [
+              {
+                target: 'pino-pretty',
+                options: {
+                  colorize: true,
+                  translateTime: 'SYS:yyyy-mm-dd HH:MM:ss',
+                  ignore: 'pid,hostname',
+                  messageKey: 'message',
+                },
+                level: 'debug',
+              },
+            ]
+          : [
+              {
+                target: 'pino/file',
+                options: { destination: 1 },
+                level: 'info',
+              },
+            ]),
+      ],
+    },
+    messageKey: 'message',
+    serializers: {
+      req: (req: { method: string; url: string }) => ({
+        method: req.method,
+        url: req.url,
+      }),
+      res: (res: { statusCode: number }) => ({
+        statusCode: res.statusCode,
+      }),
+    },
+  },
+};

package/templates/postgres/src/shared/validation-options.ts

@@ -0,0 +1,38 @@
+import { ValidationError, ValidationPipeOptions } from '@nestjs/common';
+import { AppException } from './exceptions/app.exception';
+import { ErrorCodes } from './exceptions/error-codes';
+
+function formatErrors(errors: ValidationError[]): { field: string; constraints: Record<string, string> }[] {
+  return errors.flatMap((error) => {
+    if (error.children && error.children.length > 0) {
+      return formatErrors(error.children).map((child) => ({
+        ...child,
+        field: `${error.property}.${child.field}`,
+      }));
+    }
+    return [
+      {
+        field: error.property,
+        constraints: (error.constraints ?? {}) as Record<string, string>,
+      },
+    ];
+  });
+}
+
+export const validationOptions: ValidationPipeOptions = {
+  whitelist: true,
+  forbidNonWhitelisted: true,
+  transform: true,
+  transformOptions: {
+    enableImplicitConversion: true,
+  },
+  exceptionFactory: (errors: ValidationError[]) => {
+    const formattedErrors = formatErrors(errors);
+    return new AppException({
+      code: ErrorCodes.VALIDATION_FAILED,
+      message: 'Validation failed',
+      statusCode: 400,
+      details: formattedErrors,
+    });
+  },
+};