fix(core): pm2 peer 범위 확대 및 optional 전환

.changeset/smooth-dryers-occur.md

@@ -0,0 +1,7 @@
+---
+"@naverpay/prometheus-core": minor
+---
+
+fix(core): pm2 peer 범위 확대 및 optional 전환
+
+PR: [fix(core): pm2 peer 범위 확대 및 optional 전환](https://github.com/NaverPayDev/prometheus/pull/20)

packages/core/README.md

@@ -316,9 +316,9 @@ interface PM2GetMessageOptions {
 
 ## 요구 사항
 
-- Node.js 16.0.0 이상
+- Node.js 16.0.0 이상 (PM2 7.x 사용 시 18.0.0 이상)
 - TypeScript 4.5 이상
-- PM2 사용 시: PM2 5.0.0 이상
+- PM2는 선택적(optional) peer dependency이며, PM2 클러스터 모드 사용 시에만 필요합니다 (PM2 5.3.0 이상, 6.x·7.x 포함)
 
 ## 라이센스
 

packages/core/package.json

@@ -54,7 +54,12 @@
         "vite": "catalog:"
     },
     "peerDependencies": {
-        "pm2": ">=5.3.0 <6.0.0"
+        "pm2": ">=5.3.0"
+    },
+    "peerDependenciesMeta": {
+        "pm2": {
+            "optional": true
+        }
     },
     "packageManager": "pnpm@10.6.5"
 }

packages/core/src/pm2/promisify.ts

@@ -1,24 +1,48 @@
 import {promisify} from 'node:util'
 
-import pm2 from 'pm2'
-
-import type {PM2RequestPacket} from './types'
+import type {PM2ProcessDescription, PM2RequestPacket} from './types'
 import type {EventEmitter} from 'node:events'
+import type PM2 from 'pm2'
+
+let pm2Module: typeof PM2 | undefined
+
+/**
+ * Lazily loads the pm2 module so that consumers who don't use PM2-based
+ * features never trigger `Cannot find module 'pm2'` at import time
+ * @returns Loaded pm2 module
+ */
+async function loadPm2(): Promise<typeof PM2> {
+    if (!pm2Module) {
+        const imported = await import('pm2')
+        pm2Module = imported.default
+    }
+    return pm2Module
+}
 
 /** Promisified PM2 connect function */
-const connect = promisify(pm2.connect.bind(pm2))
+async function connect(): Promise<void> {
+    const pm2 = await loadPm2()
+    return promisify(pm2.connect.bind(pm2))()
+}
 
 /** Promisified PM2 disconnect function */
-const disconnect = promisify(pm2.disconnect.bind(pm2))
+async function disconnect(): Promise<void> {
+    const pm2 = await loadPm2()
+    await promisify(pm2.disconnect.bind(pm2))()
+}
 
 /** Promisified PM2 list function */
-const list = promisify(pm2.list.bind(pm2))
+async function list(): Promise<PM2ProcessDescription[]> {
+    const pm2 = await loadPm2()
+    return promisify(pm2.list.bind(pm2))()
+}
 
 /**
  * Promisified PM2 launchBus function
  * @returns Promise that resolves to EventEmitter for PM2 bus communication
  */
-function launchBus(): Promise<EventEmitter> {
+async function launchBus(): Promise<EventEmitter> {
+    const pm2 = await loadPm2()
     return new Promise((resolve, reject) => {
         pm2.launchBus((error, bus) => {
             if (error) {
@@ -35,7 +59,8 @@ function launchBus(): Promise<EventEmitter> {
  * @param packet - Data packet to send
  * @returns Promise that resolves when data is sent
  */
-function sendDataToProcessId(pmId: number, packet: PM2RequestPacket): Promise<void> {
+async function sendDataToProcessId(pmId: number, packet: PM2RequestPacket): Promise<void> {
+    const pm2 = await loadPm2()
     return new Promise((resolve, reject) => {
         pm2.sendDataToProcessId(pmId, packet, (error: Error) => {
             if (error) {

packages/core/src/pm2/types.ts

@@ -1,14 +1,24 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import type {ProcessDescription} from 'pm2'
+/**
+ * Minimal subset of pm2's `ProcessDescription` fields actually used by this
+ * package, redeclared locally so consumers without pm2 installed don't hit
+ * `Cannot find module 'pm2'` when resolving this package's type declarations
+ */
+export interface PM2ProcessDescription {
+    /** Process name registered in PM2 */
+    name?: string
+    /** PM2-assigned process ID */
+    pm_id?: number
+}
 
 /** Handler function type for PM2 messages */
 export type PM2MessageHandler<T = any, R = any> = (data: T) => Promise<R> | R
 
 /** Configuration options for getting PM2 messages */
 export interface PM2GetMessageOptions {
     /** Filter function to select which processes to query */
-    filter?: (process: ProcessDescription) => boolean
+    filter?: (process: PM2ProcessDescription) => boolean
     /** Whether to include self if not managed by PM2 */
     includeSelfIfUnmanaged?: boolean
     /** Timeout in milliseconds for message collection */