ts-packages 1.0.0 → 3.0.0

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheFactory = void 0;
+const cacheErrorCodes_1 = require("src/errors/cacheErrorCodes");
+const memcache_1 = require("../adapters/memcache");
+const memory_1 = require("../adapters/memory");
+const redis_1 = require("../adapters/redis");
+const errors_1 = require("../errors");
+/**
+ * Factory for creating cache instances
+ */
+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 errors_1.CacheError(cacheErrorCodes_1.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 errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_INVALID_CONFIG, {
+                        adapter: 'redis',
+                        operation: 'create',
+                        details: {
+                            reason: 'Redis requires either host or cluster config',
+                        },
+                    });
+                }
+                return new redis_1.RedisCache(redisConfig);
+            case 'memcache':
+                return new memcache_1.MemcacheCache(config);
+            case 'memory':
+                return new memory_1.MemoryCache(config);
+            default:
+                throw new errors_1.CacheError(cacheErrorCodes_1.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 memory_1.MemoryCache({
+                adapter: 'memory',
+                namespace: config.namespace,
+                ttl: config.ttl,
+            });
+        }
+        // No fallback, throw error
+        throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_CONNECTION_FAILED, {
+            adapter: config.adapter,
+            operation: 'createWithFallback',
+            details: {
+                reason: `${config.adapter} cache is not alive and fallback is disabled`,
+            },
+        });
+    }
+}
+exports.CacheFactory = CacheFactory;

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,12 @@
+import { AppError } from '@naman_deep_singh/errors-utils';
+import type { CacheErrorCode } from './cacheErrorCodes';
+export declare class CacheError extends AppError {
+    readonly adapter?: string;
+    readonly operation?: string;
+    constructor(code: CacheErrorCode, options?: {
+        adapter?: string;
+        operation?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheError = void 0;
+const errors_utils_1 = require("@naman_deep_singh/errors-utils");
+class CacheError extends errors_utils_1.AppError {
+    constructor(code, options) {
+        super(code, undefined, options?.details, options?.cause);
+        this.adapter = options?.adapter;
+        this.operation = options?.operation;
+    }
+}
+exports.CacheError = CacheError;

package/packages/cache/dist/cjs/errors/cacheErrorCodes.d.ts

@@ -0,0 +1,22 @@
+export declare const CACHE_ERROR_CODES: {
+    readonly CACHE_ERROR: "Temporary caching issue, please retry";
+    readonly CACHE_CONNECTION_FAILED: "Failed to connect to the cache server";
+    readonly CACHE_UNSUPPORTED_ADAPTER: "The specified cache adapter is not supported";
+    readonly CACHE_INVALID_CONFIG: "The provided cache configuration is invalid";
+    readonly CACHE_KEY_NOT_FOUND: "The requested cache key was not found";
+    readonly CACHE_OPERATION_TIMEOUT: "The cache operation timed out";
+    readonly CACHE_SERIALIZE_ERROR: "Failed to serialize cached data";
+    readonly CACHE_DESERIALIZE_ERROR: "Failed to deserialize cached data";
+    readonly SESSION_CREATE_ERROR: "Failed to create a new session";
+    readonly SESSION_GET_ERROR: "Failed to get session data";
+    readonly SESSION_UPDATE_ERROR: "Failed to update session data";
+    readonly SESSION_DELETE_ERROR: "Failed to delete session data";
+    readonly SESSION_EXISTS_ERROR: "Failed to check session existence";
+    readonly SESSION_CLEAR_ERROR: "Failed to clear sessions";
+    readonly SESSION_GET_MULTIPLE_ERROR: "Failed to get multiple sessions";
+    readonly SESSION_DELETE_MULTIPLE_ERROR: "Failed to delete multiple sessions";
+    readonly SESSION_EXTEND_ERROR: "Failed to extend session expiry";
+    readonly SESSION_GET_EXTEND_ERROR: "Failed to get and extend session data";
+    readonly SESSION_NOT_FOUND: "Session not found";
+};
+export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[keyof typeof CACHE_ERROR_CODES];

package/packages/cache/dist/cjs/errors/cacheErrorCodes.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_ERROR_CODES = void 0;
+exports.CACHE_ERROR_CODES = {
+    CACHE_ERROR: 'Temporary caching issue, please retry',
+    CACHE_CONNECTION_FAILED: 'Failed to connect to the cache server',
+    CACHE_UNSUPPORTED_ADAPTER: 'The specified cache adapter is not supported',
+    CACHE_INVALID_CONFIG: 'The provided cache configuration is invalid',
+    CACHE_KEY_NOT_FOUND: 'The requested cache key was not found',
+    CACHE_OPERATION_TIMEOUT: 'The cache operation timed out',
+    CACHE_SERIALIZE_ERROR: 'Failed to serialize cached data',
+    CACHE_DESERIALIZE_ERROR: 'Failed to deserialize cached data',
+    SESSION_CREATE_ERROR: 'Failed to create a new session',
+    SESSION_GET_ERROR: 'Failed to get session data',
+    SESSION_UPDATE_ERROR: 'Failed to update session data',
+    SESSION_DELETE_ERROR: 'Failed to delete session data',
+    SESSION_EXISTS_ERROR: 'Failed to check session existence',
+    SESSION_CLEAR_ERROR: 'Failed to clear sessions',
+    SESSION_GET_MULTIPLE_ERROR: 'Failed to get multiple sessions',
+    SESSION_DELETE_MULTIPLE_ERROR: 'Failed to delete multiple sessions',
+    SESSION_EXTEND_ERROR: 'Failed to extend session expiry',
+    SESSION_GET_EXTEND_ERROR: 'Failed to get and extend session data',
+    SESSION_NOT_FOUND: 'Session not found',
+};

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

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

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

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheError = void 0;
+const errors_utils_1 = require("@naman_deep_singh/errors-utils");
+const cacheErrorCodes_1 = require("./cacheErrorCodes");
+errors_utils_1.errorMessageRegistry.register(cacheErrorCodes_1.CACHE_ERROR_CODES);
+var CacheError_1 = require("./CacheError");
+Object.defineProperty(exports, "CacheError", { enumerable: true, get: function () { return CacheError_1.CacheError; } });

package/packages/cache/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/packages/cache/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/packages/cache/dist/cjs/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/cjs/middleware/express/cacheMiddleware.js

@@ -0,0 +1,116 @@
+"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 (error) {
+            console.error('Session middleware error:', error);
+            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((error) => {
+                res.status(503).json({
+                    isAlive: false,
+                    adapter: 'unknown',
+                    timestamp: new Date(),
+                    error: error.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)) {
+                    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((error) => {
+                            console.error('Failed to cache response:', error);
+                        });
+                    }
+                }
+                res.set('X-Cache', 'MISS');
+                return originalSend.call(this, data);
+            };
+            next();
+        })
+            .catch((error) => {
+            console.error('Cache middleware error:', error);
+            next();
+        });
+    };
+}

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

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

package/packages/cache/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/packages/cache/dist/cjs/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>;
+}