@common-stack/store-redis 8.2.5-alpha.33

package/lib/templates/repositories/IRedisService.ts.template

@@ -0,0 +1,236 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IRedisService.ts
+ * @description Defines the IRedisService interface for advanced Redis operations and patterns.
+ * This interface provides high-level Redis operations beyond simple key-value storage,
+ * including pub/sub, streams, sorted sets, and distributed locking.
+ *
+ * The Redis service is designed for:
+ * - Pub/Sub messaging patterns
+ * - Distributed locking (mutex)
+ * - Rate limiting
+ * - Leaderboards and rankings (sorted sets)
+ * - Event streams
+ * - Queue management
+ *
+ * Key features:
+ * - Pub/Sub for real-time messaging
+ * - Distributed locks for resource coordination
+ * - Rate limiting for API throttling
+ * - Sorted sets for rankings and leaderboards
+ * - Redis Streams for event sourcing
+ * - Pipeline operations for performance
+ *
+ * This service layer provides advanced Redis patterns that go beyond simple caching
+ * and storage, enabling sophisticated distributed system architectures.
+ *
+ * @see IRedisCacheManager - For query caching
+ * @see IRedisStorageBackend - For simple key-value storage
+ */
+
+export interface IRedisService {
+    /**
+     * Publish a message to a Redis channel
+     * Part of the Pub/Sub pattern for real-time messaging
+     * 
+     * @param channel - Channel name to publish to
+     * @param message - Message to publish (will be stringified if object)
+     * @returns Promise resolving to number of subscribers that received the message
+     * 
+     * @example
+     * // Publish user update event
+     * await redisService.publish('user:updates', JSON.stringify({
+     *   userId: '123',
+     *   action: 'updated'
+     * }));
+     */
+    publish(channel: string, message: string): Promise<number>;
+
+    /**
+     * Subscribe to a Redis channel
+     * Receives messages published to the channel
+     * 
+     * @param channel - Channel name to subscribe to
+     * @param callback - Function called when message received
+     * @returns Promise that resolves when subscribed
+     * 
+     * @example
+     * // Subscribe to user updates
+     * await redisService.subscribe('user:updates', (message) => {
+     *   const event = JSON.parse(message);
+     *   console.log(`User ${event.userId} was ${event.action}`);
+     * });
+     */
+    subscribe(channel: string, callback: (message: string) => void): Promise<void>;
+
+    /**
+     * Unsubscribe from a Redis channel
+     * 
+     * @param channel - Channel name to unsubscribe from
+     * @returns Promise that resolves when unsubscribed
+     * 
+     * @example
+     * // Unsubscribe from updates
+     * await redisService.unsubscribe('user:updates');
+     */
+    unsubscribe(channel: string): Promise<void>;
+
+    /**
+     * Acquire a distributed lock
+     * Ensures only one process can execute critical section
+     * 
+     * @param key - Lock key (unique identifier for the resource)
+     * @param ttl - Lock TTL in milliseconds (auto-release if process dies)
+     * @param retries - Number of retry attempts
+     * @returns Promise resolving to lock token (needed for release) or null if failed
+     * 
+     * @example
+     * // Acquire lock for order processing
+     * const lock = await redisService.acquireLock('order:123:processing', 5000);
+     * if (lock) {
+     *   try {
+     *     await processOrder('123');
+     *   } finally {
+     *     await redisService.releaseLock('order:123:processing', lock);
+     *   }
+     * }
+     */
+    acquireLock(key: string, ttl: number, retries?: number): Promise<string | null>;
+
+    /**
+     * Release a distributed lock
+     * Only the process that acquired the lock can release it
+     * 
+     * @param key - Lock key
+     * @param token - Lock token returned from acquireLock
+     * @returns Promise resolving to true if lock was released
+     * 
+     * @example
+     * // Release lock after critical section
+     * await redisService.releaseLock('resource:123', lockToken);
+     */
+    releaseLock(key: string, token: string): Promise<boolean>;
+
+    /**
+     * Check rate limit for a key
+     * Implements sliding window rate limiting
+     * 
+     * @param key - Rate limit key (e.g., userId or IP address)
+     * @param limit - Maximum requests allowed
+     * @param window - Time window in seconds
+     * @returns Promise resolving to object with allowed status and remaining count
+     * 
+     * @example
+     * // Check API rate limit
+     * const rateLimitStatus = await redisService.checkRateLimit(
+     *   `api:user:${userId}`,
+     *   100,  // 100 requests
+     *   3600  // per hour
+     * );
+     * 
+     * if (!rateLimitStatus.allowed) {
+     *   throw new Error('Rate limit exceeded');
+     * }
+     */
+    checkRateLimit(
+        key: string,
+        limit: number,
+        window: number
+    ): Promise<{
+        allowed: boolean;
+        remaining: number;
+        resetAt: number;
+    }>;
+
+    /**
+     * Add member to sorted set with score
+     * Useful for leaderboards, rankings, and time-ordered data
+     * 
+     * @param key - Sorted set key
+     * @param score - Score for ordering (lower scores first)
+     * @param member - Member to add
+     * @returns Promise resolving to number of elements added
+     * 
+     * @example
+     * // Add user score to leaderboard
+     * await redisService.sortedSetAdd('leaderboard:game1', 1000, 'user-123');
+     */
+    sortedSetAdd(key: string, score: number, member: string): Promise<number>;
+
+    /**
+     * Get top members from sorted set
+     * 
+     * @param key - Sorted set key
+     * @param start - Start index (0-based)
+     * @param stop - Stop index (-1 for all)
+     * @param withScores - Whether to include scores in result
+     * @returns Promise resolving to array of members (and scores if requested)
+     * 
+     * @example
+     * // Get top 10 players
+     * const topPlayers = await redisService.sortedSetRange(
+     *   'leaderboard:game1',
+     *   0,
+     *   9,
+     *   true
+     * );
+     * // Result: [{member: 'user-1', score: 1500}, {member: 'user-2', score: 1400}, ...]
+     */
+    sortedSetRange(
+        key: string,
+        start: number,
+        stop: number,
+        withScores?: boolean
+    ): Promise<Array<{ member: string; score?: number }>>;
+
+    /**
+     * Get member rank in sorted set
+     * 
+     * @param key - Sorted set key
+     * @param member - Member to get rank for
+     * @returns Promise resolving to rank (0-based) or null if not found
+     * 
+     * @example
+     * // Get user's leaderboard position
+     * const rank = await redisService.sortedSetRank('leaderboard:game1', 'user-123');
+     * console.log(`You are ranked #${rank + 1}`);
+     */
+    sortedSetRank(key: string, member: string): Promise<number | null>;
+
+    /**
+     * Add entry to Redis Stream
+     * Useful for event sourcing and message queues
+     * 
+     * @param key - Stream key
+     * @param fields - Fields to add to stream entry
+     * @returns Promise resolving to entry ID
+     * 
+     * @example
+     * // Add event to stream
+     * const entryId = await redisService.streamAdd('events:user-actions', {
+     *   userId: '123',
+     *   action: 'login',
+     *   timestamp: Date.now().toString()
+     * });
+     */
+    streamAdd(key: string, fields: Record<string, string>): Promise<string>;
+
+    /**
+     * Read entries from Redis Stream
+     * 
+     * @param key - Stream key
+     * @param options - Read options (count, id to start from)
+     * @returns Promise resolving to array of stream entries
+     * 
+     * @example
+     * // Read last 100 events
+     * const events = await redisService.streamRead('events:user-actions', {
+     *   count: 100,
+     *   id: '0' // Start from beginning
+     * });
+     */
+    streamRead(
+        key: string,
+        options?: { count?: number; id?: string }
+    ): Promise<Array<{ id: string; fields: Record<string, string> }>>;
+}

package/lib/templates/repositories/IRedisStorageBackend.ts.template

@@ -0,0 +1,229 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IRedisStorageBackend.ts
+ * @description Defines the IRedisStorageBackend interface for simple key-value storage operations using Redis.
+ * This interface provides a clean abstraction for basic Redis operations, suitable for request-scoped storage,
+ * temporary data, session storage, and other simple caching scenarios.
+ *
+ * The storage backend is designed for:
+ * - Request-scoped temporary data
+ * - Session storage
+ * - Simple key-value caching
+ * - Temporary flags and state
+ *
+ * Unlike RedisCacheManager which is optimized for GraphQL query caching with hashing,
+ * this storage backend provides straightforward get/set/delete operations for simple use cases.
+ *
+ * Key features:
+ * - Simple key-value operations
+ * - TTL support for automatic expiration
+ * - Bulk operations for efficiency
+ * - Clear operations for cleanup
+ * - Type-safe with generics
+ *
+ * @see IRedisCacheManager - For complex caching with GraphQL queries
+ * @see IRedisKeyBuilder - For standardized key generation
+ */
+
+export interface IRedisStorageBackend {
+    /**
+     * Get a value by key
+     * Returns null if key doesn't exist
+     * 
+     * @param key - Redis key to retrieve
+     * @returns Promise resolving to the value or null
+     * 
+     * @example
+     * // Get session data
+     * const sessionData = await storage.get('session:user-123');
+     * if (sessionData) {
+     *   const session = JSON.parse(sessionData);
+     * }
+     */
+    get(key: string): Promise<string | null>;
+
+    /**
+     * Get multiple values by keys
+     * Returns array with same order as keys, null for missing keys
+     * 
+     * @param keys - Array of Redis keys to retrieve
+     * @returns Promise resolving to array of values
+     * 
+     * @example
+     * // Get multiple user preferences
+     * const keys = ['pref:user-1', 'pref:user-2', 'pref:user-3'];
+     * const values = await storage.getMany(keys);
+     */
+    getMany(keys: string[]): Promise<(string | null)[]>;
+
+    /**
+     * Set a value for a key
+     * Optionally specify TTL in seconds
+     * 
+     * @param key - Redis key to set
+     * @param value - Value to store (will be stringified if object)
+     * @param ttl - Optional time-to-live in seconds
+     * @returns Promise that resolves when set is complete
+     * 
+     * @example
+     * // Store session with 1 hour expiration
+     * await storage.set('session:user-123', JSON.stringify(sessionData), 3600);
+     * 
+     * @example
+     * // Store temporary flag
+     * await storage.set('flag:processing', 'true', 300); // 5 minutes
+     */
+    set(key: string, value: string, ttl?: number): Promise<void>;
+
+    /**
+     * Set multiple key-value pairs
+     * Efficiently stores multiple entries in one operation
+     * 
+     * @param entries - Array of key-value pairs to set
+     * @param ttl - Optional TTL to apply to all entries
+     * @returns Promise that resolves when all are set
+     * 
+     * @example
+     * // Set multiple user preferences
+     * await storage.setMany([
+     *   { key: 'pref:theme', value: 'dark' },
+     *   { key: 'pref:lang', value: 'en' }
+     * ], 86400); // 24 hours
+     */
+    setMany(entries: Array<{ key: string; value: string }>, ttl?: number): Promise<void>;
+
+    /**
+     * Delete a value by key
+     * Returns true if key existed and was deleted
+     * 
+     * @param key - Redis key to delete
+     * @returns Promise resolving to deletion success
+     * 
+     * @example
+     * // Delete session on logout
+     * const deleted = await storage.delete('session:user-123');
+     */
+    delete(key: string): Promise<boolean>;
+
+    /**
+     * Delete multiple keys
+     * Returns number of keys that were deleted
+     * 
+     * @param keys - Array of Redis keys to delete
+     * @returns Promise resolving to count of deleted keys
+     * 
+     * @example
+     * // Delete multiple cache entries
+     * const deletedCount = await storage.deleteMany([
+     *   'cache:user-1',
+     *   'cache:user-2'
+     * ]);
+     */
+    deleteMany(keys: string[]): Promise<number>;
+
+    /**
+     * Check if a key exists
+     * 
+     * @param key - Redis key to check
+     * @returns Promise resolving to true if key exists
+     * 
+     * @example
+     * // Check if session exists
+     * const hasSession = await storage.exists('session:user-123');
+     */
+    exists(key: string): Promise<boolean>;
+
+    /**
+     * Get remaining TTL for a key in seconds
+     * Returns -1 if key has no expiration
+     * Returns -2 if key doesn't exist
+     * 
+     * @param key - Redis key to check
+     * @returns Promise resolving to TTL in seconds
+     * 
+     * @example
+     * // Check session expiration
+     * const ttl = await storage.getTTL('session:user-123');
+     * if (ttl < 300) {
+     *   // Session expires in less than 5 minutes
+     * }
+     */
+    getTTL(key: string): Promise<number>;
+
+    /**
+     * Set TTL for an existing key
+     * Updates expiration time without changing the value
+     * 
+     * @param key - Redis key to update
+     * @param ttl - New TTL in seconds
+     * @returns Promise resolving to true if TTL was set
+     * 
+     * @example
+     * // Extend session by 1 hour
+     * await storage.setTTL('session:user-123', 3600);
+     */
+    setTTL(key: string, ttl: number): Promise<boolean>;
+
+    /**
+     * Clear all keys matching a pattern
+     * Uses SCAN to find keys, then deletes them
+     * 
+     * @param pattern - Redis pattern to match (supports wildcards)
+     * @returns Promise resolving to count of deleted keys
+     * 
+     * @example
+     * // Clear all session keys for a tenant
+     * const cleared = await storage.clearPattern('APP:tenant-123:session:*');
+     * 
+     * @example
+     * // Clear all temporary keys
+     * await storage.clearPattern('APP:*:temp:*');
+     */
+    clearPattern(pattern: string): Promise<number>;
+
+    /**
+     * Clear all keys in this storage's namespace
+     * Useful for cleanup operations
+     * 
+     * @returns Promise that resolves when clear is complete
+     * 
+     * @example
+     * // Clear all storage on request end
+     * res.on('finish', async () => {
+     *   await storage.clear();
+     * });
+     */
+    clear(): Promise<void>;
+
+    /**
+     * Increment a numeric value
+     * Creates key with value 0 if it doesn't exist
+     * 
+     * @param key - Redis key to increment
+     * @param amount - Amount to increment by (default: 1)
+     * @returns Promise resolving to new value
+     * 
+     * @example
+     * // Increment counter
+     * const newCount = await storage.increment('counter:requests');
+     * 
+     * @example
+     * // Add to score
+     * const score = await storage.increment('score:user-123', 10);
+     */
+    increment(key: string, amount?: number): Promise<number>;
+
+    /**
+     * Decrement a numeric value
+     * Creates key with value 0 if it doesn't exist
+     * 
+     * @param key - Redis key to decrement
+     * @param amount - Amount to decrement by (default: 1)
+     * @returns Promise resolving to new value
+     * 
+     * @example
+     * // Decrement available slots
+     * const remaining = await storage.decrement('slots:available');
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+}

package/lib/templates/repositories/redisCommonTypes.ts.template

@@ -0,0 +1,189 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file redisCommonTypes.ts
+ * @description Defines common types and interfaces used across the Redis data access layer.
+ * These types provide a standardized approach to working with Redis operations, including
+ * key management, caching, and storage patterns.
+ *
+ * Key components include:
+ * - RedisKeyOptions: Configuration for building standardized Redis keys
+ * - RedisNamespace: Enum for organizing keys into logical namespaces
+ * - CacheContext: Context information for cache operations (tenant, user, org)
+ * - CachePolicy: Configuration for cache TTL and scope
+ * - RedisValue: Union type for values that can be stored in Redis
+ * - RedisHashValue: Type for Redis hash field values
+ * - RedisScanOptions: Options for scanning Redis keys
+ *
+ * These types ensure consistency across Redis operations, providing type safety and
+ * clear contracts for data caching and storage throughout the application.
+ *
+ * @see IRedisCacheManager - Cache manager interface using these types
+ * @see IRedisStorageBackend - Storage backend interface using these types
+ * @see IRedisKeyBuilder - Key builder interface using these types
+ */
+
+/**
+ * Options for building Redis keys with standardized format
+ * 
+ * @property tenantId - Tenant ID for multi-tenant isolation (defaults to 'default')
+ * @property namespace - Namespace to categorize keys (e.g., 'cache', 'session', 'storage')
+ * @property segments - Additional key segments to append
+ * @property userId - Optional user ID for user-specific keys
+ * 
+ * @example
+ * const keyOptions: RedisKeyOptions = {
+ *   tenantId: 'tenant-123',
+ *   namespace: RedisNamespace.CACHE,
+ *   segments: ['user', 'profile']
+ * };
+ * // Produces key: APP_NAME:tenant-123:cache:user:profile
+ */
+export interface RedisKeyOptions {
+    tenantId?: string;
+    namespace: string;
+    segments: string[];
+    userId?: string;
+}
+
+/**
+ * Standard Redis namespaces for organizing keys
+ * Using namespaces helps prevent key collisions and makes bulk operations easier
+ * 
+ * @example
+ * // Use namespaces to organize cache keys
+ * const cacheKey = buildRedisKey({
+ *   tenantId: 'tenant-123',
+ *   namespace: RedisNamespace.CACHE,
+ *   segments: ['query', 'users']
+ * });
+ */
+export enum RedisNamespace {
+    CACHE = 'cache',
+    SESSION = 'session',
+    TENANT = 'tenant',
+    CONFIG = 'config',
+    EXTENSION = 'extension',
+    CONTRIBUTION = 'contribution',
+    STORAGE = 'storage',
+    PERMISSION = 'permission',
+    TEMP = 'temp',
+    QUEUE = 'queue',
+    LOCK = 'lock',
+}
+
+/**
+ * Context for cache operations
+ * Provides tenant, user, and organization isolation for cached data
+ * 
+ * @property tenantId - Tenant identifier for multi-tenant applications
+ * @property userId - User identifier for user-specific caching
+ * @property orgId - Organization identifier for org-level caching
+ * 
+ * @example
+ * const ctx: CacheContext = {
+ *   tenantId: 'tenant-123',
+ *   userId: 'user-456',
+ *   orgId: 'org-789'
+ * };
+ */
+export interface CacheContext {
+    tenantId?: string;
+    userId?: string;
+    orgId?: string;
+}
+
+/**
+ * Cache policy for controlling cache behavior
+ * 
+ * @property maxAge - Maximum age in seconds (TTL)
+ * @property scope - Cache scope (PUBLIC, PRIVATE, etc.)
+ * 
+ * @example
+ * const policy: CachePolicy = {
+ *   maxAge: 3600, // 1 hour
+ *   scope: 'PRIVATE'
+ * };
+ */
+export interface CachePolicy {
+    maxAge: number;
+    scope?: string;
+}
+
+/**
+ * Union type for values that can be stored in Redis
+ * Covers most common data types stored in Redis
+ */
+export type RedisValue = string | number | Buffer | null;
+
+/**
+ * Type for Redis hash field values
+ * Hashes in Redis store field-value pairs
+ */
+export type RedisHashValue = Record<string, string>;
+
+/**
+ * Options for scanning Redis keys
+ * Used for iterating through keys matching a pattern
+ * 
+ * @property match - Pattern to match keys (supports wildcards)
+ * @property count - Number of keys to return per iteration
+ * @property type - Optional Redis data type to filter by
+ * 
+ * @example
+ * const scanOptions: RedisScanOptions = {
+ *   match: 'APP:tenant-*:cache:*',
+ *   count: 100,
+ *   type: 'string'
+ * };
+ */
+export interface RedisScanOptions {
+    match?: string;
+    count?: number;
+    type?: 'string' | 'list' | 'set' | 'zset' | 'hash' | 'stream';
+}
+
+/**
+ * Result from a Redis SCAN operation
+ * 
+ * @property cursor - Next cursor position (0 means scan is complete)
+ * @property keys - Array of keys matching the scan criteria
+ */
+export interface RedisScanResult {
+    cursor: string;
+    keys: string[];
+}
+
+/**
+ * Options for Redis bulk operations
+ * Used when performing operations on multiple keys
+ * 
+ * @property pipeline - Whether to use Redis pipeline for batch operations
+ * @property transaction - Whether to wrap operations in a MULTI/EXEC transaction
+ */
+export interface RedisBulkOptions {
+    pipeline?: boolean;
+    transaction?: boolean;
+}
+
+/**
+ * Redis connection configuration
+ * 
+ * @property host - Redis server host
+ * @property port - Redis server port
+ * @property password - Optional password for authentication
+ * @property db - Database number to use
+ * @property keyPrefix - Prefix to add to all keys
+ * @property maxRetriesPerRequest - Maximum retry attempts
+ * @property enableReadyCheck - Whether to check connection is ready
+ * @property lazyConnect - Whether to delay connection until first command
+ */
+export interface RedisConnectionConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    keyPrefix?: string;
+    maxRetriesPerRequest?: number;
+    enableReadyCheck?: boolean;
+    lazyConnect?: boolean;
+}

package/lib/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Redis utility functions
+ */
+export * from './redis-key-builder';
+export * from './redis-key-sanitizer';

package/lib/utils/redis-key-builder.d.ts

@@ -0,0 +1,32 @@
+import type { RedisKeyOptions } from '../interfaces/redis-key-options';
+/**
+ * Build a standardized Redis key with proper formatting and sanitization
+ *
+ * Format: <APP_NAME>:<tenantId>:<namespace>:<segments...>
+ *
+ * @example
+ * buildRedisKey({
+ *   tenantId: 'tenant-123',
+ *   namespace: RedisNamespace.CACHE,
+ *   segments: ['user', 'profile']
+ * })
+ * // Returns: "APP_NAME:tenant-123:cache:user:profile"
+ */
+export declare function buildRedisKey(options: RedisKeyOptions): string;
+/**
+ * Build a Redis key pattern for wildcard matching
+ *
+ * @example
+ * buildRedisKeyPattern({
+ *   tenantId: 'tenant-123',
+ *   namespace: RedisNamespace.CACHE,
+ *   segments: ['user', '*']
+ * })
+ * // Returns: "APP_NAME:tenant-123:cache:user:*"
+ */
+export declare function buildRedisKeyPattern(options: RedisKeyOptions): string;
+/**
+ * Validate if a string is a valid Redis key
+ * Redis keys can be up to 512MB but should be kept reasonable
+ */
+export declare function isValidRedisKey(key: string): boolean;