ts-packages 1.0.0 → 3.0.0

package/packages/cache/dist/esm/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    adapter: 'redis' | 'memcache' | 'memory';
+    namespace?: string;
+    ttl?: number;
+    fallback?: boolean;
+}
+/**
+ * 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';
+    host?: string;
+    port?: number;
+    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;
+}
+/**
+ * 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/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,18 @@
+import { BaseCache } from '../../core/BaseCache';
+import type { HealthCheckResponse, MemcacheCacheConfig } from '../../types';
+export declare class MemcacheCache<T = unknown> extends BaseCache<T> {
+    private memcacheConfig;
+    private client;
+    private isConnected;
+    constructor(memcacheConfig: MemcacheCacheConfig);
+    connect(): Promise<void>;
+    private ensureConnected;
+    private ping;
+    exists(key: string): Promise<boolean>;
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    isAlive(): Promise<HealthCheckResponse>;
+    close(): Promise<void>;
+}

package/packages/cache/dist/types/adapters/memcache/index.d.ts

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

package/packages/cache/dist/types/adapters/memory/MemoryCache.d.ts

@@ -0,0 +1,63 @@
+import { BaseCache } from '../../core/BaseCache';
+import type { HealthCheckResponse, MemoryCacheConfig } from '../../types';
+/**
+ * In-memory cache adapter for development and testing
+ */
+export declare class MemoryCache<T = unknown> extends BaseCache<T> {
+    private memoryCacheConfig;
+    private store;
+    private cleanupInterval;
+    constructor(memoryCacheConfig: MemoryCacheConfig);
+    /**
+     * Start periodic cleanup of expired items
+     */
+    private startCleanup;
+    /**
+     * Get a value from memory
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in memory
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a key from memory
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys with current namespace
+     */
+    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
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Decrement a numeric value
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+    /**
+     * Check if memory cache is alive
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close memory cache
+     */
+    close(): Promise<void>;
+}

package/packages/cache/dist/types/adapters/memory/index.d.ts

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

package/packages/cache/dist/types/adapters/redis/RedisCache.d.ts

@@ -0,0 +1,67 @@
+import { BaseCache } from '../../core/BaseCache';
+import type { HealthCheckResponse, RedisCacheConfig } from '../../types';
+/**
+ * Redis cache adapter
+ */
+export declare class RedisCache<T = unknown> extends BaseCache<T> {
+    private redisConfig;
+    private client;
+    private isConnected;
+    constructor(redisConfig: RedisCacheConfig);
+    /**
+     * Connect to Redis
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure client is connected
+     */
+    private ensureConnected;
+    /**
+     * Get a value from Redis
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a value in Redis
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a key from Redis
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys with current namespace
+     */
+    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
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Decrement a numeric value
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+    /**
+     * Check if Redis is alive
+     */
+    isAlive(): Promise<HealthCheckResponse>;
+    /**
+     * Close Redis connection
+     */
+    close(): Promise<void>;
+}

package/packages/cache/dist/types/adapters/redis/index.d.ts

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

package/packages/cache/dist/types/core/BaseCache.d.ts

@@ -0,0 +1,78 @@
+import type { BatchResult, CacheConfig, CacheStats, HealthCheckResponse } from '../types';
+import type { ICache } from './interfaces';
+/**
+ * Abstract base class for all cache adapters
+ */
+export declare abstract class BaseCache<T = unknown> implements ICache<T> {
+    protected config: CacheConfig;
+    protected readonly namespace: string;
+    protected readonly ttl: number;
+    protected stats: CacheStats;
+    constructor(config: CacheConfig);
+    /**
+     * Build full key with namespace prefix
+     */
+    protected buildKey(key: string): string;
+    /**
+     * Deserialize string to object
+     */
+    protected deserialize(data: string): T;
+    /**
+     * Serialize object to string
+     */
+    protected serialize(value: T): string;
+    /**
+     * Track cache hit
+     */
+    protected recordHit(): void;
+    /**
+     * Track cache miss
+     */
+    protected recordMiss(): void;
+    /**
+     * Track cache set
+     */
+    protected recordSet(): void;
+    /**
+     * Track cache delete
+     */
+    protected recordDelete(): void;
+    /**
+     * Reset statistics
+     */
+    protected resetStats(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Abstract methods - must be implemented by subclasses
+     */
+    abstract get(key: string): Promise<T | null>;
+    abstract set(key: string, value: T, ttl?: number): Promise<void>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract clear(): Promise<void>;
+    abstract isAlive(): Promise<HealthCheckResponse>;
+    abstract close(): Promise<void>;
+    /**
+     * Default implementation for getMultiple
+     */
+    getMultiple(keys: string[]): Promise<BatchResult<T>>;
+    /**
+     * Default implementation for setMultiple
+     */
+    setMultiple(data: Record<string, T>, ttl?: number): Promise<void>;
+    /**
+     * Default implementation for deleteMultiple
+     */
+    deleteMultiple(keys: string[]): Promise<number>;
+    /**
+     * Default implementation for increment
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Default implementation for decrement
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+}

package/packages/cache/dist/types/core/factory.d.ts

@@ -0,0 +1,16 @@
+import type { CacheConfig } from '../types';
+import type { ICache } from './interfaces';
+/**
+ * Factory for creating cache instances
+ */
+export declare class CacheFactory {
+    /**
+     * Create a cache instance based on configuration
+     */
+    static create<T = unknown>(config: CacheConfig): ICache<T>;
+    /**
+     * Create a cache with fallback support
+     * If primary adapter fails to connect, falls back to memory cache
+     */
+    static createWithFallback<T = unknown>(config: CacheConfig): Promise<ICache<T>>;
+}

package/packages/cache/dist/types/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/types/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/types/core/interfaces/index.d.ts

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

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

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

package/packages/cache/dist/types/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/types/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/types/middleware/express/index.d.ts

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

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

package/packages/cache/dist/types/session/index.d.ts

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