@fuzionx/framework 0.1.38 → 0.1.41

package/lib/services/Storage.js

@@ -1,112 +1,112 @@
-/**
- * Storage — 파일 저장 추상화 (Local / S3)
- *
- * put(path, tempPath) — 임시파일 → 최종 위치 이동.
- * Local: file.move(tempPath, fullPath)
- * S3: Node.js 스트리밍 업로드 (큐 Task 권장)
- *
- * @see docs/framework/15-file-upload.md
- * @see docs/framework/class-design.mm.md (Storage)
- */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-
-export default class Storage {
-    /**
-     * @param {object} opts
-     * @param {string} [opts.driver='local'] - 'local' | 's3'
-     * @param {string} [opts.basePath='./storage'] - 로컬 저장 경로
-     * @param {object} [opts.s3] - S3 설정 { bucket, region, credentials }
-     * @param {import('./FileHelper.js').default} [opts.fileHelper] - FileHelper 인스턴스
-     */
-    constructor(opts = {}) {
-        this.driver = opts.driver || 'local';
-        this.basePath = opts.basePath || './storage';
-        this._s3 = opts.s3 || null;
-        this._file = opts.fileHelper || null;
-    }
-
-    /**
-     * 임시파일 → 최종 위치 이동
-     * @param {string} filePath - 상대 경로 (e.g. 'uploads/avatar.jpg')
-     * @param {string} tempPath - 임시 파일 경로 (/tmp/fuzionx_upload_xxx)
-     * @returns {Promise<string>} - 저장된 URL 또는 경로
-     */
-    async put(filePath, tempPath) {
-        if (this.driver === 's3') {
-            return this._s3Put(filePath, tempPath);
-        }
-        const fullPath = path.join(this.basePath, filePath);
-        await fs.mkdir(path.dirname(fullPath), { recursive: true });
-        // FileHelper로 이동 (Bridge file.move → Rust 직접)
-        if (this._file) {
-            await this._file.move(tempPath, fullPath);
-        } else {
-            // 폴백: fs.rename (cross-device 시 copy+unlink)
-            await fs.rename(tempPath, fullPath).catch(async () => {
-                await fs.copyFile(tempPath, fullPath);
-                await fs.unlink(tempPath);
-            });
-        }
-        return fullPath;
-    }
-
-    /**
-     * 파일 읽기
-     * @param {string} filePath
-     * @returns {Promise<Buffer>}
-     */
-    async get(filePath) {
-        if (this.driver === 's3') {
-            return this._s3Get(filePath);
-        }
-        return fs.readFile(path.join(this.basePath, filePath));
-    }
-
-    /**
-     * 파일 삭제
-     * @param {string} filePath
-     * @returns {Promise<void>}
-     */
-    async delete(filePath) {
-        if (this.driver === 's3') {
-            return this._s3Delete(filePath);
-        }
-        await fs.unlink(path.join(this.basePath, filePath));
-    }
-
-    /**
-     * 파일 존재 여부
-     * @param {string} filePath
-     * @returns {Promise<boolean>}
-     */
-    async exists(filePath) {
-        try {
-            if (this.driver === 's3') {
-                return this._s3Exists(filePath);
-            }
-            await fs.access(path.join(this.basePath, filePath));
-            return true;
-        } catch {
-            return false;
-        }
-    }
-
-    /**
-     * 파일 URL (public 접근용)
-     * @param {string} filePath
-     * @returns {string}
-     */
-    url(filePath) {
-        if (this.driver === 's3' && this._s3) {
-            return `https://${this._s3.bucket}.s3.${this._s3.region}.amazonaws.com/${filePath}`;
-        }
-        return `/storage/${filePath}`;
-    }
-
-    // ── S3 스텁 (Phase 5+ 구현) ──
-    async _s3Put(filePath, tempPath) { throw new Error('S3 driver not implemented'); }
-    async _s3Get(filePath) { throw new Error('S3 driver not implemented'); }
-    async _s3Delete(filePath) { throw new Error('S3 driver not implemented'); }
-    async _s3Exists(filePath) { throw new Error('S3 driver not implemented'); }
-}
+/**
+ * Storage — 파일 저장 추상화 (Local / S3)
+ *
+ * put(path, tempPath) — 임시파일 → 최종 위치 이동.
+ * Local: file.move(tempPath, fullPath)
+ * S3: Node.js 스트리밍 업로드 (큐 Task 권장)
+ *
+ * @see docs/framework/15-file-upload.md
+ * @see docs/framework/class-design.mm.md (Storage)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export default class Storage {
+    /**
+     * @param {object} opts
+     * @param {string} [opts.driver='local'] - 'local' | 's3'
+     * @param {string} [opts.basePath='./storage'] - 로컬 저장 경로
+     * @param {object} [opts.s3] - S3 설정 { bucket, region, credentials }
+     * @param {import('./FileHelper.js').default} [opts.fileHelper] - FileHelper 인스턴스
+     */
+    constructor(opts = {}) {
+        this.driver = opts.driver || 'local';
+        this.basePath = opts.basePath || './storage';
+        this._s3 = opts.s3 || null;
+        this._file = opts.fileHelper || null;
+    }
+
+    /**
+     * 임시파일 → 최종 위치 이동
+     * @param {string} filePath - 상대 경로 (e.g. 'uploads/avatar.jpg')
+     * @param {string} tempPath - 임시 파일 경로 (/tmp/fuzionx_upload_xxx)
+     * @returns {Promise<string>} - 저장된 URL 또는 경로
+     */
+    async put(filePath, tempPath) {
+        if (this.driver === 's3') {
+            return this._s3Put(filePath, tempPath);
+        }
+        const fullPath = path.join(this.basePath, filePath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        // FileHelper로 이동 (Bridge file.move → Rust 직접)
+        if (this._file) {
+            await this._file.move(tempPath, fullPath);
+        } else {
+            // 폴백: fs.rename (cross-device 시 copy+unlink)
+            await fs.rename(tempPath, fullPath).catch(async () => {
+                await fs.copyFile(tempPath, fullPath);
+                await fs.unlink(tempPath);
+            });
+        }
+        return fullPath;
+    }
+
+    /**
+     * 파일 읽기
+     * @param {string} filePath
+     * @returns {Promise<Buffer>}
+     */
+    async get(filePath) {
+        if (this.driver === 's3') {
+            return this._s3Get(filePath);
+        }
+        return fs.readFile(path.join(this.basePath, filePath));
+    }
+
+    /**
+     * 파일 삭제
+     * @param {string} filePath
+     * @returns {Promise<void>}
+     */
+    async delete(filePath) {
+        if (this.driver === 's3') {
+            return this._s3Delete(filePath);
+        }
+        await fs.unlink(path.join(this.basePath, filePath));
+    }
+
+    /**
+     * 파일 존재 여부
+     * @param {string} filePath
+     * @returns {Promise<boolean>}
+     */
+    async exists(filePath) {
+        try {
+            if (this.driver === 's3') {
+                return this._s3Exists(filePath);
+            }
+            await fs.access(path.join(this.basePath, filePath));
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 파일 URL (public 접근용)
+     * @param {string} filePath
+     * @returns {string}
+     */
+    url(filePath) {
+        if (this.driver === 's3' && this._s3) {
+            return `https://${this._s3.bucket}.s3.${this._s3.region}.amazonaws.com/${filePath}`;
+        }
+        return `/storage/${filePath}`;
+    }
+
+    // ── S3 스텁 (Phase 5+ 구현) ──
+    async _s3Put(filePath, tempPath) { throw new Error('S3 driver not implemented'); }
+    async _s3Get(filePath) { throw new Error('S3 driver not implemented'); }
+    async _s3Delete(filePath) { throw new Error('S3 driver not implemented'); }
+    async _s3Exists(filePath) { throw new Error('S3 driver not implemented'); }
+}

package/lib/utilities/ArrUtil.js

@@ -1,112 +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;
-}
+/**
+ * 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

@@ -1,98 +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;
-}
+/**
+ * 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;
+}