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

package/lib/containers/container.d.ts

@@ -0,0 +1,2 @@
+import { interfaces } from 'inversify';
+export declare const infraContainer: (settings: any) => interfaces.ContainerModule;

package/lib/containers/container.js

@@ -0,0 +1,9 @@
+import { ContainerModule } from 'inversify';
+import { SERVER_TYPES } from 'common/server';
+import { RedisCacheManager } from '../services/RedisCacheManager.js';
+
+const infraContainer = (settings) => new ContainerModule((bind) => {
+    bind(SERVER_TYPES.RedisCacheManager).to(RedisCacheManager).inSingletonScope();
+});
+
+export { infraContainer };

package/lib/containers/index.d.ts

@@ -0,0 +1 @@
+export * from './container';

package/lib/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ioredis';
+export * from './upstash-redis';
+export * from './keyBuilder';

package/lib/core/ioredis.d.ts

@@ -0,0 +1,15 @@
+import Redis from 'ioredis';
+import { IRedisClient } from 'common/server';
+export declare class IORedisClient implements IRedisClient {
+    private redis;
+    constructor(config: {
+        url: string;
+    });
+    get(key: string): Promise<any | null>;
+    set(key: string, value: string, options?: {
+        ex?: number;
+    }): Promise<string>;
+    delMulti(keys: string[]): Promise<any>;
+    del(key: string): Promise<number>;
+    on(event: string, cb: (...args: any[]) => void): Redis;
+}

package/lib/core/ioredis.js

@@ -0,0 +1,31 @@
+import Redis from 'ioredis';
+
+class IORedisClient {
+    redis;
+    constructor(config) {
+        this.redis = new Redis(config.url);
+    }
+    async get(key) {
+        const data = await this.redis.get(key);
+        return data;
+    }
+    async set(key, value, options) {
+        if (options?.ex) {
+            return await this.redis.set(key, value, 'EX', options?.ex);
+        }
+        else {
+            return await this.redis.set(key, value);
+        }
+    }
+    async delMulti(keys) {
+        return await this.redis.del(keys);
+    }
+    async del(key) {
+        return await this.redis.del(key);
+    }
+    on(event, cb) {
+        return this.redis.on(event, cb);
+    }
+}
+
+export { IORedisClient };

package/lib/core/keyBuilder/generate-query-cache-key.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file generate-query-cache-key.ts
+ * @description Generates consistent cache keys for GraphQL queries
+ *
+ * This utility creates deterministic cache keys by hashing GraphQL queries and variables,
+ * with proper sanitization for Redis key compatibility (e.g., Auth0 userIds with pipes).
+ *
+ * Key format: queryName:queryHash[:variablesHash]
+ * - Query is hashed using SHA-256 for consistent, compact keys
+ * - Variables are optionally hashed if provided
+ * - All components are sanitized for Redis key safety
+ */
+import { DocumentNode } from 'graphql/language/index.js';
+export type GenerateQueryCacheKeyOptions = {
+    query: string | DocumentNode;
+    variables: Record<string, unknown>;
+    userId?: string;
+    tenantId?: string;
+    appName?: string;
+    logger?: any;
+};
+/**
+ * Generates a cache key for GraphQL queries using standardized Redis key builder
+ *
+ * Key format: `[appName]:[tenantId]:[userId]:queryName:queryHash[:variablesHash]`
+ * or legacy format: `[tenantId]:[userId]:queryName:queryHash[:variablesHash]`
+ * - Query and variables are hashed for consistent, compact keys
+ * - Uses buildRedisKey for proper sanitization and validation
+ * - Optional components are omitted if not provided
+ *
+ * @param options - Cache key generation options
+ * @returns Generated cache key string
+ *
+ * @example
+ * ```typescript
+ * // With appName (recommended)
+ * generateQueryCacheKey({
+ *   query: GetUserDocument,
+ *   variables: { userId: '123' },
+ *   userId: 'auth0|123',
+ *   tenantId: 'default',
+ *   appName: 'MY_APP',
+ *   logger: myLogger
+ * })
+ * // Returns: 'MY_APP:default:auth0-123:user:hash1:hash2'
+ *
+ * // Legacy format without appName (for backward compatibility)
+ * generateQueryCacheKey({
+ *   query: GetUserDocument,
+ *   variables: { userId: '123' },
+ *   userId: 'auth0|123',
+ *   tenantId: 'default',
+ * })
+ * // Returns: 'default:auth0-123:user:hash1:hash2'
+ * ```
+ */
+export declare const generateQueryCacheKey: ({ query, variables, logger, userId, tenantId, appName, }: GenerateQueryCacheKeyOptions) => string;

package/lib/core/keyBuilder/generate-query-cache-key.js

@@ -0,0 +1,88 @@
+import { createHash } from 'crypto';
+import { print } from 'graphql/language/index.js';
+import { buildRedisKey } from './sanitize-redis-key.js';
+
+/**
+ * @file generate-query-cache-key.ts
+ * @description Generates consistent cache keys for GraphQL queries
+ *
+ * This utility creates deterministic cache keys by hashing GraphQL queries and variables,
+ * with proper sanitization for Redis key compatibility (e.g., Auth0 userIds with pipes).
+ *
+ * Key format: queryName:queryHash[:variablesHash]
+ * - Query is hashed using SHA-256 for consistent, compact keys
+ * - Variables are optionally hashed if provided
+ * - All components are sanitized for Redis key safety
+ */
+/**
+ * Generates a cache key for GraphQL queries using standardized Redis key builder
+ *
+ * Key format: `[appName]:[tenantId]:[userId]:queryName:queryHash[:variablesHash]`
+ * or legacy format: `[tenantId]:[userId]:queryName:queryHash[:variablesHash]`
+ * - Query and variables are hashed for consistent, compact keys
+ * - Uses buildRedisKey for proper sanitization and validation
+ * - Optional components are omitted if not provided
+ *
+ * @param options - Cache key generation options
+ * @returns Generated cache key string
+ *
+ * @example
+ * ```typescript
+ * // With appName (recommended)
+ * generateQueryCacheKey({
+ *   query: GetUserDocument,
+ *   variables: { userId: '123' },
+ *   userId: 'auth0|123',
+ *   tenantId: 'default',
+ *   appName: 'MY_APP',
+ *   logger: myLogger
+ * })
+ * // Returns: 'MY_APP:default:auth0-123:user:hash1:hash2'
+ *
+ * // Legacy format without appName (for backward compatibility)
+ * generateQueryCacheKey({
+ *   query: GetUserDocument,
+ *   variables: { userId: '123' },
+ *   userId: 'auth0|123',
+ *   tenantId: 'default',
+ * })
+ * // Returns: 'default:auth0-123:user:hash1:hash2'
+ * ```
+ */
+const generateQueryCacheKey = ({ query, variables, logger, userId, tenantId, appName, }) => {
+    const normalizedQuery = (typeof query === 'string' ? query : print(query)).trim();
+    const [, queryName] = normalizedQuery?.match(/{\s*(\w+)/) ?? [];
+    // Log the data right before hashing
+    if (logger && typeof logger.trace === 'function') {
+        logger.trace('About to hash normalized query: [%s]', normalizedQuery);
+        logger.trace('About to hash variables: [%j]', variables);
+    }
+    const queryHash = createHash('sha256').update(normalizedQuery).digest('hex');
+    const variablesHash = variables ? createHash('sha256').update(JSON.stringify(variables)).digest('hex') : null;
+    // Build segments: queryName, queryHash, and optional variablesHash
+    const segments = [queryName, queryHash];
+    if (variablesHash) {
+        segments.push(variablesHash);
+    }
+    // If appName is provided, use the full standardized format
+    if (appName) {
+        return buildRedisKey({
+            appName,
+            tenantId,
+            userId,
+            segments,
+        });
+    }
+    // Legacy format for backward compatibility (no appName)
+    // Still uses buildRedisKey for sanitization, but strips the appName prefix
+    const fullKey = buildRedisKey({
+        appName: '__temp__',
+        tenantId,
+        userId,
+        segments,
+    });
+    // Remove the temporary appName prefix: __temp__:
+    return fullKey.substring('__temp__:'.length);
+};
+
+export { generateQueryCacheKey };

package/lib/core/keyBuilder/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Redis Utilities
+ *
+ * Utility functions for Redis key building, sanitization, and cache key generation.
+ * These utilities provide consistent Redis key formatting across applications.
+ */
+export * from './sanitize-redis-key';
+export * from './redis-key-builder';
+export * from './generate-query-cache-key';
+import { type RedisKeyBuilderOptions } from './redis-key-builder';
+/**
+ * Simplified buildRedisKey that uses APP_NAME from environment
+ */
+export declare function buildRedisKey(options: Omit<RedisKeyBuilderOptions, 'appName'>): string;
+/**
+ * Simplified buildRedisKeyPattern that uses APP_NAME from environment
+ */
+export declare function buildRedisKeyPattern(options: Omit<RedisKeyBuilderOptions, 'appName'>): string;

package/lib/core/keyBuilder/index.js

@@ -0,0 +1,27 @@
+import { buildRedisKeyWithNamespace, buildRedisKeyPatternWithNamespace } from './redis-key-builder.js';
+export { RedisNamespace, extractNamespaceFromRedisKey, extractTenantIdFromRedisKey, isValidRedisKeyWithNamespace, parseRedisKey } from './redis-key-builder.js';
+import 'crypto';
+import 'graphql/language/index.js';
+
+/**
+ * Redis Utilities
+ *
+ * Utility functions for Redis key building, sanitization, and cache key generation.
+ * These utilities provide consistent Redis key formatting across applications.
+ */
+/**
+ * Simplified buildRedisKey that uses APP_NAME from environment
+ */
+function buildRedisKey(options) {
+    const appName = process.env.APP_NAME || 'APP';
+    return buildRedisKeyWithNamespace({ ...options, appName });
+}
+/**
+ * Simplified buildRedisKeyPattern that uses APP_NAME from environment
+ */
+function buildRedisKeyPattern(options) {
+    const appName = process.env.APP_NAME || 'APP';
+    return buildRedisKeyPatternWithNamespace({ ...options, appName });
+}
+
+export { buildRedisKey, buildRedisKeyPattern, buildRedisKeyPatternWithNamespace, buildRedisKeyWithNamespace };

package/lib/core/keyBuilder/redis-key-builder.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Centralized Redis Key Builder
+ *
+ * Enforces consistent Redis key formatting across the entire application.
+ * Standard format: <APP_NAME>:<tenantId>:<namespace>:<...segments>
+ *
+ * Key Design Principles:
+ * 1. All keys MUST start with APP_NAME for application isolation
+ * 2. All keys SHOULD include tenantId for multi-tenancy (use 'default' if no tenant context)
+ * 3. Keys are sanitized to remove invalid Redis characters
+ * 4. Use namespaces to organize keys by domain/feature
+ */
+/**
+ * Options for building Redis keys with namespace support
+ */
+export interface RedisKeyBuilderOptions {
+    /** Application name for key prefix (e.g., 'CDMBASE_TEST') */
+    appName: string;
+    /** Tenant ID for multi-tenancy. Use 'default' for global/system keys */
+    tenantId?: string;
+    /** Optional user ID for user-specific keys */
+    userId?: string;
+    /** Namespace for organizing keys (e.g., 'cache', 'session', 'tenant', 'config') */
+    namespace: string;
+    /** Additional key segments (e.g., ['user', userId] or ['query', queryName]) */
+    segments: string[];
+}
+/**
+ * Builds a standardized Redis key with namespace and consistent formatting
+ *
+ * Format: <APP_NAME>:<tenantId>:<namespace>:<segment1>:<segment2>:...
+ *
+ * @param options - Key building options
+ * @returns Formatted and sanitized Redis key
+ *
+ * @example
+ * ```typescript
+ * // Cache key with tenant
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'tenant-123',
+ *   namespace: 'cache',
+ *   segments: ['user', userId, 'profile']
+ * });
+ * // => "CDMBASE_TEST:tenant-123:cache:user:auth0-123:profile"
+ *
+ * // Global configuration key
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'default',
+ *   namespace: 'config',
+ *   segments: ['extension', 'permissions']
+ * });
+ * // => "CDMBASE_TEST:default:config:extension:permissions"
+ *
+ * // Session key without tenant
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   namespace: 'session',
+ *   segments: ['abc123']
+ * });
+ * // => "CDMBASE_TEST:default:session:abc123"
+ * ```
+ */
+export declare function buildRedisKeyWithNamespace(options: RedisKeyBuilderOptions): string;
+/**
+ * Builds a wildcard pattern for Redis KEYS command with namespace support
+ *
+ * @param options - Key building options (segments can include '*' wildcards)
+ * @returns Redis key pattern for matching multiple keys
+ *
+ * @example
+ * ```typescript
+ * // Match all cache keys for a tenant
+ * buildRedisKeyPatternWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'tenant-123',
+ *   namespace: 'cache',
+ *   segments: ['*']
+ * });
+ * // => "CDMBASE_TEST:tenant-123:cache:*"
+ *
+ * // Match all user cache keys across all tenants
+ * buildRedisKeyPatternWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: '*',
+ *   namespace: 'cache',
+ *   segments: ['user', '*']
+ * });
+ * // => "CDMBASE_TEST:*:cache:user:*"
+ * ```
+ */
+export declare function buildRedisKeyPatternWithNamespace(options: RedisKeyBuilderOptions): string;
+/**
+ * Common namespaces used across the application
+ * These provide a standardized vocabulary for organizing Redis keys
+ */
+export declare const RedisNamespace: {
+    /** GraphQL/API response caching */
+    readonly CACHE: "cache";
+    /** User session data */
+    readonly SESSION: "session";
+    /** Tenant information cache */
+    readonly TENANT: "tenant";
+    /** Configuration and settings */
+    readonly CONFIG: "config";
+    /** Extension/plugin data */
+    readonly EXTENSION: "extension";
+    /** Contribution points */
+    readonly CONTRIBUTION: "contribution";
+    /** Request-scoped storage */
+    readonly STORAGE: "storage";
+    /** Permission and access control */
+    readonly PERMISSION: "permission";
+    /** Temporary/TTL based data */
+    readonly TEMP: "temp";
+};
+export type RedisNamespaceType = (typeof RedisNamespace)[keyof typeof RedisNamespace];
+/**
+ * Extracts tenant ID from a Redis key if present
+ *
+ * @param key - Redis key to parse
+ * @returns Tenant ID or null if not found/parseable
+ */
+export declare function extractTenantIdFromRedisKey(key: string): string | null;
+/**
+ * Extracts namespace from a Redis key if present
+ *
+ * @param key - Redis key to parse
+ * @returns Namespace or null if not found/parseable
+ */
+export declare function extractNamespaceFromRedisKey(key: string): string | null;
+/**
+ * Validates if a key follows the standard format with namespace
+ *
+ * @param key - Redis key to validate
+ * @returns True if key follows standard format
+ */
+export declare function isValidRedisKeyWithNamespace(key: string): boolean;
+/**
+ * Parses a Redis key into its components
+ *
+ * @param key - Redis key to parse
+ * @returns Parsed key components or null if invalid
+ */
+export interface ParsedRedisKey {
+    appName: string;
+    tenantId: string;
+    namespace: string;
+    segments: string[];
+}
+export declare function parseRedisKey(key: string): ParsedRedisKey | null;

package/lib/core/keyBuilder/redis-key-builder.js

@@ -0,0 +1,185 @@
+import { sanitizeRedisKeyComponent } from './sanitize-redis-key.js';
+
+/**
+ * Centralized Redis Key Builder
+ *
+ * Enforces consistent Redis key formatting across the entire application.
+ * Standard format: <APP_NAME>:<tenantId>:<namespace>:<...segments>
+ *
+ * Key Design Principles:
+ * 1. All keys MUST start with APP_NAME for application isolation
+ * 2. All keys SHOULD include tenantId for multi-tenancy (use 'default' if no tenant context)
+ * 3. Keys are sanitized to remove invalid Redis characters
+ * 4. Use namespaces to organize keys by domain/feature
+ */
+/**
+ * Builds a standardized Redis key with namespace and consistent formatting
+ *
+ * Format: <APP_NAME>:<tenantId>:<namespace>:<segment1>:<segment2>:...
+ *
+ * @param options - Key building options
+ * @returns Formatted and sanitized Redis key
+ *
+ * @example
+ * ```typescript
+ * // Cache key with tenant
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'tenant-123',
+ *   namespace: 'cache',
+ *   segments: ['user', userId, 'profile']
+ * });
+ * // => "CDMBASE_TEST:tenant-123:cache:user:auth0-123:profile"
+ *
+ * // Global configuration key
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'default',
+ *   namespace: 'config',
+ *   segments: ['extension', 'permissions']
+ * });
+ * // => "CDMBASE_TEST:default:config:extension:permissions"
+ *
+ * // Session key without tenant
+ * buildRedisKeyWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   namespace: 'session',
+ *   segments: ['abc123']
+ * });
+ * // => "CDMBASE_TEST:default:session:abc123"
+ * ```
+ */
+function buildRedisKeyWithNamespace(options) {
+    const { appName, tenantId = 'default', userId, namespace, segments } = options;
+    // Sanitize all components
+    const sanitizedAppName = sanitizeRedisKeyComponent(appName);
+    const sanitizedTenantId = sanitizeRedisKeyComponent(tenantId);
+    const sanitizedNamespace = sanitizeRedisKeyComponent(namespace);
+    const sanitizedSegments = segments.map(sanitizeRedisKeyComponent);
+    // Build key with consistent format, including userId if provided
+    const parts = [sanitizedAppName, sanitizedTenantId];
+    if (userId) {
+        parts.push(sanitizeRedisKeyComponent(userId));
+    }
+    parts.push(sanitizedNamespace, ...sanitizedSegments);
+    return parts.join(':');
+}
+/**
+ * Builds a wildcard pattern for Redis KEYS command with namespace support
+ *
+ * @param options - Key building options (segments can include '*' wildcards)
+ * @returns Redis key pattern for matching multiple keys
+ *
+ * @example
+ * ```typescript
+ * // Match all cache keys for a tenant
+ * buildRedisKeyPatternWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: 'tenant-123',
+ *   namespace: 'cache',
+ *   segments: ['*']
+ * });
+ * // => "CDMBASE_TEST:tenant-123:cache:*"
+ *
+ * // Match all user cache keys across all tenants
+ * buildRedisKeyPatternWithNamespace({
+ *   appName: 'CDMBASE_TEST',
+ *   tenantId: '*',
+ *   namespace: 'cache',
+ *   segments: ['user', '*']
+ * });
+ * // => "CDMBASE_TEST:*:cache:user:*"
+ * ```
+ */
+function buildRedisKeyPatternWithNamespace(options) {
+    // For patterns, allow '*' to pass through without sanitization
+    const { appName, tenantId = '*', userId, namespace, segments } = options;
+    const sanitizedAppName = sanitizeRedisKeyComponent(appName);
+    const sanitizedTenantId = tenantId === '*' ? '*' : sanitizeRedisKeyComponent(tenantId);
+    const sanitizedNamespace = sanitizeRedisKeyComponent(namespace);
+    const sanitizedSegments = segments.map((seg) => (seg === '*' ? '*' : sanitizeRedisKeyComponent(seg)));
+    // Build pattern with userId if provided
+    const parts = [sanitizedAppName, sanitizedTenantId];
+    if (userId !== undefined) {
+        parts.push(userId === '*' ? '*' : sanitizeRedisKeyComponent(userId));
+    }
+    parts.push(sanitizedNamespace, ...sanitizedSegments);
+    return parts.join(':');
+}
+/**
+ * Common namespaces used across the application
+ * These provide a standardized vocabulary for organizing Redis keys
+ */
+const RedisNamespace = {
+    /** GraphQL/API response caching */
+    CACHE: 'cache',
+    /** User session data */
+    SESSION: 'session',
+    /** Tenant information cache */
+    TENANT: 'tenant',
+    /** Configuration and settings */
+    CONFIG: 'config',
+    /** Extension/plugin data */
+    EXTENSION: 'extension',
+    /** Contribution points */
+    CONTRIBUTION: 'contribution',
+    /** Request-scoped storage */
+    STORAGE: 'storage',
+    /** Permission and access control */
+    PERMISSION: 'permission',
+    /** Temporary/TTL based data */
+    TEMP: 'temp',
+};
+/**
+ * Extracts tenant ID from a Redis key if present
+ *
+ * @param key - Redis key to parse
+ * @returns Tenant ID or null if not found/parseable
+ */
+function extractTenantIdFromRedisKey(key) {
+    const parts = key.split(':');
+    // Format: APP_NAME:tenantId:namespace:...
+    if (parts.length >= 3) {
+        return parts[1];
+    }
+    return null;
+}
+/**
+ * Extracts namespace from a Redis key if present
+ *
+ * @param key - Redis key to parse
+ * @returns Namespace or null if not found/parseable
+ */
+function extractNamespaceFromRedisKey(key) {
+    const parts = key.split(':');
+    // Format: APP_NAME:tenantId:namespace:...
+    if (parts.length >= 3) {
+        return parts[2];
+    }
+    return null;
+}
+/**
+ * Validates if a key follows the standard format with namespace
+ *
+ * @param key - Redis key to validate
+ * @returns True if key follows standard format
+ */
+function isValidRedisKeyWithNamespace(key) {
+    const parts = key.split(':');
+    // Minimum format: APP_NAME:tenantId:namespace
+    return parts.length >= 3 && parts[0].length > 0 && parts[1].length > 0 && parts[2].length > 0;
+}
+function parseRedisKey(key) {
+    const parts = key.split(':');
+    if (parts.length < 3) {
+        return null;
+    }
+    return {
+        appName: parts[0],
+        tenantId: parts[1],
+        namespace: parts[2],
+        segments: parts.slice(3),
+    };
+}
+
+export { RedisNamespace, buildRedisKeyPatternWithNamespace, buildRedisKeyWithNamespace, extractNamespaceFromRedisKey, extractTenantIdFromRedisKey, isValidRedisKeyWithNamespace, parseRedisKey };