raffel 0.1.2

package/dist/cache/factory.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Cache Driver Factory
+ *
+ * Creates cache drivers with lazy loading.
+ * Drivers are only imported when actually used.
+ */
+import type { CacheDriver, CacheDriverType, CacheDriverConfig, MemoryDriverOptions, FileDriverOptions, RedisDriverOptions, S3DBDriverOptions } from './types.js';
+/**
+ * Create a cache driver by type
+ *
+ * Drivers are lazily loaded to avoid bundling unused dependencies.
+ *
+ * @example Memory driver (default)
+ * ```typescript
+ * const driver = await createDriver('memory', {
+ *   maxSize: 5000,
+ *   evictionPolicy: 'lru',
+ * })
+ * ```
+ *
+ * @example File driver
+ * ```typescript
+ * const driver = await createDriver('file', {
+ *   directory: '.cache',
+ *   maxFiles: 10000,
+ * })
+ * ```
+ *
+ * @example Redis driver
+ * ```typescript
+ * const driver = await createDriver('redis', {
+ *   client: redisClient,
+ *   prefix: 'myapp:cache:',
+ * })
+ * ```
+ *
+ * @example S3DB driver
+ * ```typescript
+ * const driver = await createDriver('s3db', {
+ *   s3db: s3dbInstance,
+ *   resource: 'cache',
+ * })
+ * ```
+ */
+export declare function createDriver(type: 'memory', options?: MemoryDriverOptions): Promise<CacheDriver>;
+export declare function createDriver(type: 'file', options?: FileDriverOptions): Promise<CacheDriver>;
+export declare function createDriver(type: 'redis', options: RedisDriverOptions): Promise<CacheDriver>;
+export declare function createDriver(type: 's3db', options: S3DBDriverOptions): Promise<CacheDriver>;
+/**
+ * Create a cache driver from a configuration object
+ *
+ * @example
+ * ```typescript
+ * const driver = await createDriverFromConfig({
+ *   driver: 'memory',
+ *   options: { maxSize: 5000 },
+ * })
+ * ```
+ */
+export declare function createDriverFromConfig(config: CacheDriverConfig): Promise<CacheDriver>;
+/**
+ * Synchronous driver creation (for cases where async is not possible)
+ *
+ * Note: This eagerly loads all driver code. Use createDriver() when possible
+ * for better tree-shaking and lazy loading.
+ */
+export declare function createDriverSync(type: 'memory', options?: MemoryDriverOptions): CacheDriver;
+export declare function createDriverSync(type: 'file', options?: FileDriverOptions): CacheDriver;
+/**
+ * Available driver types
+ */
+export declare const DRIVER_TYPES: CacheDriverType[];
+/**
+ * Check if a driver type is valid
+ */
+export declare function isValidDriverType(type: string): type is CacheDriverType;
+//# sourceMappingURL=factory.d.ts.map

package/dist/cache/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/cache/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAoDnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAAA;AACvB,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAA;AACvB,wBAAsB,YAAY,CAChC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAA;AACvB,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAAA;AA2BvB;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAa5F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,WAAW,CAAA;AACd,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,WAAW,CAAA;AA0Bd;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,eAAe,EAAwC,CAAA;AAElF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE"}

package/dist/cache/factory.js

@@ -0,0 +1,130 @@
+/**
+ * Cache Driver Factory
+ *
+ * Creates cache drivers with lazy loading.
+ * Drivers are only imported when actually used.
+ */
+// Lazy-loaded driver constructors
+let MemoryDriverClass = null;
+let FileDriverClass = null;
+let RedisDriverClass = null;
+let S3DBDriverClass = null;
+/**
+ * Lazily load the Memory driver
+ */
+async function loadMemoryDriver() {
+    if (!MemoryDriverClass) {
+        const module = await import('./drivers/memory.js');
+        MemoryDriverClass = module.MemoryDriver;
+    }
+    return MemoryDriverClass;
+}
+/**
+ * Lazily load the File driver
+ */
+async function loadFileDriver() {
+    if (!FileDriverClass) {
+        const module = await import('./drivers/file.js');
+        FileDriverClass = module.FileDriver;
+    }
+    return FileDriverClass;
+}
+/**
+ * Lazily load the Redis driver
+ */
+async function loadRedisDriver() {
+    if (!RedisDriverClass) {
+        const module = await import('./drivers/redis.js');
+        RedisDriverClass = module.RedisDriver;
+    }
+    return RedisDriverClass;
+}
+/**
+ * Lazily load the S3DB driver
+ */
+async function loadS3DBDriver() {
+    if (!S3DBDriverClass) {
+        const module = await import('./drivers/s3db.js');
+        S3DBDriverClass = module.S3DBDriver;
+    }
+    return S3DBDriverClass;
+}
+export async function createDriver(type, options) {
+    switch (type) {
+        case 'memory': {
+            const Driver = await loadMemoryDriver();
+            return new Driver(options);
+        }
+        case 'file': {
+            const Driver = await loadFileDriver();
+            return new Driver(options);
+        }
+        case 'redis': {
+            const Driver = await loadRedisDriver();
+            return new Driver(options);
+        }
+        case 's3db': {
+            const Driver = await loadS3DBDriver();
+            return new Driver(options);
+        }
+        default:
+            throw new Error(`Unknown cache driver type: ${type}`);
+    }
+}
+/**
+ * Create a cache driver from a configuration object
+ *
+ * @example
+ * ```typescript
+ * const driver = await createDriverFromConfig({
+ *   driver: 'memory',
+ *   options: { maxSize: 5000 },
+ * })
+ * ```
+ */
+export async function createDriverFromConfig(config) {
+    switch (config.driver) {
+        case 'memory':
+            return createDriver('memory', config.options);
+        case 'file':
+            return createDriver('file', config.options);
+        case 'redis':
+            return createDriver('redis', config.options);
+        case 's3db':
+            return createDriver('s3db', config.options);
+        default:
+            throw new Error(`Unknown cache driver: ${config.driver}`);
+    }
+}
+export function createDriverSync(type, options) {
+    // For sync creation, we need to use require-style imports
+    // This is a fallback for when async/await is not available
+    switch (type) {
+        case 'memory': {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { MemoryDriver } = require('./drivers/memory.js');
+            return new MemoryDriver(options);
+        }
+        case 'file': {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { FileDriver } = require('./drivers/file.js');
+            return new FileDriver(options);
+        }
+        case 'redis':
+        case 's3db':
+            throw new Error(`${type} driver requires async initialization. Use createDriver() instead.`);
+        default:
+            throw new Error(`Unknown cache driver type: ${type}`);
+    }
+}
+/**
+ * Available driver types
+ */
+export const DRIVER_TYPES = ['memory', 'file', 'redis', 's3db'];
+/**
+ * Check if a driver type is valid
+ */
+export function isValidDriverType(type) {
+    return DRIVER_TYPES.includes(type);
+}
+//# sourceMappingURL=factory.js.map

package/dist/cache/factory.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Cache Module
+ *
+ * Pluggable cache system with multiple driver support.
+ *
+ * Available drivers:
+ * - `memory`: High-performance in-memory cache (default)
+ *   - LRU/FIFO eviction
+ *   - Memory limits (bytes, percentage)
+ *   - Container-aware (Docker/K8s)
+ *   - Optional compression
+ *
+ * - `file`: File-system based persistent cache
+ *   - Survives restarts
+ *   - Size limits
+ *   - Optional compression
+ *
+ * - `redis`: Redis-backed distributed cache
+ *   - Works with any Redis-compatible client
+ *   - Key prefixing
+ *   - Optional compression
+ *
+ * - `s3db`: S3-based persistent cache
+ *   - Works with S3DB library
+ *   - Distributed cache
+ *   - High durability
+ *
+ * @example Basic usage with memory driver
+ * ```typescript
+ * import { createDriver } from 'raffel/cache'
+ *
+ * const cache = await createDriver('memory', {
+ *   maxSize: 5000,
+ *   evictionPolicy: 'lru',
+ *   compression: true,
+ * })
+ *
+ * await cache.set('users:123', user, 60000) // 1 minute TTL
+ * const result = await cache.get('users:123')
+ * ```
+ *
+ * @example Using with cache interceptor
+ * ```typescript
+ * import { createCacheInterceptor } from 'raffel/middleware'
+ * import { createDriver } from 'raffel/cache'
+ *
+ * const driver = await createDriver('redis', {
+ *   client: redisClient,
+ * })
+ *
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driver,
+ * })
+ *
+ * server.use(cache)
+ * ```
+ */
+export type { CacheDriver, CacheEntry, CacheGetResult, CacheStats, MemoryStats, CompressionStats, EvictionPolicy, CompressionConfig, MemoryDriverOptions, FileDriverOptions, RedisDriverOptions, RedisLikeClient, S3DBDriverOptions, S3DBLikeClient, CacheDriverType, CacheDriverConfig, EvictionInfo, PressureInfo, } from './types.js';
+export { createDriver, createDriverFromConfig, createDriverSync, DRIVER_TYPES, isValidDriverType, } from './factory.js';
+export { MemoryDriver, createMemoryDriver, FileDriver, createFileDriver, RedisDriver, createRedisDriver, S3DBDriver, createS3DBDriver, } from './drivers/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAGH,YAAY,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAA"}

package/dist/cache/index.js

@@ -0,0 +1,63 @@
+/**
+ * Cache Module
+ *
+ * Pluggable cache system with multiple driver support.
+ *
+ * Available drivers:
+ * - `memory`: High-performance in-memory cache (default)
+ *   - LRU/FIFO eviction
+ *   - Memory limits (bytes, percentage)
+ *   - Container-aware (Docker/K8s)
+ *   - Optional compression
+ *
+ * - `file`: File-system based persistent cache
+ *   - Survives restarts
+ *   - Size limits
+ *   - Optional compression
+ *
+ * - `redis`: Redis-backed distributed cache
+ *   - Works with any Redis-compatible client
+ *   - Key prefixing
+ *   - Optional compression
+ *
+ * - `s3db`: S3-based persistent cache
+ *   - Works with S3DB library
+ *   - Distributed cache
+ *   - High durability
+ *
+ * @example Basic usage with memory driver
+ * ```typescript
+ * import { createDriver } from 'raffel/cache'
+ *
+ * const cache = await createDriver('memory', {
+ *   maxSize: 5000,
+ *   evictionPolicy: 'lru',
+ *   compression: true,
+ * })
+ *
+ * await cache.set('users:123', user, 60000) // 1 minute TTL
+ * const result = await cache.get('users:123')
+ * ```
+ *
+ * @example Using with cache interceptor
+ * ```typescript
+ * import { createCacheInterceptor } from 'raffel/middleware'
+ * import { createDriver } from 'raffel/cache'
+ *
+ * const driver = await createDriver('redis', {
+ *   client: redisClient,
+ * })
+ *
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driver,
+ * })
+ *
+ * server.use(cache)
+ * ```
+ */
+// Factory
+export { createDriver, createDriverFromConfig, createDriverSync, DRIVER_TYPES, isValidDriverType, } from './factory.js';
+// Drivers (for direct import when needed)
+export { MemoryDriver, createMemoryDriver, FileDriver, createFileDriver, RedisDriver, createRedisDriver, S3DBDriver, createS3DBDriver, } from './drivers/index.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAwBH,UAAU;AACV,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,0CAA0C;AAC1C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAA"}

package/dist/cache/types.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Cache Driver Types
+ *
+ * Protocol-agnostic cache abstraction with pluggable drivers.
+ * Inspired by Recker's cache architecture.
+ */
+/**
+ * Cache entry stored by drivers
+ */
+export interface CacheEntry {
+    /** The cached value (JSON-serializable) */
+    value: unknown;
+    /** When the entry expires (Unix timestamp in ms) */
+    expiresAt: number;
+    /** When the entry was created */
+    createdAt: number;
+    /** Optional tags for grouping/invalidation */
+    tags?: string[];
+}
+/**
+ * Result from cache get operations
+ */
+export interface CacheGetResult {
+    /** The cached entry */
+    entry: CacheEntry;
+    /** Whether the entry is stale (past TTL but within grace period) */
+    stale?: boolean;
+}
+/**
+ * Cache driver interface
+ *
+ * All drivers must implement these core methods.
+ * Drivers handle serialization, storage, and cleanup internally.
+ */
+export interface CacheDriver {
+    /** Driver name for identification */
+    readonly name: string;
+    /**
+     * Get a cached entry
+     * @returns The cached entry or undefined if not found/expired
+     */
+    get(key: string): Promise<CacheGetResult | undefined>;
+    /**
+     * Set a cached entry
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttlMs - Time to live in milliseconds
+     * @param tags - Optional tags for grouping
+     */
+    set(key: string, value: unknown, ttlMs: number, tags?: string[]): Promise<void>;
+    /**
+     * Delete a cached entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries or entries matching a prefix
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Check if a key exists (without fetching value)
+     */
+    has?(key: string): Promise<boolean>;
+    /**
+     * Get all keys matching a pattern (for debugging/admin)
+     */
+    keys?(pattern?: string): Promise<string[]>;
+    /**
+     * Get driver statistics
+     */
+    stats?(): CacheStats;
+    /**
+     * Shutdown the driver (cleanup timers, connections, etc.)
+     */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of sets */
+    sets: number;
+    /** Number of deletes */
+    deletes: number;
+    /** Number of evictions */
+    evictions: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Total items in cache */
+    totalItems: number;
+    /** Current memory usage in bytes (if tracked) */
+    memoryUsageBytes?: number;
+    /** Maximum memory limit in bytes (if configured) */
+    maxMemoryBytes?: number;
+}
+/**
+ * Memory usage statistics
+ */
+export interface MemoryStats {
+    currentMemoryBytes: number;
+    maxMemoryBytes: number;
+    memoryUsagePercent: number;
+    totalItems: number;
+    maxSize: number;
+    evictedDueToMemory: number;
+    memoryPressureEvents: number;
+    averageItemSize: number;
+}
+/**
+ * Compression statistics
+ */
+export interface CompressionStats {
+    enabled: boolean;
+    totalItems: number;
+    compressedItems: number;
+    compressionThreshold: number;
+    totalOriginalSize: number;
+    totalCompressedSize: number;
+    compressionRatio: number;
+    spaceSavingsPercent: number;
+}
+/**
+ * Eviction policy for memory driver
+ */
+export type EvictionPolicy = 'lru' | 'fifo';
+/**
+ * Compression configuration
+ */
+export interface CompressionConfig {
+    /** Enable compression */
+    enabled: boolean;
+    /** Minimum size in bytes to trigger compression (default: 1024) */
+    threshold?: number;
+}
+/**
+ * Memory driver options
+ */
+export interface MemoryDriverOptions {
+    /**
+     * Maximum number of items to store
+     * @default 1000
+     */
+    maxSize?: number;
+    /**
+     * Maximum memory usage in bytes (0 = use auto-calculated limit)
+     * Cannot be used together with maxMemoryPercent
+     */
+    maxMemoryBytes?: number;
+    /**
+     * Maximum memory as fraction of system memory (0-1)
+     * Example: 0.1 = 10% of system RAM
+     * Cannot be used together with maxMemoryBytes
+     */
+    maxMemoryPercent?: number;
+    /**
+     * Eviction policy when cache is full
+     * @default 'lru'
+     */
+    evictionPolicy?: EvictionPolicy;
+    /**
+     * Compression configuration
+     */
+    compression?: boolean | CompressionConfig;
+    /**
+     * Enable statistics tracking
+     * @default false
+     */
+    enableStats?: boolean;
+    /**
+     * Interval in ms for memory health checks
+     * Set to 0 to disable periodic checks
+     * @default 15000
+     */
+    monitorInterval?: number;
+    /**
+     * Evict cache when V8 heap usage exceeds this threshold (0-1)
+     * @default 0.6
+     */
+    heapUsageThreshold?: number;
+    /**
+     * Interval in ms to clean up expired items
+     * @default 60000
+     */
+    cleanupInterval?: number;
+    /**
+     * Callback when items are evicted
+     */
+    onEvict?: (info: EvictionInfo) => void;
+    /**
+     * Callback when memory pressure is detected
+     */
+    onPressure?: (info: PressureInfo) => void;
+}
+/**
+ * Eviction event information
+ */
+export interface EvictionInfo {
+    reason: 'size' | 'memory' | 'heap' | 'expired';
+    key?: string;
+    freedBytes: number;
+    currentBytes: number;
+    maxMemoryBytes: number;
+}
+/**
+ * Memory pressure event information
+ */
+export interface PressureInfo {
+    reason: 'limit' | 'heap';
+    heapLimit: number;
+    heapUsed: number;
+    heapRatio?: number;
+    currentBytes: number;
+    maxMemoryBytes: number;
+    freedBytes: number;
+}
+/**
+ * File driver options
+ */
+export interface FileDriverOptions {
+    /**
+     * Directory to store cache files
+     * @default '.cache'
+     */
+    directory?: string;
+    /**
+     * Maximum number of files to keep
+     * @default 10000
+     */
+    maxFiles?: number;
+    /**
+     * Maximum total size in bytes
+     */
+    maxSizeBytes?: number;
+    /**
+     * Enable compression for files
+     */
+    compression?: boolean;
+    /**
+     * Cleanup interval in ms
+     * @default 300000 (5 minutes)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * Redis driver options
+ *
+ * Duck-typed: accepts any Redis-like client with get/set/del methods.
+ */
+export interface RedisDriverOptions {
+    /**
+     * Redis client instance (ioredis, node-redis, etc.)
+     * Must implement: get, set, del, keys, scan methods
+     */
+    client: RedisLikeClient;
+    /**
+     * Key prefix for namespacing
+     * @default 'raffel:cache:'
+     */
+    prefix?: string;
+    /**
+     * Enable compression before storing
+     */
+    compression?: boolean;
+}
+/**
+ * Duck-typed Redis client interface
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: string, duration?: number): Promise<unknown>;
+    setex?(key: string, seconds: number, value: string): Promise<unknown>;
+    del(key: string | string[]): Promise<number>;
+    keys?(pattern: string): Promise<string[]>;
+    scan?(cursor: string | number, ...args: unknown[]): Promise<[string, string[]]>;
+    quit?(): Promise<unknown>;
+}
+/**
+ * S3DB driver options
+ */
+export interface S3DBDriverOptions {
+    /**
+     * S3DB instance
+     */
+    s3db: S3DBLikeClient;
+    /**
+     * Resource name for cache entries
+     * @default 'cache'
+     */
+    resource?: string;
+    /**
+     * Enable compression
+     */
+    compression?: boolean;
+}
+/**
+ * Duck-typed S3DB client interface
+ */
+export interface S3DBLikeClient {
+    get(resource: string, key: string): Promise<unknown>;
+    set(resource: string, key: string, value: unknown, options?: object): Promise<void>;
+    delete(resource: string, key: string): Promise<void>;
+    list?(resource: string, options?: object): Promise<unknown[]>;
+    clear?(resource: string): Promise<void>;
+}
+/**
+ * Cache driver type union
+ */
+export type CacheDriverType = 'memory' | 'file' | 'redis' | 's3db';
+/**
+ * Cache driver configuration
+ */
+export type CacheDriverConfig = {
+    driver: 'memory';
+    options?: MemoryDriverOptions;
+} | {
+    driver: 'file';
+    options?: FileDriverOptions;
+} | {
+    driver: 'redis';
+    options: RedisDriverOptions;
+} | {
+    driver: 's3db';
+    options: S3DBDriverOptions;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

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