@fuzionx/framework 0.1.39 → 0.1.41

package/lib/services/Service.js

@@ -1,261 +1,261 @@
-/**
- * Service — 비즈니스 로직 기본 클래스
- *
- * 컨트롤러는 얇게, 비즈니스 로직은 서비스에.
- * 트랜잭션, 캐싱, 병렬 실행, 재시도, 뮤텍스 지원.
- *
- * @see docs/framework/07-service-layer.md
- * @see docs/framework/class-design.mm.md (Service)
- */
-import Base from '../core/Base.js';
-import { ServiceError } from '../core/AppError.js';
-
-/** @type {Map<string, { value: *, expires: number }>} 전역 캐시 스토어 */
-const _cache = new Map();
-
-/** @type {Map<string, Promise>} 전역 뮤텍스 락 */
-const _locks = new Map();
-
-export default class Service extends Base {
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  트랜잭션
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * SQL 트랜잭션 실행
-     * @param {Function} callback - (trx) => Promise<T>
-     * @returns {Promise<T>}
-     */
-    async transaction(callback) {
-        const cm = this.app?._connectionManager;
-        if (!cm) throw new Error('Database not configured for transactions');
-
-        const conn = cm.get();
-        if (conn.type === 'knex' && conn.db) {
-            return conn.db.transaction(callback);
-        }
-        throw new Error('SQL database not configured for transactions');
-    }
-
-    /**
-     * MongoDB 트랜잭션 실행
-     * @param {string} connName - MongoDB 연결명
-     * @param {Function} callback - (session) => Promise<T>
-     * @returns {Promise<T>}
-     */
-    async mongoTransaction(connName, callback) {
-        const cm = this.app?._connectionManager;
-        if (!cm) throw new Error('Database not configured');
-
-        const conn = cm.get(connName);
-        if (conn.type !== 'mongo' || !conn.mongoose) {
-            throw new Error(`MongoDB connection '${connName}' not found`);
-        }
-
-        const session = await conn.mongoose.startSession();
-        try {
-            session.startTransaction();
-            const result = await callback(session);
-            await session.commitTransaction();
-            return result;
-        } catch (err) {
-            await session.abortTransaction();
-            throw err;
-        } finally {
-            session.endSession();
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  캐시
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * TTL 기반 인메모리 캐시로 감싸기
-     *
-     * @param {string} key - 캐시 키
-     * @param {number} ttl - TTL (초)
-     * @param {Function} fn - 캐시 미스 시 실행할 함수
-     * @returns {Promise<*>}
-     *
-     * @example
-     * const stats = await this.withCache('dashboard:stats', 300, async () => {
-     *     return this.db.Order.raw('SELECT SUM(total) ...');
-     * });
-     */
-    async withCache(key, ttl, fn) {
-        const cached = _cache.get(key);
-        if (cached && cached.expires > Date.now()) {
-            return cached.value;
-        }
-
-        const value = await fn();
-        _cache.set(key, {
-            value,
-            expires: Date.now() + (ttl * 1000),
-        });
-        return value;
-    }
-
-    /**
-     * 캐시 키 무효화
-     * @param {string} key
-     */
-    invalidateCache(key) {
-        _cache.delete(key);
-    }
-
-    /**
-     * 전체 캐시 초기화
-     */
-    clearCache() {
-        _cache.clear();
-    }
-
-    /**
-     * 캐시 존재 여부
-     * @param {string} key
-     * @returns {boolean}
-     */
-    hasCache(key) {
-        const cached = _cache.get(key);
-        return cached ? cached.expires > Date.now() : false;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  병렬 실행
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 여러 함수를 병렬 실행
-     *
-     * @param {Array<Function>} tasks - () => Promise 형태의 함수 배열
-     * @param {object} [opts]
-     * @param {boolean} [opts.failFast=false] - true면 하나 실패 시 전체 reject
-     * @returns {Promise<Array>} 결과 배열 (failFast=false 시 에러도 포함)
-     *
-     * @example
-     * const [users, orders, stats] = await this.runParallel([
-     *     () => this.db.User.count(),
-     *     () => this.db.Order.where('status', 'active').get(),
-     *     () => this.calculateStats(),
-     * ]);
-     */
-    async runParallel(tasks, opts = {}) {
-        const promises = tasks.map(fn => fn());
-
-        if (opts.failFast) {
-            return Promise.all(promises);
-        }
-
-        const results = await Promise.allSettled(promises);
-        return results.map(r => {
-            if (r.status === 'fulfilled') return r.value;
-            // 실패 시 에러 객체 반환 (throw하지 않음)
-            return r.reason;
-        });
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  재시도
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 재시도 + 지수 백오프
-     *
-     * @param {Function} fn - 실행할 함수
-     * @param {object} [opts]
-     * @param {number} [opts.retries=3] - 재시도 횟수
-     * @param {number} [opts.delay=1000] - 초기 지연 (ms)
-     * @param {number} [opts.backoff=2] - 백오프 배수
-     * @param {Function} [opts.shouldRetry] - (err, attempt) => boolean
-     * @returns {Promise<*>}
-     *
-     * @example
-     * const data = await this.retryable(
-     *     () => fetch('https://api.external.com/data'),
-     *     { retries: 3, delay: 1000, backoff: 2 }
-     * );
-     */
-    async retryable(fn, opts = {}) {
-        const { retries = 3, delay = 1000, backoff = 2, shouldRetry } = opts;
-        let lastError;
-        let currentDelay = delay;
-
-        for (let attempt = 0; attempt <= retries; attempt++) {
-            try {
-                return await fn();
-            } catch (err) {
-                lastError = err;
-
-                if (attempt === retries) break;
-                if (shouldRetry && !shouldRetry(err, attempt)) break;
-
-                await new Promise(r => setTimeout(r, currentDelay));
-                currentDelay *= backoff;
-            }
-        }
-
-        throw lastError;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  뮤텍스
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 동시 실행 방지 (in-process lock)
-     *
-     * 같은 key에 대해 동시에 1개만 실행.
-     * 이전 실행 완료 후 다음 실행.
-     *
-     * @param {string} key - 락 키
-     * @param {Function} fn - 실행할 함수
-     * @returns {Promise<*>}
-     *
-     * @example
-     * await this.mutex('order:process:' + orderId, async () => {
-     *     const order = await this.db.Order.findOrFail(orderId);
-     *     await order.update({ status: 'processing' });
-     * });
-     */
-    async mutex(key, fn) {
-        // 이전 락이 있으면 대기
-        while (_locks.has(key)) {
-            await _locks.get(key);
-        }
-
-        // 새 락 설정
-        let releaseLock;
-        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
-        _locks.set(key, lockPromise);
-
-        try {
-            return await fn();
-        } finally {
-            _locks.delete(key);
-            releaseLock();
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  에러
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 에러 생성 헬퍼
-     * @param {string} message
-     * @param {number} [status=400]
-     * @returns {ServiceError}
-     */
-    error(message, status = 400) {
-        return new ServiceError(message, status);
-    }
-}
-
-/**
- * 캐시 스토어 접근 (테스트용)
- * @returns {Map}
- */
-export { _cache, _locks };
+/**
+ * Service — 비즈니스 로직 기본 클래스
+ *
+ * 컨트롤러는 얇게, 비즈니스 로직은 서비스에.
+ * 트랜잭션, 캐싱, 병렬 실행, 재시도, 뮤텍스 지원.
+ *
+ * @see docs/framework/07-service-layer.md
+ * @see docs/framework/class-design.mm.md (Service)
+ */
+import Base from '../core/Base.js';
+import { ServiceError } from '../core/AppError.js';
+
+/** @type {Map<string, { value: *, expires: number }>} 전역 캐시 스토어 */
+const _cache = new Map();
+
+/** @type {Map<string, Promise>} 전역 뮤텍스 락 */
+const _locks = new Map();
+
+export default class Service extends Base {
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  트랜잭션
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * SQL 트랜잭션 실행
+     * @param {Function} callback - (trx) => Promise<T>
+     * @returns {Promise<T>}
+     */
+    async transaction(callback) {
+        const cm = this.app?._connectionManager;
+        if (!cm) throw new Error('Database not configured for transactions');
+
+        const conn = cm.get();
+        if (conn.type === 'knex' && conn.db) {
+            return conn.db.transaction(callback);
+        }
+        throw new Error('SQL database not configured for transactions');
+    }
+
+    /**
+     * MongoDB 트랜잭션 실행
+     * @param {string} connName - MongoDB 연결명
+     * @param {Function} callback - (session) => Promise<T>
+     * @returns {Promise<T>}
+     */
+    async mongoTransaction(connName, callback) {
+        const cm = this.app?._connectionManager;
+        if (!cm) throw new Error('Database not configured');
+
+        const conn = cm.get(connName);
+        if (conn.type !== 'mongo' || !conn.mongoose) {
+            throw new Error(`MongoDB connection '${connName}' not found`);
+        }
+
+        const session = await conn.mongoose.startSession();
+        try {
+            session.startTransaction();
+            const result = await callback(session);
+            await session.commitTransaction();
+            return result;
+        } catch (err) {
+            await session.abortTransaction();
+            throw err;
+        } finally {
+            session.endSession();
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  캐시
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * TTL 기반 인메모리 캐시로 감싸기
+     *
+     * @param {string} key - 캐시 키
+     * @param {number} ttl - TTL (초)
+     * @param {Function} fn - 캐시 미스 시 실행할 함수
+     * @returns {Promise<*>}
+     *
+     * @example
+     * const stats = await this.withCache('dashboard:stats', 300, async () => {
+     *     return this.db.Order.raw('SELECT SUM(total) ...');
+     * });
+     */
+    async withCache(key, ttl, fn) {
+        const cached = _cache.get(key);
+        if (cached && cached.expires > Date.now()) {
+            return cached.value;
+        }
+
+        const value = await fn();
+        _cache.set(key, {
+            value,
+            expires: Date.now() + (ttl * 1000),
+        });
+        return value;
+    }
+
+    /**
+     * 캐시 키 무효화
+     * @param {string} key
+     */
+    invalidateCache(key) {
+        _cache.delete(key);
+    }
+
+    /**
+     * 전체 캐시 초기화
+     */
+    clearCache() {
+        _cache.clear();
+    }
+
+    /**
+     * 캐시 존재 여부
+     * @param {string} key
+     * @returns {boolean}
+     */
+    hasCache(key) {
+        const cached = _cache.get(key);
+        return cached ? cached.expires > Date.now() : false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  병렬 실행
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 여러 함수를 병렬 실행
+     *
+     * @param {Array<Function>} tasks - () => Promise 형태의 함수 배열
+     * @param {object} [opts]
+     * @param {boolean} [opts.failFast=false] - true면 하나 실패 시 전체 reject
+     * @returns {Promise<Array>} 결과 배열 (failFast=false 시 에러도 포함)
+     *
+     * @example
+     * const [users, orders, stats] = await this.runParallel([
+     *     () => this.db.User.count(),
+     *     () => this.db.Order.where('status', 'active').get(),
+     *     () => this.calculateStats(),
+     * ]);
+     */
+    async runParallel(tasks, opts = {}) {
+        const promises = tasks.map(fn => fn());
+
+        if (opts.failFast) {
+            return Promise.all(promises);
+        }
+
+        const results = await Promise.allSettled(promises);
+        return results.map(r => {
+            if (r.status === 'fulfilled') return r.value;
+            // 실패 시 에러 객체 반환 (throw하지 않음)
+            return r.reason;
+        });
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  재시도
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 재시도 + 지수 백오프
+     *
+     * @param {Function} fn - 실행할 함수
+     * @param {object} [opts]
+     * @param {number} [opts.retries=3] - 재시도 횟수
+     * @param {number} [opts.delay=1000] - 초기 지연 (ms)
+     * @param {number} [opts.backoff=2] - 백오프 배수
+     * @param {Function} [opts.shouldRetry] - (err, attempt) => boolean
+     * @returns {Promise<*>}
+     *
+     * @example
+     * const data = await this.retryable(
+     *     () => fetch('https://api.external.com/data'),
+     *     { retries: 3, delay: 1000, backoff: 2 }
+     * );
+     */
+    async retryable(fn, opts = {}) {
+        const { retries = 3, delay = 1000, backoff = 2, shouldRetry } = opts;
+        let lastError;
+        let currentDelay = delay;
+
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                return await fn();
+            } catch (err) {
+                lastError = err;
+
+                if (attempt === retries) break;
+                if (shouldRetry && !shouldRetry(err, attempt)) break;
+
+                await new Promise(r => setTimeout(r, currentDelay));
+                currentDelay *= backoff;
+            }
+        }
+
+        throw lastError;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  뮤텍스
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 동시 실행 방지 (in-process lock)
+     *
+     * 같은 key에 대해 동시에 1개만 실행.
+     * 이전 실행 완료 후 다음 실행.
+     *
+     * @param {string} key - 락 키
+     * @param {Function} fn - 실행할 함수
+     * @returns {Promise<*>}
+     *
+     * @example
+     * await this.mutex('order:process:' + orderId, async () => {
+     *     const order = await this.db.Order.findOrFail(orderId);
+     *     await order.update({ status: 'processing' });
+     * });
+     */
+    async mutex(key, fn) {
+        // 이전 락이 있으면 대기
+        while (_locks.has(key)) {
+            await _locks.get(key);
+        }
+
+        // 새 락 설정
+        let releaseLock;
+        const lockPromise = new Promise(resolve => { releaseLock = resolve; });
+        _locks.set(key, lockPromise);
+
+        try {
+            return await fn();
+        } finally {
+            _locks.delete(key);
+            releaseLock();
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  에러
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 에러 생성 헬퍼
+     * @param {string} message
+     * @param {number} [status=400]
+     * @returns {ServiceError}
+     */
+    error(message, status = 400) {
+        return new ServiceError(message, status);
+    }
+}
+
+/**
+ * 캐시 스토어 접근 (테스트용)
+ * @returns {Map}
+ */
+export { _cache, _locks };