@tndhuy/create-app 1.0.0

package/templates/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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,
+    });
+  },
+};

package/templates/mongo/src/shared/valueobjects/date.valueobject.spec.ts

@@ -0,0 +1,40 @@
+import { DateValueObject } from './date.valueobject';
+
+describe('DateValueObject', () => {
+  it('should store and return a valid Date', () => {
+    const date = new Date('2024-01-15T10:00:00Z');
+    const vo = new DateValueObject(date);
+    expect(vo.value).toEqual(date);
+  });
+
+  it('should throw when constructed with an invalid Date (NaN time)', () => {
+    expect(() => new DateValueObject(new Date('invalid'))).toThrow(
+      'Date value must be a valid Date',
+    );
+  });
+
+  it('should throw when constructed with a non-Date value', () => {
+    expect(() => new DateValueObject('2024-01-01' as any)).toThrow(
+      'Date value must be a valid Date',
+    );
+  });
+
+  it('should throw when constructed with null', () => {
+    expect(() => new DateValueObject(null as any)).toThrow(
+      'Date value must be a valid Date',
+    );
+  });
+
+  it('should be equal to another DateValueObject with the same date value', () => {
+    const date = new Date('2024-06-01T00:00:00Z');
+    const vo1 = new DateValueObject(date);
+    const vo2 = new DateValueObject(new Date('2024-06-01T00:00:00Z'));
+    expect(vo1.equals(vo2)).toBe(true);
+  });
+
+  it('should not be equal to a DateValueObject with a different date', () => {
+    const vo1 = new DateValueObject(new Date('2024-01-01'));
+    const vo2 = new DateValueObject(new Date('2024-12-31'));
+    expect(vo1.equals(vo2)).toBe(false);
+  });
+});

package/templates/mongo/src/shared/valueobjects/date.valueobject.ts

@@ -0,0 +1,14 @@
+import { ValueObject } from '../base/value-object';
+
+export class DateValueObject extends ValueObject<{ value: Date }> {
+  constructor(value: Date) {
+    if (!(value instanceof Date) || isNaN(value.getTime())) {
+      throw new Error('Date value must be a valid Date');
+    }
+    super({ value });
+  }
+
+  get value(): Date {
+    return this.props.value;
+  }
+}

package/templates/mongo/src/shared/valueobjects/id.valueobject.spec.ts

@@ -0,0 +1,28 @@
+import { IdValueObject } from './id.valueobject';
+
+describe('IdValueObject', () => {
+  it('should store and return the id value', () => {
+    const id = new IdValueObject('abc-123');
+    expect(id.value).toBe('abc-123');
+  });
+
+  it('should throw when constructed with an empty string', () => {
+    expect(() => new IdValueObject('')).toThrow('ID must not be empty');
+  });
+
+  it('should throw when constructed with whitespace-only string', () => {
+    expect(() => new IdValueObject('   ')).toThrow('ID must not be empty');
+  });
+
+  it('should be equal to another IdValueObject with the same value', () => {
+    const id1 = new IdValueObject('abc-123');
+    const id2 = new IdValueObject('abc-123');
+    expect(id1.equals(id2)).toBe(true);
+  });
+
+  it('should not be equal to another IdValueObject with a different value', () => {
+    const id1 = new IdValueObject('abc-123');
+    const id2 = new IdValueObject('xyz-456');
+    expect(id1.equals(id2)).toBe(false);
+  });
+});

package/templates/mongo/src/shared/valueobjects/id.valueobject.ts

@@ -0,0 +1,14 @@
+import { ValueObject } from '../base/value-object';
+
+export class IdValueObject extends ValueObject<{ value: string }> {
+  constructor(value: string) {
+    if (!value || value.trim().length === 0) {
+      throw new Error('ID must not be empty');
+    }
+    super({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/mongo/src/shared/valueobjects/index.ts

@@ -0,0 +1,4 @@
+export { IdValueObject } from './id.valueobject';
+export { StringValueObject } from './string.valueobject';
+export { NumberValueObject } from './number.valueobject';
+export { DateValueObject } from './date.valueobject';