ts-packages 1.0.0 → 2.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,22 @@
+/**
+ * Custom error class for cache operations
+ */
+export class CacheError extends Error {
+	public readonly code: string
+	public readonly adapter?: string
+	public readonly originalError?: Error
+
+	constructor(
+		message: string,
+		code = 'CACHE_ERROR',
+		adapter?: string,
+		originalError?: Error,
+	) {
+		super(message)
+		this.name = 'CacheError'
+		this.code = code
+		this.adapter = adapter
+		this.originalError = originalError
+		Object.setPrototypeOf(this, CacheError.prototype)
+	}
+}

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

@@ -0,0 +1 @@
+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 (err) {
+			console.error('Session middleware error:', err)
+			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((err) => {
+					res.status(503).json({
+						isAlive: false,
+						adapter: 'unknown',
+						timestamp: new Date(),
+						error: (err 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((err) => {
+								console.error('Failed to cache response:', err)
+							})
+						}
+					}
+
+					res.set('X-Cache', 'MISS')
+					return originalSend.call(this, data as any)
+				}
+
+				next()
+			})
+			.catch((err) => {
+				console.error('Cache middleware error:', err)
+				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 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 (err) {
+			throw new CacheError(
+				`Failed to create session "${sessionId}"`,
+				'SESSION_CREATE_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * Get session data
+	 */
+	async get(sessionId: string): Promise<SessionData | null> {
+		try {
+			return await this.cache.get(sessionId)
+		} catch (err) {
+			throw new CacheError(
+				`Failed to get session "${sessionId}"`,
+				'SESSION_GET_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * 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(
+					`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 as Error,
+			)
+		}
+	}
+
+	/**
+	 * Delete session
+	 */
+	async delete(sessionId: string): Promise<boolean> {
+		try {
+			return await this.cache.delete(sessionId)
+		} catch (err) {
+			throw new CacheError(
+				`Failed to delete session "${sessionId}"`,
+				'SESSION_DELETE_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * Check if session exists
+	 */
+	async exists(sessionId: string): Promise<boolean> {
+		try {
+			return await this.cache.exists(sessionId)
+		} catch (err) {
+			throw new CacheError(
+				`Failed to check session "${sessionId}" existence`,
+				'SESSION_EXISTS_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * Clear all sessions
+	 */
+	async clear(): Promise<void> {
+		try {
+			await this.cache.clear()
+		} catch (err) {
+			throw new CacheError(
+				'Failed to clear sessions',
+				'SESSION_CLEAR_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * 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 (err) {
+			throw new CacheError(
+				'Failed to get multiple sessions',
+				'SESSION_GET_MULTIPLE_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * Delete multiple sessions
+	 */
+	async deleteMultiple(sessionIds: string[]): Promise<number> {
+		try {
+			return await this.cache.deleteMultiple(sessionIds)
+		} catch (err) {
+			throw new CacheError(
+				'Failed to delete multiple sessions',
+				'SESSION_DELETE_MULTIPLE_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * Extend session expiry
+	 */
+	async extend(sessionId: string, ttl?: number): Promise<void> {
+		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 as Error,
+			)
+		}
+	}
+
+	/**
+	 * 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 (err) {
+			if (err instanceof CacheError) {
+				throw err
+			}
+			throw new CacheError(
+				`Failed to get and extend session "${sessionId}"`,
+				'SESSION_GET_EXTEND_ERROR',
+				'session',
+				err as Error,
+			)
+		}
+	}
+
+	/**
+	 * 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
+}

package/packages/cache/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "baseUrl": ".",
+    "paths": {
+      "*": ["*", "*.ts", "*.js"]
+    }
+  },
+  "include": ["src/**/*"]
+}

package/packages/cache/tsconfig.cjs.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "rootDir": "./src",
+    "outDir": "./dist/cjs"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}