blendsdk 5.33.0

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

@@ -0,0 +1,251 @@
+/**
+ * In-memory cache provider with TTL support.
+ *
+ * Zero external dependencies — suitable for development, testing,
+ * and single-instance applications. Mimics Redis behavior:
+ * - TTL in seconds (stored as expiration timestamps)
+ * - Returns -1 for no expiry, -2 for missing key (ttl method)
+ * - Pattern matching with * wildcard
+ * - Periodic cleanup of expired entries
+ *
+ * Values are JSON-serialized/deserialized to match Redis behavior,
+ * ensuring what goes in is what comes out with no reference sharing.
+ *
+ * @packageDocumentation
+ */
+import { CacheProvider } from "./abstract-cache-provider.js";
+// ---------------------------------------------------------------------------
+// Default Constants
+// ---------------------------------------------------------------------------
+/** Default cleanup interval: 60 seconds */
+const DEFAULT_CLEANUP_INTERVAL_MS = 60_000;
+// ---------------------------------------------------------------------------
+// MemoryCacheProvider
+// ---------------------------------------------------------------------------
+/**
+ * In-memory cache provider with TTL support.
+ *
+ * Uses a `Map<string, MemoryCacheEntry>` for storage with JSON serialization
+ * to match Redis behavior. Expired entries are lazily evicted on access and
+ * periodically cleaned up via a configurable interval timer.
+ *
+ * @example
+ * ```typescript
+ * const cache = new MemoryCacheProvider({
+ *     rootKey: 'TestApp',
+ *     defaultTTL: 60,
+ *     cleanupIntervalMs: 5000,
+ * });
+ *
+ * await cache.set('key', { data: true });
+ * const value = await cache.get<{ data: boolean }>('key');
+ * ```
+ */
+export class MemoryCacheProvider extends CacheProvider {
+    /** Internal storage map: prefixed key → cache entry */
+    store;
+    /** Handle for the periodic cleanup interval (undefined if stopped) */
+    cleanupInterval;
+    /** Cleanup interval in milliseconds */
+    cleanupIntervalMs;
+    /**
+     * Create a new in-memory cache provider.
+     *
+     * @param config - Memory cache configuration with rootKey and optional cleanup interval
+     */
+    constructor(config) {
+        super(config);
+        this.store = new Map();
+        this.cleanupIntervalMs = config.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
+        // Start periodic cleanup of expired entries to prevent memory leaks
+        this.startCleanup();
+    }
+    // -----------------------------------------------------------------------
+    // Core Operations
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async set(key, value, ttlSeconds) {
+        const fullKey = this.buildKey(key);
+        const serialized = JSON.stringify(value);
+        const effectiveTTL = this.resolveTTL(ttlSeconds);
+        const entry = {
+            value: serialized,
+            // Convert TTL in seconds to an absolute expiration timestamp in ms
+            expiresAt: effectiveTTL !== undefined ? Date.now() + effectiveTTL * 1000 : undefined,
+        };
+        this.store.set(fullKey, entry);
+    }
+    /** @inheritDoc */
+    async get(key) {
+        const fullKey = this.buildKey(key);
+        const entry = this.store.get(fullKey);
+        if (!entry) {
+            return undefined;
+        }
+        // Lazy eviction: check if the entry has expired
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.store.delete(fullKey);
+            return undefined;
+        }
+        // Deserialize — treat parse failures as cache miss (matches Redis provider)
+        try {
+            return JSON.parse(entry.value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** @inheritDoc */
+    async delete(key) {
+        const fullKey = this.buildKey(key);
+        return this.store.delete(fullKey);
+    }
+    /** @inheritDoc */
+    async exists(key) {
+        const fullKey = this.buildKey(key);
+        const entry = this.store.get(fullKey);
+        if (!entry) {
+            return false;
+        }
+        // Lazy eviction: check if the entry has expired
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.store.delete(fullKey);
+            return false;
+        }
+        return true;
+    }
+    /** @inheritDoc */
+    async expire(key, ttlSeconds) {
+        const fullKey = this.buildKey(key);
+        const entry = this.store.get(fullKey);
+        if (!entry) {
+            return false;
+        }
+        // Cannot update TTL on an already-expired entry
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.store.delete(fullKey);
+            return false;
+        }
+        // Update the expiration timestamp
+        entry.expiresAt = Date.now() + ttlSeconds * 1000;
+        return true;
+    }
+    /** @inheritDoc */
+    async ttl(key) {
+        const fullKey = this.buildKey(key);
+        const entry = this.store.get(fullKey);
+        // Key doesn't exist
+        if (!entry) {
+            return -2;
+        }
+        // Lazy eviction: check if the entry has expired
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.store.delete(fullKey);
+            return -2;
+        }
+        // No expiry set — key persists indefinitely
+        if (entry.expiresAt === undefined) {
+            return -1;
+        }
+        // Calculate remaining TTL in seconds (round up to match Redis behavior)
+        const remaining = Math.ceil((entry.expiresAt - Date.now()) / 1000);
+        return remaining > 0 ? remaining : -2;
+    }
+    // -----------------------------------------------------------------------
+    // Pattern Operations
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async deletePattern(pattern) {
+        const fullPattern = this.buildPattern(pattern);
+        const regex = this.patternToRegex(fullPattern);
+        let deleted = 0;
+        // Collect keys first to avoid mutating the map during iteration
+        const keysToDelete = [];
+        for (const key of this.store.keys()) {
+            if (regex.test(key)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.store.delete(key);
+            deleted++;
+        }
+        return deleted;
+    }
+    /** @inheritDoc */
+    async clear() {
+        // Only delete keys under this rootKey namespace (not other namespaces)
+        const prefix = this.buildKey("");
+        // Collect keys first to avoid mutating the map during iteration
+        const keysToDelete = [];
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.store.delete(key);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------------------------------
+    /** @inheritDoc */
+    async health() {
+        // In-memory cache is always healthy as long as the process is running
+        return true;
+    }
+    /** @inheritDoc */
+    async shutdown() {
+        // Stop the cleanup interval to prevent further timer callbacks
+        if (this.cleanupInterval !== undefined) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        // Clear all entries from the store
+        this.store.clear();
+    }
+    // -----------------------------------------------------------------------
+    // Internal Helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Convert a glob-style pattern (with * wildcards) to a RegExp.
+     *
+     * Escapes all regex special characters except *, which becomes .* to
+     * match any sequence of characters (mimicking Redis SCAN MATCH behavior).
+     *
+     * @param pattern - Glob pattern (e.g., 'MyApp:user:*')
+     * @returns RegExp that matches the pattern
+     */
+    patternToRegex(pattern) {
+        const escaped = pattern
+            .replace(/[.+?^${}()|[\]\\]/g, "\\$&") // Escape regex specials
+            .replace(/\*/g, ".*"); // Convert * wildcard to .*
+        return new RegExp(`^${escaped}$`);
+    }
+    /**
+     * Start periodic cleanup of expired entries.
+     *
+     * Prevents unbounded memory growth from expired-but-not-accessed entries.
+     * The interval timer is unref'd so it doesn't prevent Node.js from exiting.
+     */
+    startCleanup() {
+        // Only start if interval is positive (0 or negative disables cleanup)
+        if (this.cleanupIntervalMs <= 0) {
+            return;
+        }
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [key, entry] of this.store.entries()) {
+                if (entry.expiresAt !== undefined && now > entry.expiresAt) {
+                    this.store.delete(key);
+                }
+            }
+        }, this.cleanupIntervalMs);
+        // Unref so the interval doesn't prevent the Node.js process from exiting
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+}
+//# sourceMappingURL=memory-cache-provider.js.map

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

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

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

@@ -0,0 +1,124 @@
+/**
+ * In-memory pub/sub provider for development and testing.
+ *
+ * Uses in-process Maps and EventEmitter-style delivery. No network connections
+ * or external dependencies — perfect for unit tests and local development.
+ *
+ * Key behaviors:
+ * - JSON round-trip on publish (matches Redis serialization behavior)
+ * - Glob pattern matching via regex conversion (supports *, ?)
+ * - Synchronous delivery within the same event loop tick
+ * - Handler errors isolated via safeInvoke (log + continue)
+ * - Health always returns true (no external dependencies)
+ *
+ * @packageDocumentation
+ */
+import { PubSubProvider } from "./abstract-pubsub-provider.js";
+import type { MemoryPubSubConfig, MessageHandler } from "./types.js";
+/**
+ * In-memory pub/sub provider for development and testing.
+ *
+ * Delivers messages synchronously within the same process.
+ * No external connections required — always healthy.
+ *
+ * @example
+ * ```typescript
+ * const pubsub = new MemoryPubSubProvider({ channelPrefix: 'Test' });
+ * await pubsub.subscribe<string>('greet', (msg) => console.log(msg.data));
+ * await pubsub.publish('greet', 'Hello!');
+ * ```
+ */
+export declare class MemoryPubSubProvider extends PubSubProvider {
+    /** Exact channel handlers: Map<userChannel, Set<MessageHandler>> */
+    protected handlers: Map<string, Set<MessageHandler>>;
+    /** Pattern handlers: Map<userPattern, Set<MessageHandler>> */
+    protected patternHandlers: Map<string, Set<MessageHandler>>;
+    /**
+     * Create a new in-memory pub/sub provider.
+     *
+     * @param config - Optional configuration with channelPrefix and serviceName
+     */
+    constructor(config?: MemoryPubSubConfig);
+    /**
+     * Publish a message to a channel.
+     *
+     * Performs a JSON round-trip to match Redis behavior:
+     * - Ensures data is JSON-serializable (throws if not)
+     * - Handlers receive a new object (no shared references)
+     *
+     * @param channel - Channel name (prefix applied automatically)
+     * @param data - Message payload (will be JSON-serialized)
+     * @returns Number of handlers that received the message
+     */
+    publish<T>(channel: string, data: T): Promise<number>;
+    /**
+     * Subscribe to an exact channel.
+     *
+     * Multiple handlers can be registered for the same channel.
+     * Duplicate handlers are deduplicated by the underlying Set.
+     *
+     * @param channel - Exact channel name
+     * @param handler - Handler function for incoming messages
+     */
+    subscribe<T = unknown>(channel: string, handler: MessageHandler<T>): Promise<void>;
+    /**
+     * Unsubscribe from an exact channel.
+     * Removes all handlers for the specified channel.
+     *
+     * @param channel - Channel name to unsubscribe from
+     */
+    unsubscribe(channel: string): Promise<void>;
+    /**
+     * Subscribe to a channel pattern with glob wildcards.
+     *
+     * Supports Redis-style glob patterns:
+     * - `*` matches any sequence of characters
+     * - `?` matches exactly one character
+     *
+     * @param pattern - Glob pattern (e.g., 'order:*')
+     * @param handler - Handler function for matching messages
+     */
+    psubscribe<T = unknown>(pattern: string, handler: MessageHandler<T>): Promise<void>;
+    /**
+     * Unsubscribe from a channel pattern.
+     * Removes all handlers for the specified pattern.
+     *
+     * @param pattern - Pattern to unsubscribe from
+     */
+    punsubscribe(pattern: string): Promise<void>;
+    /**
+     * Get currently active subscriptions.
+     *
+     * @returns Object with exact `channels` and glob `patterns` arrays
+     */
+    activeSubscriptions(): {
+        channels: string[];
+        patterns: string[];
+    };
+    /**
+     * Health check — always returns true for in-memory provider.
+     * There are no external connections to verify.
+     */
+    health(): Promise<boolean>;
+    /**
+     * Shutdown — clears all handlers.
+     * No connections to close for in-memory provider.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Match a channel name against a glob pattern.
+     *
+     * Converts glob syntax to a regular expression:
+     * - `*` → `.*` (match any sequence of characters)
+     * - `?` → `.` (match exactly one character)
+     *
+     * All other regex-special characters are escaped to prevent
+     * accidental regex injection from channel or pattern names.
+     *
+     * @param channel - The channel name to test
+     * @param pattern - The glob pattern to match against
+     * @returns true if the channel matches the pattern
+     */
+    protected matchGlob(channel: string, pattern: string): boolean;
+}
+//# sourceMappingURL=memory-pubsub-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-pubsub-provider.d.ts","sourceRoot":"","sources":["../src/memory-pubsub-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAEpF;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACpD,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;IAErD,8DAA8D;IAC9D,SAAS,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;IAE5D;;;;OAIG;gBACS,MAAM,CAAC,EAAE,kBAAkB;IAUvC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAoC3D;;;;;;;;OAQG;IACG,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxF;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;;;;;;OASG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzF;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,mBAAmB,IAAI;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;IAWjE;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;CASjE"}

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

@@ -0,0 +1,195 @@
+/**
+ * In-memory pub/sub provider for development and testing.
+ *
+ * Uses in-process Maps and EventEmitter-style delivery. No network connections
+ * or external dependencies — perfect for unit tests and local development.
+ *
+ * Key behaviors:
+ * - JSON round-trip on publish (matches Redis serialization behavior)
+ * - Glob pattern matching via regex conversion (supports *, ?)
+ * - Synchronous delivery within the same event loop tick
+ * - Handler errors isolated via safeInvoke (log + continue)
+ * - Health always returns true (no external dependencies)
+ *
+ * @packageDocumentation
+ */
+import { PubSubProvider } from "./abstract-pubsub-provider.js";
+/**
+ * In-memory pub/sub provider for development and testing.
+ *
+ * Delivers messages synchronously within the same process.
+ * No external connections required — always healthy.
+ *
+ * @example
+ * ```typescript
+ * const pubsub = new MemoryPubSubProvider({ channelPrefix: 'Test' });
+ * await pubsub.subscribe<string>('greet', (msg) => console.log(msg.data));
+ * await pubsub.publish('greet', 'Hello!');
+ * ```
+ */
+export class MemoryPubSubProvider extends PubSubProvider {
+    /** Exact channel handlers: Map<userChannel, Set<MessageHandler>> */
+    handlers;
+    /** Pattern handlers: Map<userPattern, Set<MessageHandler>> */
+    patternHandlers;
+    /**
+     * Create a new in-memory pub/sub provider.
+     *
+     * @param config - Optional configuration with channelPrefix and serviceName
+     */
+    constructor(config) {
+        super(config ?? {});
+        this.handlers = new Map();
+        this.patternHandlers = new Map();
+    }
+    // -------------------------------------------------------------------
+    // Core Operations
+    // -------------------------------------------------------------------
+    /**
+     * Publish a message to a channel.
+     *
+     * Performs a JSON round-trip to match Redis behavior:
+     * - Ensures data is JSON-serializable (throws if not)
+     * - Handlers receive a new object (no shared references)
+     *
+     * @param channel - Channel name (prefix applied automatically)
+     * @param data - Message payload (will be JSON-serialized)
+     * @returns Number of handlers that received the message
+     */
+    async publish(channel, data) {
+        // JSON round-trip to match Redis behavior — ensures serializable data
+        // and gives handlers a fresh copy (no shared references)
+        const serialized = JSON.stringify(data);
+        const deserialized = JSON.parse(serialized);
+        let receiverCount = 0;
+        // Deliver to exact channel handlers
+        const channelHandlers = this.handlers.get(channel);
+        if (channelHandlers) {
+            for (const handler of channelHandlers) {
+                const envelope = { channel, data: deserialized };
+                void this.safeInvoke(handler, envelope);
+                receiverCount++;
+            }
+        }
+        // Deliver to matching pattern handlers
+        for (const [pattern, patternHandlerSet] of this.patternHandlers) {
+            if (this.matchGlob(channel, pattern)) {
+                for (const handler of patternHandlerSet) {
+                    const envelope = {
+                        channel,
+                        data: deserialized,
+                        pattern,
+                    };
+                    void this.safeInvoke(handler, envelope);
+                    receiverCount++;
+                }
+            }
+        }
+        return receiverCount;
+    }
+    /**
+     * Subscribe to an exact channel.
+     *
+     * Multiple handlers can be registered for the same channel.
+     * Duplicate handlers are deduplicated by the underlying Set.
+     *
+     * @param channel - Exact channel name
+     * @param handler - Handler function for incoming messages
+     */
+    async subscribe(channel, handler) {
+        if (!this.handlers.has(channel)) {
+            this.handlers.set(channel, new Set());
+        }
+        this.handlers.get(channel).add(handler);
+    }
+    /**
+     * Unsubscribe from an exact channel.
+     * Removes all handlers for the specified channel.
+     *
+     * @param channel - Channel name to unsubscribe from
+     */
+    async unsubscribe(channel) {
+        this.handlers.delete(channel);
+    }
+    /**
+     * Subscribe to a channel pattern with glob wildcards.
+     *
+     * Supports Redis-style glob patterns:
+     * - `*` matches any sequence of characters
+     * - `?` matches exactly one character
+     *
+     * @param pattern - Glob pattern (e.g., 'order:*')
+     * @param handler - Handler function for matching messages
+     */
+    async psubscribe(pattern, handler) {
+        if (!this.patternHandlers.has(pattern)) {
+            this.patternHandlers.set(pattern, new Set());
+        }
+        this.patternHandlers.get(pattern).add(handler);
+    }
+    /**
+     * Unsubscribe from a channel pattern.
+     * Removes all handlers for the specified pattern.
+     *
+     * @param pattern - Pattern to unsubscribe from
+     */
+    async punsubscribe(pattern) {
+        this.patternHandlers.delete(pattern);
+    }
+    /**
+     * Get currently active subscriptions.
+     *
+     * @returns Object with exact `channels` and glob `patterns` arrays
+     */
+    activeSubscriptions() {
+        return {
+            channels: Array.from(this.handlers.keys()),
+            patterns: Array.from(this.patternHandlers.keys()),
+        };
+    }
+    // -------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------
+    /**
+     * Health check — always returns true for in-memory provider.
+     * There are no external connections to verify.
+     */
+    async health() {
+        return true;
+    }
+    /**
+     * Shutdown — clears all handlers.
+     * No connections to close for in-memory provider.
+     */
+    async shutdown() {
+        this.handlers.clear();
+        this.patternHandlers.clear();
+    }
+    // -------------------------------------------------------------------
+    // Internal: Glob Matching
+    // -------------------------------------------------------------------
+    /**
+     * Match a channel name against a glob pattern.
+     *
+     * Converts glob syntax to a regular expression:
+     * - `*` → `.*` (match any sequence of characters)
+     * - `?` → `.` (match exactly one character)
+     *
+     * All other regex-special characters are escaped to prevent
+     * accidental regex injection from channel or pattern names.
+     *
+     * @param channel - The channel name to test
+     * @param pattern - The glob pattern to match against
+     * @returns true if the channel matches the pattern
+     */
+    matchGlob(channel, pattern) {
+        // Escape regex special chars, then convert glob wildcards to regex equivalents
+        const regexStr = pattern
+            .replace(/[.+^${}()|[\]\\]/g, "\\$&") // Escape regex specials (not * or ?)
+            .replace(/\*/g, ".*") // * → .* (any sequence)
+            .replace(/\?/g, "."); // ? → . (single char)
+        const regex = new RegExp(`^${regexStr}$`);
+        return regex.test(channel);
+    }
+}
+//# sourceMappingURL=memory-pubsub-provider.js.map

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

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