@spfn/core
Version:
SPFN Framework Core - File-based routing, transactions, repository pattern
212 lines (206 loc) • 6.29 kB
TypeScript
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 };