@tndhuy/create-app 1.0.0

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

@@ -0,0 +1,48 @@
+import { NumberValueObject } from './number.valueobject';
+
+describe('NumberValueObject', () => {
+  it('should store and return the numeric value', () => {
+    const vo = new NumberValueObject(42);
+    expect(vo.value).toBe(42);
+  });
+
+  it('should store zero as a valid value', () => {
+    const vo = new NumberValueObject(0);
+    expect(vo.value).toBe(0);
+  });
+
+  it('should store negative numbers', () => {
+    const vo = new NumberValueObject(-7);
+    expect(vo.value).toBe(-7);
+  });
+
+  it('should throw when constructed with NaN', () => {
+    expect(() => new NumberValueObject(NaN)).toThrow(
+      'Number value must be a finite number',
+    );
+  });
+
+  it('should throw when constructed with Infinity', () => {
+    expect(() => new NumberValueObject(Infinity)).toThrow(
+      'Number value must be a finite number',
+    );
+  });
+
+  it('should throw when constructed with negative Infinity', () => {
+    expect(() => new NumberValueObject(-Infinity)).toThrow(
+      'Number value must be a finite number',
+    );
+  });
+
+  it('should be equal to another NumberValueObject with the same value', () => {
+    const vo1 = new NumberValueObject(99);
+    const vo2 = new NumberValueObject(99);
+    expect(vo1.equals(vo2)).toBe(true);
+  });
+
+  it('should not be equal to a NumberValueObject with a different value', () => {
+    const vo1 = new NumberValueObject(1);
+    const vo2 = new NumberValueObject(2);
+    expect(vo1.equals(vo2)).toBe(false);
+  });
+});

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

@@ -0,0 +1,14 @@
+import { ValueObject } from '../base/value-object';
+
+export class NumberValueObject extends ValueObject<{ value: number }> {
+  constructor(value: number) {
+    if (!Number.isFinite(value)) {
+      throw new Error('Number value must be a finite number');
+    }
+    super({ value });
+  }
+
+  get value(): number {
+    return this.props.value;
+  }
+}

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

@@ -0,0 +1,37 @@
+import { StringValueObject } from './string.valueobject';
+
+describe('StringValueObject', () => {
+  it('should store and return the string value', () => {
+    const vo = new StringValueObject('hello');
+    expect(vo.value).toBe('hello');
+  });
+
+  it('should throw when constructed with null', () => {
+    expect(() => new StringValueObject(null as any)).toThrow(
+      'String value must not be null or undefined',
+    );
+  });
+
+  it('should throw when constructed with undefined', () => {
+    expect(() => new StringValueObject(undefined as any)).toThrow(
+      'String value must not be null or undefined',
+    );
+  });
+
+  it('should be equal to another StringValueObject with the same value', () => {
+    const vo1 = new StringValueObject('hello');
+    const vo2 = new StringValueObject('hello');
+    expect(vo1.equals(vo2)).toBe(true);
+  });
+
+  it('should not be equal to a StringValueObject with a different value', () => {
+    const vo1 = new StringValueObject('hello');
+    const vo2 = new StringValueObject('world');
+    expect(vo1.equals(vo2)).toBe(false);
+  });
+
+  it('should allow empty strings (only null/undefined are rejected)', () => {
+    const vo = new StringValueObject('');
+    expect(vo.value).toBe('');
+  });
+});

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

@@ -0,0 +1,14 @@
+import { ValueObject } from '../base/value-object';
+
+export class StringValueObject extends ValueObject<{ value: string }> {
+  constructor(value: string) {
+    if (value === null || value === undefined) {
+      throw new Error('String value must not be null or undefined');
+    }
+    super({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/mongo/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/templates/mongo/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "target": "ES2023",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "paths": {
+      "@shared/*": ["src/shared/*"]
+    },
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "noImplicitAny": false
+  },
+  "exclude": ["node_modules", "dist", "test", "packages"]
+}

package/templates/postgres/.env.example

@@ -0,0 +1,32 @@
+# Application
+PORT=3000
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/template_db?schema=public
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# API
+API_VERSION=1
+APP_NAME=NestJS Backend Template
+APP_DESCRIPTION=API Documentation
+REQUEST_TIMEOUT=30000
+
+# Rate Limiting
+THROTTLE_TTL=60
+THROTTLE_LIMIT=100
+
+# Docs
+DOCS_USER=admin
+DOCS_PASS=admin
+
+# Observability - Logging
+# LOG_LEVEL is controlled by NODE_ENV (debug in dev, info in prod)
+
+# Observability - OpenTelemetry (opt-in)
+OTEL_ENABLED=false
+OTEL_SERVICE_NAME=nestjs-backend-template
+OTEL_PROMETHEUS_PORT=9464
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

package/templates/postgres/Dockerfile

@@ -0,0 +1,64 @@
+# =========================
+# 1) Dependencies
+# =========================
+FROM node:22-alpine AS deps
+
+RUN apk upgrade --no-cache \
+  && addgroup -g 1001 -S appgroup \
+  && adduser -S appuser -u 1001 -G appgroup
+
+WORKDIR /app
+RUN chown appuser:appgroup /app
+
+COPY --chown=appuser:appgroup package*.json ./
+COPY --chown=appuser:appgroup prisma ./prisma/
+COPY --chown=appuser:appgroup prisma.config.ts ./
+
+USER appuser
+
+RUN npm ci --fetch-timeout=600000 --fetch-retries=5
+
+
+# =========================
+# 2) Builder
+# =========================
+FROM deps AS builder
+
+COPY --chown=appuser:appgroup . .
+
+RUN npx prisma generate && npm run build
+
+
+# =========================
+# 3) Runner (Production)
+# =========================
+FROM node:22-alpine AS runner
+
+RUN apk upgrade --no-cache \
+  && apk add --no-cache curl \
+  && addgroup -g 1001 -S appgroup \
+  && adduser -S appuser -u 1001 -G appgroup
+
+WORKDIR /app
+
+COPY --from=builder --chown=appuser:appgroup /app/package*.json ./
+COPY --from=builder --chown=appuser:appgroup /app/prisma ./prisma
+COPY --from=builder --chown=appuser:appgroup /app/prisma.config.ts ./prisma.config.ts
+
+RUN npm ci --omit=dev --fetch-timeout=600000 --fetch-retries=5 && npm cache clean --force
+
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+
+RUN mkdir -p logs && chown appuser:appgroup logs
+
+ENV NODE_ENV=production \
+    PORT=3000
+
+USER appuser
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/src/main"]

package/templates/postgres/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+    },
+  },
+);

package/templates/postgres/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/postgres/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "nestjs-backend-template",
+  "version": "0.0.1",
+  "description": "",
+  "author": "",
+  "private": true,
+  "license": "UNLICENSED",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/src/main",
+    "db:migrate:deploy": "prisma migrate deploy",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/swagger": "^11.2.6",
+    "@nestjs/terminus": "^11.1.1",
+    "@nestjs/throttler": "^6.5.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/exporter-prometheus": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@prisma/adapter-pg": "^7.5.0",
+    "@prisma/client": "^7.5.0",
+    "@scalar/nestjs-api-reference": "^1.1.5",
+    "@types/pg": "^8.20.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "cockatiel": "^3.2.1",
+    "express-basic-auth": "^1.2.1",
+    "ioredis": "^5.10.1",
+    "nestjs-pino": "^4.6.1",
+    "pg": "^8.20.0",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.3",
+    "pino-roll": "^4.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@types/express": "^5.0.0",
+    "@types/ioredis": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.4.2",
+    "prisma": "^7.5.0",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/templates/postgres/prisma/schema.prisma

@@ -0,0 +1,14 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+model Item {
+  id        String   @id
+  name      String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}

package/templates/postgres/prisma.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig, env } from 'prisma/config';
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  migrations: {
+    path: 'prisma/migrations',
+  },
+  datasource: {
+    url: process.env.DATABASE_URL ?? 'postgresql://localhost:5432/app',
+  },
+});

package/templates/postgres/src/app.module.ts

@@ -0,0 +1,34 @@
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { AppConfigModule } from './infrastructure/config/config.module';
+import { DatabaseModule } from './infrastructure/database/prisma.module';
+import { CacheModule } from './infrastructure/cache/redis.module';
+import { HealthModule } from './infrastructure/health/health.module';
+import { ExampleModule } from './modules/example/example.module';
+import { CorrelationIdMiddleware } from './common/middleware/correlation-id.middleware';
+import { LoggerModule } from './shared/logger/logger.module';
+
+@Module({
+  imports: [
+    AppConfigModule,
+    DatabaseModule,
+    CacheModule,
+    HealthModule,
+    ExampleModule,
+    LoggerModule,
+    ThrottlerModule.forRoot([
+      {
+        ttl: parseInt(process.env.THROTTLE_TTL ?? '60', 10) * 1000,
+        limit: parseInt(process.env.THROTTLE_LIMIT ?? '100', 10),
+      },
+    ]),
+  ],
+  controllers: [],
+  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
+  }
+}

package/templates/postgres/src/common/decorators/public-api.decorator.ts

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const PUBLIC_API_KEY = 'public_api';
+/**
+ * Decorator to mark an endpoint as Public API.
+ * This will trigger the TransformInterceptor to wrap the response in { success: true, data: T }.
+ * Without this decorator, the response remains raw.
+ */
+export const PublicApi = () => SetMetadata(PUBLIC_API_KEY, true);

package/templates/postgres/src/common/decorators/raw-response.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+import { RAW_RESPONSE_KEY } from '../interceptors/transform.interceptor';
+
+export const RawResponse = () => SetMetadata(RAW_RESPONSE_KEY, true);

package/templates/postgres/src/common/filters/http-exception.filter.spec.ts

@@ -0,0 +1,95 @@
+import { HttpException } from '@nestjs/common';
+import { AppException } from '../../shared/exceptions/app.exception';
+import { ErrorCodes } from '../../shared/exceptions/error-codes';
+import { HttpExceptionFilter } from './http-exception.filter';
+
+function createMockHost(jsonMock: jest.Mock) {
+  const statusMock = jest.fn().mockReturnValue({ json: jsonMock });
+  const response = { status: statusMock };
+  const request = { method: 'GET', url: '/test' };
+  return {
+    switchToHttp: () => ({
+      getResponse: () => response,
+      getRequest: () => request,
+    }),
+  } as any;
+}
+
+describe('HttpExceptionFilter', () => {
+  let filter: HttpExceptionFilter;
+  let jsonMock: jest.Mock;
+
+  beforeEach(() => {
+    filter = new HttpExceptionFilter();
+    jsonMock = jest.fn();
+  });
+
+  it('should format AppException(NOT_FOUND) to correct error shape', () => {
+    const exception = new AppException({
+      code: ErrorCodes.NOT_FOUND,
+      message: 'Item not found',
+      statusCode: 404,
+    });
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    expect(jsonMock).toHaveBeenCalledWith({
+      success: false,
+      error: {
+        code: 'NOT_FOUND',
+        message: 'Item not found',
+        statusCode: 404,
+        details: null,
+      },
+    });
+  });
+
+  it('should include details array from AppException', () => {
+    const details = [{ field: 'email', constraints: { isEmail: 'must be email' } }];
+    const exception = new AppException({
+      code: ErrorCodes.VALIDATION_FAILED,
+      message: 'Validation failed',
+      statusCode: 400,
+      details,
+    });
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    expect(jsonMock).toHaveBeenCalledWith({
+      success: false,
+      error: {
+        code: 'VALIDATION_FAILED',
+        message: 'Validation failed',
+        statusCode: 400,
+        details,
+      },
+    });
+  });
+
+  it('should handle generic HttpException(403) with FORBIDDEN code', () => {
+    const exception = new HttpException('Forbidden', 403);
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    const call = jsonMock.mock.calls[0][0];
+    expect(call.success).toBe(false);
+    expect(call.error.statusCode).toBe(403);
+    expect(call.error.code).toBe('FORBIDDEN');
+    expect(call.error.details).toBeNull();
+  });
+
+  it('should handle generic HttpException(500) with INTERNAL_SERVER_ERROR code', () => {
+    const exception = new HttpException('Internal Server Error', 500);
+    const host = createMockHost(jsonMock);
+
+    filter.catch(exception, host);
+
+    const call = jsonMock.mock.calls[0][0];
+    expect(call.success).toBe(false);
+    expect(call.error.statusCode).toBe(500);
+    expect(call.error.code).toBe('INTERNAL_SERVER_ERROR');
+  });
+});

package/templates/postgres/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,43 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { LoggerService } from '../../shared/logger/logger.service';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  constructor(private readonly logger: LoggerService) {}
+
+  catch(exception: HttpException, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const statusCode = exception.getStatus();
+    const res = exception.getResponse() as any;
+    
+    const code = res.error || HttpStatus[statusCode] || 'INTERNAL_ERROR';
+    const message = res.message || exception.message;
+
+    this.logger.error(
+      `[${request.method}] ${request.url} - ${statusCode} ${code}: ${message}`,
+      exception.stack,
+    );
+
+    // Standardized Error Response
+    response.status(statusCode).json({
+      success: false,
+      error: {
+        code,
+        message,
+        statusCode,
+        timestamp: new Date().toISOString(),
+        path: request.url,
+      },
+    });
+  }
+}

package/templates/postgres/src/common/filters/rpc-exception.filter.ts

@@ -0,0 +1,18 @@
+// RPC Exception Filter — placeholder for microservice completeness.
+// Requires @nestjs/microservices to be installed.
+// When @nestjs/microservices is added, uncomment the implementation below.
+
+/*
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import { RpcException } from '@nestjs/microservices';
+import { throwError } from 'rxjs';
+
+@Catch(RpcException)
+export class RpcExceptionFilter implements ExceptionFilter {
+  catch(exception: RpcException, _host: ArgumentsHost) {
+    return throwError(() => exception.getError());
+  }
+}
+*/
+
+export {};

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

@@ -0,0 +1,5 @@
+export * from './filters/http-exception.filter';
+export * from './interceptors/transform.interceptor';
+export * from './interceptors/timeout.interceptor';
+export * from './decorators/raw-response.decorator';
+export * from './middleware/correlation-id.middleware';

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

@@ -0,0 +1,32 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable, throwError, TimeoutError } from 'rxjs';
+import { catchError, timeout } from 'rxjs/operators';
+import { AppException } from '../../shared/exceptions/app.exception';
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const timeoutMs = process.env.REQUEST_TIMEOUT
+      ? parseInt(process.env.REQUEST_TIMEOUT, 10)
+      : DEFAULT_TIMEOUT_MS;
+
+    return next.handle().pipe(
+      timeout(timeoutMs),
+      catchError((err) => {
+        if (err instanceof TimeoutError) {
+          return throwError(
+            () =>
+              new AppException({
+                code: 'REQUEST_TIMEOUT',
+                message: 'Request timeout',
+                statusCode: 408,
+              }),
+          );
+        }
+        return throwError(() => err);
+      }),
+    );
+  }
+}