typescript-express-starter 10.2.1 → 11.0.0

package/templates/default/src/interfaces/users.interface.ts

@@ -0,0 +1,9 @@
+/**
+ * @deprecated Use User entity class from @entities/user.entity instead
+ * This interface is kept for backward compatibility only
+ */
+export interface User {
+  id?: string | number; // uuid or number-string
+  email: string;
+  password: string;
+}

package/templates/default/src/middlewares/auth.middleware.ts

@@ -0,0 +1,49 @@
+import type { Request, Response, NextFunction } from 'express';
+import { verify, TokenExpiredError, JsonWebTokenError } from 'jsonwebtoken';
+import { container } from 'tsyringe';
+import { SECRET_KEY } from '@config/env';
+import { HttpException } from '@exceptions/httpException';
+import { DataStoredInToken, RequestWithUser } from '@interfaces/auth.interface';
+import { UsersRepository } from '@repositories/users.repository';
+
+const getAuthorization = (req: RequestWithUser) => {
+  const cookie = req.cookies['Authorization'];
+  if (cookie) return cookie;
+
+  const header = req.header('Authorization');
+  if (header && header.startsWith('Bearer ')) {
+    return header.replace('Bearer ', '').trim();
+  }
+  return null;
+};
+
+export const AuthMiddleware = async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const userReq = req as RequestWithUser;
+    const token = getAuthorization(userReq);
+    if (!token) return next(new HttpException(401, 'Authentication token missing'));
+
+    let payload: DataStoredInToken;
+    try {
+      payload = verify(token, SECRET_KEY as string) as DataStoredInToken;
+    } catch (err) {
+      if (err instanceof TokenExpiredError) {
+        return next(new HttpException(401, 'Authentication token expired'));
+      }
+      if (err instanceof JsonWebTokenError) {
+        return next(new HttpException(401, 'Invalid authentication token'));
+      }
+      return next(new HttpException(401, 'Authentication failed'));
+    }
+
+    // 타입 일치 유의 (number/string)
+    const userRepo = container.resolve(UsersRepository);
+    const findUser = await userRepo.findById(String(payload.id));
+    if (!findUser) return next(new HttpException(401, 'User not found with this token'));
+
+    (req as RequestWithUser).user = findUser;
+    next();
+  } catch {
+    next(new HttpException(500, 'Authentication middleware error'));
+  }
+};

package/templates/default/src/middlewares/error.middleware.ts

@@ -0,0 +1,89 @@
+import { Request, Response, NextFunction } from 'express';
+import { JsonWebTokenError, TokenExpiredError } from 'jsonwebtoken';
+import { ZodError } from 'zod';
+import { NODE_ENV } from '@config/env';
+import { HttpException } from '@exceptions/httpException';
+import { logger } from '@utils/logger';
+
+type ValidationIssue = { path: string; message: string };
+type HttpExceptionWithData = HttpException & { data?: unknown };
+type WithStack = { stack?: string };
+
+interface ErrorDetails {
+  code: number;
+  message: string;
+  data?: unknown;
+  stack?: string;
+}
+interface ErrorResponseBody {
+  success: false;
+  error: ErrorDetails;
+}
+
+/** 타입가드들 */
+const isZodError = (e: unknown): e is ZodError => {
+  return e instanceof ZodError;
+};
+
+/** jsonwebtoken은 런타임에 따라 클래스 경계 이슈가 있을 수 있어 name 기반 가드 권장 */
+const isTokenExpiredError = (e: unknown): e is TokenExpiredError => {
+  return e instanceof Error && (e as any).name === 'TokenExpiredError';
+};
+const isJsonWebTokenError = (e: unknown): e is JsonWebTokenError => {
+  return e instanceof Error && (e as any).name === 'JsonWebTokenError';
+};
+
+const toHttpException = (err: unknown): HttpException => {
+  if (err instanceof HttpException) return err;
+
+  if (isZodError(err)) {
+    const data: ValidationIssue[] = err.issues.map((i) => ({
+      path: i.path.join('.'),
+      message: i.message,
+    }));
+    return new HttpException(400, 'Validation failed', data);
+  }
+
+  if (isTokenExpiredError(err)) return new HttpException(401, 'Token expired');
+  if (isJsonWebTokenError(err)) return new HttpException(401, 'Invalid token');
+
+  const e = err as Error | undefined;
+  return new HttpException(500, e?.message || 'Internal Server Error');
+};
+
+const extractStack = (err: unknown): string | undefined => {
+  if (err && typeof err === 'object' && 'stack' in err) {
+    const s = (err as WithStack).stack;
+    return typeof s === 'string' ? s : undefined;
+  }
+  return undefined;
+};
+
+export const ErrorMiddleware = (
+  error: unknown,
+  req: Request,
+  res: Response,
+  _next: NextFunction,
+) => {
+  const httpErr = toHttpException(error);
+  const status = httpErr.status || 500;
+  const message = httpErr.message || 'Something went wrong';
+
+  if (res.headersSent) return _next(httpErr);
+
+  const stack = extractStack(httpErr);
+  logger.error(
+    `[${req.method}] ${req.originalUrl} | ${status} | ${message}${stack ? `\n${stack}` : ''}`,
+  );
+
+  const body: ErrorResponseBody = {
+    success: false,
+    error: { code: status, message },
+  };
+
+  const maybeData = (httpErr as HttpExceptionWithData).data;
+  if (typeof maybeData !== 'undefined') body.error.data = maybeData;
+  if (NODE_ENV === 'development' && stack) body.error.stack = stack;
+
+  res.status(status).json(body);
+};

package/templates/default/src/middlewares/notFound.middleware.ts

@@ -0,0 +1,6 @@
+import type { RequestHandler } from 'express';
+import { HttpException } from '@exceptions/httpException';
+
+export const NotFoundMiddleware: RequestHandler = (_req, _res, next) => {
+  next(new HttpException(404, 'Not Found'));
+};

package/templates/default/src/middlewares/validation.middleware.ts

@@ -0,0 +1,15 @@
+import { NextFunction, Request, Response } from 'express';
+import type { ZodTypeAny } from 'zod';
+import { HttpException } from '@exceptions/httpException';
+
+export function ValidationMiddleware(schema: ZodTypeAny) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      const message = result.error.issues.map((e) => e.message).join(', ');
+      return next(new HttpException(400, message));
+    }
+    req.body = result.data;
+    next();
+  };
+}

package/templates/default/src/repositories/users.repository.ts

@@ -0,0 +1,55 @@
+import { singleton } from 'tsyringe';
+import { User, type UserPersistenceData } from '@entities/user.entity';
+
+export interface IUsersRepository {
+  findAll(): Promise<User[]>;
+  findById(id: string): Promise<User | undefined>;
+  findByEmail(email: string): Promise<User | undefined>;
+  save(user: User): Promise<User>;
+  update(id: string, user: User): Promise<User | undefined>;
+  delete(id: string): Promise<boolean>;
+}
+
+@singleton()
+export class UsersRepository implements IUsersRepository {
+  private users: UserPersistenceData[] = [];
+
+  async findAll(): Promise<User[]> {
+    return this.users.map((userData) => User.fromPersistence(userData));
+  }
+
+  async findById(id: string): Promise<User | undefined> {
+    const userData = this.users.find((u) => u.id === id);
+    return userData ? User.fromPersistence(userData) : undefined;
+  }
+
+  async findByEmail(email: string): Promise<User | undefined> {
+    const userData = this.users.find((u) => u.email === email.toLowerCase());
+    return userData ? User.fromPersistence(userData) : undefined;
+  }
+
+  async save(user: User): Promise<User> {
+    const persistenceData = user.toPersistence();
+    this.users.push(persistenceData);
+    return user;
+  }
+
+  async update(id: string, user: User): Promise<User | undefined> {
+    const idx = this.users.findIndex((u) => u.id === id);
+    if (idx === -1) return undefined;
+
+    this.users[idx] = user.toPersistence();
+    return user;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const idx = this.users.findIndex((u) => u.id === id);
+    if (idx === -1) return false;
+    this.users.splice(idx, 1);
+    return true;
+  }
+
+  reset() {
+    this.users = [];
+  }
+}

package/templates/default/src/routes/auth.route.ts

@@ -0,0 +1,31 @@
+import { Router } from 'express';
+import { injectable, inject } from 'tsyringe';
+import { AuthController } from '@controllers/auth.controller';
+import { createUserSchema } from '@dtos/users.dto';
+import { Routes } from '@interfaces/routes.interface';
+import { AuthMiddleware } from '@middlewares/auth.middleware';
+import { ValidationMiddleware } from '@middlewares/validation.middleware';
+
+@injectable()
+export class AuthRoute implements Routes {
+  public router: Router = Router();
+  public path = '/auth';
+
+  constructor(@inject(AuthController) private authController: AuthController) {
+    this.initializeRoutes();
+  }
+
+  private initializeRoutes() {
+    this.router.post(
+      `${this.path}/signup`,
+      ValidationMiddleware(createUserSchema),
+      this.authController.signUp,
+    );
+    this.router.post(
+      `${this.path}/login`,
+      ValidationMiddleware(createUserSchema),
+      this.authController.logIn,
+    );
+    this.router.post(`${this.path}/logout`, AuthMiddleware, this.authController.logOut);
+  }
+}

package/templates/default/src/routes/users.route.ts

@@ -0,0 +1,32 @@
+import { Router } from 'express';
+import { injectable, inject } from 'tsyringe';
+import { UsersController } from '@controllers/users.controller';
+import { createUserSchema, updateUserSchema } from '@dtos/users.dto';
+import { Routes } from '@interfaces/routes.interface';
+import { ValidationMiddleware } from '@middlewares/validation.middleware';
+
+@injectable()
+export class UsersRoute implements Routes {
+  public router: Router = Router();
+  public path = '/users';
+
+  constructor(@inject(UsersController) private userController: UsersController) {
+    this.initializeRoutes();
+  }
+
+  private initializeRoutes() {
+    this.router.get(this.path, this.userController.getUsers);
+    this.router.get(`${this.path}/:id`, this.userController.getUserById);
+    this.router.post(
+      this.path,
+      ValidationMiddleware(createUserSchema),
+      this.userController.createUser,
+    );
+    this.router.put(
+      `${this.path}/:id`,
+      ValidationMiddleware(updateUserSchema),
+      this.userController.updateUser,
+    );
+    this.router.delete(`${this.path}/:id`, this.userController.deleteUser);
+  }
+}

package/templates/default/src/server.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import '@config/env';
+import { container } from 'tsyringe';
+import App from '@/app';
+import { UsersRepository } from '@repositories/users.repository';
+import { AuthRoute } from '@routes/auth.route';
+import { UsersRoute } from '@routes/users.route';
+
+// DI 등록
+container.registerInstance(UsersRepository, new UsersRepository());
+
+// 라우트 모듈을 필요에 따라 동적으로 배열화 가능
+const routes = [container.resolve(UsersRoute), container.resolve(AuthRoute)];
+
+// API prefix는 app.ts에서 기본값 세팅, 필요하면 인자로 전달
+const appInstance = new App(routes);
+
+// listen()이 서버 객체(http.Server)를 반환하도록 app.ts를 살짝 수정
+const server = appInstance.listen(); // PORT를 쓰려면 이렇게 전달도 가능
+
+// Graceful Shutdown: 운영환경에서 필수!
+if (server && typeof server.close === 'function') {
+  ['SIGINT', 'SIGTERM'].forEach((signal) => {
+    process.on(signal, () => {
+      console.log(`Received ${signal}, closing server...`);
+      server.close(() => {
+        console.log('HTTP server closed gracefully');
+        // 필요하면 DB/Redis 등 외부 자원 해제 코드 추가
+        process.exit(0);
+      });
+    });
+  });
+}
+
+export default server;

package/templates/default/src/services/auth.service.ts

@@ -0,0 +1,67 @@
+import { sign } from 'jsonwebtoken';
+import { injectable, inject } from 'tsyringe';
+import { NODE_ENV, SECRET_KEY } from '@config/env';
+import { HttpException } from '@exceptions/httpException';
+import { DataStoredInToken, TokenData } from '@interfaces/auth.interface';
+import { User, type UserCreateData } from '@entities/user.entity';
+import { UsersRepository } from '@repositories/users.repository';
+import type { IUsersRepository } from '@repositories/users.repository';
+
+@injectable()
+export class AuthService {
+  constructor(@inject(UsersRepository) private usersRepository: IUsersRepository) {}
+
+  private createToken(user: User): TokenData {
+    if (!SECRET_KEY) throw new Error('SECRET_KEY is not defined');
+
+    if (user.id === undefined) {
+      throw new Error('User id is undefined');
+    }
+
+    const dataStoredInToken: DataStoredInToken = { id: user.id };
+    const expiresIn = 60 * 60; // 1h
+    const token = sign(dataStoredInToken, SECRET_KEY as string, { expiresIn });
+    return { expiresIn, token };
+  }
+
+  private createCookie(tokenData: TokenData): string {
+    return `Authorization=${tokenData.token}; HttpOnly; Max-Age=${
+      tokenData.expiresIn
+    }; Path=/; SameSite=Lax;${NODE_ENV === 'production' ? ' Secure;' : ''}`;
+  }
+
+  public async signup(userData: UserCreateData): Promise<User> {
+    const findUser = await this.usersRepository.findByEmail(userData.email);
+    if (findUser) throw new HttpException(409, `Email is already in use`);
+
+    // Entity 클래스의 팩토리 메서드로 생성 (모든 검증이 자동 처리됨)
+    const newUser = await User.create(userData);
+    await this.usersRepository.save(newUser);
+    return newUser;
+  }
+
+  public async login(loginData: {
+    email: string;
+    password: string;
+  }): Promise<{ cookie: string; user: User }> {
+    const findUser = await this.usersRepository.findByEmail(loginData.email);
+    if (!findUser) throw new HttpException(401, `Invalid email or password.`);
+
+    // Entity의 도메인 메서드로 패스워드 검증
+    const isPasswordMatching = await findUser.verifyPassword(loginData.password);
+    if (!isPasswordMatching) throw new HttpException(401, 'Password is incorrect');
+
+    const tokenData = this.createToken(findUser);
+    const cookie = this.createCookie(tokenData);
+
+    return { cookie, user: findUser };
+  }
+
+  public async logout(user: User): Promise<void> {
+    // 로그아웃은 실제 서비스에서는 서버에서 세션/리프레시토큰을 블랙리스트 처리 등 구현 가능
+    // 여기서는 클라이언트의 쿠키를 삭제하면 충분
+    console.log(`User with email ${user.email} logged out.`);
+
+    return;
+  }
+}

package/templates/default/src/services/users.service.ts

@@ -0,0 +1,48 @@
+import { injectable, inject } from 'tsyringe';
+import { HttpException } from '@exceptions/httpException';
+import { User, type UserCreateData } from '@entities/user.entity';
+import { UsersRepository } from '@repositories/users.repository';
+import type { IUsersRepository } from '@repositories/users.repository';
+
+@injectable()
+export class UsersService {
+  constructor(@inject(UsersRepository) private usersRepository: IUsersRepository) {}
+
+  async getAllUsers(): Promise<User[]> {
+    return this.usersRepository.findAll();
+  }
+
+  async getUserById(id: string): Promise<User> {
+    const user = await this.usersRepository.findById(id);
+    if (!user) throw new HttpException(404, 'User not found');
+    return user;
+  }
+
+  async createUser(userData: UserCreateData): Promise<User> {
+    // Entity에서 이메일 중복 검사를 위해 먼저 확인
+    const exists = await this.usersRepository.findByEmail(userData.email);
+    if (exists) throw new HttpException(409, 'Email already exists');
+
+    // Entity 클래스의 팩토리 메서드로 생성 (모든 검증이 자동 처리됨)
+    const user = await User.create(userData);
+    await this.usersRepository.save(user);
+    return user;
+  }
+
+  async updateUser(id: string, updateData: { email?: string; password?: string }): Promise<User> {
+    const existingUser = await this.usersRepository.findById(id);
+    if (!existingUser) throw new HttpException(404, 'User not found');
+
+    // Entity의 도메인 메서드를 사용하여 업데이트
+    await existingUser.updateProfile(updateData);
+
+    const updated = await this.usersRepository.update(id, existingUser);
+    if (!updated) throw new HttpException(404, 'User not found');
+    return updated;
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    const deleted = await this.usersRepository.delete(id);
+    if (!deleted) throw new HttpException(404, 'User not found');
+  }
+}

package/templates/default/src/utils/asyncHandler.ts

@@ -0,0 +1,8 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+
+export type AsyncHandler = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export const asyncHandler =
+  (fn: AsyncHandler): RequestHandler =>
+  (req, res, next) =>
+    Promise.resolve(fn(req, res, next)).catch(next);

package/templates/default/src/utils/logger.ts

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import pino from 'pino';
+import { LOG_DIR, LOG_LEVEL, NODE_ENV } from '@config/env';
+
+// 로그 환경 설정
+const isProd = NODE_ENV === 'production';
+const logRoot = LOG_DIR || 'logs';
+const logLevel = LOG_LEVEL || 'info';
+
+// 현재 런타임 위치(프로젝트 실행 디렉토리)에 logs 폴더 생성
+const projectRoot = process.cwd(); // 현재 프로세스 실행 디렉토리
+const logDir = join(projectRoot, logRoot);
+
+// 로그 디렉토리 생성 (에러 핸들링 포함)
+try {
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+    console.log(`[Logger Init] Created log directory: ${logDir}`);
+  } else {
+    console.log(`[Logger Init] Log directory already exists: ${logDir}`);
+  }
+} catch (error) {
+  console.error(`[Logger Init] Failed to create log directory: ${logDir}`, error);
+  throw error;
+}
+
+// 파일 로깅용 경로
+const prodFile = join(logDir, 'app');
+const devFile = join(logDir, 'app.dev');
+const errorFile = join(logDir, 'error');
+
+// Pino 인스턴스
+const transport = pino.transport({
+  targets: isProd
+    ? [
+        // prod: 일자/용량 기반 롤링 + 30일 보관 (전체 로그)
+        {
+          target: 'pino-roll',
+          level: logLevel,
+          options: {
+            file: prodFile, // 최종 파일: app.2025-08-29.log 등
+            frequency: 'daily', // 'daily' | 'hourly' | number(ms)
+            size: '50m', // 용량 기준 분할
+            dateFormat: 'yyyy-MM-dd',
+            extension: '.log',
+            mkdir: true,
+            symlink: true, // current.log 심볼릭 링크 생성
+            limit: { count: 30 }, // 30개 보관
+            // limit: { count: 30, removeOtherLogFiles: false }, // PM2/클러스터면 주의
+          },
+        },
+        // prod: 에러 전용 파일 (보관 60일 등 별도 정책 가능)
+        {
+          target: 'pino-roll',
+          level: 'error',
+          options: {
+            file: errorFile,
+            frequency: 'daily',
+            size: '50m',
+            dateFormat: 'yyyy-MM-dd',
+            extension: '.log',
+            mkdir: true,
+            symlink: true,
+            limit: { count: 60 },
+          },
+        },
+      ]
+    : [
+        // dev: 예쁜 콘솔 출력
+        {
+          target: 'pino-pretty',
+          level: logLevel,
+          options: {
+            colorize: true,
+            translateTime: 'yyyy-mm-dd HH:MM:ss',
+            ignore: 'pid,hostname',
+          },
+        },
+        // dev: 파일도 같이 굴리고 싶다면(선택) — 필요 없으면 이 블록을 지워도 됨
+        {
+          target: 'pino-roll',
+          level: logLevel,
+          options: {
+            file: devFile,
+            frequency: 'daily',
+            size: '20m',
+            dateFormat: 'yyyy-MM-dd',
+            extension: '.log',
+            mkdir: true,
+            symlink: true,
+            limit: { count: 7 },
+          },
+        },
+      ],
+});
+
+// ── Logger 인스턴스
+export const logger = pino(
+  {
+    level: logLevel,
+    base: undefined,
+    timestamp: pino.stdTimeFunctions.isoTime,
+    redact: {
+      paths: ['req.headers.authorization', 'password', 'token'],
+      censor: '[REDACTED]',
+    },
+  },
+  transport,
+);
+
+// morgan stream
+export const stream = { write: (msg: string) => logger.info(msg.trim()) };

package/{lib/typeorm → templates/default}/tsconfig.json

@@ -1,40 +1,41 @@
 {
-  "compileOnSave": false,
   "compilerOptions": {
-    "target": "es2017",
-    "lib": ["es2017", "esnext.asynciterable"],
-    "typeRoots": ["node_modules/@types"],
-    "allowSyntheticDefaultImports": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "node",
+    "target": "es2020",
     "module": "commonjs",
-    "pretty": true,
-    "sourceMap": true,
-    "declaration": true,
+    "moduleResolution": "node",
     "outDir": "dist",
-    "allowJs": true,
-    "noEmit": false,
-    "esModuleInterop": true,
-    "resolveJsonModule": true,
-    "importHelpers": true,
+    "declaration": true,
+    "sourceMap": true,
+    "strict": true,
+    "lib": ["es2020", "esnext.asynciterable"],
+
     "baseUrl": "src",
     "paths": {
       "@/*": ["*"],
-      "@config": ["config"],
+      "@config/*": ["config/*"],
       "@controllers/*": ["controllers/*"],
-      "@database": ["database"],
       "@dtos/*": ["dtos/*"],
       "@entities/*": ["entities/*"],
       "@exceptions/*": ["exceptions/*"],
       "@interfaces/*": ["interfaces/*"],
       "@middlewares/*": ["middlewares/*"],
+      "@repositories/*": ["repositories/*"],
       "@routes/*": ["routes/*"],
       "@services/*": ["services/*"],
       "@utils/*": ["utils/*"]
-    }
+    },
+
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "importHelpers": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "pretty": true,
+    "allowJs": false,
+    "noEmit": false
   },
-  "include": ["src/**/*.ts", "src/**/*.json", ".env"],
-  "exclude": ["node_modules", "src/http", "src/logs"]
+  "include": ["src/**/*.ts", "src/**/*.json"],
+  "exclude": ["node_modules", "dist", "coverage", "logs", "src/http"]
 }