@memberjunction/redis-provider 0.0.1 → 5.9.0

package/dist/RedisLocalStorageProvider.d.ts

@@ -0,0 +1,491 @@
+/**
+ * @fileoverview Redis-backed implementation of {@link ILocalStorageProvider}.
+ *
+ * This module provides a drop-in replacement for `InMemoryLocalStorageProvider`
+ * that persists data in Redis, enabling:
+ *
+ * - **Shared caching** across multiple MJAPI server instances (horizontal scaling)
+ * - **Persistence** across process restarts
+ * - **Native TTL** via Redis `EXPIRE` — expired keys are automatically reclaimed
+ *
+ * Compatible with any Redis-protocol service: self-hosted Redis, Azure Managed Redis,
+ * AWS ElastiCache, Redis Cloud, Upstash, etc.
+ *
+ * @module @memberjunction/redis-provider
+ */
+import Redis from 'ioredis';
+import type { RedisOptions } from 'ioredis';
+import { ILocalStorageProvider } from '@memberjunction/core';
+import type { CacheChangedEvent } from '@memberjunction/core';
+/**
+ * Configuration options for the Redis local storage provider.
+ *
+ * Accepts either a Redis connection URL string or an `ioredis` options object,
+ * plus optional MemberJunction-specific settings.
+ *
+ * @example
+ * ```typescript
+ * // Simple URL connection (works with Azure, AWS, self-hosted)
+ * const config: RedisProviderConfig = {
+ *     url: 'rediss://default:password@my-redis.example.com:6380'
+ * };
+ *
+ * // Full options object with MJ settings
+ * const config: RedisProviderConfig = {
+ *     options: {
+ *         host: 'localhost',
+ *         port: 6379,
+ *         password: 'secret',
+ *         tls: {},
+ *         db: 0,
+ *     },
+ *     keyPrefix: 'myapp',
+ *     defaultTTLSeconds: 600,
+ * };
+ * ```
+ */
+export interface RedisProviderConfig {
+    /**
+     * Redis connection URL (e.g., `redis://localhost:6379`, `rediss://user:pass@host:6380`).
+     * Mutually exclusive with `options`.
+     * The `rediss://` scheme enables TLS, which is required for most cloud-hosted Redis services.
+     */
+    url?: string;
+    /**
+     * Full `ioredis` options object for fine-grained connection control.
+     * Mutually exclusive with `url`.
+     *
+     * @see https://github.com/redis/ioredis?tab=readme-ov-file#connect-to-redis
+     */
+    options?: RedisOptions;
+    /**
+     * Optional prefix prepended to all Redis keys. Useful for isolating
+     * MemberJunction data in a shared Redis instance.
+     *
+     * Keys are stored as `{keyPrefix}:{category}:{key}`.
+     *
+     * @default 'mj'
+     */
+    keyPrefix?: string;
+    /**
+     * Default time-to-live in seconds applied to every `SetItem` call
+     * unless overridden by the `ttlSeconds` parameter.
+     *
+     * Set to `0` or `undefined` to store keys without expiration (persistent).
+     *
+     * @default undefined (no expiration)
+     */
+    defaultTTLSeconds?: number;
+    /**
+     * Maximum number of connection retry attempts before giving up.
+     * Each retry uses exponential backoff (doubling delay up to 30 seconds).
+     *
+     * @default 10
+     */
+    maxRetries?: number;
+    /**
+     * Whether to log connection events (connect, disconnect, error) via
+     * MemberJunction's `LogStatus` / `LogError` functions.
+     *
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Whether to enable Redis pub/sub for cross-server cache invalidation.
+     * When enabled, the provider will:
+     * - **Publish** a {@link CacheChangedEvent} on every `SetItem`, `Remove`, and `ClearCategory` call
+     * - **Subscribe** (via a dedicated second Redis connection) for events from other servers
+     * - **Emit** local events so consumers (like `LocalCacheManager`) can dispatch to registered callbacks
+     *
+     * Pub/sub is **not** started automatically — call {@link RedisLocalStorageProvider.StartListening}
+     * after construction to begin subscribing.
+     *
+     * @default false
+     */
+    enablePubSub?: boolean;
+}
+/**
+ * Redis-backed implementation of the MemberJunction {@link ILocalStorageProvider} interface.
+ *
+ * Provides persistent, shared caching for server-side environments using Redis.
+ * This is a drop-in replacement for `InMemoryLocalStorageProvider` — all consumers
+ * (like `LocalCacheManager`, `ProviderBase` metadata caching, etc.) work without
+ * any code changes.
+ *
+ * ### Key Structure
+ *
+ * All keys follow the pattern: `{prefix}:{category}:{key}`
+ *
+ * - **prefix** — configurable, defaults to `"mj"` to isolate MJ data in shared Redis instances
+ * - **category** — maps to the MJ cache category (`RunViewCache`, `Metadata`, `DatasetCache`, etc.)
+ * - **key** — the original key from the caller
+ *
+ * Categories are tracked in a Redis Set at `{prefix}:__categories__:{category}` so that
+ * `ClearCategory()` and `GetCategoryKeys()` operations are efficient.
+ *
+ * ### TTL Support
+ *
+ * Redis has native key expiration. The provider supports TTL at two levels:
+ * 1. **`defaultTTLSeconds`** in config — applied to all `SetItem` calls
+ * 2. **`ttlSeconds` parameter** on `SetItem` — overrides the default per-call
+ *
+ * ### Error Handling
+ *
+ * Redis operations are wrapped in try/catch blocks. Connection errors are logged
+ * via `LogError()` but do not throw — the provider gracefully returns `null` for
+ * reads and silently skips writes. This prevents a Redis outage from crashing the
+ * application. The `ioredis` client handles automatic reconnection.
+ *
+ * @example
+ * ```typescript
+ * import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
+ *
+ * const provider = new RedisLocalStorageProvider({
+ *     url: 'redis://localhost:6379',
+ *     defaultTTLSeconds: 300  // 5-minute default TTL
+ * });
+ *
+ * await provider.SetItem('user:123', JSON.stringify(userData), 'UserCache');
+ * const cached = await provider.GetItem('user:123', 'UserCache');
+ * ```
+ */
+export declare class RedisLocalStorageProvider implements ILocalStorageProvider {
+    private _client;
+    private _keyPrefix;
+    private _defaultTTLSeconds;
+    private _enableLogging;
+    private _connected;
+    private _enablePubSub;
+    private _subscriber;
+    private _pubSubChannel;
+    private _eventEmitter;
+    private _subscriberConnected;
+    private _config;
+    /**
+     * Creates a new Redis local storage provider and establishes a connection.
+     *
+     * The constructor sets up the `ioredis` client with automatic reconnection,
+     * error handling, and optional logging. The client connects lazily on the
+     * first command, so construction itself does not block.
+     *
+     * @param config - Redis connection and behavior configuration.
+     *                 At minimum, provide either `url` or `options`.
+     *                 If neither is provided, connects to `localhost:6379`.
+     *
+     * @example
+     * ```typescript
+     * // Connect to local Redis
+     * const provider = new RedisLocalStorageProvider({});
+     *
+     * // Connect to Azure Managed Redis with TLS
+     * const provider = new RedisLocalStorageProvider({
+     *     url: 'rediss://default:ACCESS_KEY@myredis.redis.cache.windows.net:6380',
+     *     defaultTTLSeconds: 600
+     * });
+     *
+     * // Connect to AWS ElastiCache
+     * const provider = new RedisLocalStorageProvider({
+     *     options: {
+     *         host: 'my-cluster.abc123.use1.cache.amazonaws.com',
+     *         port: 6379,
+     *         tls: {}
+     *     }
+     * });
+     * ```
+     */
+    constructor(config?: RedisProviderConfig);
+    /**
+     * Exponential backoff retry strategy for Redis connections.
+     * Doubles the delay on each attempt (capped at 30 seconds) and gives up
+     * after `maxRetries` attempts.
+     *
+     * @param times - Current retry attempt number (1-based)
+     * @param maxRetries - Maximum number of retries before giving up
+     * @returns Delay in milliseconds, or `null` to stop retrying
+     * @internal
+     */
+    private retryStrategy;
+    /**
+     * Registers event handlers on the ioredis client for logging connection
+     * lifecycle events (connect, ready, close, error, reconnecting).
+     * @internal
+     */
+    private setupEventHandlers;
+    /**
+     * Builds the full Redis key from a category and key name.
+     *
+     * Format: `{prefix}:{category}:{key}`
+     *
+     * @param key - The storage key
+     * @param category - The category for key isolation
+     * @returns The fully-qualified Redis key string
+     * @internal
+     */
+    private buildKey;
+    /**
+     * Builds the Redis Set key used to track all keys in a category.
+     *
+     * Format: `{prefix}:__categories__:{category}`
+     *
+     * @param category - The category name
+     * @returns The Redis key for the category's membership set
+     * @internal
+     */
+    private buildCategorySetKey;
+    /**
+     * Retrieves a value from Redis by key and optional category.
+     *
+     * @param key - The key to look up
+     * @param category - Optional category for key isolation (defaults to `"default"`)
+     * @returns The stored string value, or `null` if the key doesn't exist or Redis is unavailable
+     *
+     * @example
+     * ```typescript
+     * const value = await provider.GetItem('entity-metadata', 'Metadata');
+     * if (value) {
+     *     const metadata = JSON.parse(value);
+     * }
+     * ```
+     */
+    GetItem(key: string, category?: string): Promise<string | null>;
+    /**
+     * Stores a value in Redis under the given key and optional category.
+     *
+     * If a `ttlSeconds` is provided, the key will automatically expire after that
+     * duration. Otherwise, the configured `defaultTTLSeconds` is used. If neither
+     * is set, the key persists indefinitely.
+     *
+     * The key is also added to a Redis Set that tracks all keys in the category,
+     * enabling efficient `ClearCategory()` and `GetCategoryKeys()` operations.
+     *
+     * @param key - The key to store under
+     * @param value - The string value to store
+     * @param category - Optional category for key isolation (defaults to `"default"`)
+     * @param ttlSeconds - Optional time-to-live in seconds. Overrides `defaultTTLSeconds` from config.
+     *
+     * @example
+     * ```typescript
+     * // Store with default TTL
+     * await provider.SetItem('view:users', JSON.stringify(results), 'RunViewCache');
+     *
+     * // Store with explicit 10-minute TTL
+     * await provider.SetItem('view:users', JSON.stringify(results), 'RunViewCache', 600);
+     * ```
+     */
+    SetItem(key: string, value: string, category?: string, ttlSeconds?: number): Promise<void>;
+    /**
+     * Removes a key from Redis and from its category tracking set.
+     *
+     * @param key - The key to remove
+     * @param category - Optional category for key isolation (defaults to `"default"`)
+     *
+     * @example
+     * ```typescript
+     * await provider.Remove('view:users', 'RunViewCache');
+     * ```
+     */
+    Remove(key: string, category?: string): Promise<void>;
+    /**
+     * Clears all keys belonging to a specific category.
+     *
+     * Uses the category tracking Set to find all member keys, deletes them
+     * in a single pipeline call, then removes the tracking Set itself.
+     *
+     * @param category - The category to clear. If empty, clears the `"default"` category.
+     *
+     * @example
+     * ```typescript
+     * // Clear all cached RunView results
+     * await provider.ClearCategory('RunViewCache');
+     * ```
+     */
+    ClearCategory(category: string): Promise<void>;
+    /**
+     * Returns all keys belonging to a specific category.
+     *
+     * Reads from the category tracking Set, so the result reflects keys
+     * that were added via `SetItem` (some may have expired via TTL but
+     * will still appear in the set until cleaned up).
+     *
+     * @param category - The category to list keys from
+     * @returns Array of original key names (without the Redis prefix/category prefix)
+     *
+     * @example
+     * ```typescript
+     * const keys = await provider.GetCategoryKeys('RunViewCache');
+     * console.log(`${keys.length} cached views`);
+     * ```
+     */
+    GetCategoryKeys(category: string): Promise<string[]>;
+    /**
+     * Whether the Redis client currently has an active connection.
+     *
+     * Note: `ioredis` automatically reconnects on failure, so a `false` value
+     * here is usually transient. The provider continues to accept commands
+     * (they queue until reconnection succeeds or retry limit is hit).
+     */
+    get IsConnected(): boolean;
+    /**
+     * Returns the underlying `ioredis` client instance for advanced operations.
+     *
+     * Use with caution — direct client access bypasses key prefixing and
+     * category tracking. Prefer the `ILocalStorageProvider` methods for
+     * standard operations.
+     *
+     * @example
+     * ```typescript
+     * // Use for Redis-specific commands like pub/sub, streams, etc.
+     * const client = provider.Client;
+     * await client.publish('cache-invalidation', 'entity:Users');
+     * ```
+     */
+    get Client(): Redis;
+    /**
+     * Gracefully disconnects from Redis.
+     *
+     * Sends a `QUIT` command and waits for pending replies. After calling this
+     * method, the provider should not be used for further operations.
+     *
+     * Call this during application shutdown to ensure clean disconnection.
+     *
+     * @example
+     * ```typescript
+     * // During application shutdown
+     * process.on('SIGTERM', async () => {
+     *     await redisProvider.Disconnect();
+     *     process.exit(0);
+     * });
+     * ```
+     */
+    Disconnect(): Promise<void>;
+    /**
+     * Checks if a key exists in the specified category.
+     *
+     * This is more efficient than `GetItem()` when you only need to check
+     * existence without retrieving the value (avoids transferring the value
+     * over the network).
+     *
+     * @param key - The key to check
+     * @param category - Optional category for key isolation (defaults to `"default"`)
+     * @returns `true` if the key exists and has not expired
+     *
+     * @example
+     * ```typescript
+     * if (await provider.Exists('view:users', 'RunViewCache')) {
+     *     // Use cached value
+     * }
+     * ```
+     */
+    Exists(key: string, category?: string): Promise<boolean>;
+    /**
+     * Returns the remaining time-to-live (in seconds) for a key.
+     *
+     * @param key - The key to check
+     * @param category - Optional category for key isolation (defaults to `"default"`)
+     * @returns TTL in seconds, `-1` if no expiration is set, `-2` if the key doesn't exist,
+     *          or `null` if Redis is unavailable
+     *
+     * @example
+     * ```typescript
+     * const ttl = await provider.GetTTL('view:users', 'RunViewCache');
+     * if (ttl !== null && ttl > 0) {
+     *     console.log(`Key expires in ${ttl} seconds`);
+     * }
+     * ```
+     */
+    GetTTL(key: string, category?: string): Promise<number | null>;
+    /**
+     * Pings the Redis server to verify connectivity.
+     *
+     * Useful for health checks and connection validation.
+     *
+     * @returns `true` if the server responds with `PONG`, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * const healthy = await provider.Ping();
+     * if (!healthy) {
+     *     console.error('Redis is unreachable');
+     * }
+     * ```
+     */
+    Ping(): Promise<boolean>;
+    /**
+     * Starts listening for cache change events from other server instances.
+     * Creates a dedicated Redis connection for pub/sub (required by Redis protocol —
+     * a client in subscribe mode cannot execute other commands).
+     *
+     * Must be called explicitly after construction. No-op if `enablePubSub` is `false`
+     * in the config, or if already listening.
+     *
+     * @example
+     * ```typescript
+     * const provider = new RedisLocalStorageProvider({
+     *     url: 'redis://localhost:6379',
+     *     enablePubSub: true
+     * });
+     * await provider.StartListening();
+     *
+     * // Register for change events
+     * provider.OnCacheChanged((event) => {
+     *     console.log(`Key "${event.CacheKey}" changed by server ${event.SourceServerId}`);
+     * });
+     * ```
+     */
+    StartListening(): Promise<void>;
+    /**
+     * Creates the subscriber Redis client, mirroring the main client's connection config.
+     * @internal
+     */
+    private createSubscriberClient;
+    /**
+     * Sets up event handlers on the subscriber client for logging.
+     * @internal
+     */
+    private setupSubscriberEventHandlers;
+    /**
+     * Handles an incoming pub/sub message. Parses the {@link CacheChangedEvent},
+     * filters out self-originated events, and emits to local listeners.
+     * @internal
+     */
+    private handlePubSubMessage;
+    /**
+     * Publishes a cache change event to Redis pub/sub. Called internally by
+     * `SetItem`, `Remove`, and `ClearCategory`. No-op if pub/sub is disabled.
+     *
+     * @param cacheKey - The cache key that changed
+     * @param category - The storage category
+     * @param action - What happened ('set', 'removed', 'category_cleared')
+     * @param data - The new value (only for 'set' actions)
+     * @internal
+     */
+    private publishChange;
+    /**
+     * Registers a callback for cache change events from other servers.
+     * The callback fires whenever another server instance modifies a cached entry
+     * (via `SetItem`, `Remove`, or `ClearCategory`).
+     *
+     * Events from this server instance (identified by {@link MJGlobal.ProcessUUID})
+     * are automatically filtered out.
+     *
+     * @param callback - Function invoked with the {@link CacheChangedEvent}
+     * @returns A function that, when called, removes this callback registration
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = provider.OnCacheChanged((event) => {
+     *     // Dispatch to LocalCacheManager for callback routing
+     *     LocalCacheManager.Instance.DispatchCacheChange(event);
+     * });
+     *
+     * // Later, on shutdown:
+     * unsubscribe();
+     * ```
+     */
+    OnCacheChanged(callback: (event: CacheChangedEvent) => void): () => void;
+    /**
+     * Whether the pub/sub subscriber connection is currently active.
+     */
+    get IsSubscriberConnected(): boolean;
+}
+//# sourceMappingURL=RedisLocalStorageProvider.d.ts.map

package/dist/RedisLocalStorageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisLocalStorageProvider.d.ts","sourceRoot":"","sources":["../src/RedisLocalStorageProvider.ts"],"names":[],"mappings":"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"}