@naman_deep_singh/cache 1.1.0

package/dist/esm/session/SessionStore.js

@@ -0,0 +1,149 @@
+import { CacheError } from '../errors';
+/**
+ * Session store wrapper around cache adapters
+ * Provides session management functionality
+ */
+export 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 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 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 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 CacheError) {
+                throw err;
+            }
+            throw new 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 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 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 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 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 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 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 CacheError) {
+                throw err;
+            }
+            throw new 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 CacheError) {
+                throw err;
+            }
+            throw new CacheError(`Failed to get and extend session "${sessionId}"`, 'SESSION_GET_EXTEND_ERROR', 'session', err);
+        }
+    }
+}

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

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

package/dist/esm/session/index.js

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

package/dist/esm/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/esm/types.js

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

package/dist/types/adapters/memcache/MemcacheCache.d.ts

@@ -0,0 +1,71 @@
+import type { MemcacheCacheConfig, HealthCheckResponse } from '../../types';
+import { BaseCache } from '../../core/BaseCache';
+/**
+ * Memcache adapter
+ */
+export declare class MemcacheCache<T = unknown> extends BaseCache<T> {
+    private memcacheConfig;
+    private client;
+    private isConnected;
+    constructor(memcacheConfig: MemcacheCacheConfig);
+    /**
+     * Connect to Memcache
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure client is connected
+     */
+    private ensureConnected;
+    /**
+     * Ping memcache
+     */
+    private ping;
+    /**
+     * Get a value from Memcache
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in Memcache
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a key from Memcache
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys (Memcache limitation: flushes entire cache)
+     */
+    clear(): Promise<void>;
+    /**
+     * Get multiple values at once
+     */
+    getMultiple(keys: string[]): Promise<Record<string, T | null>>;
+    /**
+     * 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 (not natively supported by Memcache in this library)
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Decrement a numeric value
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+    /**
+     * Check if Memcache is alive
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close Memcache connection
+     */
+    close(): Promise<void>;
+}

package/dist/types/adapters/memcache/index.d.ts

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

package/dist/types/adapters/memory/MemoryCache.d.ts

@@ -0,0 +1,63 @@
+import type { MemoryCacheConfig, HealthCheckResponse } from '../../types';
+import { BaseCache } from '../../core/BaseCache';
+/**
+ * In-memory cache adapter for development and testing
+ */
+export declare class MemoryCache<T = unknown> extends BaseCache<T> {
+    private memoryCacheConfig;
+    private store;
+    private cleanupInterval;
+    constructor(memoryCacheConfig: MemoryCacheConfig);
+    /**
+     * Start periodic cleanup of expired items
+     */
+    private startCleanup;
+    /**
+     * Get a value from memory
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in memory
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a key from memory
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys with current namespace
+     */
+    clear(): Promise<void>;
+    /**
+     * Get multiple values at once
+     */
+    getMultiple(keys: string[]): Promise<Record<string, T | null>>;
+    /**
+     * 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>;
+    /**
+     * Check if memory cache is alive
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close memory cache
+     */
+    close(): Promise<void>;
+}

package/dist/types/adapters/memory/index.d.ts

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

package/dist/types/adapters/redis/RedisCache.d.ts

@@ -0,0 +1,67 @@
+import type { RedisCacheConfig, HealthCheckResponse } from '../../types';
+import { BaseCache } from '../../core/BaseCache';
+/**
+ * Redis cache adapter
+ */
+export declare class RedisCache<T = unknown> extends BaseCache<T> {
+    private redisConfig;
+    private client;
+    private isConnected;
+    constructor(redisConfig: RedisCacheConfig);
+    /**
+     * Connect to Redis
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure client is connected
+     */
+    private ensureConnected;
+    /**
+     * Get a value from Redis
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in Redis
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a key from Redis
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys with current namespace
+     */
+    clear(): Promise<void>;
+    /**
+     * Get multiple values at once
+     */
+    getMultiple(keys: string[]): Promise<Record<string, T | null>>;
+    /**
+     * 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>;
+    /**
+     * Check if Redis is alive
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close Redis connection
+     */
+    close(): Promise<void>;
+}

package/dist/types/adapters/redis/index.d.ts

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

package/dist/types/core/BaseCache.d.ts

@@ -0,0 +1,78 @@
+import type { CacheConfig, CacheStats, HealthCheckResponse, BatchResult } 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/dist/types/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/dist/types/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/types/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/types/core/interfaces/index.d.ts

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

package/dist/types/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/types/errors/index.d.ts

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

package/dist/types/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/types/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;