@jeonghochoi/core-worker

NestJS 기반 Worker / Batch / Scheduler 서비스에서 공통으로 사용하는
인프라 레벨 모듈들을 모아둔 패키지입니다.

DB, HTTP, Mail, Logger, Crypto, File 처리 등
워커 전반에서 반복적으로 필요한 기능을 일관된 인터페이스로 제공합니다.

이 패키지는 비즈니스 로직을 포함하지 않습니다.
워커 인프라 표준화 및 중복 코드 제거를 목적으로 합니다.

✨ Features

• ✅ Worker 공통 인프라 모듈 제공
• ✅ 다중 DB(MySQL / PostgreSQL / MSSQL) 지원
• ✅ HTTP Client + Retry 공통화
• ✅ 메일(SMTP / SES) 전송 추상화
• ✅ 파일 업로드(S3 / FTP / Local) 유틸
• ✅ Excel / CSV 대용량 파일 처리
• ✅ 암·복호화 및 범용 유틸
• ✅ tsup 기반 ESM 패키징

📦 Installation

npm install @jeonghochoi/core-worker
# or
yarn add @jeonghochoi/core-worker

⚠️ NestJS Worker 환경을 전제로 합니다.

📁 Project Structure

src
├─ core
│  ├─ config        # 환경 변수 / 설정 관리
│  ├─ database      # DB 어댑터 (mysql, pg, mssql)
│  ├─ http          # HTTP Client (axios 기반)
│  ├─ logger        # Pino 기반 로거
│  ├─ mail          # Mail (SMTP / SES)
│  └─ index.ts
│
├─ tool
│  ├─ crypto        # 암·복호화 / 해시 유틸
│  ├─ file          # 파일 처리 / 업로드
│  ├─ tool          # 범용 유틸
│  └─ index.ts
│
└─ index.ts         # Public entry

🔗 Peer Dependencies

이 패키지는 아래 패키지를 호스트 프로젝트에서 직접 설치해야 합니다.

{
    "@nestjs/common": "^10 || ^11",
    "@nestjs/config": "^3 || ^4"
}

NestJS 메이저 버전에 직접 종속되지 않도록
peerDependencies로 분리되어 있습니다.

📚 Included Dependencies

Database

• mysql2
• pg
• mssql

HTTP

• axios
• axios-retry
• rxjs

Mail

• nodemailer
• handlebars
• @aws-sdk/client-ses

File / Storage

• exceljs
• csv-stringify
• basic-ftp
• @aws-sdk/client-s3

Logging / Validation

• pino
• zod

🚀 Usage (패키지 사용하는 쪽에서 선언/사용하기)

이 패키지는 단일 엔트리포인트(@jeonghochoi/core-worker)를 통해 export 됩니다.

import { CoreConfigModule, LoggerModule } from '@jeonghochoi/core-worker';

@jeonghochoi/core-worker/tool 같은 서브패스 import는 exports에 열려있지 않으므로, 항상 루트 경로(@jeonghochoi/core-worker)에서 import 해야 합니다.

1) 호스트 프로젝트에서 의존성 선언

npm install @jeonghochoi/core-worker @nestjs/common @nestjs/config zod

2) AppModule에서 CoreConfigModule + 인프라 모듈 선언

import { Module } from '@nestjs/common';
import { z } from 'zod';
import {
    CoreConfigModule,
    DatabaseConfigSchema,
    DatabaseModule,
    HttpModule,
    loadEnv,
    LoggerConfigSchema,
    LoggerModule,
    MailModule,
    SmtpConfigSchema,
} from '@jeonghochoi/core-worker';

const WorkerConfigSchema = z.object({
    logger: LoggerConfigSchema,
    database: DatabaseConfigSchema,
    smtp: SmtpConfigSchema,
    mailTemplateDir: z.string(),
});

@Module({
    imports: [
        CoreConfigModule.forRoot({
            schema: WorkerConfigSchema,
            load: loadEnv,
        }),
        LoggerModule,
        HttpModule,
        DatabaseModule,
        MailModule,
    ],
})
export class AppModule {}

3) 서비스에서 주입받아 사용

import { Injectable } from '@nestjs/common';
import {
    DatabaseAdapterRegistry,
    HttpClient,
    MailService,
    WorkerLogger,
} from '@jeonghochoi/core-worker';

@Injectable()
export class BatchJob {
    constructor(
        private readonly logger: WorkerLogger,
        private readonly httpClient: HttpClient,
        private readonly dbRegistry: DatabaseAdapterRegistry,
        private readonly mailService: MailService
    ) {}

    async run() {
        this.logger.log('batch started');

        // HTTP
        this.httpClient.register('partner', {
            baseURL: 'https://api.example.com',
            timeoutMs: 5000,
            retries: 3,
        });
        const health = await this.httpClient.use('partner').get('/health');

        // DB
        const db = await this.dbRegistry.getConnection('main');
        await db.query('select 1');

        // Mail
        await this.mailService.send('smtp', 'job-finished', { ok: true }, {
            to: '[email protected]',
            subject: 'Batch done',
        });

        this.logger.log(`health: ${health.status}`);
    }
}

4) 유틸 함수 사용

import { Codec, Hash, Tool } from '@jeonghochoi/core-worker';

const base64 = Codec.toBase64('worker');
const sha = Hash.sha256('payload');
const txId = Tool.unique.txId();

🛠 Build

npm run build

• tsup 기반 빌드
• ESM 패키지
• 결과물은 dist/ 디렉토리에 생성됩니다.

📐 Design Principles

• Worker 친화적 구조
• Stateless 설계 지향
• 비즈니스 로직 배제
• 인프라 코드의 재사용성과 일관성 우선
• API 서버보다 Batch / Queue / Scheduler 사용을 전제로 설계

⚠️ Notes

• API 서버에서도 사용은 가능하지만 일부 모듈은 워커 기준으로 설계됨
• 장기 실행 프로세스(daemon) 환경을 고려하여 작성됨
• Windows / Linux 환경 모두 대응

📄 License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...