@withwiz/toolkit 0.1.0

package/dist/cache/hybrid-cache-manager.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Hybrid Cache Manager
+ *
+ * Redis + 인메모리 하이브리드 캐시 매니저
+ * - Redis 우선 사용
+ * - Redis 실패 시 인메모리 폴백
+ * - 백엔드 모드에 따른 동적 전환
+ * - 전역 Redis 에러 상태와 연동
+ */
+import type { CacheBackendType, HybridCacheMetrics, HybridConnectionStatus, IUnifiedCacheManager, InMemoryCacheConfig } from './cache-types';
+/**
+ * Redis 캐시 매니저 인터페이스 (RedisCacheManager와 호환)
+ */
+interface IRedisCacheManager {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePattern(pattern: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    increment(key: string, value?: number): Promise<number>;
+    expire(key: string, ttl: number): Promise<void>;
+    getMetrics(): object;
+    getConnectionStatus(): object;
+    checkConnection(): Promise<boolean>;
+}
+/**
+ * 하이브리드 캐시 매니저 설정
+ */
+export interface HybridCacheManagerConfig {
+    /** 캐시 백엔드 타입 */
+    backend: CacheBackendType;
+    /** Redis 매니저 인스턴스 (null이면 Redis 비활성화) */
+    redisManager: IRedisCacheManager | null;
+    /** 인메모리 캐시 설정 */
+    inmemoryConfig?: Partial<InMemoryCacheConfig>;
+    /** Redis 에러 시 인메모리 폴백 여부 */
+    fallbackOnRedisError?: boolean;
+    /** hybrid 모드에서 인메모리에도 저장 여부 */
+    writeToMemory?: boolean;
+    /** Redis 에러 임계값 (이 값 이상이면 일시적으로 Redis 비활성화) */
+    redisErrorThreshold?: number;
+    /** Redis 재연결 시도 간격 (ms) */
+    redisReconnectInterval?: number;
+}
+/**
+ * 하이브리드 캐시 매니저
+ */
+export declare class HybridCacheManager implements IUnifiedCacheManager {
+    private prefix;
+    private config;
+    private redisManager;
+    private memoryCache;
+    private redisErrorCount;
+    private lastRedisError;
+    private lastRedisErrorMessage;
+    private isRedisTemporarilyDisabled;
+    private redisReconnectTimer;
+    private redisFallbackCount;
+    constructor(prefix: string, config: HybridCacheManagerConfig);
+    /**
+     * 캐시에서 값 조회
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * 캐시에 값 저장
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * 캐시에서 항목 삭제
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 패턴 매칭으로 캐시 삭제
+     */
+    deletePattern(pattern: string): Promise<void>;
+    /**
+     * 키 존재 여부 확인
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 값 증가
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * TTL 설정
+     */
+    expire(key: string, ttl: number): Promise<void>;
+    /**
+     * 하이브리드 캐시 메트릭 조회
+     */
+    getMetrics(): HybridCacheMetrics;
+    /**
+     * 연결 상태 조회
+     */
+    getConnectionStatus(): HybridConnectionStatus;
+    /**
+     * 연결 체크
+     */
+    checkConnection(): Promise<boolean>;
+    /**
+     * 설정 조회
+     */
+    getConfig(): object;
+    /**
+     * 실제 사용할 백엔드 결정
+     * - 전역 Redis 비활성화 상태도 확인
+     */
+    private getEffectiveBackend;
+    /**
+     * Redis 에러 처리
+     * - 전역 Redis 상태도 함께 업데이트
+     */
+    private handleRedisError;
+    /**
+     * Redis 일시 비활성화
+     */
+    private disableRedisTemporarily;
+    /**
+     * Redis 재연결 시도
+     */
+    private tryReconnectRedis;
+    /**
+     * Redis 에러 상태 초기화 (로컬 상태만)
+     * - 전역 상태는 cache-redis.ts에서 관리 (Redis 성공 시 자동 리셋)
+     */
+    private resetRedisErrorState;
+    /**
+     * 리소스 정리
+     */
+    destroy(): void;
+    /**
+     * 전역 인스턴스 맵 가져오기 (HMR 안전)
+     */
+    private static getGlobalInstances;
+    /**
+     * 싱글톤 인스턴스 가져오기
+     */
+    static getInstance(prefix: string, config: HybridCacheManagerConfig): HybridCacheManager;
+    /**
+     * 모든 인스턴스 종료
+     */
+    static destroyAll(): void;
+    /**
+     * 인스턴스 초기화 (테스트용)
+     */
+    static clearInstances(): void;
+}
+export {};

package/dist/cache/hybrid-cache-manager.js

@@ -0,0 +1,13 @@
+import {
+  HybridCacheManager
+} from "../chunk-HV3DGSSH.js";
+import "../chunk-Z4D4CMDA.js";
+import "../chunk-SS56XFLI.js";
+import "../chunk-6LTZCXNC.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  HybridCacheManager
+};

package/dist/cache/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cache Module Entry Point
+ *
+ * 캐시 모듈의 통합 진입점
+ * - 모든 캐시 관련 기능을 re-export
+ */
+export { initializeCache, isCacheEnabled, getEnv, getENV, getConfig, getDefaultConfig, validateRedisEnvironment, } from './cache-env';
+export { checkRedisConnection, isRedisAvailableNow, getRedisClient, logRedisInitialization, isRedisGloballyDisabled, notifyRedisError, resetRedisGlobalState, getRedisGlobalStatus, } from './cache-redis';
+export type { CacheMetrics, RedisConnectionStatus } from './cache-redis';
+export { getCacheConfig, getCacheTTL } from './cache-config';
+export type { CacheOptions } from './cache-config';
+export { INMEMORY_CACHE_DEFAULTS, CACHE_TTL_DEFAULTS, CACHE_DURATION_DEFAULTS, CACHE_ENV_VARS, ONE_MINUTE, FIVE_MINUTES, TEN_MINUTES, FIFTEEN_MINUTES, THIRTY_MINUTES, ONE_HOUR, ONE_DAY, THIRTY_DAYS, } from './cache-defaults';
+export { RedisCacheManager } from './redis-cache-manager';
+export { NoopCacheManager } from './noop-cache-manager';
+export { getCacheManager, getEffectiveCacheBackend, cache, geoCache, } from './cache-factory';
+export { cacheKeys } from './cache-keys-legacy';
+export { invalidateCache } from './cache-invalidation';
+export { withCache, cacheMetrics } from './cache-wrapper';
+export { InMemoryCacheManager } from './inmemory-cache-manager';
+export { HybridCacheManager } from './hybrid-cache-manager';
+export type { InMemoryCacheConfig, CacheBackendType, HybridCacheMetrics, CacheEntry, InMemoryCacheMetrics, InMemoryCacheStats, HybridCacheConfig, HybridConnectionStatus, IUnifiedCacheManager, } from './cache-types';

package/dist/cache/index.js

@@ -0,0 +1,112 @@
+import "../chunk-EBUEBEJX.js";
+import {
+  cacheMetrics,
+  withCache
+} from "../chunk-YBSHN67U.js";
+import {
+  invalidateCache
+} from "../chunk-4KJXENRM.js";
+import {
+  cache,
+  geoCache,
+  getCacheManager,
+  getEffectiveCacheBackend
+} from "../chunk-AIHQBQ3E.js";
+import {
+  HybridCacheManager
+} from "../chunk-HV3DGSSH.js";
+import {
+  InMemoryCacheManager
+} from "../chunk-Z4D4CMDA.js";
+import "../chunk-SS56XFLI.js";
+import {
+  NoopCacheManager
+} from "../chunk-Q7IP4JMW.js";
+import {
+  RedisCacheManager
+} from "../chunk-GL2NANFH.js";
+import {
+  getCacheConfig,
+  getCacheTTL
+} from "../chunk-TXGNSECL.js";
+import {
+  cacheKeys
+} from "../chunk-JBCDEAMW.js";
+import {
+  checkRedisConnection,
+  getRedisClient,
+  getRedisGlobalStatus,
+  isRedisAvailableNow,
+  isRedisGloballyDisabled,
+  logRedisInitialization,
+  notifyRedisError,
+  resetRedisGlobalState
+} from "../chunk-6LTZCXNC.js";
+import {
+  getConfig,
+  getDefaultConfig,
+  getENV,
+  getEnv,
+  initializeCache,
+  isCacheEnabled,
+  validateRedisEnvironment
+} from "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import {
+  CACHE_DURATION_DEFAULTS,
+  CACHE_ENV_VARS,
+  CACHE_TTL_DEFAULTS,
+  FIFTEEN_MINUTES,
+  FIVE_MINUTES,
+  INMEMORY_CACHE_DEFAULTS,
+  ONE_DAY,
+  ONE_HOUR,
+  ONE_MINUTE,
+  TEN_MINUTES,
+  THIRTY_DAYS,
+  THIRTY_MINUTES
+} from "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  CACHE_DURATION_DEFAULTS,
+  CACHE_ENV_VARS,
+  CACHE_TTL_DEFAULTS,
+  FIFTEEN_MINUTES,
+  FIVE_MINUTES,
+  HybridCacheManager,
+  INMEMORY_CACHE_DEFAULTS,
+  InMemoryCacheManager,
+  NoopCacheManager,
+  ONE_DAY,
+  ONE_HOUR,
+  ONE_MINUTE,
+  RedisCacheManager,
+  TEN_MINUTES,
+  THIRTY_DAYS,
+  THIRTY_MINUTES,
+  cache,
+  cacheKeys,
+  cacheMetrics,
+  checkRedisConnection,
+  geoCache,
+  getCacheConfig,
+  getCacheManager,
+  getCacheTTL,
+  getConfig,
+  getDefaultConfig,
+  getENV,
+  getEffectiveCacheBackend,
+  getEnv,
+  getRedisClient,
+  getRedisGlobalStatus,
+  initializeCache,
+  invalidateCache,
+  isCacheEnabled,
+  isRedisAvailableNow,
+  isRedisGloballyDisabled,
+  logRedisInitialization,
+  notifyRedisError,
+  resetRedisGlobalState,
+  validateRedisEnvironment,
+  withCache
+};

package/dist/cache/inmemory-cache-manager.d.ts

@@ -0,0 +1,163 @@
+/**
+ * In-Memory Cache Manager
+ *
+ * LRU + TTL 기반 인메모리 캐시 매니저
+ * - LRU (Least Recently Used): 가장 오래 접근되지 않은 항목 제거
+ * - TTL (Time To Live): 만료 시간 기반 항목 제거
+ * - 메모리 제한: 최대 항목 수 및 메모리 크기 제한
+ */
+import type { InMemoryCacheConfig, InMemoryCacheMetrics, InMemoryCacheStats, IUnifiedCacheManager } from './cache-types';
+/**
+ * 인메모리 캐시 매니저 클래스
+ * RedisCacheManager와 동일한 인터페이스를 구현하여 호환성 보장
+ */
+export declare class InMemoryCacheManager implements IUnifiedCacheManager {
+    private cache;
+    private accessOrder;
+    private config;
+    private currentMemoryBytes;
+    private cleanupTimer;
+    private metrics;
+    private prefix;
+    constructor(prefix: string, config?: Partial<InMemoryCacheConfig>);
+    /**
+     * 캐시에서 값 조회
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * 캐시에 값 저장
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * 캐시에서 항목 삭제
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 패턴 매칭으로 캐시 삭제
+     * 간단한 glob 패턴 지원 (* 와일드카드)
+     */
+    deletePattern(pattern: string): Promise<void>;
+    /**
+     * 키 존재 여부 확인
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 값 증가 (카운터용)
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * TTL 설정/갱신
+     */
+    expire(key: string, ttl: number): Promise<void>;
+    /**
+     * 전체 캐시 초기화
+     */
+    clear(): void;
+    /**
+     * 리소스 정리 (서버 종료 시 호출)
+     */
+    destroy(): void;
+    /**
+     * 캐시 메트릭 조회
+     */
+    getMetrics(): InMemoryCacheMetrics;
+    /**
+     * 캐시 통계 조회
+     */
+    getStats(): InMemoryCacheStats;
+    /**
+     * 연결 상태 조회 (인메모리는 항상 연결됨)
+     */
+    getConnectionStatus(): object;
+    /**
+     * 연결 체크 (인메모리는 항상 true)
+     */
+    checkConnection(): Promise<boolean>;
+    /**
+     * 설정 조회
+     */
+    getConfig(): InMemoryCacheConfig & {
+        prefix: string;
+    };
+    /**
+     * 전체 키 생성 (prefix 포함)
+     */
+    private getFullKey;
+    /**
+     * 항목 만료 여부 확인
+     */
+    private isExpired;
+    /**
+     * 항목 삭제 (내부용)
+     */
+    private deleteEntry;
+    /**
+     * 메모리 크기 추정
+     * JSON 직렬화 크기 * 2 (UTF-16) + 객체 오버헤드
+     */
+    private estimateSize;
+    /**
+     * eviction 필요 여부 확인
+     */
+    private needsEviction;
+    /**
+     * 교체 정책에 따른 항목 제거
+     */
+    private evict;
+    /**
+     * LRU 교체: 가장 오래 접근되지 않은 항목 제거
+     */
+    private evictLRU;
+    /**
+     * FIFO 교체: 가장 먼저 들어온 항목 제거
+     */
+    private evictFIFO;
+    /**
+     * TTL 교체: 가장 빨리 만료될 항목 제거
+     */
+    private evictTTL;
+    /**
+     * 접근 순서 업데이트 (LRU용)
+     */
+    private updateAccessOrder;
+    /**
+     * 접근 순서에서 제거
+     */
+    private removeFromAccessOrder;
+    /**
+     * 히트율 업데이트
+     */
+    private updateHitRate;
+    /**
+     * glob 패턴을 정규식으로 변환
+     */
+    private patternToRegex;
+    /**
+     * 만료 항목 정리 타이머 시작
+     */
+    private startCleanupTimer;
+    /**
+     * 만료된 항목 일괄 정리
+     */
+    private cleanupExpired;
+    /**
+     * 전역 인스턴스 맵 가져오기 (HMR 안전)
+     */
+    private static getGlobalInstances;
+    /**
+     * 싱글톤 인스턴스 가져오기
+     */
+    static getInstance(prefix: string, config?: Partial<InMemoryCacheConfig>): InMemoryCacheManager;
+    /**
+     * 모든 인스턴스 종료
+     */
+    static destroyAll(): void;
+    /**
+     * 인스턴스 초기화 (테스트용)
+     */
+    static clearInstances(): void;
+    /**
+     * 모든 인스턴스의 통계 조회
+     */
+    static getAllStats(): Record<string, InMemoryCacheStats>;
+}

package/dist/cache/inmemory-cache-manager.js

@@ -0,0 +1,9 @@
+import {
+  InMemoryCacheManager
+} from "../chunk-Z4D4CMDA.js";
+import "../chunk-SS56XFLI.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  InMemoryCacheManager
+};

package/dist/cache/noop-cache-manager.d.ts

@@ -0,0 +1,36 @@
+import type { IUnifiedCacheManager } from './cache-types';
+export declare class NoopCacheManager implements IUnifiedCacheManager {
+    private prefix;
+    constructor(prefix: string);
+    get<T>(_key: string): Promise<T | null>;
+    set<T>(_key: string, _value: T, _ttl?: number): Promise<void>;
+    delete(_key: string): Promise<void>;
+    deletePattern(_pattern: string): Promise<void>;
+    exists(_key: string): Promise<boolean>;
+    increment(): Promise<number>;
+    expire(): Promise<void>;
+    getMetrics(): {
+        hits: number;
+        misses: number;
+        errors: number;
+        totalRequests: number;
+        hitRate: number;
+        averageResponseTime: number;
+    };
+    getConnectionStatus(): {
+        isConnected: boolean;
+        connectionErrors: number;
+    };
+    checkConnection(): Promise<boolean>;
+    getConfig(): {
+        prefix: string;
+        enabled: boolean;
+        reason: string;
+        envVars: {
+            [x: string]: string;
+            CACHE_ENABLED: string;
+            UPSTASH_REDIS_REST_URL: string;
+            UPSTASH_REDIS_REST_TOKEN: string;
+        };
+    };
+}

package/dist/cache/noop-cache-manager.js

@@ -0,0 +1,11 @@
+import {
+  NoopCacheManager
+} from "../chunk-Q7IP4JMW.js";
+import "../chunk-TXGNSECL.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  NoopCacheManager
+};

package/dist/cache/redis-cache-manager.d.ts

@@ -0,0 +1,34 @@
+import { CacheMetrics, RedisConnectionStatus } from "./cache-redis";
+import type { IUnifiedCacheManager } from "./cache-types";
+export declare class RedisCacheManager implements IUnifiedCacheManager {
+    private prefix;
+    private metrics;
+    private connectionStatus;
+    private constructor();
+    private static getGlobalInstances;
+    static getInstance(prefix: string): RedisCacheManager;
+    static clearInstances(): void;
+    private updateMetrics;
+    getMetrics(): CacheMetrics;
+    getConnectionStatus(): RedisConnectionStatus;
+    checkConnection(): Promise<boolean>;
+    getConfig(): {
+        prefix: string;
+        enabled: boolean;
+        redisAvailable: boolean;
+        envVars: {
+            CACHE_ENABLED: string;
+            UPSTASH_REDIS_REST_URL: string;
+            UPSTASH_REDIS_REST_TOKEN: string;
+        };
+    };
+    private getKey;
+    private serializeData;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePattern(pattern: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    increment(key: string, value?: number): Promise<number>;
+    expire(key: string, ttl: number): Promise<void>;
+}

package/dist/cache/redis-cache-manager.js

@@ -0,0 +1,11 @@
+import {
+  RedisCacheManager
+} from "../chunk-GL2NANFH.js";
+import "../chunk-6LTZCXNC.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  RedisCacheManager
+};

package/dist/chunk-26Y7VEYG.js

@@ -0,0 +1,93 @@
+import {
+  getPlatform
+} from "./chunk-KWTBD4CM.js";
+
+// src/system/environment.ts
+import os from "os";
+function checkEnvironmentVariables() {
+  const platform = getPlatform();
+  const requiredVars = [
+    "DATABASE_URL",
+    "NEXT_PUBLIC_BASE_URL",
+    "JWT_SECRET",
+    "UPSTASH_REDIS_REST_URL",
+    "UPSTASH_REDIS_REST_TOKEN"
+  ];
+  const optionalVars = [
+    "IPGEOLOCATION_API_KEY",
+    "MAXMIND_LICENSE_KEY",
+    "CACHE_ENABLED"
+  ];
+  const results = [];
+  for (const key of requiredVars) {
+    const value = process.env[key];
+    const ok = !!value;
+    results.push({
+      key,
+      ok,
+      value: ok ? value.length > 20 ? value.substring(0, 20) + "..." : value : void 0
+    });
+  }
+  for (const key of optionalVars) {
+    const value = process.env[key];
+    const ok = !!value;
+    results.push({
+      key,
+      ok,
+      value: ok ? value.length > 20 ? value.substring(0, 20) + "..." : value : void 0
+    });
+  }
+  results.push({
+    key: "PLATFORM",
+    ok: true,
+    value: platform === "darwin" ? "macOS" : "Linux"
+  });
+  results.push({
+    key: "NODE_ENV",
+    ok: true,
+    value: process.env.NODE_ENV || "development"
+  });
+  results.push({
+    key: "ARCHITECTURE",
+    ok: true,
+    value: process.arch
+  });
+  results.push({
+    key: "NODE_VERSION",
+    ok: true,
+    value: process.version
+  });
+  results.push({
+    key: "HOSTNAME",
+    ok: true,
+    value: os.hostname()
+  });
+  results.push({
+    key: "USER_HOME",
+    ok: true,
+    value: os.homedir()
+  });
+  results.push({
+    key: "TEMP_DIR",
+    ok: true,
+    value: os.tmpdir()
+  });
+  if (platform === "darwin") {
+    results.push({
+      key: "MACOS_VERSION",
+      ok: true,
+      value: os.release()
+    });
+  } else {
+    results.push({
+      key: "LINUX_DISTRO",
+      ok: true,
+      value: os.release()
+    });
+  }
+  return results;
+}
+
+export {
+  checkEnvironmentVariables
+};