ts-packages 1.0.0 → 2.0.0

package/packages/cache/dist/cjs/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/cjs/session/SessionStore.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+const errors_1 = require("../errors");
+/**
+ * Session store wrapper around cache adapters
+ * Provides session management functionality
+ */
+class SessionStore {
+    constructor(cache, options = {}) {
+        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, data, ttl) {
+        try {
+            const ttlValue = ttl ?? this.options.ttl;
+            await this.cache.set(sessionId, data, ttlValue);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to create session "${sessionId}"`, 'SESSION_CREATE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get session data
+     */
+    async get(sessionId) {
+        try {
+            return await this.cache.get(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to get session "${sessionId}"`, 'SESSION_GET_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Update/merge session data
+     */
+    async update(sessionId, data) {
+        try {
+            const current = await this.cache.get(sessionId);
+            if (!current) {
+                throw new errors_1.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 errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to update session "${sessionId}"`, 'SESSION_UPDATE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Delete session
+     */
+    async delete(sessionId) {
+        try {
+            return await this.cache.delete(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to delete session "${sessionId}"`, 'SESSION_DELETE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Check if session exists
+     */
+    async exists(sessionId) {
+        try {
+            return await this.cache.exists(sessionId);
+        }
+        catch (err) {
+            throw new errors_1.CacheError(`Failed to check session "${sessionId}" existence`, 'SESSION_EXISTS_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Clear all sessions
+     */
+    async clear() {
+        try {
+            await this.cache.clear();
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to clear sessions', 'SESSION_CLEAR_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get all session keys (limited use - may be slow with large datasets)
+     */
+    async getMultiple(sessionIds) {
+        try {
+            return await this.cache.getMultiple(sessionIds);
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to get multiple sessions', 'SESSION_GET_MULTIPLE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Delete multiple sessions
+     */
+    async deleteMultiple(sessionIds) {
+        try {
+            return await this.cache.deleteMultiple(sessionIds);
+        }
+        catch (err) {
+            throw new errors_1.CacheError('Failed to delete multiple sessions', 'SESSION_DELETE_MULTIPLE_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Extend session expiry
+     */
+    async extend(sessionId, ttl) {
+        try {
+            const current = await this.cache.get(sessionId);
+            if (!current) {
+                throw new errors_1.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 errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to extend session "${sessionId}"`, 'SESSION_EXTEND_ERROR', 'session', err);
+        }
+    }
+    /**
+     * Get session data and extend expiry in one operation
+     */
+    async getAndExtend(sessionId, ttl) {
+        try {
+            const data = await this.get(sessionId);
+            if (data) {
+                await this.extend(sessionId, ttl);
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof errors_1.CacheError) {
+                throw err;
+            }
+            throw new errors_1.CacheError(`Failed to get and extend session "${sessionId}"`, 'SESSION_GET_EXTEND_ERROR', 'session', err);
+        }
+    }
+    /**
+     * 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() {
+        return;
+    }
+}
+exports.SessionStore = SessionStore;

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

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

package/packages/cache/dist/cjs/session/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+var SessionStore_1 = require("./SessionStore");
+Object.defineProperty(exports, "SessionStore", { enumerable: true, get: function () { return SessionStore_1.SessionStore; } });

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,71 @@
+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
+     */
+    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>;
+}