@qwickapps/server 1.6.1 → 1.7.1

package/dist/src/plugins/cache-plugin.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Cache Plugin
+ *
+ * Provides caching capabilities with Redis or in-memory storage.
+ * Supports Redis via 'ioredis' library or zero-dependency in-memory LRU cache.
+ *
+ * ## Features
+ * - Dual-mode: Redis (persistent, distributed) or Memory (fast, local)
+ * - Connection management with automatic reconnection (Redis)
+ * - LRU eviction with TTL expiration (Memory)
+ * - Key prefixing for multi-tenant/multi-app scenarios
+ * - TTL-based caching with get/set operations
+ * - Automatic health checks
+ * - Multiple named instances support
+ * - Graceful shutdown
+ *
+ * ## Usage (Redis)
+ *
+ * ```typescript
+ * import { createGateway, createCachePlugin, getCache } from '@qwickapps/server';
+ *
+ * const gateway = createGateway({
+ *   // ... config
+ *   plugins: [
+ *     createCachePlugin({
+ *       type: 'redis',
+ *       url: process.env.REDIS_URL,
+ *       keyPrefix: 'myapp:',
+ *     }),
+ *   ],
+ * });
+ *
+ * // In your service code:
+ * const cache = getCache();
+ * await cache.set('user:123', userData, 3600); // Cache for 1 hour
+ * const user = await cache.get<User>('user:123');
+ * ```
+ *
+ * ## Usage (In-Memory)
+ *
+ * ```typescript
+ * // Zero external dependencies - perfect for demos and testing
+ * createCachePlugin({
+ *   type: 'memory',
+ *   keyPrefix: 'demo:',
+ *   defaultTtl: 3600,
+ *   maxMemoryEntries: 5000,
+ * })
+ * ```
+ *
+ * ## Multiple Caches
+ *
+ * ```typescript
+ * // Register multiple caches with different names
+ * createCachePlugin({ url: primaryUrl, keyPrefix: 'session:' }, 'sessions');
+ * createCachePlugin({ type: 'memory', keyPrefix: 'cache:' }, 'content');
+ *
+ * // Access by name
+ * const sessions = getCache('sessions');
+ * const content = getCache('content');
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Plugin } from '../core/plugin-registry.js';
+type Redis = import('ioredis').default;
+/**
+ * Configuration for the cache plugin
+ */
+export interface CachePluginConfig {
+    /** Cache type: 'redis' or 'memory' (default: 'redis' if url provided, 'memory' otherwise) */
+    type?: 'redis' | 'memory';
+    /** Redis connection URL (required for type='redis', e.g., redis://localhost:6379) */
+    url?: string;
+    /** Key prefix for all cache operations (default: '') */
+    keyPrefix?: string;
+    /** Default TTL in seconds for set operations (default: 3600 = 1 hour) */
+    defaultTtl?: number;
+    /** Maximum number of entries for memory cache (default: 10000, only used for type='memory') */
+    maxMemoryEntries?: number;
+    /** Maximum number of retry attempts (default: 3, only used for type='redis') */
+    maxRetries?: number;
+    /** Retry delay in milliseconds (default: 1000, only used for type='redis') */
+    retryDelayMs?: number;
+    /** Connection timeout in milliseconds (default: 5000, only used for type='redis') */
+    connectTimeoutMs?: number;
+    /** Command timeout in milliseconds (default: 5000, only used for type='redis') */
+    commandTimeoutMs?: number;
+    /** Register a health check for this cache (default: true) */
+    healthCheck?: boolean;
+    /** Name for the health check (default: 'redis' or 'memory') */
+    healthCheckName?: string;
+    /** Health check interval in milliseconds (default: 30000) */
+    healthCheckInterval?: number;
+    /** Called when connection is ready (only used for type='redis') */
+    onConnect?: () => void;
+    /** Called on connection errors (only used for type='redis') */
+    onError?: (error: Error) => void;
+    /** Enable lazy connect - don't connect until first command (default: false, only used for type='redis') */
+    lazyConnect?: boolean;
+}
+/**
+ * Cache instance returned by the plugin
+ */
+export interface CacheInstance {
+    /**
+     * Get a value from cache
+     * @param key - Cache key (prefix is applied automatically)
+     * @returns Parsed JSON value or null if not found
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Get a raw string value from cache
+     * @param key - Cache key (prefix is applied automatically)
+     * @returns Raw string value or null if not found
+     */
+    getRaw(key: string): Promise<string | null>;
+    /**
+     * Set a value in cache with TTL
+     * @param key - Cache key (prefix is applied automatically)
+     * @param value - Value to cache (will be JSON stringified)
+     * @param ttlSeconds - Time to live in seconds (uses defaultTtl if not specified)
+     */
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Set a raw string value in cache with TTL
+     * @param key - Cache key (prefix is applied automatically)
+     * @param value - Raw string value to cache
+     * @param ttlSeconds - Time to live in seconds (uses defaultTtl if not specified)
+     */
+    setRaw(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a key from cache
+     * @param key - Cache key (prefix is applied automatically)
+     * @returns true if key was deleted, false if it didn't exist
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete multiple keys matching a pattern
+     * @param pattern - Pattern to match (prefix is applied automatically)
+     * @returns Number of keys deleted
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Check if a key exists in cache
+     * @param key - Cache key (prefix is applied automatically)
+     * @returns true if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Set expiration time on a key
+     * @param key - Cache key (prefix is applied automatically)
+     * @param ttlSeconds - Time to live in seconds
+     * @returns true if timeout was set, false if key doesn't exist
+     */
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Get remaining TTL for a key
+     * @param key - Cache key (prefix is applied automatically)
+     * @returns TTL in seconds, -1 if no expiry, -2 if key doesn't exist
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * Increment a numeric value
+     * @param key - Cache key (prefix is applied automatically)
+     * @param delta - Amount to increment by (default: 1)
+     * @returns New value after increment
+     */
+    incr(key: string, delta?: number): Promise<number>;
+    /**
+     * Get all keys matching a pattern
+     * @param pattern - Pattern to match (prefix is applied automatically)
+     * @returns Array of matching keys (without prefix)
+     * @deprecated Use scanKeys() for production - keys() blocks Redis on large datasets
+     */
+    keys(pattern: string): Promise<string[]>;
+    /**
+     * Scan keys matching a pattern using cursor-based iteration (non-blocking)
+     * @param pattern - Pattern to match (prefix is applied automatically)
+     * @param options - Optional scan configuration
+     * @param options.count - Hint for how many keys to return per iteration (default: 100)
+     * @returns Array of matching keys (without prefix)
+     */
+    scanKeys(pattern: string, options?: {
+        count?: number;
+    }): Promise<string[]>;
+    /**
+     * Flush all keys with the configured prefix
+     * @returns Number of keys deleted
+     */
+    flush(): Promise<number>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<{
+        connected: boolean;
+        keyCount: number;
+        usedMemory?: string;
+    }>;
+    /**
+     * Get the underlying Redis client (for advanced use cases)
+     */
+    getClient(): Redis;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+}
+/**
+ * Get a cache instance by name
+ *
+ * @param name - Instance name (default: 'default')
+ * @returns The cache instance
+ * @throws Error if the instance is not registered
+ *
+ * @example
+ * ```typescript
+ * const cache = getCache();
+ * const user = await cache.get<User>('user:123');
+ * ```
+ */
+export declare function getCache(name?: string): CacheInstance;
+/**
+ * Check if a cache instance is registered
+ *
+ * @param name - Instance name (default: 'default')
+ * @returns true if the instance exists
+ */
+export declare function hasCache(name?: string): boolean;
+/**
+ * Create a cache plugin
+ *
+ * @param config - Cache configuration
+ * @param instanceName - Name for this cache instance (default: 'default')
+ * @returns A plugin
+ *
+ * @example
+ * ```typescript
+ * createCachePlugin({
+ *   url: process.env.REDIS_URL,
+ *   keyPrefix: 'myapp:',
+ *   defaultTtl: 3600,
+ *   healthCheck: true,
+ * });
+ * ```
+ */
+export declare function createCachePlugin(config: CachePluginConfig, instanceName?: string): Plugin;
+export {};
+//# sourceMappingURL=cache-plugin.d.ts.map

package/dist/src/plugins/cache-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache-plugin.ts"],"names":[],"mappings":"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"}