typescript-express-starter 10.2.1 → 11.0.0

package/devtools/vitest/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    environment: 'node',
+    globals: true, // 전역 expect/describe/it 사용 시 편의. 원치 않으면 제거
+    setupFiles: ['src/test/setup.ts'],
+    include: ['src/test/**/*.{test,spec}.ts'], // src/test/e2e, src/test/unit에 최적화
+    exclude: ['node_modules', 'dist', 'coverage', 'logs'],
+    coverage: {
+      provider: 'v8', // v8 사용 시
+      reporter: ['text', 'html', 'lcov'],
+      reportsDirectory: 'coverage',
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/**/*.d.ts', 'src/**/index.ts', 'src/test/**'],
+    },
+    // e2e에서 포트/자원 충돌나면 단일 스레드:
+    // poolOptions: { threads: { singleThread: true } },
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-express-starter",
-  "version": "10.2.1",
+  "version": "11.0.0",
   "description": "Quick and Easy TypeScript Express Starter",
   "author": "AGUMON <ljlm0402@gmail.com>",
   "license": "MIT",
@@ -29,27 +29,40 @@
     "nginx",
     "swc"
   ],
-  "main": "bin/cli.js",
+  "type": "module",
+  "main": "bin/starter.js",
   "bin": {
-    "typescript-express-starter": "bin/cli.js"
+    "typescript-express-starter": "bin/starter.js"
   },
   "scripts": {
-    "start": "node bin/cli.js"
+    "start": "node bin/starter.js"
   },
   "dependencies": {
-    "chalk": "^4.1.2",
-    "edit-json-file": "^1.5.0",
-    "gitignore": "^0.6.0",
-    "inquirer": "^6.5.2",
+    "@clack/prompts": "^0.11.0",
+    "chalk": "^5.6.2",
+    "cli-progress": "^3.12.0",
+    "edit-json-file": "^1.8.1",
+    "execa": "^9.6.1",
+    "fs-extra": "^11.3.3",
+    "gitignore": "^0.7.0",
+    "inquirer": "^12.11.1",
     "ncp": "^2.0.0",
-    "ora": "^4.0.3"
+    "ora": "^8.2.0",
+    "recast": "^0.23.11"
+  },
+  "devDependencies": {
+    "@babel/parser": "^7.28.5",
+    "@types/node": "^24.10.6",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "ts-morph": "^26.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">= 10.13.0",
-    "npm": ">= 6.11.0"
+    "node": ">= 16.13.0",
+    "npm": ">= 9.11.0"
   },
   "repository": {
     "type": "git",

package/templates/default/nodemon.json

@@ -0,0 +1,7 @@
+{
+  "watch": ["src", ".env"],
+  "ext": "js,ts,json",
+  "ignore": ["logs/*", "**/*.spec.ts", "**/*.test.ts"],
+  "exec": "tsx src/server.ts",
+  "delay": "500"
+}

package/templates/default/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "default",
+  "version": "1.0.0",
+  "description": "default template",
+  "scripts": {
+    "start": "cross-env NODE_ENV=production node dist/server.js",
+    "dev": "cross-env NODE_ENV=development nodemon",
+    "dev:watch": "tsx watch src/server.ts",
+    "build": "tsc && tsc-alias"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "compression": "^1.8.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.5",
+    "crypto": "^1.0.1",
+    "dotenv": "^17.2.1",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.0.1",
+    "helmet": "^8.1.0",
+    "hpp": "^0.2.3",
+    "jsonwebtoken": "^9.0.2",
+    "morgan": "^1.10.1",
+    "pino": "^9.9.0",
+    "pino-pretty": "^13.1.1",
+    "pino-roll": "^3.1.0",
+    "reflect-metadata": "^0.2.2",
+    "tslib": "^2.8.1",
+    "tsyringe": "^4.10.0",
+    "zod": "^4.1.3"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.8.1",
+    "@types/cookie-parser": "^1.4.9",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/hpp": "^0.2.6",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^24.3.0",
+    "cross-env": "^10.0.0",
+    "node-gyp": "^11.4.2",
+    "nodemon": "^3.1.10",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/templates/default/src/app.ts

@@ -0,0 +1,118 @@
+import compression from 'compression';
+import cookieParser from 'cookie-parser';
+import cors from 'cors';
+import express from 'express';
+import rateLimit from 'express-rate-limit';
+import helmet from 'helmet';
+import hpp from 'hpp';
+import morgan from 'morgan';
+import { NODE_ENV, PORT, LOG_FORMAT, CREDENTIALS, CORS_ORIGIN_LIST } from '@config/env';
+import { Routes } from '@interfaces/routes.interface';
+import { ErrorMiddleware } from '@middlewares/error.middleware';
+import { NotFoundMiddleware } from '@middlewares/notFound.middleware';
+import { logger, stream } from '@utils/logger';
+
+class App {
+  public app: express.Application;
+  public env: string;
+  public port: string | number;
+
+  constructor(routes: Routes[], apiPrefix = '/api/v1') {
+    this.app = express();
+    this.env = NODE_ENV || 'development';
+    this.port = PORT || 3000;
+
+    this.initializeTrustProxy();
+    this.initializeMiddlewares();
+    this.initializeRoutes(routes, apiPrefix);
+    this.initializeErrorHandling();
+  }
+
+  public listen() {
+    const server = this.app.listen(this.port, () => {
+      logger.info(`=================================`);
+      logger.info(`======= ENV: ${this.env} =======`);
+      logger.info(`🚀 App listening on the port ${this.port}`);
+      logger.info(`=================================`);
+    });
+
+    return server;
+  }
+
+  public getServer() {
+    return this.app;
+  }
+
+  private initializeTrustProxy() {
+    // Nginx, Heroku, Cloudflare 등 프록시 환경에서 실IP 추출을 위해 필요
+    this.app.set('trust proxy', 1);
+  }
+
+  private initializeMiddlewares() {
+    this.app.use(
+      rateLimit({
+        windowMs: 60_000,
+        limit: this.env === 'production' ? 100 : 1000,
+        standardHeaders: true,
+        legacyHeaders: false,
+        skip: (req) =>
+          this.env !== 'production' ||
+          ['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.ip ?? ''),
+      }),
+    );
+
+    this.app.use(morgan(LOG_FORMAT || 'dev', { stream }));
+
+    // CORS 화이트리스트를 환경변수에서 관리
+    const allowedOrigins =
+      CORS_ORIGIN_LIST.length > 0 ? CORS_ORIGIN_LIST : ['http://localhost:3000'];
+
+    this.app.use(
+      cors({
+        origin: (origin, callback) => {
+          if (!origin || allowedOrigins.includes(origin)) {
+            callback(null, true);
+          } else {
+            callback(new Error('Not allowed by CORS'));
+          }
+        },
+        credentials: CREDENTIALS,
+      }),
+    );
+
+    this.app.use(hpp());
+    this.app.use(
+      helmet({
+        contentSecurityPolicy:
+          this.env === 'production'
+            ? {
+                directives: {
+                  defaultSrc: ["'self'"],
+                  scriptSrc: ["'self'", "'unsafe-inline'"],
+                  objectSrc: ["'none'"],
+                  upgradeInsecureRequests: [],
+                },
+              }
+            : false, // 개발 환경에서는 CSP 비활성화 (hot reload 등 편의)
+        referrerPolicy: { policy: 'no-referrer' },
+      }),
+    );
+    this.app.use(compression());
+    this.app.use(express.json({ limit: '10mb' }));
+    this.app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+    this.app.use(cookieParser());
+  }
+
+  private initializeRoutes(routes: Routes[], apiPrefix: string) {
+    routes.forEach((route) => {
+      this.app.use(apiPrefix, route.router);
+    });
+  }
+
+  private initializeErrorHandling() {
+    this.app.use(NotFoundMiddleware);
+    this.app.use(ErrorMiddleware);
+  }
+}
+
+export default App;

package/templates/default/src/config/env.ts

@@ -0,0 +1,78 @@
+import { config } from 'dotenv';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { z } from 'zod';
+
+/**
+ * 1) dotenv 로드 순서
+ *    - .env (공통)
+ *    - .env.{NODE_ENV}.local (환경별 override, 있으면 덮어씀)
+ */
+config(); // .env
+const nodeEnv = process.env.NODE_ENV || 'development';
+const layerPath = resolve(process.cwd(), `.env.${nodeEnv}.local`);
+if (existsSync(layerPath)) {
+  config({ path: layerPath });
+}
+
+/**
+ * 2) Zod 스키마 정의
+ *    - 필수/선택/기본값 정책은 필요에 맞게 수정 가능
+ */
+const EnvSchema = z
+  .object({
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    PORT: z.coerce.number().int().positive().optional(), // 기본값은 app.ts에서 3000 처리
+
+    SECRET_KEY: z.string().min(1),
+
+    LOG_FORMAT: z.string().min(1).optional(), // 기본값은 app.ts에서 'dev'
+    LOG_DIR: z.string().min(1),
+    LOG_LEVEL: z.string().min(1),
+
+    ORIGIN: z.string().min(1), // 필요시 배열화 가능
+    CREDENTIALS: z.coerce.boolean(), // 'true'/'false' 문자열 → boolean
+    CORS_ORIGINS: z.string().optional(), // "http://a.com,http://b.com"
+
+    API_SERVER_URL: z.string().url().optional(),
+
+    SENTRY_DSN: z.string().default(''),
+    REDIS_URL: z.string().url().default('redis://localhost:6379'),
+  })
+  .strip();
+
+/**
+ * 3) 검증(모듈 import 시점에 실행)
+ */
+const parsed = EnvSchema.safeParse(process.env);
+if (!parsed.success) {
+  console.error('\n❌ Invalid environment variables:\n');
+  console.error(parsed.error.format());
+  process.exit(1);
+}
+const env = parsed.data;
+
+/**
+ * 4) 타입 안전한 상수 export
+ *    - 다른 파일에서는 process.env 직접 쓰지 말고 여기서만 가져가세요.
+ */
+export const NODE_ENV = env.NODE_ENV;
+export const PORT = env.PORT; // app.ts에서 PORT || 3000
+export const SECRET_KEY = env.SECRET_KEY;
+
+export const LOG_FORMAT = env.LOG_FORMAT; // app.ts에서 LOG_FORMAT || 'dev'
+export const LOG_DIR = env.LOG_DIR;
+export const LOG_LEVEL = env.LOG_LEVEL;
+
+export const ORIGIN = env.ORIGIN;
+export const CREDENTIALS = env.CREDENTIALS;
+
+export const SENTRY_DSN = env.SENTRY_DSN;
+export const REDIS_URL = env.REDIS_URL;
+export const API_SERVER_URL = env.API_SERVER_URL;
+
+// CORS Origins를 배열로도 제공 (없으면 [])
+export const CORS_ORIGIN_LIST =
+  env.CORS_ORIGINS?.split(',')
+    .map((s) => s.trim())
+    .filter(Boolean) ?? [];

package/templates/default/src/controllers/auth.controller.ts

@@ -0,0 +1,40 @@
+import type { Request, Response } from 'express';
+import { injectable, inject } from 'tsyringe';
+import { RequestWithUser } from '@interfaces/auth.interface';
+import { type UserCreateData } from '@entities/user.entity';
+import { AuthService } from '@services/auth.service';
+import { asyncHandler } from '@utils/asyncHandler';
+
+@injectable()
+export class AuthController {
+  constructor(@inject(AuthService) private readonly authService: AuthService) {}
+
+  public signUp = asyncHandler(async (req: Request, res: Response) => {
+    const userData: UserCreateData = req.body;
+    const signUpUserData = await this.authService.signup(userData);
+
+    res.status(201).json({ data: signUpUserData.toResponse(), message: 'signup' });
+  });
+
+  public logIn = asyncHandler(async (req: Request, res: Response) => {
+    const loginData: { email: string; password: string } = req.body;
+    const { cookie, user } = await this.authService.login(loginData);
+
+    res.setHeader('Set-Cookie', [cookie]);
+    res.status(200).json({ data: user.toResponse(), message: 'login' });
+  });
+
+  public logOut = asyncHandler(async (req: Request, res: Response) => {
+    const userReq = req as RequestWithUser;
+    const user = userReq.user;
+    await this.authService.logout(user);
+
+    res.clearCookie('Authorization', {
+      httpOnly: true,
+      path: '/',
+      sameSite: 'lax',
+      // secure: true, // 프로덕션에서 HTTPS일 때만
+    });
+    res.status(200).json({ message: 'logout' });
+  });
+}

package/templates/default/src/controllers/users.controller.ts

@@ -0,0 +1,46 @@
+import type { Request, Response } from 'express';
+import { injectable, inject } from 'tsyringe';
+import { type UserCreateData } from '@entities/user.entity';
+import { UsersService } from '@services/users.service';
+import { asyncHandler } from '@utils/asyncHandler';
+
+@injectable()
+export class UsersController {
+  constructor(@inject(UsersService) private readonly userService: UsersService) {}
+
+  getUsers = asyncHandler(async (req: Request, res: Response) => {
+    const users = await this.userService.getAllUsers();
+    const userResponses = users.map((user) => user.toResponse());
+
+    res.json({ data: userResponses, message: 'findAll' });
+  });
+
+  getUserById = asyncHandler(async (req: Request, res: Response) => {
+    const userId: string = req.params.id;
+    const user = await this.userService.getUserById(userId);
+
+    res.json({ data: user.toResponse(), message: 'findById' });
+  });
+
+  createUser = asyncHandler(async (req: Request, res: Response) => {
+    const userData: UserCreateData = req.body;
+    const user = await this.userService.createUser(userData);
+
+    res.status(201).json({ data: user.toResponse(), message: 'create' });
+  });
+
+  updateUser = asyncHandler(async (req: Request, res: Response) => {
+    const userId: string = req.params.id;
+    const updateData: { email?: string; password?: string } = req.body;
+    const user = await this.userService.updateUser(userId, updateData);
+
+    res.json({ data: user.toResponse(), message: 'update' });
+  });
+
+  deleteUser = asyncHandler(async (req: Request, res: Response) => {
+    const userId: string = req.params.id;
+    await this.userService.deleteUser(userId);
+
+    res.status(204).json({ message: 'delete' });
+  });
+}

package/templates/default/src/dtos/users.dto.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+
+// 이메일 스키마 - Entity의 검증 규칙과 일치
+export const emailSchema = z
+  .string()
+  .min(1, { message: 'Email is required' })
+  .max(254, { message: 'Email is too long (max 254 characters)' })
+  .email({ message: 'Invalid email format' })
+  .transform((email) => email.toLowerCase().trim());
+
+// 비밀번호 스키마 - Entity의 검증 규칙과 일치
+export const passwordSchema = z
+  .string()
+  .min(8, { message: 'Password must be at least 8 characters long' })
+  .max(128, { message: 'Password is too long (max 128 characters)' })
+  .refine((password) => /\d/.test(password) && /[a-zA-Z]/.test(password), {
+    message: 'Password must contain at least one letter and one number',
+  });
+
+// 회원가입/로그인 DTO
+export const createUserSchema = z.object({
+  email: emailSchema,
+  password: passwordSchema,
+});
+
+export type CreateUserDto = z.infer<typeof createUserSchema>;
+
+// 로그인 DTO (동일하지만 명시적으로 분리)
+export const loginUserSchema = z.object({
+  email: emailSchema,
+  password: z.string().min(1, { message: 'Password is required' }), // 로그인시에는 기존 패스워드 검증 생략
+});
+
+export type LoginUserDto = z.infer<typeof loginUserSchema>;
+
+// 수정 DTO (모든 필드 optional)
+export const updateUserSchema = z.object({
+  email: emailSchema.optional(),
+  password: passwordSchema.optional(),
+});
+
+export type UpdateUserDto = z.infer<typeof updateUserSchema>;

package/templates/default/src/entities/user.entity.ts

@@ -0,0 +1,190 @@
+import { hash, compare } from 'bcryptjs';
+import crypto from 'crypto';
+
+export interface UserPersistenceData {
+  id: string;
+  email: string;
+  password: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface UserCreateData {
+  email: string;
+  password: string;
+}
+
+export class User {
+  private constructor(
+    private readonly _id: string,
+    private _email: string,
+    private _password: string,
+    private readonly _createdAt: Date = new Date(),
+    private _updatedAt: Date = new Date(),
+  ) {}
+
+  // 팩토리 메서드 - 새로운 사용자 생성
+  static async create(data: UserCreateData): Promise<User> {
+    const id = User.generateId();
+    const validatedEmail = User.validateEmail(data.email);
+    const hashedPassword = await User.hashPassword(data.password);
+
+    return new User(id, validatedEmail, hashedPassword);
+  }
+
+  // 기존 데이터로부터 복원 (DB에서 조회한 경우)
+  static fromPersistence(data: UserPersistenceData): User {
+    return new User(
+      data.id,
+      data.email,
+      data.password,
+      data.createdAt || new Date(),
+      data.updatedAt || new Date(),
+    );
+  }
+
+  // 비즈니스 로직 - 이메일 변경
+  async changeEmail(newEmail: string): Promise<void> {
+    const validatedEmail = User.validateEmail(newEmail);
+    this._email = validatedEmail;
+    this._updatedAt = new Date();
+  }
+
+  // 비즈니스 로직 - 패스워드 변경
+  async changePassword(newPassword: string): Promise<void> {
+    User.validatePassword(newPassword);
+    const hashedPassword = await User.hashPassword(newPassword);
+    this._password = hashedPassword;
+    this._updatedAt = new Date();
+  }
+
+  // 패스워드 검증
+  async verifyPassword(inputPassword: string): Promise<boolean> {
+    return compare(inputPassword, this._password);
+  }
+
+  // 도메인 규칙 - 이메일 검증
+  private static validateEmail(email: string): string {
+    if (!email || typeof email !== 'string') {
+      throw new Error('Email is required');
+    }
+
+    const trimmedEmail = email.trim();
+
+    if (trimmedEmail.length === 0) {
+      throw new Error('Email cannot be empty');
+    }
+
+    if (trimmedEmail.length > 254) {
+      throw new Error('Email is too long (max 254 characters)');
+    }
+
+    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+    if (!emailRegex.test(trimmedEmail)) {
+      throw new Error('Invalid email format');
+    }
+
+    return trimmedEmail.toLowerCase();
+  }
+
+  // 도메인 규칙 - 패스워드 검증
+  private static validatePassword(password: string): void {
+    if (!password || typeof password !== 'string') {
+      throw new Error('Password is required');
+    }
+
+    if (password.length < 8) {
+      throw new Error('Password must be at least 8 characters long');
+    }
+
+    if (password.length > 128) {
+      throw new Error('Password is too long (max 128 characters)');
+    }
+
+    // 최소 하나의 숫자와 하나의 문자 포함
+    const hasNumber = /\d/.test(password);
+    const hasLetter = /[a-zA-Z]/.test(password);
+
+    if (!hasNumber || !hasLetter) {
+      throw new Error('Password must contain at least one letter and one number');
+    }
+  }
+
+  // 패스워드 해싱
+  private static async hashPassword(password: string): Promise<string> {
+    User.validatePassword(password);
+    return hash(password, 12); // 보안 강화를 위해 12 rounds 사용
+  }
+
+  // ID 생성
+  private static generateId(): string {
+    return crypto.randomUUID();
+  }
+
+  // Getter들 - 외부에서 직접 수정 불가능
+  get id(): string {
+    return this._id;
+  }
+  get email(): string {
+    return this._email;
+  }
+  get password(): string {
+    return this._password;
+  }
+  get createdAt(): Date {
+    return new Date(this._createdAt);
+  } // 방어적 복사
+  get updatedAt(): Date {
+    return new Date(this._updatedAt);
+  } // 방어적 복사
+
+  // 도메인 메서드 - 사용자 정보 업데이트
+  async updateProfile(data: { email?: string; password?: string }): Promise<void> {
+    let hasChanges = false;
+
+    if (data.email && data.email !== this._email) {
+      await this.changeEmail(data.email);
+      hasChanges = true;
+    }
+
+    if (data.password) {
+      await this.changePassword(data.password);
+      hasChanges = true;
+    }
+
+    if (hasChanges) {
+      this._updatedAt = new Date();
+    }
+  }
+
+  // 영속성을 위한 직렬화
+  toPersistence(): UserPersistenceData {
+    return {
+      id: this._id,
+      email: this._email,
+      password: this._password,
+      createdAt: this._createdAt,
+      updatedAt: this._updatedAt,
+    };
+  }
+
+  // API 응답용 직렬화 (패스워드 제외)
+  toResponse(): {
+    id: string;
+    email: string;
+    createdAt: Date;
+    updatedAt: Date;
+  } {
+    return {
+      id: this._id,
+      email: this._email,
+      createdAt: this._createdAt,
+      updatedAt: this._updatedAt,
+    };
+  }
+
+  // 동등성 비교
+  equals(other: User): boolean {
+    return this._id === other._id;
+  }
+}

package/templates/default/src/exceptions/httpException.ts

@@ -0,0 +1,14 @@
+export class HttpException extends Error {
+  public status: number;
+  public message: string;
+  public data?: unknown;
+
+  constructor(status: number, message: string, data?: unknown) {
+    super(message);
+    this.status = status;
+    this.message = message;
+    this.data = data;
+    this.name = this.constructor.name;
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+}

package/{lib/knex → templates/default}/src/interfaces/auth.interface.ts

@@ -1,8 +1,8 @@
-import { Request } from 'express';
-import { User } from '@interfaces/users.interface';
+import type { Request } from 'express';
+import { User } from '@entities/user.entity';
 
 export interface DataStoredInToken {
-  id: number;
+  id: number | string;
 }
 
 export interface TokenData {