@withwiz/toolkit 0.1.0

package/dist/cache/cache-invalidation.d.ts

@@ -0,0 +1,90 @@
+import type { RedisCacheManager, HybridCacheManager, InMemoryCacheManager, NoopCacheManager } from "./index";
+type CacheManager = RedisCacheManager | HybridCacheManager | InMemoryCacheManager | NoopCacheManager;
+/**
+ * 범용 캐시 무효화 헬퍼 함수들
+ *
+ * @example
+ * ```typescript
+ * import { invalidateCache } from '@withwiz/cache';
+ *
+ * // 기본 캐시에서 단일 키 삭제
+ * await invalidateCache.byKey('my-key');
+ *
+ * // 기본 캐시에서 패턴으로 삭제
+ * await invalidateCache.byPattern('user:*');
+ *
+ * // 모든 캐시 삭제
+ * await invalidateCache.all();
+ * ```
+ */
+export declare const invalidateCache: {
+    /**
+     * 기본 캐시에서 단일 키 삭제
+     * @param key - 삭제할 캐시 키
+     */
+    byKey: (key: string) => Promise<void>;
+    /**
+     * 기본 캐시에서 패턴으로 삭제
+     * @param pattern - 삭제할 캐시 키 패턴 (예: "user:*")
+     */
+    byPattern: (pattern: string) => Promise<void>;
+    /**
+     * GeoIP 캐시에서 단일 키 삭제
+     * @param key - 삭제할 캐시 키
+     */
+    geoByKey: (key: string) => Promise<void>;
+    /**
+     * GeoIP 캐시에서 패턴으로 삭제
+     * @param pattern - 삭제할 캐시 키 패턴
+     */
+    geoByPattern: (pattern: string) => Promise<void>;
+    /**
+     * 기본 캐시 전체 삭제
+     */
+    all: () => Promise<void>;
+    /**
+     * GeoIP 캐시 전체 삭제
+     */
+    allGeo: () => Promise<void>;
+};
+/**
+ * 주어진 캐시 매니저에서 키 삭제
+ *
+ * @example
+ * ```typescript
+ * import { getCacheManager } from '@withwiz/cache';
+ * import { deleteFromCache } from '@withwiz/cache/cache-invalidation';
+ *
+ * const myCache = getCacheManager('my-prefix');
+ * await deleteFromCache(myCache, 'my-key');
+ * ```
+ */
+export declare function deleteFromCache(cacheManager: CacheManager, key: string): Promise<void>;
+/**
+ * 주어진 캐시 매니저에서 패턴으로 삭제
+ *
+ * @example
+ * ```typescript
+ * import { getCacheManager } from '@withwiz/cache';
+ * import { deletePatternFromCache } from '@withwiz/cache/cache-invalidation';
+ *
+ * const myCache = getCacheManager('my-prefix');
+ * await deletePatternFromCache(myCache, 'user:*');
+ * ```
+ */
+export declare function deletePatternFromCache(cacheManager: CacheManager, pattern: string): Promise<void>;
+/**
+ * 여러 캐시 매니저에서 동시에 패턴 삭제
+ *
+ * @example
+ * ```typescript
+ * import { getCacheManager } from '@withwiz/cache';
+ * import { deletePatternFromMultipleCaches } from '@withwiz/cache/cache-invalidation';
+ *
+ * const cache1 = getCacheManager('prefix1');
+ * const cache2 = getCacheManager('prefix2');
+ * await deletePatternFromMultipleCaches([cache1, cache2], 'user:*');
+ * ```
+ */
+export declare function deletePatternFromMultipleCaches(cacheManagers: CacheManager[], pattern: string): Promise<void>;
+export {};

package/dist/cache/cache-invalidation.js

@@ -0,0 +1,24 @@
+import {
+  deleteFromCache,
+  deletePatternFromCache,
+  deletePatternFromMultipleCaches,
+  invalidateCache
+} from "../chunk-4KJXENRM.js";
+import "../chunk-AIHQBQ3E.js";
+import "../chunk-HV3DGSSH.js";
+import "../chunk-Z4D4CMDA.js";
+import "../chunk-SS56XFLI.js";
+import "../chunk-Q7IP4JMW.js";
+import "../chunk-GL2NANFH.js";
+import "../chunk-TXGNSECL.js";
+import "../chunk-6LTZCXNC.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  deleteFromCache,
+  deletePatternFromCache,
+  deletePatternFromMultipleCaches,
+  invalidateCache
+};

package/dist/cache/cache-keys-legacy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Legacy Cache Keys
+ *
+ * @deprecated CacheKeys (<your-project>/config/cache-keys.ts)를 사용하세요.
+ *
+ * 캐시 키 생성 헬퍼 함수들 (레거시 호환성 유지)
+ */
+/**
+ * @deprecated CacheKeys (<your-project>/config/cache-keys.ts)를 사용하세요.
+ * 이 객체는 레거시 호환성을 위해 유지됩니다.
+ */
+export declare const cacheKeys: {
+    geographyStats: (linkId: string) => string;
+    timelineStats: (linkId: string) => string;
+    deviceStats: (linkId: string) => string;
+    browserStats: (linkId: string) => string;
+    osStats: (linkId: string) => string;
+    adminCountryStats: () => string;
+    adminCityStats: () => string;
+    adminDailyStats: () => string;
+    adminDeviceStats: () => string;
+    adminBrowserStats: () => string;
+    userLinks: (userId: string) => string;
+    userStats: (userId: string) => string;
+    linkInfo: (linkId: string) => string;
+    linkClicks: (linkId: string) => string;
+    geoLocation: (ipAddress: string) => string;
+    community: {
+        popularTags: (period: string, limit: number) => string;
+        tagLinks: (tagId: string, page: number, pageSize: number, sortBy: string, period: string) => string;
+        recentLinks: (page: number, pageSize: number) => string;
+        trendingLinks: (period: string, algorithm: string, limit: number) => string;
+        searchLinks: (query: string, tagIds: string, sortBy: string, page: number, pageSize: number) => string;
+    };
+};

package/dist/cache/cache-keys-legacy.js

@@ -0,0 +1,7 @@
+import {
+  cacheKeys
+} from "../chunk-JBCDEAMW.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  cacheKeys
+};

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

@@ -0,0 +1,74 @@
+/**
+ * Redis Client Management
+ *
+ * Redis 클라이언트 초기화 및 연결 상태 관리
+ * - 전역 Redis 에러 상태 관리 (싱글톤)
+ * - 에러 발생 시 즉시 폴백 지원
+ */
+import { Redis } from '@upstash/redis';
+/**
+ * Redis가 전역적으로 비활성화되었는지 확인
+ */
+export declare function isRedisGloballyDisabled(): boolean;
+/**
+ * Redis 에러 발생 시 호출 (전역 상태 업데이트)
+ */
+export declare function notifyRedisError(error: Error, source: string): void;
+/**
+ * Redis 전역 상태 초기화 (재연결 성공 시)
+ */
+export declare function resetRedisGlobalState(): void;
+/**
+ * 전역 Redis 상태 조회
+ */
+export declare function getRedisGlobalStatus(): {
+    isDisabled: boolean;
+    errorCount: number;
+    lastErrorTime: Date | null;
+    lastErrorMessage: string | null;
+};
+/**
+ * 캐시 메트릭 인터페이스
+ */
+export interface CacheMetrics {
+    hits: number;
+    misses: number;
+    errors: number;
+    totalRequests: number;
+    hitRate: number;
+    averageResponseTime: number;
+    lastError?: string;
+    lastErrorTime?: Date;
+}
+/**
+ * Redis 연결 상태 인터페이스
+ */
+export interface RedisConnectionStatus {
+    isConnected: boolean;
+    lastPingTime?: Date;
+    connectionErrors: number;
+    lastConnectionError?: string;
+    lastConnectionErrorTime?: Date;
+}
+/**
+ * Redis 연결 상태 확인
+ */
+export declare function checkRedisConnection(): Promise<{
+    success: boolean;
+    error?: string;
+    details?: any;
+}>;
+/**
+ * Redis 연결 상태 확인 함수 (지연 평가)
+ * - 전역 Redis 비활성화 상태도 확인
+ */
+export declare function isRedisAvailableNow(): boolean;
+/**
+ * Redis 클라이언트 가져오기 (지연 초기화)
+ * - 전역 Redis 비활성화 상태 확인
+ */
+export declare function getRedisClient(): Redis | null;
+/**
+ * Redis 캐시 초기화 로그 (최초 1회, 지연 실행)
+ */
+export declare function logRedisInitialization(): void;

package/dist/cache/cache-redis.js

@@ -0,0 +1,24 @@
+import {
+  checkRedisConnection,
+  getRedisClient,
+  getRedisGlobalStatus,
+  isRedisAvailableNow,
+  isRedisGloballyDisabled,
+  logRedisInitialization,
+  notifyRedisError,
+  resetRedisGlobalState
+} from "../chunk-6LTZCXNC.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  checkRedisConnection,
+  getRedisClient,
+  getRedisGlobalStatus,
+  isRedisAvailableNow,
+  isRedisGloballyDisabled,
+  logRedisInitialization,
+  notifyRedisError,
+  resetRedisGlobalState
+};

package/dist/cache/cache-types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * In-Memory Cache Types
+ *
+ * 인메모리 캐시 관련 타입 정의
+ */
+/**
+ * 인메모리 캐시 설정 인터페이스
+ */
+export interface InMemoryCacheConfig {
+    /** 최대 항목 수 (기본: 100,000) */
+    maxSize: number;
+    /** 최대 메모리 MB (기본: 200) */
+    maxMemoryMB: number;
+    /** 교체 정책: lru | fifo | ttl */
+    evictionPolicy: 'lru' | 'fifo' | 'ttl';
+    /** 만료 항목 정리 주기 (ms, 기본: 60000) */
+    cleanupInterval: number;
+    /** 기본 TTL (초, 기본: 3600) */
+    defaultTTL: number;
+}
+/**
+ * 인메모리 캐시 설정 기본값
+ */
+export declare const DEFAULT_INMEMORY_CONFIG: InMemoryCacheConfig;
+/**
+ * 캐시 엔트리 인터페이스
+ */
+export interface CacheEntry<T> {
+    /** 저장된 값 */
+    value: T;
+    /** 만료 시간 (Unix timestamp, ms) */
+    expiresAt: number;
+    /** 추정 메모리 크기 (bytes) */
+    size: number;
+    /** 마지막 접근 시간 (LRU용, Unix timestamp, ms) */
+    accessedAt: number;
+    /** 생성 시간 (FIFO용, Unix timestamp, ms) */
+    createdAt: number;
+}
+/**
+ * 인메모리 캐시 메트릭
+ */
+export interface InMemoryCacheMetrics {
+    /** 캐시 히트 수 */
+    hits: number;
+    /** 캐시 미스 수 */
+    misses: number;
+    /** 교체로 인한 제거 수 */
+    evictions: number;
+    /** TTL 만료로 인한 제거 수 */
+    expirations: number;
+    /** 총 요청 수 */
+    totalRequests: number;
+    /** 히트율 (%) */
+    hitRate: number;
+}
+/**
+ * 인메모리 캐시 통계
+ */
+export interface InMemoryCacheStats {
+    /** 현재 항목 수 */
+    itemCount: number;
+    /** 현재 메모리 사용량 (MB) */
+    memoryUsageMB: number;
+    /** 최대 항목 수 */
+    maxSize: number;
+    /** 최대 메모리 (MB) */
+    maxMemoryMB: number;
+    /** 사용률 (%) */
+    utilizationPercent: number;
+    /** 메모리 사용률 (%) */
+    memoryUtilizationPercent: number;
+}
+/**
+ * 캐시 백엔드 타입
+ */
+export type CacheBackendType = 'redis' | 'memory' | 'hybrid';
+/**
+ * 하이브리드 캐시 설정
+ */
+export interface HybridCacheConfig {
+    /** 백엔드 타입 */
+    backend: CacheBackendType;
+    /** Redis 에러 시 인메모리 폴백 여부 */
+    fallbackOnRedisError: boolean;
+    /** Redis 실패 시 인메모리에 저장 여부 */
+    writeToMemoryOnRedisError: boolean;
+    /** 인메모리 캐시 설정 */
+    inmemory: InMemoryCacheConfig;
+}
+/**
+ * 하이브리드 캐시 설정 기본값
+ */
+export declare const DEFAULT_HYBRID_CONFIG: HybridCacheConfig;
+/**
+ * 하이브리드 캐시 메트릭
+ */
+export interface HybridCacheMetrics {
+    /** Redis 캐시 메트릭 (null이면 Redis 비활성화) */
+    redis: {
+        hits: number;
+        misses: number;
+        errors: number;
+        totalRequests: number;
+        hitRate: number;
+        averageResponseTime: number;
+    } | null;
+    /** 인메모리 캐시 메트릭 */
+    memory: InMemoryCacheMetrics;
+    /** 통합 메트릭 */
+    combined: {
+        totalHits: number;
+        totalMisses: number;
+        /** Redis 실패로 인메모리 폴백한 횟수 */
+        redisFallbacks: number;
+        hitRate: number;
+    };
+}
+/**
+ * 하이브리드 캐시 연결 상태
+ */
+export interface HybridConnectionStatus {
+    /** Redis 연결 상태 */
+    redisConnected: boolean;
+    /** 인메모리 캐시 활성화 여부 */
+    memoryActive: boolean;
+    /** 현재 사용 중인 백엔드 */
+    currentBackend: CacheBackendType;
+    /** Redis 에러 카운트 */
+    redisErrorCount: number;
+    /** 마지막 Redis 에러 시간 */
+    lastRedisError: Date | null;
+    /** 마지막 Redis 에러 메시지 */
+    lastRedisErrorMessage: string | null;
+    /** Redis가 전역적으로 비활성화되었는지 여부 */
+    redisGloballyDisabled?: boolean;
+}
+/**
+ * 통합 캐시 매니저 인터페이스
+ * CacheManager, HybridCacheManager, InMemoryCache 모두 이 인터페이스를 구현
+ */
+export interface IUnifiedCacheManager {
+    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>;
+    getMetrics(): InMemoryCacheMetrics | HybridCacheMetrics | object;
+    getConnectionStatus(): HybridConnectionStatus | object;
+    checkConnection(): Promise<boolean>;
+}

package/dist/cache/cache-types.js

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

package/dist/cache/cache-wrapper.d.ts

@@ -0,0 +1,27 @@
+import { CacheOptions } from './cache-config';
+export declare function getCacheBackendLabel(): string;
+/**
+ * 캐시 래퍼 함수 (데이터베이스 쿼리 결과 캐싱)
+ *
+ * prefix 처리:
+ * 1. prefix가 제공된 경우: 최종 키 = prefix:key
+ *    예: withCache('recent-links:1:10', fn, { prefix: 'community' })
+ *    → 캐시 키: community:recent-links:1:10
+ *
+ * 2. prefix가 없는 경우: 최종 키 = key (그대로 사용)
+ *    예: withCache('community:recent-links:1:10', fn)
+ *    → 캐시 키: community:recent-links:1:10
+ */
+export declare function withCache<T>(key: string, fetchFunction: () => Promise<T>, options?: CacheOptions): Promise<T>;
+/**
+ * 캐시 성능 메트릭
+ */
+export declare const cacheMetrics: {
+    hits: number;
+    misses: number;
+    errors: number;
+    totalRequests: number;
+    averageResponseTime: number;
+    readonly hitRate: number;
+    reset(): void;
+};

package/dist/cache/cache-wrapper.js

@@ -0,0 +1,22 @@
+import {
+  cacheMetrics,
+  getCacheBackendLabel,
+  withCache
+} from "../chunk-YBSHN67U.js";
+import "../chunk-AIHQBQ3E.js";
+import "../chunk-HV3DGSSH.js";
+import "../chunk-Z4D4CMDA.js";
+import "../chunk-SS56XFLI.js";
+import "../chunk-Q7IP4JMW.js";
+import "../chunk-GL2NANFH.js";
+import "../chunk-TXGNSECL.js";
+import "../chunk-6LTZCXNC.js";
+import "../chunk-I47QEDTX.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-IQQKKUAV.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  cacheMetrics,
+  getCacheBackendLabel,
+  withCache
+};

package/dist/cache/cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cache Module - Backward Compatibility Re-export
+ *
+ * 이 파일은 기존 import 경로 호환성을 위해 유지됩니다.
+ * 모든 내용은 index.ts에서 re-export됩니다.
+ *
+ * @example
+ * // 기존 방식 (계속 동작)
+ * import { cache, withCache } from '@withwiz/cache/cache';
+ *
+ * // 신규 권장 방식
+ * import { cache, withCache } from '@withwiz/cache';
+ */
+export * from './index';

package/dist/cache/cache.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
+};