ts-packages 1.0.0 → 2.0.0

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,134 @@
+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 (err) {
+            throw new CacheError(`Failed to deserialize cache value for key`, 'DESERIALIZE_ERROR', this.config.adapter, err);
+        }
+    }
+    /**
+     * Serialize object to string
+     */
+    serialize(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch (err) {
+            throw new CacheError(`Failed to serialize cache value`, 'SERIALIZE_ERROR', this.config.adapter, err);
+        }
+    }
+    /**
+     * 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,56 @@
+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('Cannot specify both host and cluster config', 'INVALID_CONFIG');
+                }
+                // Require either single or cluster
+                if (!redisConfig.host && !redisConfig.cluster) {
+                    throw new CacheError('Redis requires either host or cluster config', 'INVALID_CONFIG');
+                }
+                return new RedisCache(redisConfig);
+            case 'memcache':
+                return new MemcacheCache(config);
+            case 'memory':
+                return new MemoryCache(config);
+            default:
+                throw new CacheError(`Unknown cache adapter: ${config.adapter}`, 'UNKNOWN_ADAPTER');
+        }
+    }
+    /**
+     * 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(`Failed to initialize ${config.adapter} cache and fallback is disabled`, 'CACHE_INIT_ERROR');
+    }
+}

package/packages/cache/dist/esm/core/interfaces/ICache.d.ts

@@ -0,0 +1,58 @@
+import type { BatchResult, CacheStats, HealthCheckResponse } from '../../types';
+/**
+ * Main cache interface - defines all cache operations
+ */
+export interface ICache<T = unknown> {
+    /**
+     * Get a value from cache
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get multiple values at once
+     */
+    getMultiple(keys: string[]): Promise<BatchResult<T>>;
+    /**
+     * Set multiple values at once
+     */
+    setMultiple(data: Record<string, T>, ttl?: number): Promise<void>;
+    /**
+     * Delete multiple keys at once
+     */
+    deleteMultiple(keys: string[]): Promise<number>;
+    /**
+     * Increment a numeric value
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Decrement a numeric value
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+    /**
+     * Get cache statistics
+     */
+    getStats?(): Promise<CacheStats>;
+    /**
+     * Check cache health
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close/disconnect cache connection
+     */
+    close(): Promise<void>;
+}

package/packages/cache/dist/esm/core/interfaces/ICache.js

@@ -0,0 +1 @@
+export {};

package/packages/cache/dist/esm/core/interfaces/ISession.d.ts

@@ -0,0 +1,30 @@
+import type { SessionData } from '../../types';
+/**
+ * Session store interface
+ */
+export interface ISession {
+    /**
+     * Get session data
+     */
+    get(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Set session data
+     */
+    set(sessionId: string, data: SessionData, ttl?: number): Promise<void>;
+    /**
+     * Delete session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
+    /**
+     * Update/merge session data
+     */
+    update(sessionId: string, data: Partial<SessionData>): Promise<void>;
+}

package/packages/cache/dist/esm/core/interfaces/ISession.js

@@ -0,0 +1 @@
+export {};

package/packages/cache/dist/esm/core/interfaces/index.d.ts

@@ -0,0 +1,2 @@
+export { ICache } from './ICache';
+export { ISession } from './ISession';

package/packages/cache/dist/esm/core/interfaces/index.js

@@ -0,0 +1 @@
+export {};

package/packages/cache/dist/esm/errors/CacheError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Custom error class for cache operations
+ */
+export declare class CacheError extends Error {
+    readonly code: string;
+    readonly adapter?: string;
+    readonly originalError?: Error;
+    constructor(message: string, code?: string, adapter?: string, originalError?: Error);
+}

package/packages/cache/dist/esm/errors/CacheError.js

@@ -0,0 +1,13 @@
+/**
+ * Custom error class for cache operations
+ */
+export class CacheError extends Error {
+    constructor(message, code = 'CACHE_ERROR', adapter, originalError) {
+        super(message);
+        this.name = 'CacheError';
+        this.code = code;
+        this.adapter = adapter;
+        this.originalError = originalError;
+        Object.setPrototypeOf(this, CacheError.prototype);
+    }
+}

package/packages/cache/dist/esm/errors/index.d.ts

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

package/packages/cache/dist/esm/errors/index.js

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

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

@@ -0,0 +1,10 @@
+export type { CacheConfig, RedisCacheConfig, MemcacheCacheConfig, MemoryCacheConfig, SessionData, SessionOptions, CacheStats, HealthCheckResponse, BatchResult, CacheEntry, } from './types';
+export { CacheError } from './errors';
+export type { ICache, ISession } from './core/interfaces';
+export { BaseCache } from './core/BaseCache';
+export { RedisCache } from './adapters/redis';
+export { MemcacheCache } from './adapters/memcache';
+export { MemoryCache } from './adapters/memory';
+export { CacheFactory } from './core/factory';
+export { SessionStore } from './session';
+export { cacheSessionMiddleware, cacheHealthCheckMiddleware, cacheResponseMiddleware, } from './middleware/express';

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

@@ -0,0 +1,14 @@
+// Errors
+export { CacheError } from './errors';
+// Base Cache
+export { BaseCache } from './core/BaseCache';
+// Adapters
+export { RedisCache } from './adapters/redis';
+export { MemcacheCache } from './adapters/memcache';
+export { MemoryCache } from './adapters/memory';
+// Factory
+export { CacheFactory } from './core/factory';
+// Session
+export { SessionStore } from './session';
+// Middleware
+export { cacheSessionMiddleware, cacheHealthCheckMiddleware, cacheResponseMiddleware, } from './middleware/express';

package/packages/cache/dist/esm/middleware/express/cacheMiddleware.d.ts

@@ -0,0 +1,22 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { ICache } from '../../core/interfaces';
+import type { SessionStore } from '../../session/SessionStore';
+/**
+ * Express middleware for session management using cache
+ */
+export declare function cacheSessionMiddleware(sessionStore: SessionStore, options?: {
+    sessionIdHeader?: string;
+    sessionDataKey?: string;
+}): (req: Request, _res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Express middleware for cache health check
+ */
+export declare function cacheHealthCheckMiddleware(cache: ICache, endpoint?: string): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Express middleware for cache request/response caching
+ */
+export declare function cacheResponseMiddleware(cache: ICache<string>, options?: {
+    ttl?: number;
+    keyPrefix?: string;
+    excludeStatusCodes?: number[];
+}): (req: Request, res: Response, next: NextFunction) => void;

package/packages/cache/dist/esm/middleware/express/cacheMiddleware.js

@@ -0,0 +1,111 @@
+/**
+ * Express middleware for session management using cache
+ */
+export function cacheSessionMiddleware(sessionStore, options) {
+    const sessionIdHeader = options?.sessionIdHeader ?? 'x-session-id';
+    const sessionDataKey = options?.sessionDataKey ?? 'session';
+    return async (req, _res, next) => {
+        try {
+            // Get session ID from header or cookie
+            const sessionId = req.get(sessionIdHeader) || req.cookies?.[sessionIdHeader];
+            if (sessionId) {
+                // Fetch session data and extend expiry
+                const sessionData = await sessionStore.getAndExtend(sessionId);
+                if (sessionData) {
+                    ;
+                    req[sessionDataKey] = sessionData;
+                }
+            }
+            next();
+        }
+        catch (err) {
+            console.error('Session middleware error:', err);
+            next();
+        }
+    };
+}
+/**
+ * Express middleware for cache health check
+ */
+export function cacheHealthCheckMiddleware(cache, endpoint = '/.health/cache') {
+    return (req, res, next) => {
+        if (req.path === endpoint && req.method === 'GET') {
+            cache
+                .isAlive()
+                .then((health) => {
+                res.status(health.isAlive ? 200 : 503).json(health);
+            })
+                .catch((err) => {
+                res.status(503).json({
+                    isAlive: false,
+                    adapter: 'unknown',
+                    timestamp: new Date(),
+                    error: err.message,
+                });
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Express middleware for cache request/response caching
+ */
+export function cacheResponseMiddleware(cache, options) {
+    const ttl = options?.ttl ?? 300; // 5 minutes default
+    const keyPrefix = options?.keyPrefix ?? 'response:';
+    const excludeStatusCodes = options?.excludeStatusCodes ?? [
+        300, 301, 302, 303, 304, 307, 308, 404, 500, 501, 502, 503,
+    ];
+    return (req, res, next) => {
+        // Only cache GET requests
+        if (req.method !== 'GET') {
+            next();
+            return;
+        }
+        const cacheKey = `${keyPrefix}${req.originalUrl || req.url}`;
+        // Try to get cached response
+        cache
+            .get(cacheKey)
+            .then((cached) => {
+            if (cached) {
+                res.set('X-Cache', 'HIT');
+                return res.send(cached);
+            }
+            // Store original send method
+            const originalSend = res.send;
+            // Override send method to cache response
+            res.send = function (data) {
+                // Check if response should be cached
+                if (res.statusCode >= 200 &&
+                    res.statusCode < 300 &&
+                    !excludeStatusCodes.includes(res.statusCode)) {
+                    let responseData = null;
+                    if (typeof data === 'string') {
+                        responseData = data;
+                    }
+                    else {
+                        try {
+                            responseData = JSON.stringify(data);
+                        }
+                        catch (_e) {
+                            responseData = null;
+                        }
+                    }
+                    if (responseData !== null) {
+                        cache.set(cacheKey, responseData, ttl).catch((err) => {
+                            console.error('Failed to cache response:', err);
+                        });
+                    }
+                }
+                res.set('X-Cache', 'MISS');
+                return originalSend.call(this, data);
+            };
+            next();
+        })
+            .catch((err) => {
+            console.error('Cache middleware error:', err);
+            next();
+        });
+    };
+}

package/packages/cache/dist/esm/middleware/express/index.d.ts

@@ -0,0 +1 @@
+export { cacheSessionMiddleware, cacheHealthCheckMiddleware, cacheResponseMiddleware, } from './cacheMiddleware';

package/packages/cache/dist/esm/middleware/express/index.js

@@ -0,0 +1 @@
+export { cacheSessionMiddleware, cacheHealthCheckMiddleware, cacheResponseMiddleware, } from './cacheMiddleware';

package/packages/cache/dist/esm/session/SessionStore.d.ts

@@ -0,0 +1,57 @@
+import type { ICache } from '../core/interfaces';
+import type { SessionData, SessionOptions } from '../types';
+/**
+ * Session store wrapper around cache adapters
+ * Provides session management functionality
+ */
+export declare class SessionStore {
+    private cache;
+    private options;
+    constructor(cache: ICache<SessionData>, options?: SessionOptions);
+    /**
+     * Create a new session
+     */
+    create(sessionId: string, data: SessionData, ttl?: number): Promise<void>;
+    /**
+     * Get session data
+     */
+    get(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Update/merge session data
+     */
+    update(sessionId: string, data: Partial<SessionData>): Promise<void>;
+    /**
+     * Delete session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all session keys (limited use - may be slow with large datasets)
+     */
+    getMultiple(sessionIds: string[]): Promise<Record<string, SessionData | null>>;
+    /**
+     * Delete multiple sessions
+     */
+    deleteMultiple(sessionIds: string[]): Promise<number>;
+    /**
+     * Extend session expiry
+     */
+    extend(sessionId: string, ttl?: number): Promise<void>;
+    /**
+     * Get session data and extend expiry in one operation
+     */
+    getAndExtend(sessionId: string, ttl?: number): Promise<SessionData | null>;
+    /**
+     * Optional close hook for graceful shutdowns.
+     * Present to allow callers to call `close()` during shutdown without
+     * requiring every store implementation to provide one.
+     */
+    close(): Promise<void>;
+}