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

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

@@ -5,109 +5,15 @@
  * 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.
+ * Most types are generated from GraphQL schema via codegen.
+ * Additional runtime types (RedisValue, RedisHashValue) are defined here.
  *
  * @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
@@ -120,70 +26,3 @@ export type RedisValue = string | number | Buffer | null;
  * 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/templates/{repositories/IRedisCacheManager.ts.template → services/RedisCacheManager.ts.template}

@@ -24,12 +24,12 @@
  * 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
+ * @see ICachePolicy - For cache TTL and scope configuration
+ * @see ICacheContext - For tenant/user isolation
  */
 
 import type { DocumentNode } from 'graphql';
-import { CacheContext, CachePolicy } from './redisCommonTypes';
+import { ICacheContext, ICachePolicy } from 'common/server';
 
 export interface IRedisCacheManager {
     /**
@@ -60,7 +60,7 @@ export interface IRedisCacheManager {
     get<T>(
         query: string | DocumentNode,
         variables: Record<string, any>,
-        ctx: CacheContext
+        ctx: ICacheContext
     ): Promise<T | null>;
 
     /**
@@ -97,8 +97,8 @@ export interface IRedisCacheManager {
         query: string | DocumentNode,
         variables: Record<string, any>,
         data: T,
-        ctx: CacheContext,
-        cachePolicy?: CachePolicy
+        ctx: ICacheContext,
+        cachePolicy?: ICachePolicy
     ): Promise<void>;
 
     /**
@@ -143,7 +143,7 @@ export interface IRedisCacheManager {
     del(
         query: string | DocumentNode,
         variables?: Record<string, unknown>,
-        ctx?: CacheContext,
+        ctx?: ICacheContext,
         shouldRemoveAll?: boolean
     ): Promise<void>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@common-stack/store-redis",
-    "version": "8.2.5-alpha.33",
+    "version": "8.2.5-alpha.35",
     "description": "Redis store utilities and services for common-stack",
     "license": "UNLICENSED",
     "author": "CDMBase LLC",
@@ -24,13 +24,14 @@
         "watch": "npm run build:lib:watch"
     },
     "dependencies": {
-        "@common-stack/core": "8.2.5-alpha.15"
+        "@common-stack/core": "8.2.5-alpha.35"
     },
     "devDependencies": {
-        "common": "8.2.5-alpha.15",
+        "common": "8.2.5-alpha.35",
         "ioredis": "^5.3.2"
     },
     "peerDependencies": {
+        "graphql": ">=16.0.0",
         "inversify": "*",
         "ioredis": ">=5.0.0"
     },
@@ -44,15 +45,15 @@
             ],
             "repositories": [
                 "./${libDir}/templates/repositories/IRedisKeyBuilder.ts.template",
-                "./${libDir}/templates/repositories/IRedisStorageBackend.ts.template",
-                "./${libDir}/templates/repositories/IRedisCacheManager.ts.template",
-                "./${libDir}/templates/repositories/IRedisService.ts.template",
                 "./${libDir}/templates/repositories/redisCommonTypes.ts.template"
+            ],
+            "services": [
+                "./${libDir}/templates/services/RedisCacheManager.ts.template"
             ]
         }
     },
     "typescript": {
         "definition": "lib/index.d.ts"
     },
-    "gitHead": "5745649eba49ac589b9ace8c55378b6cbe130096"
+    "gitHead": "33d6be7fdf924ca76bc1b98cee3031d55a8115d7"
 }

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

@@ -1,28 +0,0 @@
-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/redis-key-options.d.ts

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

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

@@ -1,17 +0,0 @@
-/**
- * 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/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> }>>;
-}