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

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

@@ -1,236 +0,0 @@
-/* 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

@@ -1,229 +0,0 @@
-/* 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/utils/index.d.ts

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

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

@@ -1,32 +0,0 @@
-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;

package/lib/utils/redis-key-builder.js

@@ -1,68 +0,0 @@
-import { sanitizeKeyComponent } from './redis-key-sanitizer.js';
-
-/**
- * Get application name from environment or config
- * This will be replaced with actual config import during migration
- */
-const getAppName = () => {
-    return process.env.APP_NAME || 'APP';
-};
-/**
- * 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"
- */
-function buildRedisKey(options) {
-    const { tenantId = 'default', namespace, segments, userId } = options;
-    // Sanitize all components
-    const sanitizedTenantId = sanitizeKeyComponent(tenantId);
-    const sanitizedNamespace = sanitizeKeyComponent(namespace);
-    const sanitizedSegments = segments.map(sanitizeKeyComponent);
-    // Build key parts
-    const parts = [getAppName(), sanitizedTenantId, sanitizedNamespace, ...sanitizedSegments];
-    // Add userId if provided
-    if (userId) {
-        parts.splice(2, 0, sanitizeKeyComponent(userId));
-    }
-    return parts.join(':');
-}
-/**
- * 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:*"
- */
-function buildRedisKeyPattern(options) {
-    // Same as buildRedisKey but allows '*' in segments
-    return buildRedisKey(options);
-}
-/**
- * Validate if a string is a valid Redis key
- * Redis keys can be up to 512MB but should be kept reasonable
- */
-function isValidRedisKey(key) {
-    // Basic validation rules
-    if (!key || key.length === 0)
-        return false;
-    if (key.length > 1024)
-        return false; // Reasonable limit
-    // Check for invalid characters after sanitization
-    // After sanitization, keys should only contain alphanumeric, colons, hyphens, underscores
-    const validPattern = /^[a-zA-Z0-9:_-]+$/;
-    return validPattern.test(key);
-}
-
-export { buildRedisKey, buildRedisKeyPattern, isValidRedisKey };

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

@@ -1,30 +0,0 @@
-/**
- * Sanitize a Redis key component to ensure it's valid and safe
- *
- * Redis keys can contain any binary sequence, but for best practices:
- * - Avoid whitespace (spaces, tabs, newlines) - replace with underscores
- * - Avoid control characters (0x00-0x1F, 0x7F) - remove them
- * - Avoid quotes and backslashes that could cause escaping issues - remove them
- * - Replace pipes (|) with hyphens since Auth0 userIds use pipes (auth0|123)
- *
- * @param component - The key component to sanitize
- * @returns Sanitized key component
- */
-export declare function sanitizeKeyComponent(component: string): string;
-/**
- * Sanitize an entire Redis key (all components)
- * Useful for keys that are already constructed
- *
- * @param key - The complete Redis key to sanitize
- * @returns Sanitized Redis key
- */
-export declare function sanitizeRedisKey(key: string): string;
-/**
- * Escape special Redis pattern characters for exact matching
- * Useful when you want to search for keys containing wildcards literally
- * Note: Hyphens are not escaped as they're commonly used in keys
- *
- * @param pattern - The pattern to escape
- * @returns Escaped pattern
- */
-export declare function escapeRedisPattern(pattern: string): string;

package/lib/utils/redis-key-sanitizer.js

@@ -1,54 +0,0 @@
-/**
- * Sanitize a Redis key component to ensure it's valid and safe
- *
- * Redis keys can contain any binary sequence, but for best practices:
- * - Avoid whitespace (spaces, tabs, newlines) - replace with underscores
- * - Avoid control characters (0x00-0x1F, 0x7F) - remove them
- * - Avoid quotes and backslashes that could cause escaping issues - remove them
- * - Replace pipes (|) with hyphens since Auth0 userIds use pipes (auth0|123)
- *
- * @param component - The key component to sanitize
- * @returns Sanitized key component
- */
-function sanitizeKeyComponent(component) {
-    if (!component)
-        return '';
-    return component
-        .trim() // Trim first to remove leading/trailing whitespace
-        .replace(/[\s\r\n\t]+/g, '_') // Replace whitespace with underscore
-        .replace(/\|/g, '-') // Replace pipe with hyphen (Auth0 userIds: auth0|123 → auth0-123)
-        .replace(/[\x00-\x1F\x7F]/g, '') // Remove control characters
-        .replace(/["'\\]/g, ''); // Remove quotes and backslashes
-}
-/**
- * Sanitize an entire Redis key (all components)
- * Useful for keys that are already constructed
- *
- * @param key - The complete Redis key to sanitize
- * @returns Sanitized Redis key
- */
-function sanitizeRedisKey(key) {
-    if (!key)
-        return '';
-    // Split by colon, sanitize each part, rejoin
-    return key
-        .split(':')
-        .map(sanitizeKeyComponent)
-        .filter((part) => part.length > 0)
-        .join(':');
-}
-/**
- * Escape special Redis pattern characters for exact matching
- * Useful when you want to search for keys containing wildcards literally
- * Note: Hyphens are not escaped as they're commonly used in keys
- *
- * @param pattern - The pattern to escape
- * @returns Escaped pattern
- */
-function escapeRedisPattern(pattern) {
-    // Escape Redis KEYS pattern special characters: * ? [ ] ^ \
-    // Note: We don't escape hyphen (-) as it's not special outside character classes
-    return pattern.replace(/[*?[\]^\\]/g, '\\$&');
-}
-
-export { escapeRedisPattern, sanitizeKeyComponent, sanitizeRedisKey };