@fuzionx/framework 0.1.29 → 0.1.31

package/lib/schedule/Scheduler.js

@@ -1,38 +1,47 @@
 /**
- * Scheduler — Job 스케줄 관리 (마스터 프로세스)
+ * Scheduler — 정기 실행 작업 관리 (cron 스케줄)
+ *
+ * AutoLoader가 shared/jobs/ 에서 Job 클래스를 자동 스캔·등록.
+ * handle()은 메인 스레드에서 실행되므로 this.db, this.service() 등
+ * 앱 컨텍스트에 접근 가능합니다.
+ *
+ * CPU-intensive 작업은 handle() 내에서 this.worker.run()으로 위임.
  *
  * @see docs/framework/10-scheduler-queue.md
- * @see docs/framework/class-design.mm.md (Scheduler)
+ * @see lib/schedule/WorkerPool.js
  */
 export default class Scheduler {
+    /**
+     * @param {import('../core/Application.js').default} app
+     */
     constructor(app) {
         this.app = app;
+        /** @type {Array<{JobClass: typeof import('./Job.js').default}>} */
         this._jobs = [];
+        /** @type {Array<NodeJS.Timeout>} */
         this._timers = [];
-        this._running = false;
     }
 
     /**
-     * Job 등록
+     * Job 클래스 등록 (AutoLoader에서 호출)
      * @param {typeof import('./Job.js').default} JobClass
      */
     register(JobClass) {
-        this._jobs.push(JobClass);
+        if (!JobClass.schedule) return;
+        if (JobClass.enabled === false) return;
+        this._jobs.push({ JobClass });
     }
 
     /**
-     * 모든 스케줄 시작
+     * 등록된 모든 Job 시작
      */
     start() {
-        if (this._running) return;
-        this._running = true;
-
-        for (const JobClass of this._jobs) {
-            // enabled === false면 스킵 (10-scheduler-queue.md)
-            if (JobClass.enabled === false) continue;
-
-            const interval = this._parseCron(JobClass.schedule);
-            if (!interval) continue;
+        for (const { JobClass } of this._jobs) {
+            const interval = this._parseSchedule(JobClass.schedule);
+            if (!interval) {
+                this.app?.logger?.warn?.(`[Scheduler] Invalid schedule: ${JobClass.name} → '${JobClass.schedule}'`);
+                continue;
+            }
 
             const timeout = JobClass.timeout || 30000;
 
@@ -46,7 +55,11 @@ export default class Scheduler {
                         ),
                     ]);
                 } catch (err) {
-                    await job.onError(err);
+                    if (typeof job.onError === 'function') {
+                        try { await job.onError(err); } catch {}
+                    } else {
+                        this.app?.logger?.error?.(`[Scheduler] ${JobClass.name} failed: ${err.message}`);
+                    }
                 }
             };
 
@@ -62,12 +75,18 @@ export default class Scheduler {
             } else {
                 const timer = setInterval(runJob, interval);
                 this._timers.push(timer);
+                // 즉시 첫 실행
+                runJob();
             }
+
+            this.app?.logger?.info?.(
+                `[Scheduler] ${JobClass.name} registered (${JobClass.schedule}, interval=${interval}ms)`
+            );
         }
     }
 
     /**
-     * 모든 스케줄 정지
+     * 모든 타이머 정지
      */
     stop() {
         for (const timer of this._timers) {
@@ -75,87 +94,77 @@ export default class Scheduler {
             clearTimeout(timer);
         }
         this._timers = [];
-        this._running = false;
+    }
+
+    // ── Schedule 파싱 ──
+
+    /**
+     * 간편 스케줄 → ms 변환
+     *
+     * 지원 포맷:
+     *   'every:5s'  → 5000ms
+     *   'every:5m'  → 300000ms
+     *   'every:1h'  → 3600000ms
+     *   'daily:HH:MM'      → 24h (첫 실행은 _calcInitialDelay)
+     *   'weekly:DAY:HH:MM' → 7d  (첫 실행은 _calcInitialDelay)
+     */
+    _parseSchedule(schedule) {
+        if (!schedule) return null;
+
+        // every:Ns/Nm/Nh
+        const everyMatch = schedule.match(/^every:(\d+)(s|m|h)$/i);
+        if (everyMatch) {
+            const val = parseInt(everyMatch[1], 10);
+            const unit = everyMatch[2].toLowerCase();
+            if (unit === 's') return val * 1000;
+            if (unit === 'm') return val * 60000;
+            if (unit === 'h') return val * 3600000;
+        }
+
+        // daily:HH:MM → 24시간 간격
+        if (/^daily:\d{2}:\d{2}$/.test(schedule)) {
+            return 24 * 60 * 60 * 1000;
+        }
+
+        // weekly:DAY:HH:MM → 7일 간격
+        if (/^weekly:\w+:\d{2}:\d{2}$/.test(schedule)) {
+            return 7 * 24 * 60 * 60 * 1000;
+        }
+
+        return null;
     }
 
     /**
-     * daily/weekly 스케줄의 첫 실행까지 지연(ms) 계산
-     * @param {string} schedule
-     * @returns {number} 0이면 즉시 setInterval, >0이면 setTimeout 필요
-     * @private
+     * daily/weekly 스케줄의 첫 실행 지연시간 계산
      */
     _calcInitialDelay(schedule) {
         const now = new Date();
 
-        // 'daily:HH:MM'
+        // daily:HH:MM
         const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
         if (dailyMatch) {
-            const [, h, m] = dailyMatch;
             const target = new Date(now);
-            target.setHours(Number(h), Number(m), 0, 0);
+            target.setHours(parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), 0, 0);
             if (target <= now) target.setDate(target.getDate() + 1);
             return target - now;
         }
 
-        // 'weekly:day:HH:MM'
+        // weekly:DAY:HH:MM
         const weeklyMatch = schedule.match(/^weekly:(\w+):(\d{2}):(\d{2})$/);
         if (weeklyMatch) {
             const days = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
-            const [, day, h, m] = weeklyMatch;
-            const targetDay = days[day.toLowerCase()] ?? 0;
+            const targetDay = days[weeklyMatch[1].toLowerCase()];
+            if (targetDay === undefined) return 0;
+
             const target = new Date(now);
-            target.setHours(Number(h), Number(m), 0, 0);
+            target.setHours(parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), 0, 0);
+
             let diff = targetDay - now.getDay();
             if (diff < 0 || (diff === 0 && target <= now)) diff += 7;
             target.setDate(target.getDate() + diff);
             return target - now;
         }
 
-        return 0; // every:*, cron → 즉시 setInterval
-    }
-
-    /**
-     * 간단 cron 파서 — 간격(ms) 또는 다음 실행까지 지연(ms) 반환
-     * 지원:
-     *   'every:30s' / 'every:5m' / 'every:1h'
-     *   'daily:02:00' — 매일 HH:MM
-     *   'weekly:mon:09:00' — 매주 요일 HH:MM
-     *   '* * * * *' — 매분 (60초)
-     *   5-field cron — 분 단위 간격 근사
-     * @private
-     */
-    _parseCron(schedule) {
-        if (!schedule) return null;
-
-        // 'every:30s' → 30000ms
-        const everyMatch = schedule.match(/^every:(\d+)([smh])$/);
-        if (everyMatch) {
-            const [, num, unit] = everyMatch;
-            const multiplier = { s: 1000, m: 60000, h: 3600000 };
-            return Number(num) * multiplier[unit];
-        }
-
-        // 'daily:HH:MM' → 24h interval
-        const dailyMatch = schedule.match(/^daily:(\d{2}):(\d{2})$/);
-        if (dailyMatch) {
-            return 86400000;
-        }
-
-        // 'weekly:day:HH:MM' → 7일 간격
-        const weeklyMatch = schedule.match(/^weekly:\w+:\d{2}:\d{2}$/);
-        if (weeklyMatch) {
-            return 604800000;
-        }
-
-        // 5-field cron: '*/5 * * * *' → 분 단위 추출
-        const cronMatch = schedule.match(/^\*\/(\d+)\s/);
-        if (cronMatch) {
-            return Number(cronMatch[1]) * 60000;
-        }
-
-        // '* * * * *' → 60000ms (매분)
-        if (schedule.match(/^[\d*\/,-]+(\s[\d*\/,-]+){4}$/)) return 60000;
-
-        return null;
+        return 0; // every:* → 즉시 시작
     }
 }

package/lib/utilities/ArrUtil.js

@@ -0,0 +1,112 @@
+/**
+ * ArrUtil — 배열 순수 유틸리티
+ */
+
+/**
+ * 배열을 n개씩 분할
+ * @param {Array} arr
+ * @param {number} size
+ * @returns {Array<Array>}
+ *
+ * @example chunk([1,2,3,4,5], 2) → [[1,2], [3,4], [5]]
+ */
+export function chunk(arr, size) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += size) {
+        result.push(arr.slice(i, i + size));
+    }
+    return result;
+}
+
+/**
+ * 중복 제거
+ * @param {Array} arr
+ * @param {Function} [keyFn] - 비교 키 추출 함수
+ * @returns {Array}
+ */
+export function unique(arr, keyFn) {
+    if (!keyFn) return [...new Set(arr)];
+    const seen = new Set();
+    return arr.filter(item => {
+        const key = keyFn(item);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+}
+
+/**
+ * 키 기준 그룹핑
+ * @param {Array<object>} arr
+ * @param {string|Function} key
+ * @returns {object}
+ *
+ * @example groupBy([{a:1,b:'x'},{a:2,b:'x'},{a:3,b:'y'}], 'b') → { x: [...], y: [...] }
+ */
+export function groupBy(arr, key) {
+    const fn = typeof key === 'function' ? key : (item) => item[key];
+    return arr.reduce((acc, item) => {
+        const k = fn(item);
+        (acc[k] = acc[k] || []).push(item);
+        return acc;
+    }, {});
+}
+
+/**
+ * 특정 키 값만 추출
+ * @param {Array<object>} arr
+ * @param {string} key
+ * @returns {Array}
+ *
+ * @example pluck([{id:1,name:'a'},{id:2,name:'b'}], 'name') → ['a', 'b']
+ */
+export function pluck(arr, key) {
+    return arr.map(item => item[key]);
+}
+
+/**
+ * 키맵 생성 (배열 → 객체)
+ * @param {Array<object>} arr
+ * @param {string} key
+ * @returns {object}
+ *
+ * @example keyBy([{id:1,name:'a'},{id:2,name:'b'}], 'id') → { 1: {id:1,...}, 2: {id:2,...} }
+ */
+export function keyBy(arr, key) {
+    return arr.reduce((acc, item) => {
+        acc[item[key]] = item;
+        return acc;
+    }, {});
+}
+
+/**
+ * 배열 셔플 (Fisher-Yates — JS 폴백용, 프로덕션은 WASM FuzionXUtil.shuffle 사용)
+ * @param {Array} arr
+ * @returns {Array} 새 배열 (원본 미변경)
+ */
+export function shuffle(arr) {
+    const result = [...arr];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}
+
+/**
+ * 배열 flatten (1 depth)
+ * @param {Array} arr
+ * @returns {Array}
+ */
+export function flatten(arr) {
+    return arr.flat();
+}
+
+/**
+ * 배열이 비어있는지 확인
+ * @param {*} arr
+ * @returns {boolean}
+ */
+export function isEmpty(arr) {
+    return !Array.isArray(arr) || arr.length === 0;
+}

package/lib/utilities/DateUtil.js

@@ -0,0 +1,98 @@
+/**
+ * DateUtil — 날짜 순수 유틸리티
+ */
+
+/**
+ * ISO → 'YYYY-MM-DD HH:mm:ss' 포맷
+ * @param {Date|string|number} date
+ * @param {string} [fmt='YYYY-MM-DD HH:mm:ss']
+ * @returns {string}
+ */
+export function format(date, fmt = 'YYYY-MM-DD HH:mm:ss') {
+    const d = date instanceof Date ? date : new Date(date);
+    if (isNaN(d.getTime())) return '';
+
+    const pad = (n) => String(n).padStart(2, '0');
+    const tokens = {
+        YYYY: d.getFullYear(),
+        MM: pad(d.getMonth() + 1),
+        DD: pad(d.getDate()),
+        HH: pad(d.getHours()),
+        mm: pad(d.getMinutes()),
+        ss: pad(d.getSeconds()),
+    };
+
+    let result = fmt;
+    for (const [token, value] of Object.entries(tokens)) {
+        result = result.replace(token, value);
+    }
+    return result;
+}
+
+/**
+ * 상대 시간 (n분 전, n시간 전, n일 전)
+ * @param {Date|string|number} date
+ * @param {string} [locale='ko']
+ * @returns {string}
+ */
+export function ago(date, locale = 'ko') {
+    const d = date instanceof Date ? date : new Date(date);
+    const now = Date.now();
+    const diffMs = now - d.getTime();
+    const diffSec = Math.floor(diffMs / 1000);
+
+    const units = locale === 'ko'
+        ? { just: '방금 전', sec: '초 전', min: '분 전', hour: '시간 전', day: '일 전', month: '개월 전', year: '년 전' }
+        : { just: 'just now', sec: 's ago', min: 'm ago', hour: 'h ago', day: 'd ago', month: 'mo ago', year: 'y ago' };
+
+    if (diffSec < 10) return units.just;
+    if (diffSec < 60) return `${diffSec}${units.sec}`;
+    if (diffSec < 3600) return `${Math.floor(diffSec / 60)}${units.min}`;
+    if (diffSec < 86400) return `${Math.floor(diffSec / 3600)}${units.hour}`;
+    if (diffSec < 2592000) return `${Math.floor(diffSec / 86400)}${units.day}`;
+    if (diffSec < 31536000) return `${Math.floor(diffSec / 2592000)}${units.month}`;
+    return `${Math.floor(diffSec / 31536000)}${units.year}`;
+}
+
+/**
+ * 오늘인지 확인
+ * @param {Date|string|number} date
+ * @returns {boolean}
+ */
+export function isToday(date) {
+    const d = date instanceof Date ? date : new Date(date);
+    const now = new Date();
+    return d.getFullYear() === now.getFullYear()
+        && d.getMonth() === now.getMonth()
+        && d.getDate() === now.getDate();
+}
+
+/**
+ * 두 날짜 간 일수 차이
+ * @param {Date|string|number} a
+ * @param {Date|string|number} b
+ * @returns {number}
+ */
+export function diffDays(a, b) {
+    const da = a instanceof Date ? a : new Date(a);
+    const db = b instanceof Date ? b : new Date(b);
+    return Math.round((da.getTime() - db.getTime()) / 86400000);
+}
+
+/**
+ * 날짜 범위 배열 생성
+ * @param {Date|string} start
+ * @param {Date|string} end
+ * @returns {Date[]}
+ */
+export function range(start, end) {
+    const s = new Date(start);
+    const e = new Date(end);
+    const dates = [];
+    const d = new Date(s);
+    while (d <= e) {
+        dates.push(new Date(d));
+        d.setDate(d.getDate() + 1);
+    }
+    return dates;
+}

package/lib/utilities/FunctionUtil.js

@@ -0,0 +1,119 @@
+/**
+ * FunctionUtil — 함수 순수 유틸리티
+ */
+
+/**
+ * Debounce — 마지막 호출 후 delay ms 뒤 실행
+ * @param {Function} fn
+ * @param {number} delay - ms
+ * @returns {Function}
+ */
+export function debounce(fn, delay = 300) {
+    let timer;
+    const debounced = (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), delay);
+    };
+    debounced.cancel = () => clearTimeout(timer);
+    return debounced;
+}
+
+/**
+ * Throttle — delay ms 간격으로 최대 1회 실행
+ * @param {Function} fn
+ * @param {number} delay - ms
+ * @returns {Function}
+ */
+export function throttle(fn, delay = 300) {
+    let last = 0;
+    let timer;
+    return (...args) => {
+        const now = Date.now();
+        const remaining = delay - (now - last);
+        clearTimeout(timer);
+        if (remaining <= 0) {
+            last = now;
+            fn(...args);
+        } else {
+            timer = setTimeout(() => {
+                last = Date.now();
+                fn(...args);
+            }, remaining);
+        }
+    };
+}
+
+/**
+ * 한 번만 실행
+ * @param {Function} fn
+ * @returns {Function}
+ */
+export function once(fn) {
+    let called = false;
+    let result;
+    return (...args) => {
+        if (called) return result;
+        called = true;
+        result = fn(...args);
+        return result;
+    };
+}
+
+/**
+ * Promise 타임아웃 래퍼
+ * @param {Promise} promise
+ * @param {number} ms
+ * @param {string} [message='Timeout']
+ * @returns {Promise}
+ */
+export function timeout(promise, ms, message = 'Timeout') {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms)),
+    ]);
+}
+
+/**
+ * 딜레이 (async sleep)
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 함수 파이프라인 (왼→오) — 순차 실행
+ * @param {...Function} fns
+ * @returns {Function}
+ *
+ * @example pipe(addOne, double, square)(2) → square(double(addOne(2)))
+ */
+export function pipe(...fns) {
+    return (x) => fns.reduce((v, fn) => fn(v), x);
+}
+
+/**
+ * 메모이제이션 — 결과 캐싱
+ * @param {Function} fn
+ * @param {Function} [keyFn] - 캐시 키 생성 함수 (기본: 첫 인자)
+ * @returns {Function}
+ */
+export function memoize(fn, keyFn) {
+    const cache = new Map();
+    const memoized = (...args) => {
+        const key = keyFn ? keyFn(...args) : args[0];
+        if (cache.has(key)) return cache.get(key);
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    };
+    memoized.cache = cache;
+    memoized.clear = () => cache.clear();
+    return memoized;
+}
+
+/**
+ * noop — 아무것도 하지 않는 함수
+ */
+export function noop() {}

package/lib/utilities/NumUtil.js

@@ -0,0 +1,75 @@
+/**
+ * NumUtil — 숫자 순수 유틸리티
+ */
+
+/**
+ * 범위 제한 (clamp)
+ * @param {number} n
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function clamp(n, min, max) {
+    return Math.min(Math.max(n, min), max);
+}
+
+/**
+ * 범위 내 랜덤 정수
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function random(min = 0, max = 100) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * 숫자 포맷 (로케일)
+ * @param {number} n
+ * @param {string} [locale='ko-KR']
+ * @returns {string}
+ *
+ * @example format(1234567) → '1,234,567'
+ */
+export function format(n, locale = 'ko-KR') {
+    return new Intl.NumberFormat(locale).format(n);
+}
+
+/**
+ * 바이트 → 읽기 쉬운 단위 변환
+ * @param {number} bytes
+ * @param {number} [decimals=2]
+ * @returns {string}
+ *
+ * @example fileSize(1536) → '1.50 KB'
+ */
+export function fileSize(bytes, decimals = 2) {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${units[i]}`;
+}
+
+/**
+ * 퍼센트 계산
+ * @param {number} part
+ * @param {number} total
+ * @param {number} [decimals=1]
+ * @returns {number}
+ */
+export function percent(part, total, decimals = 1) {
+    if (total === 0) return 0;
+    return parseFloat(((part / total) * 100).toFixed(decimals));
+}
+
+/**
+ * 안전한 정수 파싱
+ * @param {*} value
+ * @param {number} [fallback=0]
+ * @returns {number}
+ */
+export function toInt(value, fallback = 0) {
+    const n = parseInt(value, 10);
+    return isNaN(n) ? fallback : n;
+}