ts-packages 1.0.0 → 3.0.0

package/packages/cache/src/core/interfaces/ICache.ts

@@ -0,0 +1,71 @@
+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/src/core/interfaces/ISession.ts

@@ -0,0 +1,36 @@
+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/src/core/interfaces/index.ts

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

package/packages/cache/src/errors/CacheError.ts

@@ -0,0 +1,21 @@
+import { AppError, type ErrorCode } from '@naman_deep_singh/errors-utils'
+import type { CacheErrorCode } from './cacheErrorCodes'
+
+export class CacheError extends AppError {
+	readonly adapter?: string
+	readonly operation?: string
+
+	constructor(
+		code: CacheErrorCode,
+		options?: {
+			adapter?: string
+			operation?: string
+			details?: unknown
+			cause?: Error
+		},
+	) {
+		super(code as ErrorCode, undefined, options?.details, options?.cause)
+		this.adapter = options?.adapter
+		this.operation = options?.operation
+	}
+}

package/packages/cache/src/errors/cacheErrorCodes.ts

@@ -0,0 +1,24 @@
+export const 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',
+} as const
+
+export type CacheErrorCode =
+	(typeof CACHE_ERROR_CODES)[keyof typeof CACHE_ERROR_CODES]

package/packages/cache/src/errors/index.ts

@@ -0,0 +1,6 @@
+import { errorMessageRegistry } from '@naman_deep_singh/errors-utils'
+import { CACHE_ERROR_CODES } from './cacheErrorCodes'
+
+errorMessageRegistry.register(CACHE_ERROR_CODES)
+
+export { CacheError } from './CacheError'

package/packages/cache/src/index.ts

@@ -0,0 +1,40 @@
+// Types
+export type {
+	CacheConfig,
+	RedisCacheConfig,
+	MemcacheCacheConfig,
+	MemoryCacheConfig,
+	SessionData,
+	SessionOptions,
+	CacheStats,
+	HealthCheckResponse,
+	BatchResult,
+	CacheEntry,
+} from './types'
+
+// Errors
+export { CacheError } from './errors'
+
+// Interfaces
+export type { ICache, ISession } from './core/interfaces'
+
+// Base Cache
+export { BaseCache } from './core/BaseCache'
+
+// Adapters
+export { RedisCache } from './adapters/redis'
+export { MemcacheCache } from './adapters/memcache'
+export { MemoryCache } from './adapters/memory'
+
+// Factory
+export { CacheFactory } from './core/factory'
+
+// Session
+export { SessionStore } from './session'
+
+// Middleware
+export {
+	cacheSessionMiddleware,
+	cacheHealthCheckMiddleware,
+	cacheResponseMiddleware,
+} from './middleware/express'

package/packages/cache/src/middleware/express/cacheMiddleware.ts

@@ -0,0 +1,145 @@
+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 function cacheSessionMiddleware(
+	sessionStore: SessionStore,
+	options?: {
+		sessionIdHeader?: string
+		sessionDataKey?: string
+	},
+) {
+	const sessionIdHeader = options?.sessionIdHeader ?? 'x-session-id'
+	const sessionDataKey = options?.sessionDataKey ?? 'session'
+
+	return async (req: Request, _res: Response, next: NextFunction) => {
+		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 as any)[sessionDataKey] = sessionData
+				}
+			}
+
+			next()
+		} catch (error) {
+			console.error('Session middleware error:', error)
+			next()
+		}
+	}
+}
+
+/**
+ * Express middleware for cache health check
+ */
+export function cacheHealthCheckMiddleware(
+	cache: ICache,
+	endpoint = '/.health/cache',
+) {
+	return (req: Request, res: Response, next: NextFunction) => {
+		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 as Error).message,
+					})
+				})
+			return
+		}
+
+		next()
+	}
+}
+
+/**
+ * Express middleware for cache request/response caching
+ */
+export function cacheResponseMiddleware(
+	cache: ICache<string>,
+	options?: {
+		ttl?: number
+		keyPrefix?: string
+		excludeStatusCodes?: number[]
+	},
+) {
+	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: Request, res: Response, next: NextFunction) => {
+		// 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: unknown) {
+					// Check if response should be cached
+					if (
+						res.statusCode >= 200 &&
+						res.statusCode < 300 &&
+						!excludeStatusCodes.includes(res.statusCode)
+					) {
+						let responseData: string | null = 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 as any)
+				}
+
+				next()
+			})
+			.catch((error) => {
+				console.error('Cache middleware error:', error)
+				next()
+			})
+	}
+}

package/packages/cache/src/middleware/express/index.ts

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

package/packages/cache/src/session/SessionStore.ts

@@ -0,0 +1,236 @@
+import { CacheError } from '../errors'
+
+import { CACHE_ERROR_CODES } from 'src/errors/cacheErrorCodes'
+import type { ICache } from '../core/interfaces'
+import type { SessionData, SessionOptions } from '../types'
+
+/**
+ * Session store wrapper around cache adapters
+ * Provides session management functionality
+ */
+export class SessionStore {
+	private cache: ICache<SessionData>
+	private options: Required<SessionOptions>
+
+	constructor(cache: ICache<SessionData>, options: SessionOptions = {}) {
+		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: string,
+		data: SessionData,
+		ttl?: number,
+	): Promise<void> {
+		try {
+			const ttlValue = ttl ?? this.options.ttl
+			await this.cache.set(sessionId, data, ttlValue)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_CREATE_ERROR, {
+				adapter: 'session',
+				operation: 'create',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Get session data
+	 */
+	async get(sessionId: string): Promise<SessionData | null> {
+		try {
+			return await this.cache.get(sessionId)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_GET_ERROR, {
+				adapter: 'session',
+				operation: 'get',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Update/merge session data
+	 */
+	async update(sessionId: string, data: Partial<SessionData>): Promise<void> {
+		try {
+			const current = await this.cache.get(sessionId)
+
+			if (!current) {
+				throw new CacheError(CACHE_ERROR_CODES.SESSION_NOT_FOUND, {
+					adapter: 'session',
+					operation: 'update',
+					details: { sessionId },
+				})
+			}
+
+			const merged = { ...current, ...data }
+			await this.cache.set(sessionId, merged, this.options.ttl)
+		} catch (error) {
+			if (error instanceof CacheError) {
+				throw error
+			}
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_UPDATE_ERROR, {
+				adapter: 'session',
+				operation: 'update',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Delete session
+	 */
+	async delete(sessionId: string): Promise<boolean> {
+		try {
+			return await this.cache.delete(sessionId)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_DELETE_ERROR, {
+				adapter: 'session',
+				operation: 'delete',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Check if session exists
+	 */
+	async exists(sessionId: string): Promise<boolean> {
+		try {
+			return await this.cache.exists(sessionId)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_EXISTS_ERROR, {
+				adapter: 'session',
+				operation: 'exists',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Clear all sessions
+	 */
+	async clear(): Promise<void> {
+		try {
+			await this.cache.clear()
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_CLEAR_ERROR, {
+				adapter: 'session',
+				operation: 'clear',
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Get all session keys (limited use - may be slow with large datasets)
+	 */
+	async getMultiple(
+		sessionIds: string[],
+	): Promise<Record<string, SessionData | null>> {
+		try {
+			return await this.cache.getMultiple(sessionIds)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_GET_MULTIPLE_ERROR, {
+				adapter: 'session',
+				operation: 'getMultiple',
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Delete multiple sessions
+	 */
+	async deleteMultiple(sessionIds: string[]): Promise<number> {
+		try {
+			return await this.cache.deleteMultiple(sessionIds)
+		} catch (error) {
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_DELETE_MULTIPLE_ERROR, {
+				adapter: 'session',
+				operation: 'deleteMultiple',
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Extend session expiry
+	 */
+	async extend(sessionId: string, ttl?: number): Promise<void> {
+		try {
+			const current = await this.cache.get(sessionId)
+
+			if (!current) {
+				throw new CacheError(CACHE_ERROR_CODES.SESSION_NOT_FOUND, {
+					adapter: 'session',
+					operation: 'extend',
+					details: { sessionId },
+				})
+			}
+
+			const ttlValue = ttl ?? this.options.ttl
+			await this.cache.set(sessionId, current, ttlValue)
+		} catch (error) {
+			if (error instanceof CacheError) {
+				throw error
+			}
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_EXTEND_ERROR, {
+				adapter: 'session',
+				operation: 'extend',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Get session data and extend expiry in one operation
+	 */
+	async getAndExtend(
+		sessionId: string,
+		ttl?: number,
+	): Promise<SessionData | null> {
+		try {
+			const data = await this.get(sessionId)
+
+			if (data) {
+				await this.extend(sessionId, ttl)
+			}
+
+			return data
+		} catch (error) {
+			if (error instanceof CacheError) {
+				throw error
+			}
+			throw new CacheError(CACHE_ERROR_CODES.SESSION_GET_EXTEND_ERROR, {
+				adapter: 'session',
+				operation: 'getAndExtend',
+				details: { sessionId },
+				cause: error instanceof Error ? error : undefined,
+			})
+		}
+	}
+
+	/**
+	 * Optional close hook for graceful shutdowns.
+	 * Present to allow callers to call `close()` during shutdown without
+	 * requiring every store implementation to provide one.
+	 */
+	async close(): Promise<void> {
+		return
+	}
+}

package/packages/cache/src/session/index.ts

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

package/packages/cache/src/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+	adapter: 'redis' | 'memcache' | 'memory'
+	namespace?: string
+	ttl?: number // Default TTL in seconds
+	fallback?: boolean // Enable fallback to memory cache
+}
+
+/**
+ * Redis-cluster configuration
+ */
+export interface RedisClusterConfig {
+	nodes: Array<{
+		host: string
+		port: number
+	}>
+	options?: {
+		enableReadyCheck?: boolean
+		maxRedirections?: number
+		retryDelayOnFailover?: number
+		retryDelayOnClusterDown?: number
+	}
+}
+
+/**
+ * Redis-specific configuration
+ */
+export interface RedisCacheConfig extends CacheConfig {
+	adapter: 'redis'
+	// Existing single-instance
+	host?: string
+	port?: number
+	// New cluster support
+	cluster?: RedisClusterConfig | Array<{ 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 // Maximum number of items
+}
+
+/**
+ * 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
+}