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

package/LICENSE

@@ -0,0 +1,34 @@
+PROPRIETARY LICENSE
+
+Copyright (c) 2017-2025 CDMBase LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the 
+proprietary and confidential information of CDMBase LLC ("Confidential Information").
+
+NOTICE: All information contained herein is, and remains the property of 
+CDMBase LLC. The intellectual and technical concepts contained herein are 
+proprietary to CDMBase LLC and may be covered by U.S. and Foreign Patents, 
+patents in process, and are protected by trade secret or copyright law.
+
+Dissemination of this information or reproduction of this material is strictly 
+forbidden unless prior written permission is obtained from CDMBase LLC.
+
+NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL 
+PROPERTY RIGHTS ARE GRANTED BY THIS DOCUMENT.
+
+RESTRICTIONS:
+1. You may NOT use, copy, modify, merge, publish, distribute, sublicense, 
+   and/or sell copies of the Software without explicit written permission 
+   from CDMBase LLC.
+2. You may NOT reverse engineer, decompile, or disassemble the Software.
+3. You may NOT remove or alter any proprietary notices or labels on the Software.
+4. The Software is licensed, not sold.
+
+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 
+CDMBASE LLC 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.
+
+For licensing inquiries, please contact: legal@cdmbase.com

package/README.md

@@ -0,0 +1,69 @@
+# @common-stack/store-redis
+
+Redis store utilities and services for common-stack applications.
+
+## Overview
+
+This package provides centralized Redis utilities, services, and patterns for managing Redis operations across common-stack applications. It includes:
+
+- **Key Management**: Centralized Redis key building and sanitization
+- **Cache Services**: Redis-based caching services with consistent patterns
+- **Storage Backends**: Simple key-value storage implementations
+- **Utilities**: Helper functions for Redis operations
+
+## Structure
+
+```
+src/
+├── interfaces/        # TypeScript interfaces and types
+├── services/          # Redis service implementations
+├── utils/             # Utility functions (key builders, sanitizers)
+└── index.ts          # Public API exports
+```
+
+## Future Migration
+
+This package is prepared to consolidate Redis utilities from:
+
+- `@adminide-stack/platform-server` (redis-key-builder, RedisCacheManager)
+- `@adminide-stack/auth0-server-core` (RedisStorageBackend)
+- Other Redis-related utilities across the codebase
+
+## Usage
+
+```typescript
+import { buildRedisKey, buildRedisKeyPattern, RedisNamespace } from '@common-stack/store-redis';
+
+// Build a Redis key
+const key = buildRedisKey({
+    tenantId: 'tenant-123',
+    namespace: RedisNamespace.CACHE,
+    segments: ['user', 'profile'],
+});
+// Result: APP_NAME:tenant-123:cache:user:profile
+
+// Build a pattern for bulk operations
+const pattern = buildRedisKeyPattern({
+    tenantId: 'tenant-123',
+    namespace: RedisNamespace.CACHE,
+    segments: ['user', '*'],
+});
+// Result: APP_NAME:tenant-123:cache:user:*
+```
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode
+npm run watch
+
+# Run tests
+npm test
+```
+
+## License
+
+UNLICENSED

package/lib/__tests__/redis-key-builder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/redis-key-sanitizer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @common-stack/store-redis
+ *
+ * Redis store utilities and services for common-stack applications
+ *
+ * This package will consolidate Redis utilities from across the codebase:
+ * - Key management and sanitization
+ * - Cache services
+ * - Storage backends
+ * - Redis patterns and utilities
+ */
+export * from './interfaces';
+export * from './services';
+export * from './utils';

package/lib/index.js

@@ -0,0 +1,3 @@
+export { RedisNamespace } from './interfaces/redis-key-options.js';
+export { buildRedisKey, buildRedisKeyPattern, isValidRedisKey } from './utils/redis-key-builder.js';
+export { escapeRedisPattern, sanitizeKeyComponent, sanitizeRedisKey } from './utils/redis-key-sanitizer.js';

package/lib/interfaces/cache-manager.d.ts

@@ -0,0 +1,28 @@
+import type { DocumentNode } from 'graphql';
+import type { CacheContext } from './redis-key-options';
+/**
+ * Cache policy for controlling cache behavior
+ */
+export interface CachePolicy {
+    /** Maximum age in seconds */
+    maxAge: number;
+    /** Cache scope (PUBLIC, PRIVATE, etc.) */
+    scope?: string;
+}
+/**
+ * Redis cache manager interface for GraphQL query caching
+ */
+export interface IRedisCacheManager {
+    /**
+     * Get cached data for a query
+     */
+    get<T>(query: string | DocumentNode, variables: Record<string, any>, ctx: CacheContext): Promise<T | null>;
+    /**
+     * Set cached data for a query
+     */
+    set<T>(query: string | DocumentNode, variables: Record<string, any>, data: T, ctx: CacheContext, cachePolicy?: CachePolicy): Promise<void>;
+    /**
+     * Delete cached data for a query
+     */
+    del(query: string | DocumentNode, variables?: Record<string, unknown>, ctx?: CacheContext, shouldRemoveAll?: boolean): Promise<void>;
+}

package/lib/interfaces/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Interfaces for Redis store operations
+ */
+export * from './redis-key-options';
+export * from './storage-backend';
+export * from './cache-manager';

package/lib/interfaces/redis-key-options.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for building Redis keys with standardized format
+ */
+export interface RedisKeyOptions {
+    /** Tenant ID for multi-tenant isolation */
+    tenantId?: string;
+    /** Namespace to categorize keys (e.g., 'cache', 'session', 'storage') */
+    namespace: string;
+    /** Additional key segments to append */
+    segments: string[];
+    /** Optional user ID for user-specific keys */
+    userId?: string;
+}
+/**
+ * Standard Redis namespaces for organizing keys
+ */
+export declare enum RedisNamespace {
+    CACHE = "cache",
+    SESSION = "session",
+    TENANT = "tenant",
+    CONFIG = "config",
+    EXTENSION = "extension",
+    CONTRIBUTION = "contribution",
+    STORAGE = "storage",
+    PERMISSION = "permission",
+    TEMP = "temp"
+}
+/**
+ * Context for cache operations
+ */
+export interface CacheContext {
+    tenantId?: string;
+    userId?: string;
+    orgId?: string;
+}

package/lib/interfaces/redis-key-options.js

@@ -0,0 +1,17 @@
+/**
+ * Standard Redis namespaces for organizing keys
+ */
+var RedisNamespace;
+(function (RedisNamespace) {
+    RedisNamespace["CACHE"] = "cache";
+    RedisNamespace["SESSION"] = "session";
+    RedisNamespace["TENANT"] = "tenant";
+    RedisNamespace["CONFIG"] = "config";
+    RedisNamespace["EXTENSION"] = "extension";
+    RedisNamespace["CONTRIBUTION"] = "contribution";
+    RedisNamespace["STORAGE"] = "storage";
+    RedisNamespace["PERMISSION"] = "permission";
+    RedisNamespace["TEMP"] = "temp";
+})(RedisNamespace || (RedisNamespace = {}));
+
+export { RedisNamespace };

package/lib/interfaces/storage-backend.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generic storage backend interface for simple key-value operations
+ */
+export interface IStorageBackend {
+    /**
+     * Get a value by key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value for a key
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Clear all keys in this storage
+     */
+    clear(): Promise<void>;
+}

package/lib/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Redis service implementations
+ *
+ * Note: Actual implementations will be migrated from:
+ * - @adminide-stack/platform-server/RedisCacheManager
+ * - @adminide-stack/auth0-server-core/RedisStorageBackend
+ */
+export {};

package/lib/templates/constants/SERVER_TYPES.ts.template

@@ -0,0 +1,7 @@
+export const SERVER_TYPES = {
+    RedisClient: Symbol.for('RedisClient'),
+    RedisCacheManager: Symbol.for('RedisCacheManager'),
+    RedisStorageBackend: Symbol.for('RedisStorageBackend'),
+    RedisConnectionPool: Symbol.for('RedisConnectionPool'),
+    RedisKeyBuilder: Symbol.for('RedisKeyBuilder'),
+};

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

@@ -0,0 +1,212 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IRedisCacheManager.ts
+ * @description Defines the IRedisCacheManager interface for GraphQL query caching with Redis.
+ * This interface provides sophisticated caching capabilities specifically designed for GraphQL operations,
+ * with automatic query hashing, variable-based cache keys, and wildcard invalidation support.
+ *
+ * The cache manager is optimized for:
+ * - GraphQL query result caching
+ * - Automatic cache key generation from queries and variables
+ * - Multi-tenant cache isolation
+ * - Flexible cache invalidation strategies
+ * - TTL-based expiration
+ *
+ * Key features:
+ * - Automatic hashing of GraphQL queries and variables
+ * - Cache key format: {APP_NAME}:{tenantId}:{userId}:{queryName}:{queryHash}:{variablesHash}
+ * - Support for both string queries and DocumentNode
+ * - Wildcard-based cache invalidation
+ * - Tenant and user isolation
+ * - Configurable cache policies (TTL, scope)
+ *
+ * This cache manager helps improve GraphQL API performance by caching expensive query results
+ * while maintaining cache correctness through intelligent invalidation strategies.
+ *
+ * @see IRedisStorageBackend - For simpler key-value storage
+ * @see CachePolicy - For cache TTL and scope configuration
+ * @see CacheContext - For tenant/user isolation
+ */
+
+import type { DocumentNode } from 'graphql';
+import { CacheContext, CachePolicy } from './redisCommonTypes';
+
+export interface IRedisCacheManager {
+    /**
+     * Get cached data for a GraphQL query
+     * Returns null if cache miss or cache expired
+     * 
+     * The cache key is automatically generated from the query, variables, and context
+     * 
+     * @param query - GraphQL query string or DocumentNode
+     * @param variables - Query variables for cache key generation
+     * @param ctx - Cache context (tenant, user, org)
+     * @returns Promise resolving to cached data or null
+     * 
+     * @example
+     * // Get cached user query result
+     * const cachedUser = await cacheManager.get<User>(
+     *   GET_USER_QUERY,
+     *   { userId: '123' },
+     *   { tenantId: 'tenant-1', userId: 'user-1' }
+     * );
+     * 
+     * if (!cachedUser) {
+     *   // Cache miss, fetch from database
+     *   const user = await fetchUser('123');
+     *   await cacheManager.set(GET_USER_QUERY, { userId: '123' }, user, ctx);
+     * }
+     */
+    get<T>(
+        query: string | DocumentNode,
+        variables: Record<string, any>,
+        ctx: CacheContext
+    ): Promise<T | null>;
+
+    /**
+     * Set cached data for a GraphQL query
+     * Stores the result with automatic key generation and optional TTL
+     * 
+     * @param query - GraphQL query string or DocumentNode
+     * @param variables - Query variables for cache key generation
+     * @param data - Data to cache
+     * @param ctx - Cache context (tenant, user, org)
+     * @param cachePolicy - Optional cache policy with TTL and scope
+     * @returns Promise that resolves when data is cached
+     * 
+     * @example
+     * // Cache query result for 1 hour
+     * await cacheManager.set(
+     *   GET_USERS_QUERY,
+     *   { role: 'admin' },
+     *   users,
+     *   { tenantId: 'tenant-1' },
+     *   { maxAge: 3600, scope: 'PUBLIC' }
+     * );
+     * 
+     * @example
+     * // Cache with default TTL (24 hours)
+     * await cacheManager.set(
+     *   GET_PRODUCT_QUERY,
+     *   { productId: '456' },
+     *   product,
+     *   { tenantId: 'tenant-1' }
+     * );
+     */
+    set<T>(
+        query: string | DocumentNode,
+        variables: Record<string, any>,
+        data: T,
+        ctx: CacheContext,
+        cachePolicy?: CachePolicy
+    ): Promise<void>;
+
+    /**
+     * Delete cached data for a GraphQL query
+     * Supports both exact deletion and wildcard patterns
+     * 
+     * When variables are provided: Deletes exact cache entry for those specific variables
+     * When variables are omitted: Deletes all cache entries for that query
+     * When shouldRemoveAll is true: Uses wildcard pattern to match query name
+     * 
+     * @param query - GraphQL query string or DocumentNode
+     * @param variables - Optional query variables for specific deletion
+     * @param ctx - Optional cache context for tenant/user filtering
+     * @param shouldRemoveAll - If true, removes all entries matching query name
+     * @returns Promise that resolves when deletion is complete
+     * 
+     * @example
+     * // Delete specific cached query
+     * await cacheManager.del(
+     *   GET_USER_QUERY,
+     *   { userId: '123' },
+     *   { tenantId: 'tenant-1' }
+     * );
+     * 
+     * @example
+     * // Delete all cached user queries for a tenant
+     * await cacheManager.del(
+     *   GET_USER_QUERY,
+     *   undefined,
+     *   { tenantId: 'tenant-1' },
+     *   true
+     * );
+     * 
+     * @example
+     * // Delete all variations of a query
+     * await cacheManager.del(
+     *   GET_USERS_QUERY,
+     *   undefined,
+     *   { tenantId: 'tenant-1' }
+     * );
+     */
+    del(
+        query: string | DocumentNode,
+        variables?: Record<string, unknown>,
+        ctx?: CacheContext,
+        shouldRemoveAll?: boolean
+    ): Promise<void>;
+
+    /**
+     * Clear all cache entries for a tenant
+     * Useful when tenant data changes significantly
+     * 
+     * @param tenantId - Tenant ID to clear cache for
+     * @returns Promise resolving to count of deleted entries
+     * 
+     * @example
+     * // Clear all tenant cache on major update
+     * await cacheManager.clearTenant('tenant-123');
+     */
+    clearTenant(tenantId: string): Promise<number>;
+
+    /**
+     * Clear all cache entries for a user
+     * Useful when user permissions or data changes
+     * 
+     * @param userId - User ID to clear cache for
+     * @param tenantId - Optional tenant ID to scope the clear operation
+     * @returns Promise resolving to count of deleted entries
+     * 
+     * @example
+     * // Clear user cache on permission change
+     * await cacheManager.clearUser('user-456', 'tenant-123');
+     */
+    clearUser(userId: string, tenantId?: string): Promise<number>;
+
+    /**
+     * Clear all cache entries matching a pattern
+     * Advanced operation for custom cache invalidation strategies
+     * 
+     * @param pattern - Redis pattern to match
+     * @returns Promise resolving to count of deleted entries
+     * 
+     * @example
+     * // Clear all product caches
+     * await cacheManager.clearPattern('*:getProduct:*');
+     * 
+     * @example
+     * // Clear all admin queries
+     * await cacheManager.clearPattern('APP:tenant-1:*:admin*:*');
+     */
+    clearPattern(pattern: string): Promise<number>;
+
+    /**
+     * Get cache statistics
+     * Useful for monitoring cache performance
+     * 
+     * @param tenantId - Optional tenant ID to scope statistics
+     * @returns Promise resolving to cache statistics
+     * 
+     * @example
+     * // Get overall cache stats
+     * const stats = await cacheManager.getStats();
+     * console.log(`Cache keys: ${stats.totalKeys}`);
+     * console.log(`Memory used: ${stats.memoryUsage}`);
+     */
+    getStats(tenantId?: string): Promise<{
+        totalKeys: number;
+        memoryUsage: number;
+        hitRate?: number;
+    }>;
+}

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

@@ -0,0 +1,169 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IRedisKeyBuilder.ts
+ * @description Defines the IRedisKeyBuilder interface for standardized Redis key management.
+ * This interface ensures consistent key formatting across the application with proper sanitization,
+ * tenant isolation, and namespace organization.
+ *
+ * The key builder enforces a standard format: <APP_NAME>:<tenantId>:<namespace>:<segments>
+ * This structure provides:
+ * - Multi-tenant isolation through tenantId
+ * - Organized key spaces through namespaces
+ * - Hierarchical structure through segments
+ * - Automatic sanitization of special characters
+ *
+ * Key features:
+ * - Standardized key format across the application
+ * - Automatic sanitization of pipes, spaces, control characters
+ * - Support for wildcard patterns for bulk operations
+ * - Key validation utilities
+ * - Pattern escaping for exact matching
+ *
+ * This pattern helps prevent key collisions, makes debugging easier, and enables
+ * efficient bulk operations through pattern matching.
+ *
+ * @see RedisKeyOptions - Configuration for key building
+ * @see RedisNamespace - Standard namespaces for key organization
+ */
+
+import { RedisKeyOptions } from './redisCommonTypes';
+
+export interface IRedisKeyBuilder {
+    /**
+     * Build a standardized Redis key with proper formatting and sanitization
+     * 
+     * Format: <APP_NAME>:<tenantId>:<namespace>:<segments...>
+     * 
+     * @param options - Key building options including tenant, namespace, and segments
+     * @returns Properly formatted and sanitized Redis key
+     * 
+     * @example
+     * // Build a cache key for user profile
+     * const key = keyBuilder.buildKey({
+     *   tenantId: 'tenant-123',
+     *   namespace: RedisNamespace.CACHE,
+     *   segments: ['user', 'profile', userId]
+     * });
+     * // Result: "APP_NAME:tenant-123:cache:user:profile:user-456"
+     * 
+     * @example
+     * // Build a session key
+     * const sessionKey = keyBuilder.buildKey({
+     *   tenantId: 'tenant-123',
+     *   userId: 'user-456',
+     *   namespace: RedisNamespace.SESSION,
+     *   segments: [sessionId]
+     * });
+     * // Result: "APP_NAME:tenant-123:user-456:session:session-789"
+     */
+    buildKey(options: RedisKeyOptions): string;
+
+    /**
+     * Build a Redis key pattern for wildcard matching
+     * Useful for bulk operations like deleting all keys matching a pattern
+     * 
+     * @param options - Key building options, segments can include wildcards (*)
+     * @returns Redis key pattern with wildcards
+     * 
+     * @example
+     * // Pattern to match all user cache keys for a tenant
+     * const pattern = keyBuilder.buildPattern({
+     *   tenantId: 'tenant-123',
+     *   namespace: RedisNamespace.CACHE,
+     *   segments: ['user', '*']
+     * });
+     * // Result: "APP_NAME:tenant-123:cache:user:*"
+     * 
+     * @example
+     * // Pattern to match all keys for a namespace
+     * const allCachePattern = keyBuilder.buildPattern({
+     *   tenantId: 'tenant-123',
+     *   namespace: RedisNamespace.CACHE,
+     *   segments: ['*']
+     * });
+     */
+    buildPattern(options: RedisKeyOptions): string;
+
+    /**
+     * Sanitize a key component to ensure it's valid and safe
+     * Removes/replaces special characters that could cause issues
+     * 
+     * - Replaces spaces/tabs/newlines with underscores
+     * - Replaces pipes (|) with hyphens (for Auth0 userIds: auth0|123 → auth0-123)
+     * - Removes control characters
+     * - Removes quotes and backslashes
+     * 
+     * @param component - Key component to sanitize
+     * @returns Sanitized component
+     * 
+     * @example
+     * // Sanitize Auth0 userId
+     * const sanitized = keyBuilder.sanitize('auth0|123456');
+     * // Result: "auth0-123456"
+     * 
+     * @example
+     * // Sanitize filename with spaces
+     * const sanitized = keyBuilder.sanitize('my file.txt');
+     * // Result: "my_file.txt"
+     */
+    sanitize(component: string): string;
+
+    /**
+     * Validate if a string is a valid Redis key
+     * Checks for empty strings, excessive length, and invalid characters
+     * 
+     * @param key - Key to validate
+     * @returns True if key is valid, false otherwise
+     * 
+     * @example
+     * // Validate a key
+     * const isValid = keyBuilder.isValidKey('APP:tenant:cache:user:profile');
+     * // Result: true
+     * 
+     * @example
+     * // Invalid key with spaces
+     * const isValid = keyBuilder.isValidKey('APP tenant cache');
+     * // Result: false
+     */
+    isValidKey(key: string): boolean;
+
+    /**
+     * Escape Redis pattern special characters for exact matching
+     * Useful when you want to search for keys containing wildcards literally
+     * 
+     * Escapes: * ? [ ] ^ \
+     * 
+     * @param pattern - Pattern to escape
+     * @returns Escaped pattern
+     * 
+     * @example
+     * // Escape wildcards for literal search
+     * const escaped = keyBuilder.escapePattern('file*.txt');
+     * // Result: "file\\*.txt"
+     */
+    escapePattern(pattern: string): string;
+
+    /**
+     * Parse a Redis key into its components
+     * Useful for debugging and key analysis
+     * 
+     * @param key - Redis key to parse
+     * @returns Object with parsed components (appName, tenantId, namespace, segments)
+     * 
+     * @example
+     * const parsed = keyBuilder.parseKey('APP:tenant-123:cache:user:profile');
+     * // Result: {
+     * //   appName: 'APP',
+     * //   tenantId: 'tenant-123',
+     * //   namespace: 'cache',
+     * //   segments: ['user', 'profile']
+     * // }
+     */
+    parseKey(key: string): {
+        appName: string;
+        tenantId: string;
+        namespace: string;
+        segments: string[];
+        userId?: string;
+    };
+}