@fuzionx/framework 0.1.29 → 0.1.31

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

package/lib/utilities/StrUtil.js

@@ -0,0 +1,105 @@
+/**
+ * StrUtil — 문자열 순수 유틸리티
+ */
+
+/**
+ * URL-safe slug 생성
+ * @param {string} str
+ * @returns {string}
+ */
+export function slug(str) {
+    return str
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s가-힣-]/g, '')
+        .replace(/[\s_]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * 말줄임 (한글/이모지 안전)
+ * @param {string} str
+ * @param {number} len
+ * @param {string} [suffix='…']
+ * @returns {string}
+ */
+export function truncate(str, len, suffix = '…') {
+    if (!str || str.length <= len) return str || '';
+    return str.slice(0, len) + suffix;
+}
+
+/**
+ * camelCase 변환
+ * @param {string} str
+ * @returns {string}
+ */
+export function camelCase(str) {
+    return str
+        .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+        .replace(/^[A-Z]/, c => c.toLowerCase());
+}
+
+/**
+ * snake_case 변환
+ * @param {string} str
+ * @returns {string}
+ */
+export function snakeCase(str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, '$1_$2')
+        .replace(/[-\s]+/g, '_')
+        .toLowerCase();
+}
+
+/**
+ * PascalCase 변환
+ * @param {string} str
+ * @returns {string}
+ */
+export function pascalCase(str) {
+    return str
+        .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+        .replace(/^[a-z]/, c => c.toUpperCase());
+}
+
+/**
+ * 첫 글자 대문자
+ * @param {string} str
+ * @returns {string}
+ */
+export function capitalize(str) {
+    if (!str) return '';
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * 랜덤 문자열 생성
+ * @param {number} len
+ * @param {string} [chars]
+ * @returns {string}
+ */
+export function random(len = 16, chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789') {
+    let result = '';
+    for (let i = 0; i < len; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+
+/**
+ * 마스킹 (이메일, 전화번호 등)
+ * @param {string} str
+ * @param {number} [visibleStart=2]
+ * @param {number} [visibleEnd=2]
+ * @param {string} [mask='*']
+ * @returns {string}
+ *
+ * @example mask('hello@test.com', 2, 4) → 'he*****t.com'
+ */
+export function mask(str, visibleStart = 2, visibleEnd = 2, maskChar = '*') {
+    if (!str || str.length <= visibleStart + visibleEnd) return str || '';
+    const start = str.slice(0, visibleStart);
+    const end = str.slice(-visibleEnd);
+    const middle = maskChar.repeat(str.length - visibleStart - visibleEnd);
+    return start + middle + end;
+}

package/lib/utilities/index.js

@@ -0,0 +1,18 @@
+/**
+ * Utilities — 순수 함수 유틸리티 배럴 export
+ *
+ * Helper와 달리 Bridge/App 의존 없이 import 즉시 사용 가능.
+ *
+ * @example
+ * import { PaginationUtil, StrUtil, ObjectUtil } from '@fuzionx/framework';
+ * const meta = PaginationUtil.buildMeta(100, 1, 20);
+ * const s = StrUtil.slug('Hello World');
+ * const cleaned = ObjectUtil.omit(user, ['password']);
+ */
+export * as PaginationUtil from './PaginationUtil.js';
+export * as StrUtil from './StrUtil.js';
+export * as NumUtil from './NumUtil.js';
+export * as DateUtil from './DateUtil.js';
+export * as ArrUtil from './ArrUtil.js';
+export * as FunctionUtil from './FunctionUtil.js';
+export * as ObjectUtil from './ObjectUtil.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -34,7 +34,7 @@
     "url": "https://github.com/saytohenry/fuzionx"
   },
   "dependencies": {
-    "@fuzionx/core": "^0.1.29",
+    "@fuzionx/core": "^0.1.31",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",

package/cli/templates/app/.env.example.tpl

@@ -1,14 +0,0 @@
-# .env — 이 파일을 .env로 복사 후 값을 채우세요
-
-# Database
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_USER=root
-DB_PASSWORD=
-DB_NAME={{dbName}}
-
-# Auth
-JWT_SECRET=
-
-# Redis (세션/큐 공용)
-REDIS_URL=

package/cli/templates/app/.gitignore.tpl

@@ -1,4 +0,0 @@
-.env
-node_modules/
-storage/logs/
-storage/uploads/

package/cli/templates/app/app.js.tpl

@@ -1,6 +0,0 @@
-import { Application } from '@fuzionx/framework';
-
-const app = new Application({ configPath: './fuzionx.yaml' });
-
-await app.boot();
-await app.listen();

package/cli/templates/app/database/models/User.js

@@ -1,9 +0,0 @@
-import { MariaModel } from '@fuzionx/framework';
-
-export default class User extends MariaModel {
-    static table = 'users';
-    static connection = 'main';
-    static softDelete = true;
-    static hidden = ['password'];
-    static fillable = ['name', 'email', 'password', 'role'];
-}

package/cli/templates/app/fuzionx/views/default/errors/500.html

@@ -1,14 +0,0 @@
-{% extends "layouts/main.html" %}
-
-{% block title %}500 — 서버 오류{% endblock %}
-
-{% block content %}
-<div style="text-align:center;padding:80px 20px;">
-    <h1 style="font-size:72px;color:#e74c3c;">500</h1>
-    <p style="font-size:20px;margin:16px 0;">{{ error.message | default(value='Internal Server Error') }}</p>
-    {% if config.debug and error.stack %}
-        <pre style="text-align:left;max-width:600px;margin:24px auto;background:#f5f5f5;padding:16px;border-radius:8px;overflow:auto;">{{ error.stack }}</pre>
-    {% endif %}
-    <a href="/" style="display:inline-block;margin-top:24px;padding:12px 24px;background:#e74c3c;color:#fff;text-decoration:none;border-radius:6px;">홈으로 돌아가기</a>
-</div>
-{% endblock %}

package/cli/templates/app/fuzionx/views/default/pages/home.html

@@ -1,188 +0,0 @@
-<!DOCTYPE html>
-<html lang="ko">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>FuzionX</title>
-    <style>
-        * { margin: 0; padding: 0; box-sizing: border-box; }
-        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;800&display=swap');
-
-        body {
-            font-family: 'Inter', system-ui, -apple-system, sans-serif;
-            min-height: 100vh;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            background: linear-gradient(135deg, #0f0c29 0%, #1a1a3e 40%, #24243e 100%);
-            color: #e0e0e0;
-            overflow: hidden;
-        }
-
-        .container {
-            text-align: center;
-            z-index: 1;
-            animation: fadeInUp 0.8s ease-out;
-        }
-
-        .logo {
-            font-size: 4rem;
-            font-weight: 800;
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 50%, #f093fb 100%);
-            -webkit-background-clip: text;
-            background-clip: text;
-            -webkit-text-fill-color: transparent;
-            letter-spacing: -2px;
-            margin-bottom: 0.5rem;
-        }
-
-        .subtitle {
-            font-size: 1.1rem;
-            font-weight: 300;
-            color: rgba(255, 255, 255, 0.5);
-            margin-bottom: 2.5rem;
-            letter-spacing: 2px;
-        }
-
-        .card {
-            background: rgba(255, 255, 255, 0.05);
-            backdrop-filter: blur(20px);
-            border: 1px solid rgba(255, 255, 255, 0.1);
-            border-radius: 16px;
-            padding: 2rem 3rem;
-            max-width: 480px;
-            margin: 0 auto 2rem;
-        }
-
-        .version {
-            display: inline-block;
-            background: linear-gradient(135deg, #667eea, #764ba2);
-            color: white;
-            padding: 4px 14px;
-            border-radius: 20px;
-            font-size: 0.75rem;
-            font-weight: 600;
-            letter-spacing: 1px;
-            margin-bottom: 1.5rem;
-        }
-
-        .features {
-            display: grid;
-            grid-template-columns: 1fr 1fr;
-            gap: 1rem;
-            text-align: left;
-            margin-top: 1.5rem;
-        }
-
-        .feature {
-            display: flex;
-            align-items: center;
-            gap: 8px;
-            font-size: 0.85rem;
-            color: rgba(255, 255, 255, 0.7);
-        }
-
-        .feature span {
-            font-size: 1.1rem;
-        }
-
-        .links {
-            display: flex;
-            gap: 1rem;
-            justify-content: center;
-            margin-top: 1rem;
-        }
-
-        .links a {
-            color: rgba(255, 255, 255, 0.6);
-            text-decoration: none;
-            font-size: 0.85rem;
-            padding: 8px 20px;
-            border: 1px solid rgba(255, 255, 255, 0.15);
-            border-radius: 8px;
-            transition: all 0.3s ease;
-        }
-
-        .links a:hover {
-            color: #fff;
-            border-color: #667eea;
-            background: rgba(102, 126, 234, 0.1);
-            transform: translateY(-2px);
-        }
-
-        .hint {
-            margin-top: 2rem;
-            font-size: 0.75rem;
-            color: rgba(255, 255, 255, 0.3);
-        }
-
-        .hint code {
-            background: rgba(255, 255, 255, 0.08);
-            padding: 2px 8px;
-            border-radius: 4px;
-            font-family: 'JetBrains Mono', monospace;
-        }
-
-        /* Background orbs */
-        .orb {
-            position: fixed;
-            border-radius: 50%;
-            filter: blur(80px);
-            opacity: 0.3;
-            animation: float 8s ease-in-out infinite;
-        }
-        .orb-1 { width: 400px; height: 400px; background: #667eea; top: -100px; right: -100px; }
-        .orb-2 { width: 300px; height: 300px; background: #764ba2; bottom: -80px; left: -80px; animation-delay: -4s; }
-        .orb-3 { width: 200px; height: 200px; background: #f093fb; top: 50%; left: 60%; animation-delay: -2s; }
-
-        @keyframes fadeInUp {
-            from { opacity: 0; transform: translateY(30px); }
-            to { opacity: 1; transform: translateY(0); }
-        }
-
-        @keyframes float {
-            0%, 100% { transform: translate(0, 0); }
-            50% { transform: translate(30px, -30px); }
-        }
-
-        @media (max-width: 600px) {
-            .logo { font-size: 2.5rem; }
-            .card { padding: 1.5rem; margin: 0 1rem; }
-            .features { grid-template-columns: 1fr; }
-        }
-    </style>
-</head>
-<body>
-    <div class="orb orb-1"></div>
-    <div class="orb orb-2"></div>
-    <div class="orb orb-3"></div>
-
-    <div class="container">
-        <h1 class="logo">FuzionX</h1>
-        <p class="subtitle">HIGH-PERFORMANCE NODE.JS FRAMEWORK</p>
-
-        <div class="card">
-            <div class="version">v0.1.0 · POWERED BY RUST</div>
-
-            <div class="features">
-                <div class="feature"><span>⚡</span> 500K+ RPS</div>
-                <div class="feature"><span>🦀</span> Rust N-API Bridge</div>
-                <div class="feature"><span>🎯</span> MVC Architecture</div>
-                <div class="feature"><span>🔌</span> WebSocket</div>
-                <div class="feature"><span>🗄️</span> Multi-DB ORM</div>
-                <div class="feature"><span>🔐</span> Auth & Session</div>
-                <div class="feature"><span>📡</span> Event System</div>
-                <div class="feature"><span>⏰</span> Job Scheduler</div>
-            </div>
-        </div>
-
-        <div class="links">
-            <a href="https://github.com/saytohenry/fuzionx">GitHub</a>
-            <a href="/docs">API Docs</a>
-            <a href="/api/health">Health Check</a>
-        </div>
-
-        <p class="hint">Edit <code>routes/web.js</code> to get started</p>
-    </div>
-</body>
-</html>