blendsdk 5.33.0

package/dist/webafx-cache/pubsub-plugin.d.ts

@@ -0,0 +1,128 @@
+/**
+ * WebAFX plugin integration for pub/sub providers.
+ *
+ * Provides convenience factory functions that wire a PubSubProvider instance
+ * into a WebAFX application as a singleton service with health check,
+ * graceful shutdown, and optional declarative subscription support.
+ *
+ * This is the ONLY pub/sub file that imports from @blendsdk/webafx,
+ * which is why webafx is a peer dependency (not a hard dependency).
+ *
+ * @packageDocumentation
+ */
+import type { PluginDefinition } from "../webafx/index.js";
+import { PubSubProvider } from "./abstract-pubsub-provider.js";
+import type { RedisPubSubConfig, MemoryPubSubConfig, PubSubFactoryConfig, SubscriptionDefinition } from "./types.js";
+/**
+ * Options for pub/sub plugin creation.
+ *
+ * Allows overriding the plugin priority and registering declarative
+ * subscriptions that are set up at plugin installation time.
+ */
+export interface PubSubPluginOptions {
+    /** Plugin installation priority. Default: 30 */
+    priority?: number;
+    /**
+     * Declarative subscriptions to register at plugin install time.
+     *
+     * Each entry specifies either a `channel` (exact) or `pattern` (glob)
+     * with a handler function. Subscriptions are registered in order
+     * during the plugin factory execution.
+     */
+    subscriptions?: SubscriptionDefinition[];
+}
+/**
+ * Create a WebAFX PluginDefinition from any PubSubProvider instance.
+ *
+ * Core function that wires a pub/sub provider into WebAFX:
+ * 1. Registers the provider as a singleton service in the service container
+ * 2. Registers any declarative subscriptions from options
+ * 3. Hooks the provider's health() into the /health endpoint
+ * 4. Hooks the provider's shutdown() into graceful shutdown
+ *
+ * The service name is read from `provider.serviceName` (defaults to 'pubsub').
+ *
+ * @param provider - Any PubSubProvider instance (Redis, Memory, or custom)
+ * @param options - Optional overrides for priority and declarative subscriptions
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * const pubsub = new RedisPubSubProvider({ host: 'localhost' });
+ * app.use(createPubSubPlugin(pubsub));
+ * ```
+ */
+export declare function createPubSubPlugin(provider: PubSubProvider, options?: PubSubPluginOptions): PluginDefinition;
+/**
+ * Create a WebAFX pub/sub plugin with a Redis backend. One-liner registration.
+ *
+ * Creates a RedisPubSubProvider internally and returns a PluginDefinition.
+ * The user never needs to instantiate the provider manually.
+ *
+ * @param config - Redis pub/sub configuration (host, port, channelPrefix, etc.)
+ * @param options - Optional plugin options (priority, subscriptions)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(redisPubSubPlugin({
+ *     host: 'localhost',
+ *     port: 6379,
+ *     channelPrefix: 'MyApp',
+ * }));
+ * ```
+ *
+ * @example With declarative subscriptions
+ * ```typescript
+ * app.use(redisPubSubPlugin(
+ *     { host: 'localhost', channelPrefix: 'MyApp' },
+ *     {
+ *         subscriptions: [
+ *             { channel: 'order:created', handler: handleNewOrder },
+ *             { pattern: 'audit:*', handler: handleAuditEvent },
+ *         ]
+ *     }
+ * ));
+ * ```
+ */
+export declare function redisPubSubPlugin(config: RedisPubSubConfig, options?: PubSubPluginOptions): PluginDefinition;
+/**
+ * Create a WebAFX pub/sub plugin with an In-Memory backend. One-liner registration.
+ *
+ * Creates a MemoryPubSubProvider internally and returns a PluginDefinition.
+ * Ideal for development, testing, and single-instance applications.
+ *
+ * @param config - Optional memory pub/sub configuration (channelPrefix, serviceName)
+ * @param options - Optional plugin options (priority, subscriptions)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(memoryPubSubPlugin());
+ * ```
+ */
+export declare function memoryPubSubPlugin(config?: MemoryPubSubConfig, options?: PubSubPluginOptions): PluginDefinition;
+/**
+ * Create a PubSubProvider based on configuration type.
+ *
+ * Factory function for environment-based backend switching.
+ * Returns the appropriate provider based on `config.type`.
+ * Use with `createPubSubPlugin()` to register in WebAFX.
+ *
+ * @param config - Pub/sub factory configuration with type discriminator
+ * @returns A PubSubProvider instance (Redis or Memory)
+ * @throws Error if config.type is not 'redis' or 'memory'
+ *
+ * @example
+ * ```typescript
+ * const pubsub = createPubSub({
+ *     type: process.env.NODE_ENV === 'production' ? 'redis' : 'memory',
+ *     host: process.env.REDIS_HOST,
+ *     port: Number(process.env.REDIS_PORT),
+ *     channelPrefix: 'MyApp',
+ * });
+ * app.use(createPubSubPlugin(pubsub));
+ * ```
+ */
+export declare function createPubSub(config: PubSubFactoryConfig): PubSubProvider;
+//# sourceMappingURL=pubsub-plugin.d.ts.map

package/dist/webafx-cache/pubsub-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pubsub-plugin.d.ts","sourceRoot":"","sources":["../src/pubsub-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D,OAAO,KAAK,EACR,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACzB,MAAM,YAAY,CAAC;AAapB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAC5C;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAC9B,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,gBAAgB,CA0ClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC9B,gBAAgB,CAGlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAC9B,MAAM,CAAC,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,mBAAmB,GAC9B,gBAAgB,CAGlB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc,CA0BxE"}

package/dist/webafx-cache/pubsub-plugin.js

@@ -0,0 +1,182 @@
+/**
+ * WebAFX plugin integration for pub/sub providers.
+ *
+ * Provides convenience factory functions that wire a PubSubProvider instance
+ * into a WebAFX application as a singleton service with health check,
+ * graceful shutdown, and optional declarative subscription support.
+ *
+ * This is the ONLY pub/sub file that imports from @blendsdk/webafx,
+ * which is why webafx is a peer dependency (not a hard dependency).
+ *
+ * @packageDocumentation
+ */
+import { RedisPubSubProvider } from "./redis-pubsub-provider.js";
+import { MemoryPubSubProvider } from "./memory-pubsub-provider.js";
+// ---------------------------------------------------------------------------
+// Default Constants
+// ---------------------------------------------------------------------------
+/** Default plugin priority — same as cache (30), independent plugins */
+const DEFAULT_PUBSUB_PLUGIN_PRIORITY = 30;
+// ---------------------------------------------------------------------------
+// Plugin Factory Functions
+// ---------------------------------------------------------------------------
+/**
+ * Create a WebAFX PluginDefinition from any PubSubProvider instance.
+ *
+ * Core function that wires a pub/sub provider into WebAFX:
+ * 1. Registers the provider as a singleton service in the service container
+ * 2. Registers any declarative subscriptions from options
+ * 3. Hooks the provider's health() into the /health endpoint
+ * 4. Hooks the provider's shutdown() into graceful shutdown
+ *
+ * The service name is read from `provider.serviceName` (defaults to 'pubsub').
+ *
+ * @param provider - Any PubSubProvider instance (Redis, Memory, or custom)
+ * @param options - Optional overrides for priority and declarative subscriptions
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * const pubsub = new RedisPubSubProvider({ host: 'localhost' });
+ * app.use(createPubSubPlugin(pubsub));
+ * ```
+ */
+export function createPubSubPlugin(provider, options) {
+    return {
+        name: provider.serviceName,
+        priority: options?.priority ?? DEFAULT_PUBSUB_PLUGIN_PRIORITY,
+        factory: async ({ app, logger }) => {
+            // Register the pub/sub provider as an application-wide singleton service.
+            // The factory ignores container/settings since the provider is pre-created.
+            app.registerService({
+                name: provider.serviceName,
+                type: "singleton",
+                factory: () => provider,
+                dispose: async () => {
+                    await provider.shutdown();
+                },
+            });
+            // Register declarative subscriptions (if provided in options)
+            if (options?.subscriptions) {
+                for (const sub of options.subscriptions) {
+                    if (sub.channel) {
+                        await provider.subscribe(sub.channel, sub.handler);
+                        await logger.info(`PubSub: subscribed to channel "${sub.channel}"`);
+                    }
+                    else if (sub.pattern) {
+                        await provider.psubscribe(sub.pattern, sub.handler);
+                        await logger.info(`PubSub: subscribed to pattern "${sub.pattern}"`);
+                    }
+                }
+            }
+            await logger.info(`PubSub plugin "${provider.serviceName}" initialized ` +
+                `(${provider.constructor.name})`);
+            // Return Plugin hooks for health monitoring and graceful shutdown
+            return {
+                health: () => provider.health(),
+                shutdown: () => provider.shutdown(),
+            };
+        },
+    };
+}
+/**
+ * Create a WebAFX pub/sub plugin with a Redis backend. One-liner registration.
+ *
+ * Creates a RedisPubSubProvider internally and returns a PluginDefinition.
+ * The user never needs to instantiate the provider manually.
+ *
+ * @param config - Redis pub/sub configuration (host, port, channelPrefix, etc.)
+ * @param options - Optional plugin options (priority, subscriptions)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(redisPubSubPlugin({
+ *     host: 'localhost',
+ *     port: 6379,
+ *     channelPrefix: 'MyApp',
+ * }));
+ * ```
+ *
+ * @example With declarative subscriptions
+ * ```typescript
+ * app.use(redisPubSubPlugin(
+ *     { host: 'localhost', channelPrefix: 'MyApp' },
+ *     {
+ *         subscriptions: [
+ *             { channel: 'order:created', handler: handleNewOrder },
+ *             { pattern: 'audit:*', handler: handleAuditEvent },
+ *         ]
+ *     }
+ * ));
+ * ```
+ */
+export function redisPubSubPlugin(config, options) {
+    const provider = new RedisPubSubProvider(config);
+    return createPubSubPlugin(provider, options);
+}
+/**
+ * Create a WebAFX pub/sub plugin with an In-Memory backend. One-liner registration.
+ *
+ * Creates a MemoryPubSubProvider internally and returns a PluginDefinition.
+ * Ideal for development, testing, and single-instance applications.
+ *
+ * @param config - Optional memory pub/sub configuration (channelPrefix, serviceName)
+ * @param options - Optional plugin options (priority, subscriptions)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(memoryPubSubPlugin());
+ * ```
+ */
+export function memoryPubSubPlugin(config, options) {
+    const provider = new MemoryPubSubProvider(config);
+    return createPubSubPlugin(provider, options);
+}
+/**
+ * Create a PubSubProvider based on configuration type.
+ *
+ * Factory function for environment-based backend switching.
+ * Returns the appropriate provider based on `config.type`.
+ * Use with `createPubSubPlugin()` to register in WebAFX.
+ *
+ * @param config - Pub/sub factory configuration with type discriminator
+ * @returns A PubSubProvider instance (Redis or Memory)
+ * @throws Error if config.type is not 'redis' or 'memory'
+ *
+ * @example
+ * ```typescript
+ * const pubsub = createPubSub({
+ *     type: process.env.NODE_ENV === 'production' ? 'redis' : 'memory',
+ *     host: process.env.REDIS_HOST,
+ *     port: Number(process.env.REDIS_PORT),
+ *     channelPrefix: 'MyApp',
+ * });
+ * app.use(createPubSubPlugin(pubsub));
+ * ```
+ */
+export function createPubSub(config) {
+    switch (config.type) {
+        case "redis":
+            return new RedisPubSubProvider({
+                channelPrefix: config.channelPrefix,
+                serviceName: config.serviceName,
+                host: config.host,
+                port: config.port,
+                password: config.password,
+                db: config.db,
+                url: config.url,
+            });
+        case "memory":
+            return new MemoryPubSubProvider({
+                channelPrefix: config.channelPrefix,
+                serviceName: config.serviceName,
+            });
+        default:
+            // Exhaustive check — provides a clear runtime error for invalid types
+            const unknownType = config.type;
+            throw new Error(`Unknown pub/sub type: "${unknownType}". Supported types: "redis", "memory".`);
+    }
+}
+//# sourceMappingURL=pubsub-plugin.js.map

package/dist/webafx-cache/pubsub-plugin.js.map

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

package/dist/webafx-cache/redis-cache-provider.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Redis-backed cache provider using ioredis.
+ *
+ * Production-grade implementation with:
+ * - Native TTL support via Redis EXPIRE/EX
+ * - SCAN-based pattern deletion (safe for production, never uses KEYS)
+ * - Automatic JSON serialization/deserialization
+ * - Connection health monitoring via PING
+ * - Graceful shutdown via quit()
+ *
+ * @packageDocumentation
+ */
+import { Redis } from "ioredis";
+import { CacheProvider } from "./abstract-cache-provider.js";
+import type { RedisCacheConfig } from "./types.js";
+/**
+ * Redis-backed cache provider using ioredis.
+ *
+ * Connects to a Redis instance via URL or host/port configuration.
+ * All cache operations map directly to Redis commands for optimal performance.
+ * Pattern-based operations use SCAN (not KEYS) to avoid blocking the server.
+ *
+ * @example
+ * ```typescript
+ * const cache = new RedisCacheProvider({
+ *     rootKey: 'MyApp',
+ *     host: 'localhost',
+ *     port: 6379,
+ *     defaultTTL: 300,
+ * });
+ *
+ * await cache.set('user:123', { name: 'Alice' }, 600);
+ * const user = await cache.get<User>('user:123');
+ * await cache.shutdown();
+ * ```
+ */
+export declare class RedisCacheProvider extends CacheProvider {
+    /** The ioredis client instance */
+    protected client: Redis;
+    /**
+     * Create a new Redis cache provider.
+     *
+     * If `url` is provided in config, it takes precedence over individual
+     * host/port/password/db settings. The ioredis client is created immediately
+     * and begins connecting in the background.
+     *
+     * @param config - Redis cache configuration with connection details
+     */
+    constructor(config: RedisCacheConfig);
+    /** @inheritDoc */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /** @inheritDoc */
+    get<T>(key: string): Promise<T | undefined>;
+    /** @inheritDoc */
+    delete(key: string): Promise<boolean>;
+    /** @inheritDoc */
+    exists(key: string): Promise<boolean>;
+    /** @inheritDoc */
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /** @inheritDoc */
+    ttl(key: string): Promise<number>;
+    /** @inheritDoc */
+    deletePattern(pattern: string): Promise<number>;
+    /** @inheritDoc */
+    clear(): Promise<void>;
+    /** @inheritDoc */
+    health(): Promise<boolean>;
+    /** @inheritDoc */
+    shutdown(): Promise<void>;
+    /**
+     * Use SCAN to find keys matching a pattern and delete them in batches.
+     *
+     * SCAN is non-blocking and safe for production (unlike KEYS which blocks
+     * the entire Redis server). Keys are deleted in batches as they are found.
+     *
+     * @param pattern - The full pattern to match (already includes rootKey prefix)
+     * @returns Number of keys deleted
+     */
+    protected scanAndDelete(pattern: string): Promise<number>;
+}
+//# sourceMappingURL=redis-cache-provider.d.ts.map

package/dist/webafx-cache/redis-cache-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-provider.d.ts","sourceRoot":"","sources":["../src/redis-cache-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4BnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;IACjD,kCAAkC;IAClC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;IAExB;;;;;;;;OAQG;gBACS,MAAM,EAAE,gBAAgB;IA0BpC,kBAAkB;IACZ,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvE,kBAAkB;IACZ,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAiBjD,kBAAkB;IACZ,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3C,kBAAkB;IACZ,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3C,kBAAkB;IACZ,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO/D,kBAAkB;IACZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUvC,kBAAkB;IACZ,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMrD,kBAAkB;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,kBAAkB;IACZ,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAUhC,kBAAkB;IACZ,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B;;;;;;;;OAQG;cACa,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAwBlE"}

package/dist/webafx-cache/redis-cache-provider.js

@@ -0,0 +1,209 @@
+/**
+ * Redis-backed cache provider using ioredis.
+ *
+ * Production-grade implementation with:
+ * - Native TTL support via Redis EXPIRE/EX
+ * - SCAN-based pattern deletion (safe for production, never uses KEYS)
+ * - Automatic JSON serialization/deserialization
+ * - Connection health monitoring via PING
+ * - Graceful shutdown via quit()
+ *
+ * @packageDocumentation
+ */
+import { Redis } from "ioredis";
+import { CacheProvider } from "./abstract-cache-provider.js";
+// ---------------------------------------------------------------------------
+// Default Constants
+// ---------------------------------------------------------------------------
+/** Default connection timeout in milliseconds */
+const DEFAULT_CONNECT_TIMEOUT = 5000;
+/** Default max retries per request */
+const DEFAULT_MAX_RETRIES = 3;
+/** Default Redis host */
+const DEFAULT_HOST = "localhost";
+/** Default Redis port */
+const DEFAULT_PORT = 6379;
+/** Default Redis database index */
+const DEFAULT_DB = 0;
+/** Batch size for SCAN operations — how many keys to fetch per SCAN iteration */
+const SCAN_BATCH_SIZE = 100;
+// ---------------------------------------------------------------------------
+// RedisCacheProvider
+// ---------------------------------------------------------------------------
+/**
+ * Redis-backed cache provider using ioredis.
+ *
+ * Connects to a Redis instance via URL or host/port configuration.
+ * All cache operations map directly to Redis commands for optimal performance.
+ * Pattern-based operations use SCAN (not KEYS) to avoid blocking the server.
+ *
+ * @example
+ * ```typescript
+ * const cache = new RedisCacheProvider({
+ *     rootKey: 'MyApp',
+ *     host: 'localhost',
+ *     port: 6379,
+ *     defaultTTL: 300,
+ * });
+ *
+ * await cache.set('user:123', { name: 'Alice' }, 600);
+ * const user = await cache.get<User>('user:123');
+ * await cache.shutdown();
+ * ```
+ */
+export class RedisCacheProvider extends CacheProvider {
+    /** The ioredis client instance */
+    client;
+    /**
+     * Create a new Redis cache provider.
+     *
+     * If `url` is provided in config, it takes precedence over individual
+     * host/port/password/db settings. The ioredis client is created immediately
+     * and begins connecting in the background.
+     *
+     * @param config - Redis cache configuration with connection details
+     */
+    constructor(config) {
+        super(config);
+        // Initialize ioredis client — URL takes precedence over individual options
+        if (config.url) {
+            this.client = new Redis(config.url, {
+                db: config.db,
+                connectTimeout: config.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT,
+                maxRetriesPerRequest: config.maxRetriesPerRequest ?? DEFAULT_MAX_RETRIES,
+            });
+        }
+        else {
+            this.client = new Redis({
+                host: config.host ?? DEFAULT_HOST,
+                port: config.port ?? DEFAULT_PORT,
+                password: config.password,
+                db: config.db ?? DEFAULT_DB,
+                connectTimeout: config.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT,
+                maxRetriesPerRequest: config.maxRetriesPerRequest ?? DEFAULT_MAX_RETRIES,
+            });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Core Operations
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async set(key, value, ttlSeconds) {
+        const fullKey = this.buildKey(key);
+        const serialized = JSON.stringify(value);
+        const effectiveTTL = this.resolveTTL(ttlSeconds);
+        if (effectiveTTL !== undefined) {
+            // SET with EX flag for TTL in seconds
+            await this.client.set(fullKey, serialized, "EX", effectiveTTL);
+        }
+        else {
+            // SET without expiry
+            await this.client.set(fullKey, serialized);
+        }
+    }
+    /** @inheritDoc */
+    async get(key) {
+        const fullKey = this.buildKey(key);
+        const result = await this.client.get(fullKey);
+        // Redis returns null for missing keys
+        if (result === null) {
+            return undefined;
+        }
+        // Deserialize — treat JSON parse failures as cache miss
+        try {
+            return JSON.parse(result);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** @inheritDoc */
+    async delete(key) {
+        const fullKey = this.buildKey(key);
+        const result = await this.client.del(fullKey);
+        // DEL returns the number of keys removed (0 or 1 for a single key)
+        return result === 1;
+    }
+    /** @inheritDoc */
+    async exists(key) {
+        const fullKey = this.buildKey(key);
+        const result = await this.client.exists(fullKey);
+        // EXISTS returns 1 if the key exists, 0 if it doesn't
+        return result === 1;
+    }
+    /** @inheritDoc */
+    async expire(key, ttlSeconds) {
+        const fullKey = this.buildKey(key);
+        const result = await this.client.expire(fullKey, ttlSeconds);
+        // EXPIRE returns 1 if TTL was set, 0 if key doesn't exist
+        return result === 1;
+    }
+    /** @inheritDoc */
+    async ttl(key) {
+        const fullKey = this.buildKey(key);
+        // TTL returns: positive = remaining seconds, -1 = no expiry, -2 = key missing
+        return await this.client.ttl(fullKey);
+    }
+    // -----------------------------------------------------------------------
+    // Pattern Operations
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async deletePattern(pattern) {
+        // Use SCAN to find matching keys (safe for production, non-blocking)
+        const fullPattern = this.buildPattern(pattern);
+        return await this.scanAndDelete(fullPattern);
+    }
+    /** @inheritDoc */
+    async clear() {
+        // Delete all keys under this rootKey namespace using SCAN + DEL
+        const fullPattern = this.buildPattern("*");
+        await this.scanAndDelete(fullPattern);
+    }
+    // -----------------------------------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async health() {
+        try {
+            const result = await this.client.ping();
+            return result === "PONG";
+        }
+        catch {
+            // Connection failure, timeout, etc.
+            return false;
+        }
+    }
+    /** @inheritDoc */
+    async shutdown() {
+        // Graceful disconnect — waits for pending commands to complete
+        await this.client.quit();
+    }
+    // -----------------------------------------------------------------------
+    // Internal Helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Use SCAN to find keys matching a pattern and delete them in batches.
+     *
+     * SCAN is non-blocking and safe for production (unlike KEYS which blocks
+     * the entire Redis server). Keys are deleted in batches as they are found.
+     *
+     * @param pattern - The full pattern to match (already includes rootKey prefix)
+     * @returns Number of keys deleted
+     */
+    async scanAndDelete(pattern) {
+        let cursor = "0";
+        let totalDeleted = 0;
+        do {
+            // SCAN returns [nextCursor, matchingKeys]
+            const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", SCAN_BATCH_SIZE);
+            cursor = nextCursor;
+            // Delete found keys in one DEL command (batch delete)
+            if (keys.length > 0) {
+                const deleted = await this.client.del(...keys);
+                totalDeleted += deleted;
+            }
+        } while (cursor !== "0");
+        return totalDeleted;
+    }
+}
+//# sourceMappingURL=redis-cache-provider.js.map

package/dist/webafx-cache/redis-cache-provider.js.map

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