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

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 };