blendsdk 5.33.0

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

@@ -0,0 +1,185 @@
+/**
+ * Abstract base class for all cache provider implementations.
+ *
+ * Provides a Redis-like API with transparent key namespacing via rootKey prefix.
+ * Both RedisCacheProvider and MemoryCacheProvider extend this class and implement
+ * the abstract methods with backend-specific logic.
+ *
+ * Design principles:
+ * - Application-wide singleton (not per-request)
+ * - Root key prefix isolates keys per application/concern
+ * - Configurable serviceName for multi-cache scenarios
+ * - JSON serialization for all stored values
+ * - All methods are async for a uniform API
+ *
+ * @packageDocumentation
+ */
+import type { CacheProviderConfig } from "./types.js";
+/**
+ * Abstract base class for cache implementations.
+ *
+ * All cache backends (Redis, In-Memory) derive from this class.
+ * Provides a Redis-like API with transparent key namespacing via rootKey.
+ *
+ * Usage through concrete implementations:
+ * ```typescript
+ * const cache = new RedisCacheProvider({ rootKey: 'MyApp' });
+ * await cache.set('user:123', { name: 'Alice' }, 300);
+ * const user = await cache.get<User>('user:123');
+ * ```
+ */
+export declare abstract class CacheProvider {
+    /** Root key prefix applied to all cache keys */
+    protected rootKey: string;
+    /** Service name for WebAFX service container registration */
+    protected _serviceName: string;
+    /** Default TTL in seconds (0 = no expiry) */
+    protected defaultTTL: number;
+    /**
+     * Initialize the cache provider with configuration.
+     *
+     * @param config - Base configuration with rootKey, optional serviceName and defaultTTL
+     * @throws Error if rootKey is empty or not provided
+     */
+    constructor(config: CacheProviderConfig);
+    /** Get the service name used for WebAFX service container registration */
+    get serviceName(): string;
+    /**
+     * Build the actual storage key by prepending the root prefix.
+     *
+     * This method is called by every cache operation to ensure all keys
+     * are namespaced under the rootKey, preventing key collisions in
+     * shared backends (e.g., multiple apps sharing one Redis instance).
+     *
+     * @param key - The user-provided cache key
+     * @returns The prefixed key (e.g., rootKey='MyApp', key='user:123' → 'MyApp:user:123')
+     */
+    protected buildKey(key: string): string;
+    /**
+     * Build the pattern key for pattern-based operations (deletePattern, clear).
+     *
+     * @param pattern - The user-provided pattern (e.g., 'user:*')
+     * @returns The prefixed pattern (e.g., 'MyApp:user:*')
+     */
+    protected buildPattern(pattern: string): string;
+    /**
+     * Resolve the effective TTL for an operation.
+     *
+     * Uses the provided TTL if given, otherwise falls back to defaultTTL.
+     * Returns undefined if effective TTL is 0 (meaning no expiry).
+     *
+     * @param ttlSeconds - Optional TTL override for this operation
+     * @returns The effective TTL in seconds, or undefined if no expiry
+     */
+    protected resolveTTL(ttlSeconds?: number): number | undefined;
+    /**
+     * Set a value in the cache.
+     *
+     * The value is JSON-serialized before storage. The rootKey prefix
+     * is applied automatically to the key.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @param value - Value to store (will be JSON-serialized)
+     * @param ttlSeconds - Optional TTL in seconds. Uses defaultTTL if not provided. 0 = no expiry.
+     */
+    abstract set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Get a value from the cache.
+     *
+     * The stored JSON is deserialized before returning. Returns undefined
+     * for cache misses or expired entries.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @returns The deserialized value, or undefined if not found / expired
+     */
+    abstract get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Delete a key from the cache.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @returns true if the key was deleted, false if it didn't exist
+     */
+    abstract delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists in the cache (and is not expired).
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @returns true if the key exists and is not expired
+     */
+    abstract exists(key: string): Promise<boolean>;
+    /**
+     * Update the TTL on an existing key without changing its value.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @param ttlSeconds - New TTL in seconds
+     * @returns true if the key exists and TTL was updated, false otherwise
+     */
+    abstract expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Get the remaining TTL of a key in seconds.
+     *
+     * Follows Redis conventions for return values:
+     * - Positive number: remaining TTL in seconds
+     * - -1: key exists but has no expiry
+     * - -2: key does not exist
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @returns Remaining TTL in seconds, -1 if no expiry, -2 if key doesn't exist
+     */
+    abstract ttl(key: string): Promise<number>;
+    /**
+     * Delete all keys matching a pattern within this root namespace.
+     *
+     * Pattern uses '*' as wildcard:
+     * - 'user:*' matches 'user:123', 'user:abc'
+     * - '*:session' matches 'admin:session', 'guest:session'
+     *
+     * For Redis, this uses SCAN (not KEYS) to avoid blocking the server.
+     *
+     * @param pattern - Pattern to match (rootKey prefix applied automatically)
+     * @returns Number of keys deleted
+     */
+    abstract deletePattern(pattern: string): Promise<number>;
+    /**
+     * Clear all keys under this root namespace.
+     *
+     * Only removes keys with this provider's rootKey prefix — does NOT
+     * flush the entire Redis database or clear other namespaces.
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Health check — returns true if the backend is operational.
+     *
+     * For Redis: sends a PING command and checks connectivity.
+     * For In-Memory: always returns true.
+     */
+    abstract health(): Promise<boolean>;
+    /**
+     * Graceful shutdown — close connections, clear intervals, release resources.
+     *
+     * For Redis: disconnects the ioredis client.
+     * For In-Memory: clears the cleanup interval and empties the store.
+     */
+    abstract shutdown(): Promise<void>;
+    /**
+     * Cache-aside pattern: get a value if it exists, otherwise call the factory
+     * function to produce it, cache the result, and return it.
+     *
+     * This is the most common caching pattern and is implemented once in the
+     * base class since the logic is identical for all backends.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @param factory - Async function that produces the value on cache miss
+     * @param ttlSeconds - Optional TTL in seconds for the cached value
+     * @returns The cached or freshly produced value
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.getOrSet('user:123', async () => {
+     *     return await db.fetchUser(123);
+     * }, 300); // Cache for 5 minutes
+     * ```
+     */
+    getOrSet<T>(key: string, factory: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+}
+//# sourceMappingURL=abstract-cache-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-cache-provider.d.ts","sourceRoot":"","sources":["../src/abstract-cache-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtD;;;;;;;;;;;;GAYG;AACH,8BAAsB,aAAa;IAC/B,gDAAgD;IAChD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAE1B,6DAA6D;IAC7D,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;IAE/B,6CAA6C;IAC7C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;gBACS,MAAM,EAAE,mBAAmB;IAevC,0EAA0E;IAC1E,IAAI,WAAW,IAAI,MAAM,CAExB;IAMD;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIvC;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI/C;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAS7D;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAElE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAE1C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAExD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAe7F"}

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

@@ -0,0 +1,133 @@
+/**
+ * Abstract base class for all cache provider implementations.
+ *
+ * Provides a Redis-like API with transparent key namespacing via rootKey prefix.
+ * Both RedisCacheProvider and MemoryCacheProvider extend this class and implement
+ * the abstract methods with backend-specific logic.
+ *
+ * Design principles:
+ * - Application-wide singleton (not per-request)
+ * - Root key prefix isolates keys per application/concern
+ * - Configurable serviceName for multi-cache scenarios
+ * - JSON serialization for all stored values
+ * - All methods are async for a uniform API
+ *
+ * @packageDocumentation
+ */
+import { DEFAULT_SERVICE_NAME, DEFAULT_TTL, KEY_SEPARATOR } from "./types.js";
+/**
+ * Abstract base class for cache implementations.
+ *
+ * All cache backends (Redis, In-Memory) derive from this class.
+ * Provides a Redis-like API with transparent key namespacing via rootKey.
+ *
+ * Usage through concrete implementations:
+ * ```typescript
+ * const cache = new RedisCacheProvider({ rootKey: 'MyApp' });
+ * await cache.set('user:123', { name: 'Alice' }, 300);
+ * const user = await cache.get<User>('user:123');
+ * ```
+ */
+export class CacheProvider {
+    /** Root key prefix applied to all cache keys */
+    rootKey;
+    /** Service name for WebAFX service container registration */
+    _serviceName;
+    /** Default TTL in seconds (0 = no expiry) */
+    defaultTTL;
+    /**
+     * Initialize the cache provider with configuration.
+     *
+     * @param config - Base configuration with rootKey, optional serviceName and defaultTTL
+     * @throws Error if rootKey is empty or not provided
+     */
+    constructor(config) {
+        // Validate rootKey — it must be a non-empty string for namespace isolation
+        if (!config.rootKey || config.rootKey.trim().length === 0) {
+            throw new Error("CacheProvider: rootKey is required and cannot be empty");
+        }
+        this.rootKey = config.rootKey;
+        this._serviceName = config.serviceName ?? DEFAULT_SERVICE_NAME;
+        this.defaultTTL = config.defaultTTL ?? DEFAULT_TTL;
+    }
+    // -----------------------------------------------------------------------
+    // Public Accessors
+    // -----------------------------------------------------------------------
+    /** Get the service name used for WebAFX service container registration */
+    get serviceName() {
+        return this._serviceName;
+    }
+    // -----------------------------------------------------------------------
+    // Key Building (protected helpers for subclasses)
+    // -----------------------------------------------------------------------
+    /**
+     * Build the actual storage key by prepending the root prefix.
+     *
+     * This method is called by every cache operation to ensure all keys
+     * are namespaced under the rootKey, preventing key collisions in
+     * shared backends (e.g., multiple apps sharing one Redis instance).
+     *
+     * @param key - The user-provided cache key
+     * @returns The prefixed key (e.g., rootKey='MyApp', key='user:123' → 'MyApp:user:123')
+     */
+    buildKey(key) {
+        return `${this.rootKey}${KEY_SEPARATOR}${key}`;
+    }
+    /**
+     * Build the pattern key for pattern-based operations (deletePattern, clear).
+     *
+     * @param pattern - The user-provided pattern (e.g., 'user:*')
+     * @returns The prefixed pattern (e.g., 'MyApp:user:*')
+     */
+    buildPattern(pattern) {
+        return `${this.rootKey}${KEY_SEPARATOR}${pattern}`;
+    }
+    /**
+     * Resolve the effective TTL for an operation.
+     *
+     * Uses the provided TTL if given, otherwise falls back to defaultTTL.
+     * Returns undefined if effective TTL is 0 (meaning no expiry).
+     *
+     * @param ttlSeconds - Optional TTL override for this operation
+     * @returns The effective TTL in seconds, or undefined if no expiry
+     */
+    resolveTTL(ttlSeconds) {
+        const ttl = ttlSeconds ?? this.defaultTTL;
+        return ttl > 0 ? ttl : undefined;
+    }
+    // -----------------------------------------------------------------------
+    // Concrete Methods (shared logic implemented once for all backends)
+    // -----------------------------------------------------------------------
+    /**
+     * Cache-aside pattern: get a value if it exists, otherwise call the factory
+     * function to produce it, cache the result, and return it.
+     *
+     * This is the most common caching pattern and is implemented once in the
+     * base class since the logic is identical for all backends.
+     *
+     * @param key - Cache key (rootKey prefix applied automatically)
+     * @param factory - Async function that produces the value on cache miss
+     * @param ttlSeconds - Optional TTL in seconds for the cached value
+     * @returns The cached or freshly produced value
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.getOrSet('user:123', async () => {
+     *     return await db.fetchUser(123);
+     * }, 300); // Cache for 5 minutes
+     * ```
+     */
+    async getOrSet(key, factory, ttlSeconds) {
+        // Try to get from cache first
+        const cached = await this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Cache miss — call factory to produce the value
+        const value = await factory();
+        // Store in cache with the specified or default TTL
+        await this.set(key, value, ttlSeconds);
+        return value;
+    }
+}
+//# sourceMappingURL=abstract-cache-provider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-cache-provider.js","sourceRoot":"","sources":["../src/abstract-cache-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,OAAgB,aAAa;IAC/B,gDAAgD;IACtC,OAAO,CAAS;IAE1B,6DAA6D;IACnD,YAAY,CAAS;IAE/B,6CAA6C;IACnC,UAAU,CAAS;IAE7B;;;;;OAKG;IACH,YAAY,MAA2B;QACnC,2EAA2E;QAC3E,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC9E,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC;QAC/D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,WAAW,CAAC;IACvD,CAAC;IAED,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAE1E,0EAA0E;IAC1E,IAAI,WAAW;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED,0EAA0E;IAC1E,kDAAkD;IAClD,0EAA0E;IAE1E;;;;;;;;;OASG;IACO,QAAQ,CAAC,GAAW;QAC1B,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,aAAa,GAAG,GAAG,EAAE,CAAC;IACnD,CAAC;IAED;;;;;OAKG;IACO,YAAY,CAAC,OAAe;QAClC,OAAO,GAAG,IAAI,CAAC,OAAO,GAAG,aAAa,GAAG,OAAO,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;;;OAQG;IACO,UAAU,CAAC,UAAmB;QACpC,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC;QAC1C,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,CAAC;IAyGD,0EAA0E;IAC1E,oEAAoE;IACpE,0EAA0E;IAE1E;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,QAAQ,CAAI,GAAW,EAAE,OAAyB,EAAE,UAAmB;QACzE,8BAA8B;QAC9B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,iDAAiD;QACjD,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;QAE9B,mDAAmD;QACnD,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAEvC,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/webafx-cache/abstract-pubsub-provider.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Abstract base class for all pub/sub provider implementations.
+ *
+ * Provides a typed, JSON-serialized messaging API with transparent channel
+ * prefix management. Both RedisPubSubProvider and MemoryPubSubProvider
+ * extend this class and implement the abstract methods with backend-specific logic.
+ *
+ * Design principles:
+ * - Application-wide singleton (not per-request)
+ * - Channel prefix isolates channels per application/concern
+ * - Configurable serviceName for multi-pubsub scenarios
+ * - JSON serialization for all messages
+ * - All methods are async for a uniform API
+ * - Handler errors are isolated (log + continue)
+ *
+ * Architecture note:
+ * This hierarchy is completely independent from CacheProvider. They are
+ * parallel abstractions that happen to live in the same package.
+ *
+ * @packageDocumentation
+ */
+import type { PubSubProviderConfig, PubSubMessage, MessageHandler } from "./types.js";
+/**
+ * Abstract base class for pub/sub implementations.
+ *
+ * All pub/sub backends (Redis, In-Memory) derive from this class.
+ * Provides typed, JSON-serialized messaging with channel prefix support.
+ *
+ * Usage through concrete implementations:
+ * ```typescript
+ * const pubsub = new RedisPubSubProvider({ channelPrefix: 'MyApp' });
+ * await pubsub.subscribe<OrderEvent>('order:new', (msg) => {
+ *     console.log('New order:', msg.data);
+ * });
+ * await pubsub.publish('order:new', { orderId: 123, total: 49.99 });
+ * ```
+ */
+export declare abstract class PubSubProvider {
+    /** Channel prefix for namespace isolation */
+    protected channelPrefix: string | undefined;
+    /** Service name for WebAFX registration */
+    protected _serviceName: string;
+    /**
+     * Initialize the pub/sub provider with configuration.
+     *
+     * @param config - Base configuration with optional channelPrefix and serviceName
+     */
+    constructor(config: PubSubProviderConfig);
+    /** Get the service name used for WebAFX service container registration */
+    get serviceName(): string;
+    /**
+     * Build the full channel name by prepending the prefix.
+     *
+     * Called by every publish/subscribe operation to ensure all channels
+     * are namespaced under the channelPrefix, preventing collisions
+     * when multiple applications share the same Redis instance.
+     *
+     * @param channel - User-provided channel name
+     * @returns Prefixed channel (e.g., prefix='MyApp', channel='order:new' → 'MyApp:order:new')
+     */
+    protected buildChannel(channel: string): string;
+    /**
+     * Build the full pattern by prepending the prefix.
+     *
+     * Used by psubscribe to namespace glob patterns the same way
+     * buildChannel namespaces exact channel names.
+     *
+     * @param pattern - User-provided pattern (e.g., 'order:*')
+     * @returns Prefixed pattern (e.g., 'MyApp:order:*')
+     */
+    protected buildChannelPattern(pattern: string): string;
+    /**
+     * Strip the channel prefix from a full channel name.
+     *
+     * Used when delivering messages to handlers — they should see
+     * the original channel name, not the internal prefixed version.
+     * This keeps the handler code agnostic of the prefix configuration.
+     *
+     * @param fullChannel - The prefixed channel (from Redis or internal store)
+     * @returns The user-facing channel name without prefix
+     */
+    protected stripPrefix(fullChannel: string): string;
+    /**
+     * Safely invoke a message handler, catching and logging errors.
+     *
+     * Handler errors must never break other subscribers or crash
+     * the subscriber connection. This method wraps every handler
+     * invocation in a try/catch and logs errors to console.error.
+     *
+     * @param handler - The handler function to invoke
+     * @param message - The message to pass to the handler
+     */
+    protected safeInvoke<T>(handler: MessageHandler<T>, message: PubSubMessage<T>): Promise<void>;
+    /**
+     * Publish a typed message to a channel.
+     *
+     * The data is JSON-serialized before sending. The channel prefix
+     * is applied automatically.
+     *
+     * @param channel - Channel name (prefix applied automatically)
+     * @param data - Message payload (will be JSON-serialized)
+     * @returns Number of subscribers that received the message
+     */
+    abstract publish<T>(channel: string, data: T): Promise<number>;
+    /**
+     * Subscribe to an exact channel with a typed handler.
+     *
+     * Multiple handlers can be registered for the same channel.
+     * The handler receives a `PubSubMessage<T>` with the deserialized
+     * payload and channel metadata.
+     *
+     * @param channel - Exact channel name (prefix applied automatically)
+     * @param handler - Function called when a message is received
+     */
+    abstract subscribe<T = unknown>(channel: string, handler: MessageHandler<T>): Promise<void>;
+    /**
+     * Unsubscribe from an exact channel.
+     *
+     * Removes all handlers for the specified channel and unsubscribes
+     * from the underlying transport.
+     *
+     * @param channel - Channel name to unsubscribe from
+     */
+    abstract unsubscribe(channel: string): Promise<void>;
+    /**
+     * Subscribe to a channel pattern with a typed handler.
+     *
+     * Pattern uses '*' as wildcard (glob matching). For example,
+     * 'order:*' matches 'order:new', 'order:cancelled', etc.
+     *
+     * @param pattern - Channel pattern (e.g., 'order:*')
+     * @param handler - Function called when a matching message is received
+     */
+    abstract psubscribe<T = unknown>(pattern: string, handler: MessageHandler<T>): Promise<void>;
+    /**
+     * Unsubscribe from a channel pattern.
+     *
+     * Removes all handlers for the specified pattern and unsubscribes
+     * from the underlying transport.
+     *
+     * @param pattern - Pattern to unsubscribe from
+     */
+    abstract punsubscribe(pattern: string): Promise<void>;
+    /**
+     * Get the list of currently active subscriptions.
+     *
+     * Returns user-facing channel/pattern names (prefix stripped).
+     *
+     * @returns Object with `channels` (exact) and `patterns` (glob) arrays
+     */
+    abstract activeSubscriptions(): {
+        channels: string[];
+        patterns: string[];
+    };
+    /**
+     * Health check — returns true if the backend is operational.
+     *
+     * For Redis: checks connectivity on both publisher and subscriber connections.
+     * For In-Memory: always returns true.
+     */
+    abstract health(): Promise<boolean>;
+    /**
+     * Graceful shutdown — unsubscribe all, close connections, release resources.
+     *
+     * For Redis: disconnects both publisher and subscriber ioredis clients.
+     * For In-Memory: removes all handlers.
+     */
+    abstract shutdown(): Promise<void>;
+}
+//# sourceMappingURL=abstract-pubsub-provider.d.ts.map

package/dist/webafx-cache/abstract-pubsub-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-pubsub-provider.d.ts","sourceRoot":"","sources":["../src/abstract-pubsub-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGtF;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,cAAc;IAChC,6CAA6C;IAC7C,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C,2CAA2C;IAC3C,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;gBACS,MAAM,EAAE,oBAAoB;IASxC,0EAA0E;IAC1E,IAAI,WAAW,IAAI,MAAM,CAExB;IAMD;;;;;;;;;OASG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAO/C;;;;;;;;OAQG;IACH,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOtD;;;;;;;;;OASG;IACH,SAAS,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAUlD;;;;;;;;;OASG;cACa,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnG;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAE9D;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3F;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5F;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAErD;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,IAAI;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CACrC"}

package/dist/webafx-cache/abstract-pubsub-provider.js

@@ -0,0 +1,132 @@
+/**
+ * Abstract base class for all pub/sub provider implementations.
+ *
+ * Provides a typed, JSON-serialized messaging API with transparent channel
+ * prefix management. Both RedisPubSubProvider and MemoryPubSubProvider
+ * extend this class and implement the abstract methods with backend-specific logic.
+ *
+ * Design principles:
+ * - Application-wide singleton (not per-request)
+ * - Channel prefix isolates channels per application/concern
+ * - Configurable serviceName for multi-pubsub scenarios
+ * - JSON serialization for all messages
+ * - All methods are async for a uniform API
+ * - Handler errors are isolated (log + continue)
+ *
+ * Architecture note:
+ * This hierarchy is completely independent from CacheProvider. They are
+ * parallel abstractions that happen to live in the same package.
+ *
+ * @packageDocumentation
+ */
+import { DEFAULT_PUBSUB_SERVICE_NAME, CHANNEL_SEPARATOR } from "./types.js";
+/**
+ * Abstract base class for pub/sub implementations.
+ *
+ * All pub/sub backends (Redis, In-Memory) derive from this class.
+ * Provides typed, JSON-serialized messaging with channel prefix support.
+ *
+ * Usage through concrete implementations:
+ * ```typescript
+ * const pubsub = new RedisPubSubProvider({ channelPrefix: 'MyApp' });
+ * await pubsub.subscribe<OrderEvent>('order:new', (msg) => {
+ *     console.log('New order:', msg.data);
+ * });
+ * await pubsub.publish('order:new', { orderId: 123, total: 49.99 });
+ * ```
+ */
+export class PubSubProvider {
+    /** Channel prefix for namespace isolation */
+    channelPrefix;
+    /** Service name for WebAFX registration */
+    _serviceName;
+    /**
+     * Initialize the pub/sub provider with configuration.
+     *
+     * @param config - Base configuration with optional channelPrefix and serviceName
+     */
+    constructor(config) {
+        this.channelPrefix = config.channelPrefix;
+        this._serviceName = config.serviceName ?? DEFAULT_PUBSUB_SERVICE_NAME;
+    }
+    // -------------------------------------------------------------------
+    // Public Accessors
+    // -------------------------------------------------------------------
+    /** Get the service name used for WebAFX service container registration */
+    get serviceName() {
+        return this._serviceName;
+    }
+    // -------------------------------------------------------------------
+    // Channel Building (protected helpers for subclasses)
+    // -------------------------------------------------------------------
+    /**
+     * Build the full channel name by prepending the prefix.
+     *
+     * Called by every publish/subscribe operation to ensure all channels
+     * are namespaced under the channelPrefix, preventing collisions
+     * when multiple applications share the same Redis instance.
+     *
+     * @param channel - User-provided channel name
+     * @returns Prefixed channel (e.g., prefix='MyApp', channel='order:new' → 'MyApp:order:new')
+     */
+    buildChannel(channel) {
+        if (this.channelPrefix) {
+            return `${this.channelPrefix}${CHANNEL_SEPARATOR}${channel}`;
+        }
+        return channel;
+    }
+    /**
+     * Build the full pattern by prepending the prefix.
+     *
+     * Used by psubscribe to namespace glob patterns the same way
+     * buildChannel namespaces exact channel names.
+     *
+     * @param pattern - User-provided pattern (e.g., 'order:*')
+     * @returns Prefixed pattern (e.g., 'MyApp:order:*')
+     */
+    buildChannelPattern(pattern) {
+        if (this.channelPrefix) {
+            return `${this.channelPrefix}${CHANNEL_SEPARATOR}${pattern}`;
+        }
+        return pattern;
+    }
+    /**
+     * Strip the channel prefix from a full channel name.
+     *
+     * Used when delivering messages to handlers — they should see
+     * the original channel name, not the internal prefixed version.
+     * This keeps the handler code agnostic of the prefix configuration.
+     *
+     * @param fullChannel - The prefixed channel (from Redis or internal store)
+     * @returns The user-facing channel name without prefix
+     */
+    stripPrefix(fullChannel) {
+        if (this.channelPrefix) {
+            const prefix = `${this.channelPrefix}${CHANNEL_SEPARATOR}`;
+            if (fullChannel.startsWith(prefix)) {
+                return fullChannel.slice(prefix.length);
+            }
+        }
+        return fullChannel;
+    }
+    /**
+     * Safely invoke a message handler, catching and logging errors.
+     *
+     * Handler errors must never break other subscribers or crash
+     * the subscriber connection. This method wraps every handler
+     * invocation in a try/catch and logs errors to console.error.
+     *
+     * @param handler - The handler function to invoke
+     * @param message - The message to pass to the handler
+     */
+    async safeInvoke(handler, message) {
+        try {
+            await handler(message);
+        }
+        catch (error) {
+            // Log and continue — handler errors must not break other subscribers
+            console.error(`[PubSub] Handler error on channel "${message.channel}":`, error instanceof Error ? error.message : error);
+        }
+    }
+}
+//# sourceMappingURL=abstract-pubsub-provider.js.map

package/dist/webafx-cache/abstract-pubsub-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-pubsub-provider.js","sourceRoot":"","sources":["../src/abstract-pubsub-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,cAAc;IAChC,6CAA6C;IACnC,aAAa,CAAqB;IAE5C,2CAA2C;IACjC,YAAY,CAAS;IAE/B;;;;OAIG;IACH,YAAY,MAA4B;QACpC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QAC1C,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,IAAI,2BAA2B,CAAC;IAC1E,CAAC;IAED,sEAAsE;IACtE,mBAAmB;IACnB,sEAAsE;IAEtE,0EAA0E;IAC1E,IAAI,WAAW;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED,sEAAsE;IACtE,sDAAsD;IACtD,sEAAsE;IAEtE;;;;;;;;;OASG;IACO,YAAY,CAAC,OAAe;QAClC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,GAAG,IAAI,CAAC,aAAa,GAAG,iBAAiB,GAAG,OAAO,EAAE,CAAC;QACjE,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;;;;;;;OAQG;IACO,mBAAmB,CAAC,OAAe;QACzC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,GAAG,IAAI,CAAC,aAAa,GAAG,iBAAiB,GAAG,OAAO,EAAE,CAAC;QACjE,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;;;;;;;;OASG;IACO,WAAW,CAAC,WAAmB;QACrC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,GAAG,iBAAiB,EAAE,CAAC;YAC3D,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjC,OAAO,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5C,CAAC;QACL,CAAC;QACD,OAAO,WAAW,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACO,KAAK,CAAC,UAAU,CAAI,OAA0B,EAAE,OAAyB;QAC/E,IAAI,CAAC;YACD,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,qEAAqE;YACrE,OAAO,CAAC,KAAK,CACT,sCAAsC,OAAO,CAAC,OAAO,IAAI,EACzD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CACjD,CAAC;QACN,CAAC;IACL,CAAC;CAqFJ"}