ts-packages 1.0.0 → 3.0.0

package/packages/cache/dist/esm/adapters/redis/RedisCache.js

@@ -0,0 +1,379 @@
+import { createClient, createCluster } from 'redis';
+import { CACHE_ERROR_CODES } from 'src/errors/cacheErrorCodes';
+import { BaseCache } from '../../core/BaseCache';
+import { CacheError } from '../../errors';
+/**
+ * Redis cache adapter
+ */
+export class RedisCache extends BaseCache {
+    constructor(redisConfig) {
+        super(redisConfig);
+        this.redisConfig = redisConfig;
+        this.client = null;
+        this.isConnected = false;
+    }
+    /**
+     * Connect to Redis
+     */
+    async connect() {
+        try {
+            const cluster = this.redisConfig.cluster;
+            const hasCluster = cluster &&
+                (Array.isArray(cluster)
+                    ? cluster.length > 0
+                    : cluster.nodes?.length > 0);
+            if (hasCluster && cluster) {
+                // Cluster mode
+                let nodes = [];
+                if (Array.isArray(cluster)) {
+                    nodes = cluster;
+                }
+                else {
+                    nodes = cluster.nodes;
+                }
+                this.client = createCluster({
+                    rootNodes: nodes.map((node) => ({
+                        url: `redis://${node.host}:${node.port}`,
+                    })),
+                });
+            }
+            else {
+                // Single instance mode
+                const options = {
+                    host: this.redisConfig.host ?? 'localhost',
+                    port: this.redisConfig.port ?? 6379,
+                    db: this.redisConfig.db ?? 0,
+                };
+                if (this.redisConfig.username) {
+                    options.username = this.redisConfig.username;
+                }
+                if (this.redisConfig.password) {
+                    options.password = this.redisConfig.password;
+                }
+                if (this.redisConfig.tls) {
+                    options.tls = true;
+                }
+                this.client = createClient(options);
+            }
+            if (this.client) {
+                this.client.on('error', (err) => {
+                    this.isConnected = false;
+                    console.error('Redis connection error:', err);
+                });
+                this.client.on('connect', () => {
+                    this.isConnected = true;
+                });
+                await this.client.connect();
+                this.isConnected = true;
+            }
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_CONNECTION_FAILED, {
+                adapter: 'redis',
+                operation: 'connect',
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Ensure client is connected
+     */
+    async ensureConnected() {
+        if (!this.client) {
+            await this.connect();
+        }
+    }
+    /**
+     * Get a value from Redis
+     */
+    async get(key) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            const value = await this.client.get(fullKey);
+            if (value === null) {
+                this.recordMiss();
+                return null;
+            }
+            this.recordHit();
+            return this.deserialize(value);
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'get',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Set a value in Redis
+     */
+    async set(key, value, ttl) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            const serialized = this.serialize(value);
+            const expiry = ttl ?? this.ttl;
+            if (expiry > 0) {
+                await this.client.setEx(fullKey, expiry, serialized);
+            }
+            else {
+                await this.client.set(fullKey, serialized);
+            }
+            this.recordSet();
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'set',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Delete a key from Redis
+     */
+    async delete(key) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            const result = await this.client.del(fullKey);
+            this.recordDelete();
+            return result > 0;
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'delete',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Check if key exists
+     */
+    async exists(key) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            const result = await this.client.exists(fullKey);
+            return result > 0;
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'exists',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Clear all keys with current namespace
+     */
+    async clear() {
+        try {
+            await this.ensureConnected();
+            if (this.namespace) {
+                // For cluster mode, we can't use FLUSHDB, so we skip clearing in cluster
+                // In production, use explicit key tracking or Redis ACL scoping
+                console.warn('Cluster mode: namespace clear requires explicit key tracking');
+            }
+            else {
+                // Clear all keys only in single-instance mode
+                const client = this.client;
+                if (client && typeof client.flushDb === 'function') {
+                    await client.flushDb();
+                }
+                else {
+                    console.warn('Clear operation not supported in cluster mode');
+                }
+            }
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_OPERATION_TIMEOUT, {
+                adapter: 'redis',
+                operation: 'clear',
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Get multiple values at once
+     */
+    async getMultiple(keys) {
+        try {
+            await this.ensureConnected();
+            const fullKeys = keys.map((k) => this.buildKey(k));
+            const values = await this.client.mGet(fullKeys);
+            const result = {};
+            keys.forEach((key, index) => {
+                const value = values[index];
+                if (value === null) {
+                    this.recordMiss();
+                    result[key] = null;
+                }
+                else {
+                    this.recordHit();
+                    result[key] = this.deserialize(value);
+                }
+            });
+            return result;
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'getMultiple',
+                details: { keys },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Set multiple values at once
+     */
+    async setMultiple(data, ttl) {
+        try {
+            await this.ensureConnected();
+            const expiry = ttl ?? this.ttl;
+            if (expiry > 0) {
+                // Use pipeline for batch operations with TTL
+                const pipeline = this.client.multi();
+                for (const [key, value] of Object.entries(data)) {
+                    const fullKey = this.buildKey(key);
+                    const serialized = this.serialize(value);
+                    pipeline.setEx(fullKey, expiry, serialized);
+                }
+                await pipeline.exec();
+            }
+            else {
+                // Use mSet for batch operations without TTL
+                const flatData = {};
+                for (const [key, value] of Object.entries(data)) {
+                    const fullKey = this.buildKey(key);
+                    flatData[fullKey] = this.serialize(value);
+                }
+                await this.client.mSet(flatData);
+            }
+            this.stats.sets += Object.keys(data).length;
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'setMultiple',
+                details: { keys: Object.keys(data) },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Delete multiple keys at once
+     */
+    async deleteMultiple(keys) {
+        try {
+            await this.ensureConnected();
+            const fullKeys = keys.map((k) => this.buildKey(k));
+            const result = await this.client.del(fullKeys);
+            this.stats.deletes += result;
+            return result;
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'deleteMultiple',
+                details: { keys },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Increment a numeric value
+     */
+    async increment(key, amount = 1) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            return await this.client.incrBy(fullKey, amount);
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'increment',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Decrement a numeric value
+     */
+    async decrement(key, amount = 1) {
+        try {
+            await this.ensureConnected();
+            const fullKey = this.buildKey(key);
+            return await this.client.decrBy(fullKey, amount);
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'decrement',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Check if Redis is alive
+     */
+    async isAlive() {
+        try {
+            await this.ensureConnected();
+            // Use sendCommand which works for both single and cluster
+            // `sendCommand` exists on both single and cluster clients in runtime; cast narrowly for the call
+            if (this.client &&
+                typeof this.client.sendCommand === 'function') {
+                await this.client.sendCommand(['PING']);
+            }
+            else if (this.client &&
+                typeof this.client.ping === 'function') {
+                await this.client.ping();
+            }
+            return {
+                isAlive: true,
+                adapter: 'redis',
+                timestamp: new Date(),
+            };
+        }
+        catch (error) {
+            return {
+                isAlive: false,
+                adapter: 'redis',
+                timestamp: new Date(),
+                error: error.message,
+            };
+        }
+    }
+    /**
+     * Close Redis connection
+     */
+    async close() {
+        try {
+            if (this.client && this.isConnected) {
+                await this.client.quit();
+                this.isConnected = false;
+                this.client = null;
+            }
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'redis',
+                operation: 'close',
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+}

package/packages/cache/dist/esm/adapters/redis/index.d.ts

@@ -0,0 +1 @@
+export { RedisCache } from './RedisCache';

package/packages/cache/dist/esm/adapters/redis/index.js

@@ -0,0 +1 @@
+export { RedisCache } from './RedisCache';

package/packages/cache/dist/esm/core/BaseCache.d.ts

@@ -0,0 +1,78 @@
+import type { BatchResult, CacheConfig, CacheStats, HealthCheckResponse } from '../types';
+import type { ICache } from './interfaces';
+/**
+ * Abstract base class for all cache adapters
+ */
+export declare abstract class BaseCache<T = unknown> implements ICache<T> {
+    protected config: CacheConfig;
+    protected readonly namespace: string;
+    protected readonly ttl: number;
+    protected stats: CacheStats;
+    constructor(config: CacheConfig);
+    /**
+     * Build full key with namespace prefix
+     */
+    protected buildKey(key: string): string;
+    /**
+     * Deserialize string to object
+     */
+    protected deserialize(data: string): T;
+    /**
+     * Serialize object to string
+     */
+    protected serialize(value: T): string;
+    /**
+     * Track cache hit
+     */
+    protected recordHit(): void;
+    /**
+     * Track cache miss
+     */
+    protected recordMiss(): void;
+    /**
+     * Track cache set
+     */
+    protected recordSet(): void;
+    /**
+     * Track cache delete
+     */
+    protected recordDelete(): void;
+    /**
+     * Reset statistics
+     */
+    protected resetStats(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Abstract methods - must be implemented by subclasses
+     */
+    abstract get(key: string): Promise<T | null>;
+    abstract set(key: string, value: T, ttl?: number): Promise<void>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract clear(): Promise<void>;
+    abstract isAlive(): Promise<HealthCheckResponse>;
+    abstract close(): Promise<void>;
+    /**
+     * Default implementation for getMultiple
+     */
+    getMultiple(keys: string[]): Promise<BatchResult<T>>;
+    /**
+     * Default implementation for setMultiple
+     */
+    setMultiple(data: Record<string, T>, ttl?: number): Promise<void>;
+    /**
+     * Default implementation for deleteMultiple
+     */
+    deleteMultiple(keys: string[]): Promise<number>;
+    /**
+     * Default implementation for increment
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Default implementation for decrement
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+}

package/packages/cache/dist/esm/core/BaseCache.js

@@ -0,0 +1,143 @@
+import { CACHE_ERROR_CODES } from 'src/errors/cacheErrorCodes';
+import { CacheError } from '../errors';
+/**
+ * Abstract base class for all cache adapters
+ */
+export class BaseCache {
+    constructor(config) {
+        this.config = config;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            sets: 0,
+            deletes: 0,
+        };
+        this.namespace = config.namespace ? `${config.namespace}:` : '';
+        this.ttl = config.ttl ?? 3600; // 1 hour default
+    }
+    /**
+     * Build full key with namespace prefix
+     */
+    buildKey(key) {
+        return `${this.namespace}${key}`;
+    }
+    /**
+     * Deserialize string to object
+     */
+    deserialize(data) {
+        try {
+            return JSON.parse(data);
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_DESERIALIZE_ERROR, {
+                adapter: this.config.adapter,
+                operation: 'deserialize',
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Serialize object to string
+     */
+    serialize(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch (error) {
+            throw new CacheError(CACHE_ERROR_CODES.CACHE_SERIALIZE_ERROR, {
+                adapter: this.config.adapter,
+                operation: 'serialize',
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    /**
+     * Track cache hit
+     */
+    recordHit() {
+        this.stats.hits++;
+    }
+    /**
+     * Track cache miss
+     */
+    recordMiss() {
+        this.stats.misses++;
+    }
+    /**
+     * Track cache set
+     */
+    recordSet() {
+        this.stats.sets++;
+    }
+    /**
+     * Track cache delete
+     */
+    recordDelete() {
+        this.stats.deletes++;
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            sets: 0,
+            deletes: 0,
+        };
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Default implementation for getMultiple
+     */
+    async getMultiple(keys) {
+        const result = {};
+        for (const key of keys) {
+            result[key] = await this.get(key);
+        }
+        return result;
+    }
+    /**
+     * Default implementation for setMultiple
+     */
+    async setMultiple(data, ttl) {
+        for (const [key, value] of Object.entries(data)) {
+            await this.set(key, value, ttl);
+        }
+    }
+    /**
+     * Default implementation for deleteMultiple
+     */
+    async deleteMultiple(keys) {
+        let count = 0;
+        for (const key of keys) {
+            const deleted = await this.delete(key);
+            if (deleted)
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Default implementation for increment
+     */
+    async increment(key, amount = 1) {
+        const current = await this.get(key);
+        const value = (typeof current === 'number' ? current : 0) + amount;
+        await this.set(key, value);
+        return value;
+    }
+    /**
+     * Default implementation for decrement
+     */
+    async decrement(key, amount = 1) {
+        const current = await this.get(key);
+        const value = (typeof current === 'number' ? current : 0) - amount;
+        await this.set(key, value);
+        return value;
+    }
+}

package/packages/cache/dist/esm/core/factory.d.ts

@@ -0,0 +1,16 @@
+import type { CacheConfig } from '../types';
+import type { ICache } from './interfaces';
+/**
+ * Factory for creating cache instances
+ */
+export declare class CacheFactory {
+    /**
+     * Create a cache instance based on configuration
+     */
+    static create<T = unknown>(config: CacheConfig): ICache<T>;
+    /**
+     * Create a cache with fallback support
+     * If primary adapter fails to connect, falls back to memory cache
+     */
+    static createWithFallback<T = unknown>(config: CacheConfig): Promise<ICache<T>>;
+}

package/packages/cache/dist/esm/core/factory.js

@@ -0,0 +1,78 @@
+import { CACHE_ERROR_CODES } from 'src/errors/cacheErrorCodes';
+import { MemcacheCache } from '../adapters/memcache';
+import { MemoryCache } from '../adapters/memory';
+import { RedisCache } from '../adapters/redis';
+import { CacheError } from '../errors';
+/**
+ * Factory for creating cache instances
+ */
+export class CacheFactory {
+    /**
+     * Create a cache instance based on configuration
+     */
+    static create(config) {
+        switch (config.adapter) {
+            case 'redis':
+                const redisConfig = config;
+                // Validate: can't use both single + cluster
+                if (redisConfig.host && redisConfig.cluster) {
+                    throw new CacheError(CACHE_ERROR_CODES.CACHE_INVALID_CONFIG, {
+                        adapter: 'redis',
+                        operation: 'create',
+                        details: {
+                            reason: 'Redis config cannot have both "host" and "cluster" defined',
+                        },
+                    });
+                }
+                // Require either single or cluster
+                if (!redisConfig.host && !redisConfig.cluster) {
+                    throw new CacheError(CACHE_ERROR_CODES.CACHE_INVALID_CONFIG, {
+                        adapter: 'redis',
+                        operation: 'create',
+                        details: {
+                            reason: 'Redis requires either host or cluster config',
+                        },
+                    });
+                }
+                return new RedisCache(redisConfig);
+            case 'memcache':
+                return new MemcacheCache(config);
+            case 'memory':
+                return new MemoryCache(config);
+            default:
+                throw new CacheError(CACHE_ERROR_CODES.CACHE_UNSUPPORTED_ADAPTER, {
+                    adapter: config.adapter,
+                    operation: 'create',
+                });
+        }
+    }
+    /**
+     * Create a cache with fallback support
+     * If primary adapter fails to connect, falls back to memory cache
+     */
+    static async createWithFallback(config) {
+        const cache = this.create(config);
+        // Check if primary cache is alive
+        const health = await cache.isAlive();
+        if (health.isAlive) {
+            return cache;
+        }
+        // If primary cache failed and fallback is enabled, use memory cache
+        if (config.fallback !== false) {
+            console.warn(`Failed to connect to ${config.adapter} cache, falling back to memory cache`);
+            return new MemoryCache({
+                adapter: 'memory',
+                namespace: config.namespace,
+                ttl: config.ttl,
+            });
+        }
+        // No fallback, throw error
+        throw new CacheError(CACHE_ERROR_CODES.CACHE_CONNECTION_FAILED, {
+            adapter: config.adapter,
+            operation: 'createWithFallback',
+            details: {
+                reason: `${config.adapter} cache is not alive and fallback is disabled`,
+            },
+        });
+    }
+}