@naman_deep_singh/cache 1.1.0

package/dist/cjs/core/interfaces/ICache.d.ts

@@ -0,0 +1,58 @@
+import type { CacheStats, HealthCheckResponse, BatchResult } 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/dist/cjs/core/interfaces/ICache.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/dist/cjs/core/interfaces/ISession.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/core/interfaces/index.d.ts

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

package/dist/cjs/core/interfaces/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/dist/cjs/errors/CacheError.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheError = void 0;
+/**
+ * Custom error class for cache operations
+ */
+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);
+    }
+}
+exports.CacheError = CacheError;

package/dist/cjs/errors/index.d.ts

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

package/dist/cjs/errors/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheError = void 0;
+var CacheError_1 = require("./CacheError");
+Object.defineProperty(exports, "CacheError", { enumerable: true, get: function () { return CacheError_1.CacheError; } });

package/dist/cjs/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/dist/cjs/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheResponseMiddleware = exports.cacheHealthCheckMiddleware = exports.cacheSessionMiddleware = exports.SessionStore = exports.CacheFactory = exports.MemoryCache = exports.MemcacheCache = exports.RedisCache = exports.BaseCache = exports.CacheError = void 0;
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "CacheError", { enumerable: true, get: function () { return errors_1.CacheError; } });
+// Base Cache
+var BaseCache_1 = require("./core/BaseCache");
+Object.defineProperty(exports, "BaseCache", { enumerable: true, get: function () { return BaseCache_1.BaseCache; } });
+// Adapters
+var redis_1 = require("./adapters/redis");
+Object.defineProperty(exports, "RedisCache", { enumerable: true, get: function () { return redis_1.RedisCache; } });
+var memcache_1 = require("./adapters/memcache");
+Object.defineProperty(exports, "MemcacheCache", { enumerable: true, get: function () { return memcache_1.MemcacheCache; } });
+var memory_1 = require("./adapters/memory");
+Object.defineProperty(exports, "MemoryCache", { enumerable: true, get: function () { return memory_1.MemoryCache; } });
+// Factory
+var factory_1 = require("./core/factory");
+Object.defineProperty(exports, "CacheFactory", { enumerable: true, get: function () { return factory_1.CacheFactory; } });
+// Session
+var session_1 = require("./session");
+Object.defineProperty(exports, "SessionStore", { enumerable: true, get: function () { return session_1.SessionStore; } });
+// Middleware
+var express_1 = require("./middleware/express");
+Object.defineProperty(exports, "cacheSessionMiddleware", { enumerable: true, get: function () { return express_1.cacheSessionMiddleware; } });
+Object.defineProperty(exports, "cacheHealthCheckMiddleware", { enumerable: true, get: function () { return express_1.cacheHealthCheckMiddleware; } });
+Object.defineProperty(exports, "cacheResponseMiddleware", { enumerable: true, get: function () { return express_1.cacheResponseMiddleware; } });

package/dist/cjs/middleware/express/cacheMiddleware.d.ts

@@ -0,0 +1,22 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { ICache } from '../../core/interfaces';
+import { 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/dist/cjs/middleware/express/cacheMiddleware.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheSessionMiddleware = cacheSessionMiddleware;
+exports.cacheHealthCheckMiddleware = cacheHealthCheckMiddleware;
+exports.cacheResponseMiddleware = cacheResponseMiddleware;
+/**
+ * Express middleware for session management using cache
+ */
+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
+ */
+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
+ */
+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)) {
+                    const responseData = typeof data === 'string' ? data : JSON.stringify(data);
+                    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/dist/cjs/middleware/express/index.d.ts

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

package/dist/cjs/middleware/express/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheResponseMiddleware = exports.cacheHealthCheckMiddleware = exports.cacheSessionMiddleware = void 0;
+var cacheMiddleware_1 = require("./cacheMiddleware");
+Object.defineProperty(exports, "cacheSessionMiddleware", { enumerable: true, get: function () { return cacheMiddleware_1.cacheSessionMiddleware; } });
+Object.defineProperty(exports, "cacheHealthCheckMiddleware", { enumerable: true, get: function () { return cacheMiddleware_1.cacheHealthCheckMiddleware; } });
+Object.defineProperty(exports, "cacheResponseMiddleware", { enumerable: true, get: function () { return cacheMiddleware_1.cacheResponseMiddleware; } });

package/dist/cjs/session/SessionStore.d.ts

@@ -0,0 +1,51 @@
+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>;
+}

package/dist/cjs/session/SessionStore.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+const errors_1 = require("../errors");
+/**
+ * Session store wrapper around cache adapters
+ * Provides session management functionality
+ */
+class SessionStore {
+    constructor(cache, options = {}) {
+        this.cache = cache;
+        this.options = {
+            ttl: options.ttl ?? 3600, // 1 hour default
+            serialize: options.serialize ?? ((data) => JSON.stringify(data)),
+            deserialize: options.deserialize ?? ((data) => JSON.parse(data))
+        };
+    }
+    /**
+     * Create a new session
+     */
+    async create(sessionId, data, ttl) {
+        try {
+            const ttlValue = ttl ?? this.options.ttl;
+            await this.cache.set(sessionId, data, ttlValue);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to create session "${sessionId}"`, 'SESSION_CREATE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get session data
+     */
+    async get(sessionId) {
+        try {
+            return await this.cache.get(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to get session "${sessionId}"`, 'SESSION_GET_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Update/merge session data
+     */
+    async update(sessionId, data) {
+        try {
+            const current = await this.cache.get(sessionId);
+            if (!current) {
+                throw new errors_1.CacheError(`Session "${sessionId}" not found`, 'SESSION_NOT_FOUND');
+            }
+            const merged = { ...current, ...data };
+            await this.cache.set(sessionId, merged, this.options.ttl);
+        }
+        catch (err) {
+            if (err instanceof errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to update session "${sessionId}"`, 'SESSION_UPDATE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Delete session
+     */
+    async delete(sessionId) {
+        try {
+            return await this.cache.delete(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to delete session "${sessionId}"`, 'SESSION_DELETE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Check if session exists
+     */
+    async exists(sessionId) {
+        try {
+            return await this.cache.exists(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to check session "${sessionId}" existence`, 'SESSION_EXISTS_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Clear all sessions
+     */
+    async clear() {
+        try {
+            await this.cache.clear();
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to clear sessions', 'SESSION_CLEAR_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get all session keys (limited use - may be slow with large datasets)
+     */
+    async getMultiple(sessionIds) {
+        try {
+            return await this.cache.getMultiple(sessionIds);
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to get multiple sessions', 'SESSION_GET_MULTIPLE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Delete multiple sessions
+     */
+    async deleteMultiple(sessionIds) {
+        try {
+            return await this.cache.deleteMultiple(sessionIds);
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to delete multiple sessions', 'SESSION_DELETE_MULTIPLE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Extend session expiry
+     */
+    async extend(sessionId, ttl) {
+        try {
+            const current = await this.cache.get(sessionId);
+            if (!current) {
+                throw new errors_1.CacheError(`Session "${sessionId}" not found`, 'SESSION_NOT_FOUND');
+            }
+            const ttlValue = ttl ?? this.options.ttl;
+            await this.cache.set(sessionId, current, ttlValue);
+        }
+        catch (err) {
+            if (err instanceof errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to extend session "${sessionId}"`, 'SESSION_EXTEND_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get session data and extend expiry in one operation
+     */
+    async getAndExtend(sessionId, ttl) {
+        try {
+            const data = await this.get(sessionId);
+            if (data) {
+                await this.extend(sessionId, ttl);
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to get and extend session "${sessionId}"`, 'SESSION_GET_EXTEND_ERROR', 'session', err);
+        }
+    }
+}
+exports.SessionStore = SessionStore;

package/dist/cjs/session/index.d.ts

@@ -0,0 +1,2 @@
+export { SessionStore } from './SessionStore';
+export type { SessionOptions } from '../types';

package/dist/cjs/session/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+var SessionStore_1 = require("./SessionStore");
+Object.defineProperty(exports, "SessionStore", { enumerable: true, get: function () { return SessionStore_1.SessionStore; } });

package/dist/cjs/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    adapter: 'redis' | 'memcache' | 'memory';
+    namespace?: string;
+    ttl?: number;
+    fallback?: boolean;
+}
+/**
+ * Redis-specific configuration
+ */
+export interface RedisCacheConfig extends CacheConfig {
+    adapter: 'redis';
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+}
+/**
+ * Memcache-specific configuration
+ */
+export interface MemcacheCacheConfig extends CacheConfig {
+    adapter: 'memcache';
+    servers: string | string[];
+    username?: string;
+    password?: string;
+}
+/**
+ * Memory cache configuration
+ */
+export interface MemoryCacheConfig extends CacheConfig {
+    adapter: 'memory';
+    maxSize?: number;
+}
+/**
+ * Session data structure
+ */
+export interface SessionData {
+    [key: string]: unknown;
+}
+/**
+ * Session store options
+ */
+export interface SessionOptions {
+    ttl?: number;
+    serialize?: (data: SessionData) => string;
+    deserialize?: (data: string) => SessionData;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    deletes: number;
+}
+/**
+ * Health check response
+ */
+export interface HealthCheckResponse {
+    isAlive: boolean;
+    adapter: string;
+    timestamp: Date;
+    error?: string;
+}
+/**
+ * Batch operation result
+ */
+export interface BatchResult<T> {
+    [key: string]: T | null;
+}
+/**
+ * Cache key with optional metadata
+ */
+export interface CacheEntry<T = unknown> {
+    value: T;
+    expiresAt?: number;
+    createdAt: number;
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });