redis-wizard 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,227 @@
+# Redis Wizard
+
+Redis Wizard는 `redis` 라이브러리를 감싸서 간편한 데이터베이스 작업을 제공하는 TypeScript 기반 Redis 유틸리티 패키지입니다.
+
+## 주요 기능
+
+- 🔑 **자동 키 프리픽스 관리**: 테이블/스코프 프리픽스를 자동으로 추가하여 키를 체계적으로 관리
+- 🔄 **자동 직렬화/역직렬화**: 객체를 자동으로 JSON으로 변환하여 저장하고 읽을 때 자동 파싱
+- ⏰ **만료 시간 관리**: 기본 만료 시간 설정 및 개별 키별 만료 시간 설정 지원
+- 🛡️ **타입 안정성**: TypeScript 제네릭을 통한 완전한 타입 지원
+- 🔌 **자동 연결 관리**: Redis 연결을 자동으로 초기화하고 관리
+- 📦 **간단한 API**: 직관적이고 사용하기 쉬운 메서드 제공
+
+## 설치
+
+```bash
+npm install redis-wizard
+```
+
+## 환경 변수 설정
+
+Redis 연결을 위해 다음 환경 변수를 설정하세요:
+
+```bash
+# Redis URL (필수)
+REDIS_URL=redis://localhost:6379
+
+# 또는 Redis 포트만 지정 (기본 호스트: localhost)
+REDIS_PORT=6379
+
+# 연결 풀 설정 (선택사항)
+REDIS_CONNECT_TIMEOUT=10000
+REDIS_KEEP_ALIVE=true
+REDIS_KEEP_ALIVE_DELAY=0
+REDIS_LAZY_CONNECT=false
+REDIS_MAX_RETRIES=10
+```
+
+## 사용 예제
+
+### 기본 사용법
+
+```typescript
+import { createRedis } from 'redis-wizard';
+
+// 타입 정의
+interface Application {
+  id: string;
+  title: string;
+  status: 'draft' | 'published';
+  createdAt: Date;
+}
+
+// Redis Wizard 인스턴스 생성
+const redis = createRedis<Application>({
+  table: "draft:applications",
+  cacheExpired: 3600, // 기본 만료 시간: 1시간
+});
+
+// 데이터 생성
+await redis.create("app-123", {
+  id: "app-123",
+  title: "My Application",
+  status: "draft",
+  createdAt: new Date(),
+});
+
+// 데이터 조회
+const app = await redis.read("app-123");
+console.log(app); // { id: "app-123", title: "My Application", ... }
+
+// 데이터 부분 업데이트
+const updated = await redis.update("app-123", {
+  status: "published"
+});
+console.log(updated); // 업데이트된 전체 객체
+
+// 키 존재 여부 확인
+const exists = await redis.exists("app-123");
+console.log(exists); // true
+
+// 만료 시간 설정
+await redis.setExpire("app-123", 7200); // 2시간
+
+// 남은 만료 시간 조회
+const ttl = await redis.getTtl("app-123");
+console.log(ttl); // 남은 초 수 (예: 3600)
+
+// 데이터 삭제
+await redis.delete("app-123");
+```
+
+### 개별 만료 시간 설정
+
+```typescript
+// create 시 만료 시간 지정
+await redis.create("app-456", appData, 1800); // 30분
+
+// update 시 만료 시간 지정
+await redis.update("app-456", { status: "published" }, 3600); // 1시간
+```
+
+### 연결 관리
+
+```typescript
+import { disconnect, getRedisClient } from 'redis-wizard';
+
+// Redis 클라이언트 직접 접근 (필요한 경우)
+const client = await getRedisClient();
+
+// 연결 종료
+await disconnect();
+```
+
+## API 문서
+
+### `createRedis<T>(config: RedisWizardConfig): RedisWizard<T>`
+
+Redis Wizard 인스턴스를 생성합니다.
+
+**파라미터:**
+- `config.table` (string, 필수): 테이블/스코프 프리픽스 (예: "draft:applications")
+- `config.cacheExpired` (number, 선택): 기본 캐시 만료 시간(초)
+
+**반환값:** RedisWizard 인스턴스
+
+### `read(key: string): Promise<T | null>`
+
+키에 해당하는 값을 조회합니다.
+
+**파라미터:**
+- `key` (string): 조회할 키 (table 프리픽스는 자동 추가)
+
+**반환값:** 값이 존재하면 파싱된 객체, 없으면 `null`
+
+### `create(key: string, value: T, expireSeconds?: number): Promise<void>`
+
+키-값 쌍을 저장합니다.
+
+**파라미터:**
+- `key` (string): 저장할 키 (table 프리픽스는 자동 추가)
+- `value` (T): 저장할 값 (객체는 자동 직렬화)
+- `expireSeconds` (number, 선택): 만료 시간(초), 지정하지 않으면 `config.cacheExpired` 사용
+
+### `update(key: string, partial: Partial<T>, expireSeconds?: number): Promise<T | null>`
+
+키의 값을 부분 업데이트합니다.
+
+**파라미터:**
+- `key` (string): 업데이트할 키 (table 프리픽스는 자동 추가)
+- `partial` (Partial<T>): 업데이트할 부분 값
+- `expireSeconds` (number, 선택): 만료 시간(초), 지정하지 않으면 `config.cacheExpired` 사용
+
+**반환값:** 업데이트된 값, 키가 존재하지 않으면 `null`
+
+### `delete(key: string): Promise<boolean>`
+
+키를 삭제합니다.
+
+**파라미터:**
+- `key` (string): 삭제할 키 (table 프리픽스는 자동 추가)
+
+**반환값:** 삭제 성공 여부
+
+### `exists(key: string): Promise<boolean>`
+
+키의 존재 여부를 확인합니다.
+
+**파라미터:**
+- `key` (string): 확인할 키 (table 프리픽스는 자동 추가)
+
+**반환값:** 키가 존재하면 `true`
+
+### `setExpire(key: string, seconds?: number): Promise<boolean>`
+
+키의 만료 시간을 설정합니다.
+
+**파라미터:**
+- `key` (string): 만료 시간을 설정할 키 (table 프리픽스는 자동 추가)
+- `seconds` (number, 선택): 만료 시간(초), 지정하지 않으면 `config.cacheExpired` 사용
+
+**반환값:** 설정 성공 여부
+
+### `getTtl(key: string): Promise<number | null>`
+
+키의 남은 만료 시간을 조회합니다.
+
+**파라미터:**
+- `key` (string): 조회할 키 (table 프리픽스는 자동 추가)
+
+**반환값:** 남은 만료 시간(초), 만료 시간이 없으면 `null`
+
+## 키 네이밍 규칙
+
+Redis Wizard는 자동으로 키에 프리픽스를 추가합니다:
+
+```typescript
+const redis = createRedis({
+  table: "draft:applications"
+});
+
+// "app-123" 키는 실제로 "draft:applications:app-123"로 저장됩니다
+await redis.create("app-123", data);
+```
+
+이를 통해 여러 테이블/스코프를 체계적으로 관리할 수 있습니다.
+
+## 개발
+
+```bash
+# 개발 모드 실행
+npm run dev
+
+# 빌드
+npm run build
+
+# 배포 (빌드 + 버전 업데이트 + 패키지 설정)
+npm run deploy
+```
+
+## 라이선스
+
+MIT
+
+## 작성자
+
+park-minhyeong

package/index.d.ts

@@ -10,7 +10,7 @@ export interface RedisWizardConfig {
 /**
  * Redis Wizard 인스턴스 인터페이스
  */
-export interface RedisWizard<T = any> {
+export interface RedisWizard<T = any, AutoSetKeys extends keyof T = never> {
     /**
      * 키에 해당하는 값을 조회합니다.
      * @param key - 조회할 키 (table 프리픽스는 자동 추가)
@@ -20,10 +20,10 @@ export interface RedisWizard<T = any> {
     /**
      * 키-값 쌍을 저장합니다.
      * @param key - 저장할 키 (table 프리픽스는 자동 추가)
-     * @param value - 저장할 값 (객체는 자동 직렬화)
+     * @param value - 저장할 값 (객체는 자동 직렬화, AutoSetKeys는 제외됨)
      * @param expireSeconds - 만료 시간(초), 지정하지 않으면 config.cacheExpired 사용
      */
-    create(key: string, value: T, expireSeconds?: number): Promise<void>;
+    create(key: string, value: Omit<T, AutoSetKeys>, expireSeconds?: number): Promise<void>;
     /**
      * 키의 값을 부분 업데이트합니다.
      * @param key - 업데이트할 키 (table 프리픽스는 자동 추가)
@@ -69,12 +69,19 @@ export interface RedisWizard<T = any> {
  *   status: 'draft' | 'published';
  * }
  *
+ * // AutoSetKeys 없이 사용
  * const redis = createRedis<Application>({
  *   table: "draft:applications",
  *   cacheExpired: 10000,
  * });
  *
- * await redis.create("app-123", { id: "app-123", title: "My App", status: "draft" });
+ * // AutoSetKeys 지정 (id는 자동 설정되므로 create에서 제외)
+ * const redis = createRedis<Application, "id">({
+ *   table: "draft:applications",
+ *   cacheExpired: 10000,
+ * });
+ *
+ * await redis.create("app-123", { title: "My App", status: "draft" }); // id 제외
  * const app = await redis.read("app-123");
  * await redis.update("app-123", { status: "published" });
  * await redis.delete("app-123");
@@ -83,6 +90,6 @@ export interface RedisWizard<T = any> {
  * @param config - Redis Wizard 설정
  * @returns Redis Wizard 인스턴스
  */
-export declare function createRedis<T = any>(config: RedisWizardConfig): RedisWizard<T>;
+export declare function createRedis<T = any, AutoSetKeys extends keyof T = never>(config: RedisWizardConfig): RedisWizard<T, AutoSetKeys>;
 export { disconnect } from "./services/config";
 export { getRedisClient } from "./services/config";

package/index.js

@@ -20,12 +20,19 @@ const getTtl_1 = require("./services/getTtl");
  *   status: 'draft' | 'published';
  * }
  *
+ * // AutoSetKeys 없이 사용
  * const redis = createRedis<Application>({
  *   table: "draft:applications",
  *   cacheExpired: 10000,
  * });
  *
- * await redis.create("app-123", { id: "app-123", title: "My App", status: "draft" });
+ * // AutoSetKeys 지정 (id는 자동 설정되므로 create에서 제외)
+ * const redis = createRedis<Application, "id">({
+ *   table: "draft:applications",
+ *   cacheExpired: 10000,
+ * });
+ *
+ * await redis.create("app-123", { title: "My App", status: "draft" }); // id 제외
  * const app = await redis.read("app-123");
  * await redis.update("app-123", { status: "published" });
  * await redis.delete("app-123");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "redis-wizard",
   "description": "A modern TypeScript-based Redis database utility package that provides an enhanced wrapper around the redis library, offering simplified database operations with elegant chainable queries.",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "main": "index.js",
   "scripts": {},
   "author": "park-minhyeong",

package/services/config.js

@@ -48,11 +48,11 @@ const initializeRedis = async (poolConfig) => {
     const redisUrl = process.env.REDIS_PORT ? `redis://localhost:${process.env.REDIS_PORT}` : process.env.REDIS_URL;
     if (!redisUrl) {
         const error = new Error("Redis configuration error: REDIS_URL or REDIS_PORT environment variable is not set");
-        console.error("[Redis Config] Initialization failed:", error.message);
+        console.error("[Redis Wizard] Initialization failed:", error.message);
         throw error;
     }
     if (redisClient && isConnected) {
-        console.log("[Redis Config] Client already connected, skipping initialization");
+        console.log("[Redis Wizard] Client already connected, skipping initialization");
         return;
     }
     // 환경 변수에서 연결 풀 설정 읽기
@@ -93,7 +93,7 @@ const initializeRedis = async (poolConfig) => {
         ...(finalPoolConfig.lazyConnect !== undefined && { lazyConnect: finalPoolConfig.lazyConnect }),
         ...(finalPoolConfig.maxRetriesPerRequest !== undefined && { maxRetriesPerRequest: finalPoolConfig.maxRetriesPerRequest }),
     };
-    console.log(`[Redis Config] Initializing Redis client with URL: ${redisUrl.replace(/:[^:@]+@/, ":****@")}`, {
+    console.log(`[Redis Wizard] Initializing Redis client with URL: ${redisUrl.replace(/:[^:@]+@/, ":****@")}`, {
         poolConfig: {
             connectTimeout: finalPoolConfig.connectTimeout,
             keepAlive: finalPoolConfig.keepAlive,
@@ -104,7 +104,7 @@ const initializeRedis = async (poolConfig) => {
     });
     redisClient = (0, redis_1.createClient)(clientOptions);
     redisClient.on("error", (err) => {
-        console.error("[Redis Config] Connection error occurred:", {
+        console.error("[Redis Wizard] Connection error occurred:", {
             message: err.message,
             stack: err.stack,
             timestamp: new Date().toISOString(),
@@ -112,34 +112,31 @@ const initializeRedis = async (poolConfig) => {
         isConnected = false;
     });
     redisClient.on("connect", () => {
-        console.log("[Redis Config] Connecting to Redis server...");
+        console.log("[Redis Wizard] Connecting to Redis server...");
     });
     redisClient.on("ready", () => {
-        console.log("[Redis Config] Redis client connected and ready", {
-            url: redisUrl.replace(/:[^:@]+@/, ":****@"),
-            timestamp: new Date().toISOString(),
-        });
+        console.log("[Redis Wizard] Redis client connected and ready at url: " + redisUrl);
         isConnected = true;
     });
     redisClient.on("reconnecting", () => {
-        console.warn("[Redis Config] Attempting to reconnect to Redis server...", {
+        console.warn("[Redis Wizard] Attempting to reconnect to Redis server...", {
             timestamp: new Date().toISOString(),
         });
         isConnected = false;
     });
     redisClient.on("end", () => {
-        console.log("[Redis Config] Redis connection ended", {
+        console.log("[Redis Wizard] Redis connection ended", {
             timestamp: new Date().toISOString(),
         });
         isConnected = false;
     });
     try {
-        console.log("[Redis Config] Establishing connection...");
+        console.log("[Redis Wizard] Establishing connection...");
         await redisClient.connect();
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error("[Redis Config] Failed to connect to Redis:", {
+        console.error("[Redis Wizard] Failed to connect to Redis:", {
             message: errorMessage,
             url: redisUrl.replace(/:[^:@]+@/, ":****@"),
             timestamp: new Date().toISOString(),
@@ -157,12 +154,12 @@ const initializeRedis = async (poolConfig) => {
  */
 const getRedisClient = async (poolConfig) => {
     if (!redisClient || !isConnected) {
-        console.log("[Redis Config] Client not available, initializing...");
+        console.log("[Redis Wizard] Client not available, initializing...");
         await initializeRedis(poolConfig);
     }
     if (!redisClient) {
         const error = new Error("Redis client initialization failed: client is null after initialization attempt");
-        console.error("[Redis Config]", error.message);
+        console.error("[Redis Wizard]", error.message);
         throw error;
     }
     return redisClient;
@@ -177,7 +174,7 @@ exports.getRedisClient = getRedisClient;
  */
 const configurePool = async (poolConfig) => {
     if (redisClient && isConnected) {
-        console.warn("[Redis Config] Pool configuration change requires reconnection. Disconnecting current client...");
+        console.warn("[Redis Wizard] Pool configuration change requires reconnection. Disconnecting current client...");
         await (0, exports.disconnect)();
     }
     await initializeRedis(poolConfig);
@@ -190,15 +187,15 @@ exports.configurePool = configurePool;
  */
 const disconnect = async () => {
     if (redisClient && isConnected) {
-        console.log("[Redis Config] Disconnecting Redis client...");
+        console.log("[Redis Wizard] Disconnecting Redis client...");
         try {
             await redisClient.quit();
-            console.log("[Redis Config] Redis client disconnected successfully", {
+            console.log("[Redis Wizard] Redis client disconnected successfully", {
                 timestamp: new Date().toISOString(),
             });
         }
         catch (error) {
-            console.error("[Redis Config] Error during disconnection:", {
+            console.error("[Redis Wizard] Error during disconnection:", {
                 message: error instanceof Error ? error.message : String(error),
                 timestamp: new Date().toISOString(),
             });
@@ -208,13 +205,13 @@ const disconnect = async () => {
         redisClient = null;
     }
     else {
-        console.log("[Redis Config] No active connection to disconnect");
+        console.log("[Redis Wizard] No active connection to disconnect");
     }
 };
 exports.disconnect = disconnect;
 // 애플리케이션 시작 시 Redis 연결 초기화
 initializeRedis().catch((error) => {
-    console.error("[Redis Config] Failed to initialize Redis on application startup:", {
+    console.error("[Redis Wizard] Failed to initialize Redis on application startup:", {
         message: error instanceof Error ? error.message : String(error),
         stack: error instanceof Error ? error.stack : undefined,
         timestamp: new Date().toISOString(),

package/version.txt

@@ -1 +1 @@
-0.0.1
+0.0.3