@alloy-framework/core 0.4.0 → 0.14.0

package/src/service/AlloyService.js

@@ -1,171 +0,0 @@
-import native from '@alloy-framework/rust';
-
-/**
- * 🏗️ Alloy 서비스 기반 클래스
- * Cache, Lock, Task 등 네이티브 유틸리티를 제공하는 비즈니스 서비스 기반 클래스입니다.
- * 도메인 서비스는 이 클래스를 상속하여 사용합니다.
- *
- * @example
- * class UserService extends AlloyService {
- *     async getUser(id) {
- *         return this.withCache(`user:${id}`, 300, async () => {
- *             return await UserModel.findById(id);
- *         });
- *     }
- * }
- */
-export class AlloyService {
-    constructor() {
-        /** @type {import('@alloy/rust').AlloyService} 네이티브 서비스 인스턴스 */
-        this._native = new native.AlloyService();
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 🔧 유틸리티
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 에코 테스트 (네이티브 연결 확인용)
-     * @param {string} msg - 에코 메시지
-     * @returns {string} "Native Echo: {msg}"
-     */
-    echo(msg) {
-        return this._native.echo(msg);
-    }
-
-    /**
-     * CPU 집약적 작업을 네이티브 스레드풀에서 실행
-     * @param {string} name - 작업 이름
-     * @param {number} difficulty - 난이도
-     * @returns {Promise<string>} 작업 결과
-     */
-    runTask(name, difficulty) {
-        return this._native.runTask(name, difficulty);
-    }
-
-    /**
-     * 배열의 각 항목에 대해 비동기 함수를 병렬 실행
-     * fn이 없으면 items를 Promise 배열로 간주하여 직접 해소
-     *
-     * @param {Array} items - 처리할 항목 배열 또는 Promise 배열
-     * @param {Function} [fn] - 각 항목에 적용할 비동기 함수 (item, index) => Promise (생략 가능)
-     * @param {object} [options] - 옵션 { settled: false }
-     * @param {boolean} [options.settled=false] - true면 Promise.allSettled 사용 (부분 실패 허용)
-     * @returns {Promise<Array>} 병렬 실행 결과 배열 (입력 순서 유지)
-     *
-     * @example
-     * // 패턴 1: 배열 + 매핑 함수
-     * const enriched = await this.runParallel(posts, async (post) => {
-     *     const author = await UserModel.findById(post.user_id);
-     *     return { ...post, author_name: author?.nickname };
-     * });
-     *
-     * // 패턴 2: Promise 배열 직접 해소
-     * const [users, count] = await this.runParallel([fetchUsers(), fetchCount()]);
-     *
-     * // 패턴 3: 부분 실패 허용
-     * const results = await this.runParallel(items, fetchItem, { settled: true });
-     */
-    async runParallel(items, fn, options = {}) {
-        const resolver = options.settled ? Promise.allSettled.bind(Promise) : Promise.all.bind(Promise);
-        // fn이 없으면 items를 Promise 배열로 간주
-        if (!fn) return resolver(items);
-        return resolver(items.map((item, index) => fn(item, index)));
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 📦 캐시 (Redis, 메모리 폴백)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 캐시 저장
-     * @param {string} key - 캐시 키
-     * @param {string} value - 값 (문자열)
-     * @param {number} ttlSeconds - TTL (초)
-     * @returns {Promise<void>}
-     */
-    async setCache(key, value, ttlSeconds) {
-        return await this._native.setCache(key, String(value), ttlSeconds);
-    }
-
-    /**
-     * 캐시 조회
-     * @param {string} key - 캐시 키
-     * @returns {Promise<string|null>}
-     */
-    async getCache(key) {
-        return await this._native.getCache(key);
-    }
-
-    /**
-     * 캐시 래퍼 — 캐시 miss 시 fetcher 호출 후 저장
-     * @param {string} key - 캐시 키
-     * @param {number} ttlSeconds - TTL (초)
-     * @param {Function} fetcher - 데이터 조회 함수
-     * @returns {Promise<any>} 캐시된 또는 신규 조회 데이터
-     */
-    async withCache(key, ttlSeconds, fetcher) {
-        try {
-            const cached = await this.getCache(key);
-            if (cached) {
-                return JSON.parse(cached);
-            }
-        } catch (e) {
-            console.warn(`[AlloyService] 캐시 읽기 실패 (${key}):`, e.message);
-        }
-
-        // 캐시 miss → fetcher 실행
-        const data = await fetcher();
-
-        if (data !== undefined && data !== null) {
-            try {
-                await this.setCache(key, JSON.stringify(data), ttlSeconds);
-            } catch (e) {
-                console.warn(`[AlloyService] 캐시 저장 실패 (${key}):`, e.message);
-            }
-        }
-
-        return data;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 🔐 분산 락 (Redis)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 네트워크 분산 락 획득 (Redis SET NX PX)
-     * @param {string} resource - 리소스 키
-     * @param {number} [ttlMs=5000] - TTL (밀리초)
-     * @returns {Promise<boolean>} 획득 성공 여부
-     */
-    async acquireNetworkLock(resource, ttlMs = 5000) {
-        return await this._native.acquireNetworkLock(resource, ttlMs);
-    }
-
-    /**
-     * 네트워크 분산 락 해제
-     * @param {string} resource - 리소스 키
-     * @returns {Promise<void>}
-     */
-    async releaseNetworkLock(resource) {
-        return await this._native.releaseNetworkLock(resource);
-    }
-
-    /**
-     * 로컬 프로세스 락 획득 (인메모리)
-     * @param {string} resource - 리소스 키
-     * @param {number} [ttlMs=5000] - TTL (밀리초)
-     * @returns {boolean} 획득 성공 여부
-     */
-    acquireLocalLock(resource, ttlMs = 5000) {
-        return this._native.acquireLocalLock(resource, ttlMs);
-    }
-
-    /**
-     * 로컬 프로세스 락 해제
-     * @param {string} resource - 리소스 키
-     */
-    releaseLocalLock(resource) {
-        this._native.releaseLocalLock(resource);
-    }
-}

package/src/util/AlloyError.js

@@ -1,23 +0,0 @@
-/**
- * 🚨 Alloy 표준 에러 클래스
- * HTTP 상태 코드와 에러 코드를 포함하는 구조화된 에러입니다.
- *
- * @example
- * throw new AlloyError('AUTH_SESSION_EXPIRED', '세션이 만료되었습니다', 401);
- */
-export class AlloyError extends Error {
-    /**
-     * @param {string} code - 에러 코드 (예: 'AUTH_SESSION_EXPIRED')
-     * @param {string} [message] - 사람이 읽을 수 있는 메시지 (기본값: code)
-     * @param {number} [statusCode=500] - HTTP 상태 코드
-     */
-    constructor(code, message, statusCode = 500) {
-        super(message || code);
-        /** @type {string} 에러 이름 */
-        this.name = 'AlloyError';
-        /** @type {string} 에러 코드 */
-        this.code = code;
-        /** @type {number} HTTP 상태 코드 */
-        this.statusCode = statusCode;
-    }
-}

package/src/util/Pagination.js

@@ -1,39 +0,0 @@
-/**
- * 📄 페이지네이션 유틸리티
- * 서비스 레이어에서 목록 조회 시 공통으로 사용합니다.
- */
-
-/**
- * 페이지/사이즈를 offset/limit으로 변환
- * @param {number} [page=1] - 현재 페이지 (1부터)
- * @param {number} [size=20] - 페이지당 항목 수
- * @returns {{ offset: number, limit: number }}
- */
-export function paginate(page = 1, size = 20) {
-    const safePage = Math.max(1, Math.floor(page)); // 최소 1페이지
-    const safeSize = Math.min(100, Math.max(1, Math.floor(size))); // 1~100 범위 제한
-    return {
-        offset: (safePage - 1) * safeSize,
-        limit: safeSize,
-    };
-}
-
-/**
- * 페이지네이션 응답 구성
- * @param {Array} items - 조회된 항목 배열
- * @param {number} total - 전체 항목 수
- * @param {number} page - 현재 페이지
- * @param {number} size - 페이지당 항목 수
- * @returns {{ items: Array, total: number, page: number, size: number, totalPages: number }}
- */
-export function buildResponse(items, total, page, size) {
-    const safePage = Math.max(1, Math.floor(page));
-    const safeSize = Math.min(100, Math.max(1, Math.floor(size)));
-    return {
-        items,
-        total,
-        page: safePage,
-        size: safeSize,
-        totalPages: Math.ceil(total / safeSize), // 전체 페이지 수
-    };
-}

package/src/util/index.js

@@ -1,6 +0,0 @@
-/**
- * 🔧 공용 유틸리티 모듈
- * AlloyError, Pagination 등 프레임워크 범용 유틸리티를 통합 export 합니다.
- */
-export { AlloyError } from './AlloyError.js';
-export { paginate, buildResponse } from './Pagination.js';

package/src/ws/AlloyWebSocket.js

@@ -1,130 +0,0 @@
-// native 모듈은 AlloyApp에서 constructor 파라미터로 주입받음 (모듈 레벨 import 불필요)
-
-/**
- * 🔌 Alloy WebSocket 래퍼
- * Rust 네이티브 WebSocket 세션을 JS에서 다루기 쉽게 래핑합니다.
- * AlloyApp의 ws.onConnect 콜백에서 자동 생성됩니다.
- *
- * @example
- * app.ws({
- *     onConnect(socket) {
- *         socket.send({ type: 'welcome', data: 'Hello!' });
- *     },
- *     onMessage(socket, message) {
- *         socket.broadcast({ type: 'chat', data: message });
- *     },
- * });
- */
-export class AlloyWebSocket {
-    /**
-     * @param {string} id - 세션 ID (Rust에서 UUID 자동 생성)
-     * @param {object} native - 네이티브 모듈 참조
-     * @param {object} [connectionData] - 연결 메타데이터
-     */
-    constructor(id, native, connectionData = {}) {
-        /** @type {string} 세션 ID */
-        this.id = id;
-        /** @type {object} 네이티브 모듈 참조 */
-        this.native = native;
-        /** @type {string} 연결 유형 ('local' | 'remote') */        
-        this.connectionType = connectionData.type || connectionData.connectionType || 'local';
-        /** @type {string} 클라이언트 IP */
-        this.clientIp = connectionData.ip || connectionData.clientIp || 'unknown';
-        /** @type {string} 연결 시각 */
-        this.connectedAt = connectionData.connected_at || connectionData.connectedAt || new Date().toISOString();
-        /** @type {string} 서버 ID */
-        this.server = connectionData.server || null;
-        /** @type {object} HTTP 쿠키 (세션 ID 추출용) */
-        this.cookies = connectionData.cookies || {};
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 📨 메시지 전송
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 이 소켓에게 메시지 전송
-     * @param {string|object} msg - 전송할 메시지 (객체는 JSON 변환)
-     */
-    send(msg) {
-        const payload = (typeof msg === 'object') ? JSON.stringify(msg) : String(msg);
-        if (this.native.sendTo) {
-            this.native.sendTo(this.id, payload);
-        } else {
-            console.warn('⚠️ native.sendTo not available');
-        }
-    }
-
-    /**
-     * 전체 클라이언트에게 브로드캐스트 (NATS 경유 크로스서버)
-     * @param {string|object} msg - 전송할 메시지
-     */
-    broadcast(msg) {
-        const payload = (typeof msg === 'object') ? JSON.stringify(msg) : String(msg);
-        this.native.broadcast(payload);
-    }
-
-    /**
-     * 특정 대상에게 다이렉트 메시지 전송 (NATS 경유 크로스서버)
-     * @param {string} targetId - 대상 세션 ID
-     * @param {string|object} msg - 전송할 메시지
-     */
-    sendTo(targetId, msg) {
-        const payload = (typeof msg === 'object') ? JSON.stringify(msg) : String(msg);
-        this.native.sendTo(targetId, payload);
-    }
-
-    /**
-     * 다중 수신자에게 메시지 전송 (멀티캐스트)
-     * @param {string[]} ids - 수신자 세션 ID 배열
-     * @param {string|object} msg - 전송할 메시지
-     */
-    sendToMany(ids, msg) {
-        const payload = (typeof msg === 'object') ? JSON.stringify(msg) : String(msg);
-        if (this.native.sendToMany) {
-            this.native.sendToMany(ids, payload);
-        } else {
-            // 폴백: 개별 전송
-            for (const id of ids) {
-                this.native.sendTo(id, payload);
-            }
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 📋 연결 관리
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 접속 중인 전체 클라이언트 ID 목록 (로컬 + 리모트)
-     * @returns {string[]} 세션 ID 배열
-     */
-    getOnlineClients() {
-        return this.native.getOnlineClients?.() || [];
-    }
-
-    /**
-     * 접속 중인 전체 클라이언트 상세 목록 (id + 연결 형식)
-     * @returns {{ id: string, connectionType: string }[]} 클라이언트 상세 배열
-     */
-    getOnlineClientsDetail() {
-        return this.native.getOnlineClientsDetail?.() || [];
-    }
-
-    /**
-     * 접속 중인 클라이언트 수 (로컬 + 리모트)
-     * @returns {number}
-     */
-    getOnlineCount() {
-        return this.native.getOnlineCount?.() || 0;
-    }
-
-    /**
-     * 특정 클라이언트 강제 종료 (Close Code 4001)
-     * @param {string} targetId - 대상 세션 ID
-     * @returns {boolean} 성공 여부
-     */
-    disconnectClient(targetId) {
-        return this.native.disconnectClient?.(targetId) || false;
-    }
-}

package/wasm/alloy_client_wasm.d.ts

@@ -1,174 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-
-export class AlloyClient {
-    free(): void;
-    [Symbol.dispose](): void;
-    decrypt_custom(key: string, data: string): string;
-    /**
-     * Smart DELETE Request
-     */
-    delete(path: string, encrypt_enabled?: boolean | null): Promise<any>;
-    encrypt_custom(key: string, data: string): string;
-    /**
-     * Smart GET Request (encrypt_query: defaults to true)
-     */
-    get(path: string, encrypt_enabled?: boolean | null): Promise<any>;
-    constructor(master_secret: string);
-    /**
-     * Smart PATCH Request
-     */
-    patch(path: string, json_body: any, encrypt_enabled?: boolean | null): Promise<any>;
-    /**
-     * Smart POST Request
-     */
-    post(path: string, json_body: any, encrypt_enabled?: boolean | null): Promise<any>;
-    /**
-     * Smart PUT Request
-     */
-    put(path: string, json_body: any, encrypt_enabled?: boolean | null): Promise<any>;
-    uuid(): string;
-}
-
-/**
- * 📡 AlloySocket — WASM 기반 WebSocket 클라이언트
- *
- * 이벤트 기반 메시지 ({ type, data }) 구조를 사용하며,
- * 메시지 암호화, 자동 Ping, 스마트 재연결을 지원합니다.
- */
-export class AlloySocket {
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * 🔌 서버 연결
-     */
-    connect(): void;
-    /**
-     * 🔌 명시적 연결 종료
-     */
-    disconnect(): void;
-    /**
-     * 🔍 연결 상태 확인
-     */
-    is_connected(): boolean;
-    /**
-     * 📡 AlloySocket 생성자
-     *
-     * @param url - WebSocket 서버 주소 (예: "ws://localhost:3000/ws")
-     * @param master_secret - 메시지 암호화 키
-     * @param encrypt_enabled - 암호화 활성화 여부 (기본: false)
-     */
-    constructor(url: string, master_secret: string, encrypt_enabled?: boolean | null);
-    /**
-     * 📩 이벤트 핸들러 등록
-     *
-     * @param event_type - 이벤트 타입 (예: "connect", "message", "disconnect", "chat")
-     * @param callback - JS 콜백 함수
-     */
-    on(event_type: string, callback: Function): void;
-    /**
-     * 📨 이벤트 기반 메시지 전송
-     *
-     * @param event_type - 이벤트 타입 (예: "chat", "sync")
-     * @param data - 전송할 데이터 (JS 객체)
-     */
-    send(event_type: string, data: any): void;
-    /**
-     * ⚙️ 자동 재연결 활성화/비활성화
-     */
-    set_auto_reconnect(enabled: boolean): void;
-    /**
-     * ⚙️ 최대 재연결 시도 횟수 설정
-     */
-    set_max_reconnect_attempts(count: number): void;
-    /**
-     * ⚙️ Ping 주기 설정 (밀리초)
-     */
-    set_ping_interval(ms: number): void;
-}
-
-export class AlloyUtil {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Find items > threshold (Example of complex filter)
-     */
-    static filter_gt(list: Int32Array, threshold: number): Int32Array;
-    static md5(input: string): string;
-    static sha256(input: string): string;
-    /**
-     * Shuffle a large array of integers (Fisher-Yates)
-     * Much faster than JS sort(() => 0.5 - Math.random())
-     */
-    static shuffle_i32(list: Int32Array): Int32Array;
-    /**
-     * High performance sort
-     */
-    static sort_i32(list: Int32Array): Int32Array;
-}
-
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
-
-export interface InitOutput {
-    readonly memory: WebAssembly.Memory;
-    readonly __wbg_alloyclient_free: (a: number, b: number) => void;
-    readonly __wbg_alloysocket_free: (a: number, b: number) => void;
-    readonly __wbg_alloyutil_free: (a: number, b: number) => void;
-    readonly alloyclient_decrypt_custom: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
-    readonly alloyclient_delete: (a: number, b: number, c: number, d: number) => number;
-    readonly alloyclient_encrypt_custom: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
-    readonly alloyclient_get: (a: number, b: number, c: number, d: number) => number;
-    readonly alloyclient_new: (a: number, b: number, c: number) => void;
-    readonly alloyclient_patch: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly alloyclient_post: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly alloyclient_put: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly alloyclient_uuid: (a: number, b: number) => void;
-    readonly alloysocket_connect: (a: number, b: number) => void;
-    readonly alloysocket_disconnect: (a: number) => void;
-    readonly alloysocket_is_connected: (a: number) => number;
-    readonly alloysocket_new: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly alloysocket_on: (a: number, b: number, c: number, d: number) => void;
-    readonly alloysocket_send: (a: number, b: number, c: number, d: number, e: number) => void;
-    readonly alloysocket_set_auto_reconnect: (a: number, b: number) => void;
-    readonly alloysocket_set_max_reconnect_attempts: (a: number, b: number) => void;
-    readonly alloysocket_set_ping_interval: (a: number, b: number) => void;
-    readonly alloyutil_filter_gt: (a: number, b: number, c: number, d: number) => void;
-    readonly alloyutil_md5: (a: number, b: number, c: number) => void;
-    readonly alloyutil_sha256: (a: number, b: number, c: number) => void;
-    readonly alloyutil_shuffle_i32: (a: number, b: number, c: number) => void;
-    readonly alloyutil_sort_i32: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_87: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_665: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_713: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_88: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_666: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_92: (a: number, b: number) => void;
-    readonly __wbindgen_export: (a: number, b: number) => number;
-    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_export3: (a: number) => void;
-    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
-
-/**
- * Instantiates the given `module`, which can either be bytes or
- * a precompiled `WebAssembly.Module`.
- *
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
- *
- * @returns {InitOutput}
- */
-export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
-
-/**
- * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
- * for everything else, calls `WebAssembly.instantiate` directly.
- *
- * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
- *
- * @returns {Promise<InitOutput>}
- */
-export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;