nest-cache-redis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Istiak Ahmed Tashrif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,744 @@
+# nest-cache-redis
+
+[![npm version](https://badge.fury.io/js/nest-cache-redis.svg)](https://www.npmjs.com/package/nest-cache-redis)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+
+A simplified, high-performance NestJS Redis cache module using ioredis with fire-and-forget support and debug logging.
+
+## Features
+
+✨ **Simple API** - Clean methods: `get`, `set`, `getOrSet`, `delKey`, `delKeys`, `delPattern`, `delPatterns`, `getKeysByPattern`, `reset`, `getStats`  
+🚀 **Fire and Forget Mode** - Optional non-blocking cache operations (global + method-level override)  
+🌍 **Global Module** - Register as global module by default (configurable)  
+🐛 **Debug Logging** - Built-in debug mode for cache operations  
+⚡ **SCAN instead of KEYS** - Non-blocking pattern deletion  
+⏱️ **TTL in Seconds** - Uses Redis `EX` command for better compatibility  
+🔧 **Full ioredis Config** - Access all ioredis configuration options  
+� **Cache Statistics** - Monitor cache performance with built-in stats  
+📦� **TypeScript First** - Full type safety and autocomplete
+
+## Installation
+
+```bash
+# npm will automatically install peer dependencies (npm 7+)
+npm install nest-cache-redis
+```
+
+**Note:** This package has the following peer dependencies that will be automatically installed with npm 7+:
+- `ioredis` (^5.0.0)
+- `@nestjs/common` (^9.0.0 || ^10.0.0 || ^11.0.0)
+- `reflect-metadata` (^0.1.13 || ^0.2.0)
+- `rxjs` (^7.0.0)
+
+## Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { Module } from "@nestjs/common";
+import { RedisCacheModule } from "nest-cache-redis";
+
+@Module({
+  imports: [
+    RedisCacheModule.forRoot({
+      redisOptions: {
+        host: "localhost",
+        port: 6379,
+        password: "your-password", // optional
+      },
+      ttl: 3600, // Default TTL in seconds (optional)
+      fireAndForget: false, // Set to true for non-blocking operations
+      debug: false, // Set to true to enable debug logging
+      isGlobal: true, // Register as global module (default: true)
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Use the Service
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { RedisCacheService } from "nest-cache-redis";
+
+@Injectable()
+export class UserService {
+  constructor(private readonly cache: RedisCacheService) {}
+
+  async getUser(id: string) {
+    // Try to get from cache, or compute and cache
+    return this.cache.getOrSet(
+      `user:${id}`,
+      async () => {
+        // This function only runs if cache misses
+        const user = await this.db.findUser(id);
+        return user;
+      },
+      3600 // TTL in seconds
+    );
+  }
+
+  async updateUser(id: string, data: any) {
+    await this.db.updateUser(id, data);
+
+    // Invalidate cache
+    await this.cache.delKey(`user:${id}`);
+  }
+}
+```
+
+## API Reference
+
+### Configuration Options
+
+```typescript
+interface RedisCacheModuleOptions {
+  redisOptions?: RedisOptions; // All ioredis options
+  ttl?: number; // Default TTL in seconds
+  fireAndForget?: boolean; // Non-blocking mode (default: false)
+  debug?: boolean; // Enable debug logs (default: false)
+  isGlobal?: boolean; // Register as global module (default: true)
+}
+```
+
+### Methods
+
+#### `get<T>(key: string): Promise<T | null>`
+
+Get a value from cache.
+
+```typescript
+const user = await cache.get<User>("user:123");
+if (user) {
+  console.log("Cache hit!", user);
+}
+```
+
+#### `set<T>(key: string, value: T, ttl?: number, options?: { fireAndForget?: boolean }): Promise<void>`
+
+Set a value in cache with optional TTL (in seconds). Optionally override global fireAndForget setting.
+
+```typescript
+await cache.set("user:123", { name: "John" }, 3600);
+
+// Override fireAndForget for this operation
+await cache.set("analytics:view", data, 60, { fireAndForget: true });
+```
+
+#### `getOrSet<T>(key: string, fn: () => Promise<T> | T, ttl?: number): Promise<T>`
+
+Get from cache or compute and cache the result.
+
+```typescript
+const user = await cache.getOrSet(
+  "user:123",
+  async () => await fetchUserFromDB(123),
+  3600
+);
+```
+
+#### `delKey(key: string, options?: { fireAndForget?: boolean }): Promise<number>`
+
+Delete a single key. Returns the number of keys deleted. Optionally override global fireAndForget setting.
+
+```typescript
+const deleted = await cache.delKey("user:123");
+console.log(`Deleted ${deleted} key(s)`);
+
+// Override fireAndForget for this operation
+await cache.delKey("temp:data", { fireAndForget: true });
+```
+
+#### `delKeys(keys: string[], options?: { fireAndForget?: boolean }): Promise<number>`
+
+Delete multiple keys at once. Optionally override global fireAndForget setting.
+
+```typescript
+await cache.delKeys(["user:1", "user:2", "user:3"]);
+
+// Fire and forget
+await cache.delKeys(["temp:1", "temp:2"], { fireAndForget: true });
+```
+
+#### `delPattern(pattern: string): Promise<number>`
+
+Delete all keys matching a pattern using SCAN (non-blocking).
+
+**Automatically handles `keyPrefix`:** If you configured a `keyPrefix` in Redis options (e.g., `keyPrefix: 'myapp:'`), the package automatically adds it when scanning and removes it when deleting. You don't need to include the prefix in your pattern!
+
+```typescript
+// If keyPrefix is 'myapp:', this automatically scans for 'myapp:user:*'
+await cache.delPattern("user:*");
+
+// Delete specific pattern
+await cache.delPattern("session:2024:*");
+
+// With keyPrefix 'myapp:', actual Redis keys: 'myapp:session:2024:*'
+// But you just pass the pattern without prefix!
+```
+
+#### `delPatterns(patterns: string[]): Promise<number>`
+
+Delete multiple patterns efficiently.
+
+```typescript
+await cache.delPatterns(["user:*", "session:*", "temp:*"]);
+// Each pattern automatically gets the keyPrefix if configured
+```
+
+#### `reset(options?: { fireAndForget?: boolean }): Promise<void>`
+
+Clear all cache (flushdb). Optionally override global fireAndForget setting.
+
+```typescript
+await cache.reset(); // ⚠️ Use with caution!
+
+// Fire and forget
+await cache.reset({ fireAndForget: true });
+```
+
+#### `getKeysByPattern(pattern: string): Promise<string[]>`
+
+Get all keys matching a pattern using SCAN (non-blocking). Returns keys without the prefix.
+
+**Automatically handles `keyPrefix`:** Just like `delPattern`, this method automatically adds the keyPrefix when scanning and removes it from the returned keys.
+
+```typescript
+// Get all user keys (automatically handles keyPrefix)
+const userKeys = await cache.getKeysByPattern("user:*");
+console.log(userKeys); // ['user:1', 'user:2', 'user:3']
+// Note: No prefix in returned keys, even if keyPrefix is configured!
+
+// Get session keys for specific date
+const sessionKeys = await cache.getKeysByPattern("session:2024-12:*");
+
+// Useful for debugging or monitoring
+const allKeys = await cache.getKeysByPattern("*");
+console.log(`Total keys: ${allKeys.length}`);
+```
+
+#### `getStats(): Promise<CacheStats>`
+
+Get Redis cache statistics including key count, memory usage, and connection status.
+
+```typescript
+const stats = await cache.getStats();
+console.log(stats);
+// {
+//   connected: true,
+//   keyCount: 1250,
+//   memoryUsed: '2.5M',
+//   memoryPeak: '3.1M',
+//   memoryFragmentationRatio: '1.05'
+// }
+```
+
+#### `getClient(): Redis`
+
+Get the underlying ioredis client for advanced operations.
+
+```typescript
+const client = cache.getClient();
+await client.ping(); // Direct ioredis access
+```
+
+## Advanced Configuration
+
+### Async Configuration
+
+```typescript
+import { RedisCacheModule } from "nest-cache-redis";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+
+@Module({
+  imports: [
+    RedisCacheModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        redisOptions: {
+          host: configService.get("REDIS_HOST"),
+          port: configService.get("REDIS_PORT"),
+          password: configService.get("REDIS_PASSWORD"),
+          db: configService.get("REDIS_DB", 0),
+          keyPrefix: "myapp:", // Add prefix to all keys
+          retryStrategy: (times) => Math.min(times * 50, 2000),
+        },
+        ttl: 3600,
+        fireAndForget: false,
+        debug: configService.get("NODE_ENV") === "development",
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Global vs Non-Global Module
+
+By default, the module is registered as **global** (available everywhere without re-importing). You can change this:
+
+```typescript
+// Global (default) - available in all modules
+RedisCacheModule.forRoot({
+  isGlobal: true, // default
+  redisOptions: {
+    /* ... */
+  },
+});
+
+// Non-global - must import in each module that needs it
+RedisCacheModule.forRoot({
+  isGlobal: false,
+  redisOptions: {
+    /* ... */
+  },
+});
+```
+
+### Full ioredis Configuration
+
+All ioredis options are supported:
+
+```typescript
+RedisCacheModule.forRoot({
+  redisOptions: {
+    host: "localhost",
+    port: 6379,
+    password: "secret",
+    db: 0,
+    keyPrefix: "myapp:",
+
+    // Connection
+    connectTimeout: 10000,
+    lazyConnect: false,
+    keepAlive: 30000,
+
+    // Retry
+    retryStrategy: (times) => Math.min(times * 100, 3000),
+    maxRetriesPerRequest: 3,
+
+    // TLS
+    tls: {
+      ca: fs.readFileSync("ca.crt"),
+    },
+
+    // Sentinel
+    sentinels: [
+      { host: "sentinel1", port: 26379 },
+      { host: "sentinel2", port: 26379 },
+    ],
+    name: "mymaster",
+  },
+  ttl: 3600,
+  debug: true,
+});
+```
+
+## Fire and Forget Mode
+
+When `fireAndForget: true`, cache operations don't wait for Redis responses:
+
+```typescript
+RedisCacheModule.forRoot({
+  fireAndForget: true, // Global non-blocking mode
+  redisOptions: { host: "localhost", port: 6379 },
+});
+
+// This returns immediately without waiting for Redis
+await cache.set("key", "value"); // Fires and forgets
+
+// Note: get() always waits for response
+const value = await cache.get("key"); // Always waits
+```
+
+### Method-Level Override
+
+You can override the global `fireAndForget` setting for individual operations:
+
+```typescript
+// Global setting: fireAndForget = false (wait for responses)
+RedisCacheModule.forRoot({
+  fireAndForget: false,
+  redisOptions: {
+    /* ... */
+  },
+});
+
+// In your service:
+// Wait for this operation (uses global setting)
+await cache.set("important:data", value, 3600);
+
+// Fire and forget for this specific operation
+await cache.set("analytics:event", data, 60, { fireAndForget: true });
+
+// Same for delete operations
+await cache.delKey("temp:data", { fireAndForget: true });
+await cache.delKeys(["temp:1", "temp:2"], { fireAndForget: true });
+await cache.reset({ fireAndForget: true });
+```
+
+**Use cases:**
+
+- High-throughput applications
+- When cache failures shouldn't block requests
+- Fire-and-forget cache warming
+- Analytics/logging that doesn't need confirmation
+- Temporary data that can be lost
+
+## Debug Mode
+
+Enable debug logging to see all cache operations:
+
+```typescript
+RedisCacheModule.forRoot({
+  debug: true,
+  redisOptions: { host: "localhost", port: 6379 },
+});
+```
+
+**Example debug output:**
+
+```
+[RedisCacheService] DEBUG GET key: user:123 - HIT
+[RedisCacheService] DEBUG SET key: user:456, ttl: 3600s
+[RedisCacheService] DEBUG DEL pattern: session:* - deleted 25 keys
+[RedisCacheService] DEBUG GETORSET key: user:789
+[RedisCacheService] DEBUG GETORSET key: user:789 - computing value
+[RedisCacheService] DEBUG SET key: user:789, ttl: 3600s
+```
+
+## Examples
+
+### Cache User Data
+
+```typescript
+@Injectable()
+export class UserService {
+  constructor(private cache: RedisCacheService) {}
+
+  async findOne(id: string): Promise<User> {
+    return this.cache.getOrSet(
+      `user:${id}`,
+      () => this.userRepository.findOne(id),
+      3600 // 1 hour
+    );
+  }
+
+  async update(id: string, data: UpdateUserDto): Promise<User> {
+    const user = await this.userRepository.update(id, data);
+
+    // Invalidate cache
+    await this.cache.delKey(`user:${id}`);
+
+    return user;
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.userRepository.delete(id);
+    await this.cache.delKey(`user:${id}`);
+  }
+}
+```
+
+### Cache API Responses
+
+```typescript
+@Injectable()
+export class ApiService {
+  constructor(private cache: RedisCacheService) {}
+
+  async fetchData(endpoint: string): Promise<any> {
+    const cacheKey = `api:${endpoint}`;
+
+    return this.cache.getOrSet(
+      cacheKey,
+      async () => {
+        const response = await fetch(endpoint);
+        return response.json();
+      },
+      300 // 5 minutes
+    );
+  }
+}
+```
+
+### Batch Invalidation
+
+```typescript
+@Injectable()
+export class CacheService {
+  constructor(private cache: RedisCacheService) {}
+
+  async clearUserCache(userId: string): Promise<void> {
+    // Clear all user-related cache
+    await this.cache.delPatterns([
+      `user:${userId}:*`,
+      `profile:${userId}:*`,
+      `permissions:${userId}:*`,
+    ]);
+  }
+
+  async clearAllSessions(): Promise<void> {
+    const deleted = await this.cache.delPattern("session:*");
+    console.log(`Cleared ${deleted} sessions`);
+  }
+}
+```
+
+### Session Management
+
+```typescript
+@Injectable()
+export class SessionService {
+  constructor(private cache: RedisCacheService) {}
+
+  async createSession(userId: string, data: any): Promise<string> {
+    const sessionId = generateId();
+    const key = `session:${sessionId}`;
+
+    await this.cache.set(key, { userId, ...data }, 86400); // 24 hours
+
+    return sessionId;
+  }
+
+  async getSession(sessionId: string): Promise<any> {
+    return this.cache.get(`session:${sessionId}`);
+  }
+
+  async destroySession(sessionId: string): Promise<void> {
+    await this.cache.delKey(`session:${sessionId}`);
+  }
+
+  async destroyUserSessions(userId: string): Promise<number> {
+    // Find and delete all sessions for user
+    return this.cache.delPattern(`session:*:${userId}`);
+  }
+}
+```
+
+### Monitor Cache Performance
+
+```typescript
+@Injectable()
+export class MonitoringService {
+  constructor(private cache: RedisCacheService) {}
+
+  async getCacheHealth(): Promise<any> {
+    const stats = await this.cache.getStats();
+
+    return {
+      status: stats.connected ? "healthy" : "unhealthy",
+      metrics: {
+        totalKeys: stats.keyCount,
+        memoryUsed: stats.memoryUsed,
+        memoryPeak: stats.memoryPeak,
+        fragmentationRatio: stats.memoryFragmentationRatio,
+      },
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  async checkCacheLimit(): Promise<void> {
+    const stats = await this.cache.getStats();
+
+    if (stats.keyCount > 10000) {
+      this.logger.warn(`Cache has ${stats.keyCount} keys - consider cleanup`);
+    }
+
+    // Parse memory (e.g., "2.5M" -> 2.5)
+    const memoryMB = parseFloat(stats.memoryUsed);
+    if (memoryMB > 100) {
+      this.logger.warn(
+        `Cache using ${stats.memoryUsed} - consider optimization`
+      );
+    }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Use Consistent Key Patterns
+
+```typescript
+// Good: namespace:entity:id
+user:123
+user:123:profile
+user:123:permissions
+session:abc123
+product:456
+
+// Makes pattern deletion easier
+await cache.delPattern('user:123:*');
+```
+
+### 2. Set Appropriate TTLs
+
+```typescript
+// Short-lived data
+await cache.set("rate-limit:user:123", count, 60); // 1 minute
+
+// Medium-lived data
+await cache.set("user:123", user, 3600); // 1 hour
+
+// Long-lived data
+await cache.set("config:app", config, 86400); // 24 hours
+```
+
+### 3. Handle Cache Misses Gracefully
+
+```typescript
+async getUser(id: string): Promise<User | null> {
+  try {
+    return await this.cache.getOrSet(
+      `user:${id}`,
+      () => this.db.findUser(id),
+      3600
+    );
+  } catch (error) {
+    // Log error but don't fail request
+    this.logger.error('Cache error:', error);
+    return this.db.findUser(id); // Fallback to DB
+  }
+}
+```
+
+### 4. Use Fire-and-Forget for Non-Critical Cache
+
+```typescript
+// Configure fire-and-forget for specific module
+@Module({
+  imports: [
+    RedisCacheModule.register({
+      fireAndForget: true, // Don't block on cache writes
+      redisOptions: {
+        /* ... */
+      },
+    }),
+  ],
+})
+export class AnalyticsModule {}
+```
+
+## TypeScript Support
+
+Full TypeScript support with generics:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// Type-safe cache operations
+const user = await cache.get<User>("user:123");
+if (user) {
+  console.log(user.name); // TypeScript knows this is a string
+}
+
+await cache.set<User>("user:123", {
+  id: "123",
+  name: "John",
+  email: "john@example.com",
+});
+
+const users = await cache.get<User[]>("users:active");
+```
+
+## Testing
+
+Mock the cache service in tests:
+
+```typescript
+import { Test } from "@nestjs/testing";
+import { RedisCacheService } from "nest-cache-redis";
+
+describe("UserService", () => {
+  let service: UserService;
+  let cache: RedisCacheService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        UserService,
+        {
+          provide: RedisCacheService,
+          useValue: {
+            get: jest.fn(),
+            set: jest.fn(),
+            getOrSet: jest.fn(),
+            delKey: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UserService>(UserService);
+    cache = module.get<RedisCacheService>(RedisCacheService);
+  });
+
+  it("should get user from cache", async () => {
+    const mockUser = { id: "123", name: "John" };
+    jest.spyOn(cache, "get").mockResolvedValue(mockUser);
+
+    const result = await service.getUser("123");
+
+    expect(cache.get).toHaveBeenCalledWith("user:123");
+    expect(result).toEqual(mockUser);
+  });
+});
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+Enable debug mode to see connection logs:
+
+```typescript
+RedisCacheModule.register({
+  debug: true,
+  redisOptions: {
+    host: "localhost",
+    port: 6379,
+    retryStrategy: (times) => {
+      console.log(`Retry attempt ${times}`);
+      return Math.min(times * 100, 3000);
+    },
+  },
+});
+```
+
+### Memory Issues
+
+Monitor Redis memory and set maxmemory policy:
+
+```bash
+# In redis.conf
+maxmemory 2gb
+maxmemory-policy allkeys-lru
+```
+
+### Performance Issues
+
+- Use `fireAndForget: true` for high-throughput scenarios
+- Use `delPattern()` instead of multiple `delKey()` calls
+- Batch operations with `delKeys()` instead of individual deletes
+- Set appropriate TTLs to prevent memory bloat
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## Support
+
+- GitHub Issues: [Report a bug](https://github.com/Istiak-A-Tashrif/nest-cache-redis/issues)
+- Documentation: [Full docs](https://github.com/Istiak-A-Tashrif/nest-cache-redis#readme)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './redis-cache.module';
+export * from './redis-cache.service';
+export * from './redis-cache.interface';
+export * from './redis-cache.constants';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./redis-cache.module"), exports);
+__exportStar(require("./redis-cache.service"), exports);
+__exportStar(require("./redis-cache.interface"), exports);
+__exportStar(require("./redis-cache.constants"), exports);

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

@@ -0,0 +1 @@
+export declare const REDIS_CACHE_OPTIONS = "REDIS_CACHE_OPTIONS";

package/dist/redis-cache.constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDIS_CACHE_OPTIONS = void 0;
+exports.REDIS_CACHE_OPTIONS = 'REDIS_CACHE_OPTIONS';

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

@@ -0,0 +1,22 @@
+import { ModuleMetadata, Type } from '@nestjs/common';
+import { RedisOptions } from 'ioredis';
+export interface CacheOperationOptions {
+    fireAndForget?: boolean;
+}
+export interface RedisCacheModuleOptions {
+    redisOptions?: RedisOptions;
+    ttl?: number;
+    fireAndForget?: boolean;
+    debug?: boolean;
+    isGlobal?: boolean;
+}
+export interface RedisCacheModuleOptionsFactory {
+    createRedisCacheOptions(): Promise<RedisCacheModuleOptions> | RedisCacheModuleOptions;
+}
+export interface RedisCacheModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useExisting?: Type<RedisCacheModuleOptionsFactory>;
+    useClass?: Type<RedisCacheModuleOptionsFactory>;
+    useFactory?: (...args: any[]) => Promise<RedisCacheModuleOptions> | RedisCacheModuleOptions;
+    inject?: any[];
+    isGlobal?: boolean;
+}

package/dist/redis-cache.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,8 @@
+import { DynamicModule } from '@nestjs/common';
+import { RedisCacheModuleAsyncOptions, RedisCacheModuleOptions } from './redis-cache.interface';
+export declare class RedisCacheModule {
+    static forRoot(options?: RedisCacheModuleOptions): DynamicModule;
+    static forRootAsync(options: RedisCacheModuleAsyncOptions): DynamicModule;
+    private static createAsyncProviders;
+    private static createAsyncOptionsProvider;
+}

package/dist/redis-cache.module.js

@@ -0,0 +1,73 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var RedisCacheModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheModule = void 0;
+const common_1 = require("@nestjs/common");
+const redis_cache_constants_1 = require("./redis-cache.constants");
+const redis_cache_service_1 = require("./redis-cache.service");
+let RedisCacheModule = RedisCacheModule_1 = class RedisCacheModule {
+    static forRoot(options = {}) {
+        const isGlobal = options.isGlobal !== undefined ? options.isGlobal : true;
+        return {
+            global: isGlobal,
+            module: RedisCacheModule_1,
+            providers: [
+                {
+                    provide: redis_cache_constants_1.REDIS_CACHE_OPTIONS,
+                    useValue: options,
+                },
+                redis_cache_service_1.RedisCacheService,
+            ],
+            exports: [redis_cache_service_1.RedisCacheService],
+        };
+    }
+    static forRootAsync(options) {
+        const isGlobal = options.isGlobal !== undefined ? options.isGlobal : true;
+        return {
+            global: isGlobal,
+            module: RedisCacheModule_1,
+            imports: options.imports || [],
+            providers: [
+                ...this.createAsyncProviders(options),
+                redis_cache_service_1.RedisCacheService,
+            ],
+            exports: [redis_cache_service_1.RedisCacheService],
+        };
+    }
+    static createAsyncProviders(options) {
+        if (options.useExisting || options.useFactory) {
+            return [this.createAsyncOptionsProvider(options)];
+        }
+        return [
+            this.createAsyncOptionsProvider(options),
+            {
+                provide: options.useClass,
+                useClass: options.useClass,
+            },
+        ];
+    }
+    static createAsyncOptionsProvider(options) {
+        if (options.useFactory) {
+            return {
+                provide: redis_cache_constants_1.REDIS_CACHE_OPTIONS,
+                useFactory: options.useFactory,
+                inject: options.inject || [],
+            };
+        }
+        return {
+            provide: redis_cache_constants_1.REDIS_CACHE_OPTIONS,
+            useFactory: async (optionsFactory) => await optionsFactory.createRedisCacheOptions(),
+            inject: [options.useExisting || options.useClass],
+        };
+    }
+};
+exports.RedisCacheModule = RedisCacheModule;
+exports.RedisCacheModule = RedisCacheModule = RedisCacheModule_1 = __decorate([
+    (0, common_1.Module)({})
+], RedisCacheModule);

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

@@ -0,0 +1,32 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import Redis from 'ioredis';
+import { RedisCacheModuleOptions, CacheOperationOptions } from './redis-cache.interface';
+export declare class RedisCacheService implements OnModuleDestroy {
+    private readonly options;
+    private readonly logger;
+    private readonly client;
+    private readonly defaultTtl?;
+    private readonly fireAndForget;
+    private readonly debug;
+    constructor(options: RedisCacheModuleOptions);
+    onModuleDestroy(): Promise<void>;
+    get<T = any>(key: string): Promise<T | null>;
+    set<T = any>(key: string, value: T, ttl?: number, options?: CacheOperationOptions): Promise<void>;
+    getOrSet<T = any>(key: string, fn: () => Promise<T> | T, ttl?: number): Promise<T>;
+    delKey(key: string, options?: CacheOperationOptions): Promise<number>;
+    delKeys(keys: string[], options?: CacheOperationOptions): Promise<number>;
+    delPattern(pattern: string): Promise<number>;
+    delPatterns(patterns: string[]): Promise<number>;
+    getKeysByPattern(pattern: string): Promise<string[]>;
+    reset(options?: CacheOperationOptions): Promise<void>;
+    getStats(): Promise<{
+        connected: boolean;
+        keyCount: number;
+        memoryUsed?: string;
+        memoryPeak?: string;
+        memoryFragmentationRatio?: string;
+        error?: string;
+    }>;
+    private parseMemoryInfo;
+    getClient(): Redis;
+}

package/dist/redis-cache.service.js

@@ -0,0 +1,293 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var RedisCacheService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheService = void 0;
+const common_1 = require("@nestjs/common");
+const ioredis_1 = __importDefault(require("ioredis"));
+const redis_cache_constants_1 = require("./redis-cache.constants");
+let RedisCacheService = RedisCacheService_1 = class RedisCacheService {
+    constructor(options) {
+        this.options = options;
+        this.logger = new common_1.Logger(RedisCacheService_1.name);
+        this.client = new ioredis_1.default(options.redisOptions || {});
+        this.defaultTtl = options.ttl;
+        this.fireAndForget = options.fireAndForget || false;
+        this.debug = options.debug || false;
+        this.client.on('error', (err) => {
+            this.logger.error('Redis Client Error', err);
+        });
+        this.client.on('connect', () => {
+            this.logger.log('Redis Client Connected');
+        });
+        this.client.on('reconnecting', () => {
+            this.logger.log('Redis reconnecting');
+        });
+    }
+    async onModuleDestroy() {
+        await this.client.quit();
+    }
+    async get(key) {
+        try {
+            const value = await this.client.get(key);
+            if (value === null) {
+                this.debug && this.logger.debug(`GET key: ${key} - MISS`);
+                return null;
+            }
+            this.debug && this.logger.debug(`GET key: ${key} - HIT`);
+            return JSON.parse(value);
+        }
+        catch (error) {
+            this.logger.error(`Error getting key ${key}:`, error);
+            throw error;
+        }
+    }
+    async set(key, value, ttl, options) {
+        try {
+            const serialized = JSON.stringify(value);
+            const ttlToUse = ttl ?? this.defaultTtl;
+            const useFireAndForget = options?.fireAndForget !== undefined ? options.fireAndForget : this.fireAndForget;
+            this.debug && this.logger.debug(`SET key: ${key}, ttl: ${ttlToUse || 'none'}s`);
+            const operation = ttlToUse
+                ? this.client.set(key, serialized, 'EX', ttlToUse)
+                : this.client.set(key, serialized);
+            if (useFireAndForget) {
+                operation.catch((err) => {
+                    this.logger.error(`Error setting key ${key}:`, err);
+                });
+            }
+            else {
+                await operation;
+            }
+        }
+        catch (error) {
+            this.logger.error(`Error setting key ${key}:`, error);
+            throw error;
+        }
+    }
+    async getOrSet(key, fn, ttl) {
+        try {
+            const value = await this.client.get(key);
+            if (value !== null) {
+                this.debug && this.logger.debug(`GETORSET key: ${key} - HIT`);
+                return JSON.parse(value);
+            }
+            this.debug && this.logger.debug(`GETORSET key: ${key} - computing value`);
+            const result = await fn();
+            await this.set(key, result, ttl);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Error in getOrSet for key ${key}:`, error);
+            throw error;
+        }
+    }
+    async delKey(key, options) {
+        try {
+            const useFireAndForget = options?.fireAndForget !== undefined ? options.fireAndForget : this.fireAndForget;
+            this.debug && this.logger.debug(`DEL key: ${key}`);
+            const operation = this.client.del(key);
+            if (useFireAndForget) {
+                operation.catch((err) => {
+                    this.logger.error(`Error deleting key ${key}:`, err);
+                });
+                return 0;
+            }
+            const result = await operation;
+            this.debug && this.logger.debug(`DEL key: ${key} - deleted: ${result}`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Error deleting key ${key}:`, error);
+            throw error;
+        }
+    }
+    async delKeys(keys, options) {
+        if (keys.length === 0) {
+            return 0;
+        }
+        try {
+            const useFireAndForget = options?.fireAndForget !== undefined ? options.fireAndForget : this.fireAndForget;
+            this.debug && this.logger.debug(`DEL keys: [${keys.join(', ')}] (${keys.length} keys)`);
+            const operation = this.client.del(...keys);
+            if (useFireAndForget) {
+                operation.catch((err) => {
+                    this.logger.error(`Error deleting keys:`, err);
+                });
+                return 0;
+            }
+            const result = await operation;
+            this.debug && this.logger.debug(`DEL keys - deleted: ${result}`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Error deleting keys:`, error);
+            throw error;
+        }
+    }
+    async delPattern(pattern) {
+        try {
+            const keyPrefix = this.client.options.keyPrefix || '';
+            const fullPattern = `${keyPrefix}${pattern}`;
+            let cursor = '0';
+            const allKeys = [];
+            do {
+                const result = await this.client.scan(cursor, 'MATCH', fullPattern, 'COUNT', 100);
+                cursor = result[0];
+                const keys = result[1];
+                if (keys.length > 0) {
+                    const keysWithoutPrefix = keyPrefix
+                        ? keys.map(key => key.replace(keyPrefix, ''))
+                        : keys;
+                    allKeys.push(...keysWithoutPrefix);
+                }
+            } while (cursor !== '0');
+            if (allKeys.length === 0) {
+                this.debug && this.logger.debug(`DEL pattern: ${pattern} - no keys found`);
+                return 0;
+            }
+            const operation = this.client.del(...allKeys);
+            let totalDeleted;
+            if (this.fireAndForget) {
+                operation.catch((err) => {
+                    this.logger.error(`Error deleting pattern ${pattern}:`, err);
+                });
+                totalDeleted = 0;
+            }
+            else {
+                totalDeleted = await operation;
+            }
+            this.debug && this.logger.debug(`DEL pattern: ${pattern} - deleted ${totalDeleted} keys`);
+            return totalDeleted;
+        }
+        catch (error) {
+            this.logger.error(`Error deleting pattern ${pattern}:`, error);
+            throw error;
+        }
+    }
+    async delPatterns(patterns) {
+        if (patterns.length === 0) {
+            return 0;
+        }
+        try {
+            this.debug && this.logger.debug(`DEL patterns: [${patterns.join(', ')}]`);
+            let totalDeleted = 0;
+            for (const pattern of patterns) {
+                const deleted = await this.delPattern(pattern);
+                totalDeleted += deleted;
+            }
+            this.debug && this.logger.debug(`DEL patterns - total deleted: ${totalDeleted}`);
+            return totalDeleted;
+        }
+        catch (error) {
+            this.logger.error(`Error deleting patterns:`, error);
+            throw error;
+        }
+    }
+    async getKeysByPattern(pattern) {
+        try {
+            const keyPrefix = this.client.options.keyPrefix || '';
+            const fullPattern = `${keyPrefix}${pattern}`;
+            let cursor = '0';
+            const allKeys = [];
+            do {
+                const result = await this.client.scan(cursor, 'MATCH', fullPattern, 'COUNT', 100);
+                cursor = result[0];
+                const keys = result[1];
+                if (keys.length > 0) {
+                    const keysWithoutPrefix = keyPrefix
+                        ? keys.map(key => key.replace(keyPrefix, ''))
+                        : keys;
+                    allKeys.push(...keysWithoutPrefix);
+                }
+            } while (cursor !== '0');
+            this.debug && this.logger.debug(`GET keys by pattern: ${pattern} - found ${allKeys.length} keys`);
+            return allKeys;
+        }
+        catch (error) {
+            this.logger.error(`Error getting keys by pattern ${pattern}:`, error);
+            throw error;
+        }
+    }
+    async reset(options) {
+        try {
+            const useFireAndForget = options?.fireAndForget !== undefined ? options.fireAndForget : this.fireAndForget;
+            this.debug && this.logger.debug('RESET - clearing all cache');
+            const operation = this.client.flushdb();
+            if (useFireAndForget) {
+                operation.catch((err) => {
+                    this.logger.error('Error resetting cache:', err);
+                });
+            }
+            else {
+                await operation;
+            }
+            this.debug && this.logger.debug('RESET - cache cleared');
+        }
+        catch (error) {
+            this.logger.error('Error resetting cache:', error);
+            throw error;
+        }
+    }
+    async getStats() {
+        try {
+            const connected = this.client.status === 'ready';
+            if (!connected) {
+                return {
+                    connected: false,
+                    keyCount: 0,
+                    error: 'Redis not connected',
+                };
+            }
+            const keyCount = await this.client.dbsize();
+            const memoryInfo = await this.client.info('memory');
+            const memoryUsed = this.parseMemoryInfo(memoryInfo, 'used_memory_human');
+            const memoryPeak = this.parseMemoryInfo(memoryInfo, 'used_memory_peak_human');
+            const memoryFragmentationRatio = this.parseMemoryInfo(memoryInfo, 'mem_fragmentation_ratio');
+            this.debug && this.logger.debug(`STATS - keys: ${keyCount}, memory: ${memoryUsed}`);
+            return {
+                connected,
+                keyCount,
+                memoryUsed,
+                memoryPeak,
+                memoryFragmentationRatio,
+            };
+        }
+        catch (error) {
+            this.logger.error('Error getting cache stats:', error);
+            return {
+                connected: false,
+                keyCount: 0,
+                error: error.message,
+            };
+        }
+    }
+    parseMemoryInfo(info, key) {
+        const regex = new RegExp(`${key}:(.+)`);
+        const match = info.match(regex);
+        return match ? match[1].trim() : undefined;
+    }
+    getClient() {
+        return this.client;
+    }
+};
+exports.RedisCacheService = RedisCacheService;
+exports.RedisCacheService = RedisCacheService = RedisCacheService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(redis_cache_constants_1.REDIS_CACHE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], RedisCacheService);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "nest-cache-redis",
+  "version": "1.0.0",
+  "description": "A simplified, high-performance NestJS Redis cache module with fire-and-forget support, automatic keyPrefix handling, pattern-based deletion, and TypeScript-first design",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "author": "Istiak Ahmed Tashrif <istiaktashrif@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Istiak-A-Tashrif/nest-cache-redis.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Istiak-A-Tashrif/nest-cache-redis/issues"
+  },
+  "homepage": "https://github.com/Istiak-A-Tashrif/nest-cache-redis/#readme",
+  "keywords": [
+    "nestjs",
+    "redis",
+    "ioredis",
+    "cache",
+    "nest",
+    "caching",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "ioredis": "^5.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@types/node": "^22.10.7",
+    "ioredis": "^5.8.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.7.3"
+  }
+}