@fuzionx/framework 0.1.30 → 0.1.32

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;
+}

package/lib/utilities/ObjectUtil.js

@@ -0,0 +1,170 @@
+/**
+ * ObjectUtil — 객체 순수 유틸리티
+ */
+
+/**
+ * Deep clone (structuredClone 폴백)
+ * @param {*} obj
+ * @returns {*}
+ */
+export function deepClone(obj) {
+    if (typeof structuredClone === 'function') return structuredClone(obj);
+    return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * Deep merge — 비파괴 병합
+ * @param {object} target
+ * @param {...object} sources
+ * @returns {object}
+ */
+export function deepMerge(target, ...sources) {
+    const result = { ...target };
+    for (const source of sources) {
+        if (!source) continue;
+        for (const key of Object.keys(source)) {
+            const sv = source[key];
+            const tv = result[key];
+            if (isPlainObject(sv) && isPlainObject(tv)) {
+                result[key] = deepMerge(tv, sv);
+            } else {
+                result[key] = sv;
+            }
+        }
+    }
+    return result;
+}
+
+/**
+ * 특정 키만 선택
+ * @param {object} obj
+ * @param {string[]} keys
+ * @returns {object}
+ *
+ * @example pick({ a:1, b:2, c:3 }, ['a', 'c']) → { a:1, c:3 }
+ */
+export function pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) result[key] = obj[key];
+    }
+    return result;
+}
+
+/**
+ * 특정 키 제외
+ * @param {object} obj
+ * @param {string[]} keys
+ * @returns {object}
+ */
+export function omit(obj, keys) {
+    const keySet = new Set(keys);
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        if (!keySet.has(key)) result[key] = obj[key];
+    }
+    return result;
+}
+
+/**
+ * Flatten — 중첩 객체를 dot notation으로 평탄화
+ * @param {object} obj
+ * @param {string} [prefix='']
+ * @returns {object}
+ *
+ * @example flatten({ a: { b: 1, c: { d: 2 } } }) → { 'a.b': 1, 'a.c.d': 2 }
+ */
+export function flatten(obj, prefix = '') {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const val = obj[key];
+        if (isPlainObject(val)) {
+            Object.assign(result, flatten(val, path));
+        } else {
+            result[path] = val;
+        }
+    }
+    return result;
+}
+
+/**
+ * Unflatten — dot notation → 중첩 객체
+ * @param {object} obj
+ * @returns {object}
+ */
+export function unflatten(obj) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+        const parts = key.split('.');
+        let current = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (!current[parts[i]] || typeof current[parts[i]] !== 'object') {
+                current[parts[i]] = {};
+            }
+            current = current[parts[i]];
+        }
+        current[parts[parts.length - 1]] = val;
+    }
+    return result;
+}
+
+/**
+ * 객체가 비어있는지 확인
+ * @param {*} obj
+ * @returns {boolean}
+ */
+export function isEmpty(obj) {
+    if (!obj) return true;
+    return Object.keys(obj).length === 0;
+}
+
+/**
+ * dot notation으로 값 접근
+ * @param {object} obj
+ * @param {string} path
+ * @param {*} [defaultValue]
+ * @returns {*}
+ *
+ * @example get({ a: { b: { c: 42 } } }, 'a.b.c') → 42
+ */
+export function get(obj, path, defaultValue) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object') return defaultValue;
+        current = current[part];
+    }
+    return current !== undefined ? current : defaultValue;
+}
+
+/**
+ * dot notation으로 값 설정 (비파괴 — 새 객체 반환)
+ * @param {object} obj
+ * @param {string} path
+ * @param {*} value
+ * @returns {object}
+ */
+export function set(obj, path, value) {
+    const result = deepClone(obj);
+    const parts = path.split('.');
+    let current = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (!current[parts[i]] || typeof current[parts[i]] !== 'object') {
+            current[parts[i]] = {};
+        }
+        current = current[parts[i]];
+    }
+    current[parts[parts.length - 1]] = value;
+    return result;
+}
+
+/**
+ * 순수 객체인지 확인 (Array, Date 등 제외)
+ * @param {*} val
+ * @returns {boolean}
+ */
+export function isPlainObject(val) {
+    return val !== null && typeof val === 'object' && !Array.isArray(val)
+        && Object.getPrototypeOf(val) === Object.prototype;
+}

package/lib/utilities/PaginationUtil.js

@@ -0,0 +1,81 @@
+/**
+ * PaginationUtil — 페이지네이션 순수 유틸리티
+ *
+ * Stateless 함수들. DB Pagination 클래스와 달리
+ * 인메모리 배열/수동 메타 계산에 사용.
+ *
+ * @see lib/database/Pagination.js — DB 쿼리 결과용
+ */
+
+/**
+ * 메타 계산 — total, page, perPage로 페이지네이션 정보 생성
+ * @param {number} total - 전체 레코드 수
+ * @param {number} page - 현재 페이지 (1-based)
+ * @param {number} perPage - 페이지당 수
+ * @returns {{ total, page, perPage, lastPage, hasMore, from, to }}
+ */
+export function buildMeta(total, page = 1, perPage = 20) {
+    const lastPage = Math.ceil(total / perPage) || 1;
+    const from = (page - 1) * perPage + 1;
+    const to = Math.min(page * perPage, total);
+    return {
+        total,
+        page,
+        perPage,
+        lastPage,
+        hasMore: page < lastPage,
+        from: total > 0 ? from : 0,
+        to: total > 0 ? to : 0,
+    };
+}
+
+/**
+ * 인메모리 배열 페이지네이션
+ * @param {Array} items - 전체 배열
+ * @param {number} page - 현재 페이지 (1-based)
+ * @param {number} perPage - 페이지당 수
+ * @returns {{ data: Array, meta: object }}
+ */
+export function paginate(items, page = 1, perPage = 20) {
+    const total = items.length;
+    const start = (page - 1) * perPage;
+    const data = items.slice(start, start + perPage);
+    return { data, meta: buildMeta(total, page, perPage) };
+}
+
+/**
+ * offset/limit 계산
+ * @param {number} page
+ * @param {number} perPage
+ * @returns {{ offset: number, limit: number }}
+ */
+export function offsetLimit(page = 1, perPage = 20) {
+    return {
+        offset: (page - 1) * perPage,
+        limit: perPage,
+    };
+}
+
+/**
+ * 페이지 번호 배열 생성 (페이지 네비게이션 UI용)
+ * @param {number} current - 현재 페이지
+ * @param {number} last - 마지막 페이지
+ * @param {number} [delta=2] - 현재 페이지 앞뒤로 표시할 수
+ * @returns {Array<number|'...'>}
+ *
+ * @example
+ * pageNumbers(5, 20, 2) → [1, '...', 3, 4, 5, 6, 7, '...', 20]
+ */
+export function pageNumbers(current, last, delta = 2) {
+    const pages = [];
+    const rangeStart = Math.max(2, current - delta);
+    const rangeEnd = Math.min(last - 1, current + delta);
+
+    pages.push(1);
+    if (rangeStart > 2) pages.push('...');
+    for (let i = rangeStart; i <= rangeEnd; i++) pages.push(i);
+    if (rangeEnd < last - 1) pages.push('...');
+    if (last > 1) pages.push(last);
+
+    return pages;
+}