ts-packages 2.0.0 → 3.0.0

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

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

package/packages/cache/dist/types/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@naman_deep_singh/cache",
-    "version": "1.3.2",
+    "version": "1.4.0",
     "description": "Extensible caching layer supporting Redis, Memcache, and in-memory caches with automatic fallback, namespacing, session management, and Express middleware.",
     "type": "module",
     "main": "./dist/cjs/index.js",
@@ -36,15 +36,17 @@
     "license": "ISC",
     "packageManager": "pnpm@10.20.0",
     "devDependencies": {
-        "@types/memcached": "^2.2.7",
         "@types/express": "^5.0.5",
+        "@types/memcached": "^2.2.7",
         "@types/node": "^25.0.1",
         "express": "^5.1.0",
-        "typescript": "^5.9.3",
-        "rimraf": "^5.0.5"
+        "rimraf": "^5.0.5",
+        "typescript": "^5.9.3"
     },
     "dependencies": {
-        "redis": "^4.6.10",
-        "memcached": "^2.2.2"
+        "@naman_deep_singh/errors-utils": "^1.4.2",
+        "@naman_deep_singh/response-utils": "^2.1.4",
+        "memcached": "^2.2.2",
+        "redis": "^4.6.10"
     }
 }

package/packages/cache/src/adapters/memcache/MemcacheCache.ts

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