@tndhuy/create-app 1.0.0

package/templates/mongo/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/mongo/src/modules/example/application/commands/create-item.command.ts

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

package/templates/mongo/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/mongo/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/mongo/src/modules/example/application/commands/delete-item.command.ts

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

package/templates/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/src/modules/example/application/queries/get-item.query.ts

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

package/templates/mongo/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/mongo/src/modules/example/application/queries/list-items.query.ts

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

package/templates/mongo/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/mongo/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/mongo/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/mongo/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/mongo/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/mongo/src/modules/example/example.module.ts

@@ -0,0 +1,31 @@
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { MongooseModule } from '@nestjs/mongoose';
+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 { MongooseItemRepository } from './infrastructure/persistence/mongoose-item.repository';
+import { ItemSchemaClass, ItemSchema } from './infrastructure/persistence/schemas/item.schema';
+import { ITEM_REPOSITORY } from './domain/item.repository.interface';
+
+const CommandHandlers = [CreateItemHandler, DeleteItemHandler];
+const QueryHandlers = [GetItemHandler, ListItemsHandler];
+
+@Module({
+  imports: [
+    CqrsModule,
+    MongooseModule.forFeature([{ name: ItemSchemaClass.name, schema: ItemSchema }]),
+  ],
+  controllers: [ItemController],
+  providers: [
+    ...CommandHandlers,
+    ...QueryHandlers,
+    {
+      provide: ITEM_REPOSITORY,
+      useClass: MongooseItemRepository,
+    },
+  ],
+})
+export class ExampleModule {}

package/templates/mongo/src/modules/example/infrastructure/persistence/mongoose-item.repository.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+import { IItemRepository } from '../../domain/item.repository.interface';
+import { Item } from '../../domain/item.entity';
+import { ItemName } from '../../domain/item-name.value-object';
+import { ItemSchemaClass, ItemDocument } from './schemas/item.schema';
+
+@Injectable()
+export class MongooseItemRepository implements IItemRepository {
+  constructor(
+    @InjectModel(ItemSchemaClass.name)
+    private readonly itemModel: Model<ItemDocument>,
+  ) {}
+
+  async findById(id: string): Promise<Item | null> {
+    const record = await this.itemModel.findById(id).lean().exec();
+    if (!record) return null;
+    return Item.create(record._id as string, ItemName.create(record.name));
+  }
+
+  async findAll(): Promise<Item[]> {
+    const records = await this.itemModel.find().lean().exec();
+    return records.map((r) =>
+      Item.create(r._id as string, ItemName.create(r.name)),
+    );
+  }
+
+  async save(item: Item): Promise<void> {
+    await this.itemModel
+      .findByIdAndUpdate(
+        item.id,
+        { name: item.name.value },
+        { upsert: true, new: true },
+      )
+      .exec();
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.itemModel.findByIdAndDelete(id).exec();
+  }
+}

package/templates/mongo/src/modules/example/infrastructure/persistence/schemas/item.schema.ts

@@ -0,0 +1,15 @@
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+import { HydratedDocument } from 'mongoose';
+
+export type ItemDocument = HydratedDocument<ItemSchemaClass>;
+
+@Schema({ collection: 'items', timestamps: true })
+export class ItemSchemaClass {
+  @Prop({ required: true })
+  _id: string;
+
+  @Prop({ required: true })
+  name: string;
+}
+
+export const ItemSchema = SchemaFactory.createForClass(ItemSchemaClass);

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