@spfn/core 0.1.0-alpha.8 → 0.1.0-alpha.81

package/dist/cache/index.d.ts

@@ -0,0 +1,211 @@
+import { Redis, Cluster } from 'ioredis';
+
+/**
+ * Cache factory with automatic environment variable detection
+ * Supports Valkey and Redis with multiple deployment patterns
+ *
+ * Valkey is a Redis fork (7.2.4 base) with 100% protocol compatibility
+ * https://valkey.io
+ */
+
+interface CacheClients {
+    /** Primary cache for writes (or both read/write if no replica) */
+    write?: Redis | Cluster;
+    /** Replica cache for reads (optional, falls back to write) */
+    read?: Redis | Cluster;
+}
+/**
+ * Create cache client(s) from environment variables
+ *
+ * Supported patterns (priority order):
+ * 1. Single instance: VALKEY_URL or CACHE_URL or REDIS_URL
+ * 2. Master-Replica: VALKEY_WRITE_URL + VALKEY_READ_URL (or CACHE_*, REDIS_*)
+ * 3. Sentinel: VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (or REDIS_*)
+ * 4. Cluster: VALKEY_CLUSTER_NODES (or REDIS_*)
+ *
+ * @returns Cache client(s) or undefined if no configuration found
+ *
+ * @example
+ * ```bash
+ * # Single (most common)
+ * VALKEY_URL=valkey://localhost:6379
+ * CACHE_URL=redis://localhost:6379
+ *
+ * # Legacy (still supported)
+ * REDIS_URL=redis://localhost:6379
+ * REDIS_URL=rediss://secure.redis.com:6380  # TLS
+ *
+ * # Master-Replica
+ * VALKEY_WRITE_URL=valkey://master:6379
+ * VALKEY_READ_URL=valkey://replica:6379
+ *
+ * # Sentinel
+ * VALKEY_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
+ * VALKEY_MASTER_NAME=mymaster
+ * VALKEY_PASSWORD=secret
+ *
+ * # Cluster
+ * VALKEY_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
+ * VALKEY_PASSWORD=secret
+ * ```
+ */
+declare function createCacheFromEnv(): Promise<CacheClients>;
+/**
+ * Create single cache client (backward compatibility)
+ * Only returns write instance
+ */
+declare function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>;
+
+/**
+ * Global cache instance manager
+ * Provides singleton access to cache (Valkey/Redis) across all modules
+ * Supports Master-Replica pattern with separate read/write instances
+ *
+ * When cache is unavailable, falls back to disabled mode gracefully
+ */
+
+/**
+ * Get global cache write instance
+ *
+ * @returns Cache write instance or undefined if disabled/not initialized
+ *
+ * @example
+ * ```typescript
+ * import { getCache } from '@spfn/core/cache';
+ *
+ * const cache = getCache();
+ * if (cache) {
+ *   await cache.set('key', 'value');
+ * } else {
+ *   // Cache disabled - handle gracefully
+ *   console.log('Cache unavailable, skipping...');
+ * }
+ * ```
+ */
+declare function getCache(): Redis | Cluster | undefined;
+/**
+ * Get global cache read instance (falls back to write if no replica)
+ *
+ * @returns Cache read instance or write instance as fallback, undefined if disabled
+ *
+ * @example
+ * ```typescript
+ * import { getCacheRead } from '@spfn/core/cache';
+ *
+ * const cache = getCacheRead();
+ * if (cache) {
+ *   const value = await cache.get('key');
+ * }
+ * ```
+ */
+declare function getCacheRead(): Redis | Cluster | undefined;
+/**
+ * Check if cache is disabled (connection failed or not configured)
+ *
+ * @example
+ * ```typescript
+ * import { isCacheDisabled } from '@spfn/core/cache';
+ *
+ * if (isCacheDisabled()) {
+ *   // Use alternative strategy (e.g., in-memory cache, database)
+ *   return await fetchFromDatabase();
+ * }
+ * ```
+ */
+declare function isCacheDisabled(): boolean;
+/**
+ * Set global cache instances (for testing or manual configuration)
+ *
+ * @param write - Cache write instance
+ * @param read - Cache read instance (optional, defaults to write)
+ *
+ * @example
+ * ```typescript
+ * import { setCache } from '@spfn/core/cache';
+ * import Redis from 'ioredis';
+ *
+ * const write = new Redis('redis://master:6379');
+ * const read = new Redis('redis://replica:6379');
+ * setCache(write, read);
+ * ```
+ */
+declare function setCache(write: Redis | Cluster | undefined, read?: Redis | Cluster | undefined): void;
+/**
+ * Initialize cache from environment variables
+ * Automatically called by startServer()
+ *
+ * Supported environment variables (priority order):
+ * - VALKEY_URL / CACHE_URL (single instance)
+ * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)
+ * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)
+ * - VALKEY_CLUSTER_NODES (cluster)
+ * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)
+ * - Legacy: REDIS_* (backward compatibility)
+ *
+ * @returns Object with write and read instances, or undefined if disabled
+ *
+ * @example
+ * ```typescript
+ * import { initCache } from '@spfn/core/cache';
+ *
+ * // Manual initialization (not needed if using startServer)
+ * const { write, read, disabled } = await initCache();
+ * if (!disabled) {
+ *   console.log('Cache available');
+ * }
+ * ```
+ */
+declare function initCache(): Promise<{
+    write?: Redis | Cluster;
+    read?: Redis | Cluster;
+    disabled: boolean;
+}>;
+/**
+ * Close all cache connections and cleanup
+ *
+ * @example
+ * ```typescript
+ * import { closeCache } from '@spfn/core/cache';
+ *
+ * // During graceful shutdown
+ * await closeCache();
+ * ```
+ */
+declare function closeCache(): Promise<void>;
+/**
+ * Get cache connection info (for debugging)
+ *
+ * @example
+ * ```typescript
+ * import { getCacheInfo } from '@spfn/core/cache';
+ *
+ * const info = getCacheInfo();
+ * console.log(info);
+ * // {
+ * //   hasWrite: true,
+ * //   hasRead: true,
+ * //   isReplica: true,
+ * //   disabled: false
+ * // }
+ * ```
+ */
+declare function getCacheInfo(): {
+    hasWrite: boolean;
+    hasRead: boolean;
+    isReplica: boolean;
+    disabled: boolean;
+};
+/** @deprecated Use getCache() instead */
+declare const getRedis: typeof getCache;
+/** @deprecated Use getCacheRead() instead */
+declare const getRedisRead: typeof getCacheRead;
+/** @deprecated Use setCache() instead */
+declare const setRedis: typeof setCache;
+/** @deprecated Use initCache() instead */
+declare const initRedis: typeof initCache;
+/** @deprecated Use closeCache() instead */
+declare const closeRedis: typeof closeCache;
+/** @deprecated Use getCacheInfo() instead */
+declare const getRedisInfo: typeof getCacheInfo;
+
+export { type CacheClients, type CacheClients as RedisClients, closeCache, closeRedis, createCacheFromEnv, createCacheFromEnv as createRedisFromEnv, createSingleCacheFromEnv, createSingleCacheFromEnv as createSingleRedisFromEnv, getCache, getCacheInfo, getCacheRead, getRedis, getRedisInfo, getRedisRead, initCache, initRedis, isCacheDisabled, setCache, setRedis };