ts-packages 2.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-packages",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "",
   "main": "index.js",
   "type": "module",

package/packages/cache/README.md

@@ -1,6 +1,6 @@
 # @naman_deep_singh/cache
 
-**Version:** 1.3.2 (with Redis Clustering support)
+**Version:** 1.4.0 (with Redis Clustering support)
 
 A flexible, extensible caching layer with support for Redis, Memcache, and in-memory caches. Includes session management, health checks, and Express middleware.
 
@@ -27,13 +27,109 @@ npm install @naman_deep_singh/cache redis memcached
 - `redis` (for Redis adapter)
 - `memcached` (for Memcache adapter)
 
-Both are optional if you're only using the memory adapter.
-
 ## Quick Start
 
 ### Using the Factory
 
 ```typescript
+
+Both are optional if you're only using the memory adapter.
+
+All cache-related failures throw a CacheError, which:
+
+Extends AppError
+
+Uses cache-specific error codes
+
+Supports adapter & operation metadata
+
+Integrates with centralized error message resolution via errorMessageRegistry
+
+Integrates with centralized error message resolution via errorMessageRegistry
+
+import { CacheError } from '@naman_deep_singh/cache'
+import { CACHE_ERROR_CODES } from '@naman_deep_singh/cache/errors'
+
+Cache Error Codes
+
+Cache-specific error codes are scoped to this package and are not mixed with global application error codes.
+
+Examples:
+
+CACHE_ERROR
+
+CACHE_CONNECTION_FAILED
+
+CACHE_UNSUPPORTED_ADAPTER
+
+CACHE_INVALID_CONFIG
+
+CACHE_KEY_NOT_FOUND
+
+CACHE_OPERATION_TIMEOUT
+
+CACHE_SERIALIZE_ERROR
+
+CACHE_DESERIALIZE_ERROR
+
+SESSION_CREATE_ERROR
+
+SESSION_GET_ERROR
+
+SESSION_UPDATE_ERROR
+
+SESSION_DELETE_ERROR
+
+SESSION_EXISTS_ERROR
+
+SESSION_CLEAR_ERROR
+
+SESSION_GET_MULTIPLE_ERROR
+
+SESSION_DELETE_MULTIPLE_ERROR
+
+SESSION_EXTEND_ERROR
+
+SESSION_GET_EXTEND_ERROR
+
+SESSION_NOT_FOUND
+
+These codes are registered internally using errorMessageRegistry, ensuring consistent messaging across services.
+
+Example: Handling Cache Errors
+try {
+  await cache.get('user:123')
+} catch (error) {
+  if (error instanceof CacheError) {
+    console.error('Cache error occurred', {
+      code: error.code,
+      adapter: error.adapter,
+      operation: error.operation,
+      details: error.details,
+    })
+  }
+}
+
+Example: Adapter-Level Error Throwing
+
+throw new CacheError(CACHE_ERROR_CODES.CACHE_CONNECTION_FAILED, {
+  adapter: 'memcache',
+  operation: 'connect',
+  cause: error,
+})
+
+Design Notes
+
+❌ Cache errors do not extend HTTP error classes
+
+❌ Cache errors do not pollute global ErrorCode
+
+✅ Cache errors are package-scoped
+
+✅ Error messages remain centralized and overridable
+
+✅ Metadata (adapter, operation) is preserved for observability
+
 import { CacheFactory, SessionStore } from '@naman_deep_singh/cache';
 
 // Create a Redis cache
@@ -432,12 +528,12 @@ import { CacheError } from '@naman_deep_singh/cache';
 
 try {
   await cache.get('key');
-} catch (err) {
-  if (err instanceof CacheError) {
-    console.log(`Error: ${err.message}`);
-    console.log(`Code: ${err.code}`);
-    console.log(`Adapter: ${err.adapter}`);
-    console.log(`Original error:`, err.originalError);
+} catch (error) {
+  if (error instanceof CacheError) {
+    console.log(`Error: ${error.message}`);
+    console.log(`Code: ${error.code}`);
+    console.log(`Adapter: ${error.adapter}`);
+    console.log(`Original error:`, error.originalError);
   }
 }
 

package/packages/cache/dist/cjs/adapters/memcache/MemcacheCache.d.ts

@@ -1,71 +1,18 @@
 import { BaseCache } from '../../core/BaseCache';
 import type { HealthCheckResponse, MemcacheCacheConfig } from '../../types';
-/**
- * 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
-     */
+    exists(key: string): Promise<boolean>;
     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/packages/cache/dist/cjs/adapters/memcache/MemcacheCache.js

@@ -5,11 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemcacheCache = void 0;
 const memcached_1 = __importDefault(require("memcached"));
+const cacheErrorCodes_1 = require("src/errors/cacheErrorCodes");
 const BaseCache_1 = require("../../core/BaseCache");
 const errors_1 = require("../../errors");
-/**
- * Memcache adapter
- */
 class MemcacheCache extends BaseCache_1.BaseCache {
     constructor(memcacheConfig) {
         super(memcacheConfig);
@@ -17,362 +15,158 @@ class MemcacheCache extends BaseCache_1.BaseCache {
         this.client = null;
         this.isConnected = false;
     }
-    /**
-     * Connect to Memcache
-     */
     async connect() {
         try {
             const servers = Array.isArray(this.memcacheConfig.servers)
                 ? this.memcacheConfig.servers
                 : [this.memcacheConfig.servers];
-            const options = {
+            this.client = new memcached_1.default(servers, {
                 retries: 2,
                 retry: 30000,
                 remove: true,
-                failOverServers: [],
-                maxValue: 1048576, // 1MB default
+                maxValue: 1048576,
                 idle: 30000,
-            };
-            if (this.memcacheConfig.username) {
-                ;
-                options.username = this.memcacheConfig.username;
-            }
-            if (this.memcacheConfig.password) {
-                ;
-                options.password = this.memcacheConfig.password;
-            }
-            this.client = new memcached_1.default(servers, options);
+            });
             this.isConnected = true;
-            // Test connection
             await this.ping();
         }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to connect to Memcache', 'MEMCACHE_CONNECTION_ERROR', 'memcache', err);
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_CONNECTION_FAILED, {
+                adapter: 'memcache',
+                operation: 'connect',
+                cause: error instanceof Error ? error : undefined,
+            });
         }
     }
-    /**
-     * Ensure client is connected
-     */
     async ensureConnected() {
         if (!this.client) {
             await this.connect();
         }
     }
-    /**
-     * Ping memcache
-     */
     async ping() {
         return new Promise((resolve, reject) => {
-            if (!this.client) {
-                reject(new Error('Memcache client not initialized'));
-                return;
-            }
-            this.client.touch('__ping', 1, (err) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve();
-            });
+            if (!this.client)
+                return reject(new Error('Client not initialized'));
+            this.client.touch('__ping', 1, (err) => (err ? reject(err) : resolve()));
         });
     }
-    /**
-     * Get a value from Memcache
-     */
+    async exists(key) {
+        try {
+            const value = await this.get(key);
+            return value !== null;
+        }
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'memcache',
+                operation: 'exists',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
     async get(key) {
         try {
             await this.ensureConnected();
             const fullKey = this.buildKey(key);
             return new Promise((resolve, reject) => {
                 this.client.get(fullKey, (err, data) => {
-                    if (err) {
-                        reject(err);
-                        return;
-                    }
-                    if (data === undefined || data === null) {
-                        this.recordMiss();
-                        resolve(null);
-                        return;
-                    }
-                    this.recordHit();
+                    if (err)
+                        return reject(err);
+                    if (data == null)
+                        return resolve(null);
                     try {
-                        if (typeof data === 'string') {
-                            resolve(this.deserialize(data));
-                        }
-                        else if (Buffer.isBuffer(data)) {
-                            resolve(this.deserialize(data.toString()));
-                        }
-                        else {
-                            // Unknown shape from memcached client - treat as miss
-                            this.recordMiss();
-                            resolve(null);
-                        }
+                        resolve(this.deserialize(Buffer.isBuffer(data) ? data.toString() : data));
                     }
-                    catch (parseErr) {
-                        reject(parseErr);
+                    catch (e) {
+                        reject(e);
                     }
                 });
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to get key "${key}" from Memcache`, 'MEMCACHE_GET_ERROR', 'memcache', err);
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_KEY_NOT_FOUND, {
+                adapter: 'memcache',
+                operation: 'get',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
         }
     }
-    /**
-     * Set a value in Memcache
-     */
     async set(key, value, ttl) {
         try {
             await this.ensureConnected();
             const fullKey = this.buildKey(key);
-            const serialized = this.serialize(value);
-            const expiry = ttl ?? this.ttl;
             return new Promise((resolve, reject) => {
-                this.client.set(fullKey, serialized, expiry, (err) => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        this.recordSet();
-                        resolve();
-                    }
-                });
+                this.client.set(fullKey, this.serialize(value), ttl ?? this.ttl, (err) => (err ? reject(err) : resolve()));
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to set key "${key}" in Memcache`, 'MEMCACHE_SET_ERROR', 'memcache', err);
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'memcache',
+                operation: 'set',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
+            });
         }
     }
-    /**
-     * Delete a key from Memcache
-     */
     async delete(key) {
         try {
             await this.ensureConnected();
             const fullKey = this.buildKey(key);
             return new Promise((resolve, reject) => {
-                this.client.del(fullKey, (err) => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        this.recordDelete();
-                        resolve(true);
-                    }
-                });
+                this.client.del(fullKey, (err) => (err ? reject(err) : resolve(true)));
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to delete key "${key}" from Memcache`, 'MEMCACHE_DELETE_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Check if key exists
-     */
-    async exists(key) {
-        try {
-            const value = await this.get(key);
-            return value !== null;
-        }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to check existence of key "${key}" in Memcache`, 'MEMCACHE_EXISTS_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Clear all keys (Memcache limitation: flushes entire cache)
-     */
-    async clear() {
-        try {
-            await this.ensureConnected();
-            return new Promise((resolve, reject) => {
-                this.client.flush((err) => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        resolve();
-                    }
-                });
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'memcache',
+                operation: 'delete',
+                details: { key },
+                cause: error instanceof Error ? error : undefined,
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to clear Memcache', 'MEMCACHE_CLEAR_ERROR', 'memcache', err);
-        }
     }
-    /**
-     * Get multiple values at once
-     */
-    async getMultiple(keys) {
+    async clear() {
         try {
             await this.ensureConnected();
-            const fullKeys = keys.map((k) => this.buildKey(k));
             return new Promise((resolve, reject) => {
-                this.client.getMulti(fullKeys, (err, data) => {
-                    if (err) {
-                        reject(err);
-                        return;
-                    }
-                    const result = {};
-                    if (!data || typeof data !== 'object') {
-                        // Treat as all misses
-                        for (const key of keys) {
-                            this.recordMiss();
-                            result[key] = null;
-                        }
-                        resolve(result);
-                        return;
-                    }
-                    const map = data;
-                    keys.forEach((key) => {
-                        const fullKey = this.buildKey(key);
-                        const value = map[fullKey];
-                        if (value === undefined || value === null) {
-                            this.recordMiss();
-                            result[key] = null;
-                        }
-                        else {
-                            this.recordHit();
-                            try {
-                                if (typeof value === 'string') {
-                                    result[key] = this.deserialize(value);
-                                }
-                                else if (Buffer.isBuffer(value)) {
-                                    result[key] = this.deserialize(value.toString());
-                                }
-                                else {
-                                    // Unknown, treat as miss
-                                    this.recordMiss();
-                                    result[key] = null;
-                                }
-                            }
-                            catch (parseErr) {
-                                reject(parseErr);
-                            }
-                        }
-                    });
-                    resolve(result);
-                });
+                this.client.flush((err) => (err ? reject(err) : resolve()));
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to get multiple keys from Memcache', 'MEMCACHE_GET_MULTIPLE_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Set multiple values at once
-     */
-    async setMultiple(data, ttl) {
-        try {
-            await this.ensureConnected();
-            const expiry = ttl ?? this.ttl;
-            const promises = [];
-            for (const [key, value] of Object.entries(data)) {
-                const fullKey = this.buildKey(key);
-                const serialized = this.serialize(value);
-                promises.push(new Promise((resolve, reject) => {
-                    this.client.set(fullKey, serialized, expiry, (err) => {
-                        if (err)
-                            reject(err);
-                        else
-                            resolve();
-                    });
-                }));
-            }
-            return Promise.all(promises).then(() => {
-                this.stats.sets += Object.keys(data).length;
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_OPERATION_TIMEOUT, {
+                adapter: 'memcache',
+                operation: 'clear',
+                cause: error instanceof Error ? error : undefined,
             });
         }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to set multiple keys in Memcache', 'MEMCACHE_SET_MULTIPLE_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Delete multiple keys at once
-     */
-    async deleteMultiple(keys) {
-        try {
-            await this.ensureConnected();
-            const fullKeys = keys.map((k) => this.buildKey(k));
-            let deletedCount = 0;
-            await Promise.all(fullKeys.map((key) => new Promise((resolve, reject) => {
-                this.client.del(key, (err) => {
-                    if (err) {
-                        reject(err);
-                    }
-                    else {
-                        deletedCount++;
-                        resolve();
-                    }
-                });
-            })));
-            this.stats.deletes += deletedCount;
-            return deletedCount;
-        }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to delete multiple keys from Memcache', 'MEMCACHE_DELETE_MULTIPLE_ERROR', 'memcache', err);
-        }
     }
-    /**
-     * Increment a numeric value (not natively supported by Memcache in this library)
-     */
-    async increment(key, amount = 1) {
-        try {
-            const current = await this.get(key);
-            const value = (typeof current === 'number' ? current : 0) + amount;
-            await this.set(key, value);
-            return value;
-        }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to increment key "${key}" in Memcache`, 'MEMCACHE_INCREMENT_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Decrement a numeric value
-     */
-    async decrement(key, amount = 1) {
-        try {
-            const current = await this.get(key);
-            const value = (typeof current === 'number' ? current : 0) - amount;
-            await this.set(key, value);
-            return value;
-        }
-        catch (err) {
-            throw new errors_1.CacheError(`Failed to decrement key "${key}" in Memcache`, 'MEMCACHE_DECREMENT_ERROR', 'memcache', err);
-        }
-    }
-    /**
-     * Check if Memcache is alive
-     */
     async isAlive() {
         try {
             await this.ping();
-            return {
-                isAlive: true,
-                adapter: 'memcache',
-                timestamp: new Date(),
-            };
+            return { isAlive: true, adapter: 'memcache', timestamp: new Date() };
         }
-        catch (err) {
+        catch (error) {
             return {
                 isAlive: false,
                 adapter: 'memcache',
                 timestamp: new Date(),
-                error: err.message,
+                error: error instanceof Error ? error.message : 'Unknown error',
             };
         }
     }
-    /**
-     * Close Memcache connection
-     */
     async close() {
         try {
-            if (this.client && this.isConnected) {
-                this.client.end();
-                this.isConnected = false;
-                this.client = null;
-            }
+            this.client?.end();
+            this.client = null;
+            this.isConnected = false;
         }
-        catch (err) {
-            throw new errors_1.CacheError('Failed to close Memcache connection', 'MEMCACHE_CLOSE_ERROR', 'memcache', err);
+        catch (error) {
+            throw new errors_1.CacheError(cacheErrorCodes_1.CACHE_ERROR_CODES.CACHE_ERROR, {
+                adapter: 'memcache',
+                operation: 'close',
+                cause: error instanceof Error ? error : undefined,
+            });
         }
     }
 }