raffel 0.1.2

package/dist/middleware/interceptors/bulkhead.js

@@ -0,0 +1,260 @@
+/**
+ * Bulkhead Interceptor (Concurrency Limiter)
+ *
+ * Protocol-agnostic concurrency limiting pattern.
+ * Prevents resource exhaustion by limiting concurrent executions.
+ *
+ * Features:
+ * - Maximum concurrent executions per procedure
+ * - Optional queue for overflow requests
+ * - Queue timeout to prevent indefinite waiting
+ * - Automatic slot release on completion or error
+ */
+import { RaffelError } from '../../core/router.js';
+/**
+ * Create a bulkhead (concurrency limiter) interceptor
+ *
+ * The bulkhead pattern isolates failures and prevents cascading resource exhaustion
+ * by limiting the number of concurrent executions.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - limit to 5 concurrent executions
+ * const bulkhead = createBulkheadInterceptor({ concurrency: 5 })
+ *
+ * // With queue - overflow requests wait in queue
+ * const bulkhead = createBulkheadInterceptor({
+ *   concurrency: 5,
+ *   maxQueueSize: 100,    // Wait up to 100 requests
+ *   queueTimeout: 30000,  // Timeout after 30s in queue
+ * })
+ *
+ * // Per-procedure configuration
+ * const bulkhead = createBulkheadInterceptor({
+ *   concurrency: 10,
+ *   maxQueueSize: 50,
+ *   onReject: (procedure) => {
+ *     metrics.increment('bulkhead.rejected', { procedure })
+ *   }
+ * })
+ *
+ * server
+ *   .procedure('heavy.process')
+ *   .use(bulkhead)
+ *   .handler(...)
+ * ```
+ */
+export function createBulkheadInterceptor(config) {
+    const { concurrency, maxQueueSize = 0, queueTimeout = 0, onReject, onQueued, onDequeued, } = config;
+    if (concurrency < 1) {
+        throw new Error('Bulkhead concurrency must be at least 1');
+    }
+    // State per procedure
+    const states = new Map();
+    /**
+     * Get or create bulkhead state for a procedure
+     */
+    const getState = (procedure) => {
+        let state = states.get(procedure);
+        if (!state) {
+            state = {
+                active: 0,
+                queue: [],
+            };
+            states.set(procedure, state);
+        }
+        return state;
+    };
+    /**
+     * Try to acquire a slot
+     * Returns true if slot acquired, false if should queue/reject
+     */
+    const tryAcquire = (state) => {
+        if (state.active < concurrency) {
+            state.active++;
+            return true;
+        }
+        return false;
+    };
+    /**
+     * Release a slot and process queue
+     */
+    const release = (state) => {
+        state.active--;
+        // Process next queued request if any
+        if (state.queue.length > 0 && state.active < concurrency) {
+            const next = state.queue.shift();
+            state.active++;
+            onDequeued?.();
+            next.resolve();
+        }
+    };
+    /**
+     * Wait for a slot in the queue
+     */
+    const waitForSlot = (state, procedure) => {
+        return new Promise((resolve, reject) => {
+            const request = {
+                resolve,
+                reject,
+                enqueuedAt: Date.now(),
+            };
+            state.queue.push(request);
+            onQueued?.();
+            // Set up timeout if configured
+            if (queueTimeout > 0) {
+                setTimeout(() => {
+                    const index = state.queue.indexOf(request);
+                    if (index !== -1) {
+                        state.queue.splice(index, 1);
+                        reject(new RaffelError('BULKHEAD_QUEUE_TIMEOUT', `Request timed out waiting in bulkhead queue after ${queueTimeout}ms`, {
+                            procedure,
+                            queueTimeout,
+                            queueSize: state.queue.length,
+                            activeCount: state.active,
+                        }, 503));
+                    }
+                }, queueTimeout);
+            }
+        });
+    };
+    return async (envelope, ctx, next) => {
+        const procedure = envelope.procedure;
+        const state = getState(procedure);
+        // Try to acquire slot immediately
+        if (tryAcquire(state)) {
+            try {
+                return await next();
+            }
+            finally {
+                release(state);
+            }
+        }
+        // Check if we can queue
+        if (maxQueueSize > 0 && state.queue.length < maxQueueSize) {
+            // Wait for slot
+            await waitForSlot(state, procedure);
+            try {
+                return await next();
+            }
+            finally {
+                release(state);
+            }
+        }
+        // Reject - no slot and can't queue
+        onReject?.(procedure);
+        throw new RaffelError('BULKHEAD_OVERFLOW', `Bulkhead capacity exceeded for procedure '${procedure}'`, {
+            procedure,
+            concurrency,
+            activeCount: state.active,
+            queueSize: state.queue.length,
+            maxQueueSize,
+        }, 503);
+    };
+}
+/**
+ * Create a bulkhead with procedure-specific configurations
+ *
+ * @example
+ * ```typescript
+ * const bulkhead = createProcedureBulkhead({
+ *   default: { concurrency: 10, maxQueueSize: 50 },
+ *   procedures: {
+ *     'reports.generate': { concurrency: 2 },
+ *     'files.upload': { concurrency: 5, maxQueueSize: 100 },
+ *   }
+ * })
+ * ```
+ */
+export function createProcedureBulkhead(config) {
+    const { default: defaultConfig = { concurrency: 10 }, procedures } = config;
+    // Create bulkheads for each configured procedure
+    const bulkheads = new Map();
+    // Default bulkhead
+    const defaultBulkhead = createBulkheadInterceptor(defaultConfig);
+    return async (envelope, ctx, next) => {
+        const procedure = envelope.procedure;
+        // Check for exact match
+        if (procedures[procedure]) {
+            let bulkhead = bulkheads.get(procedure);
+            if (!bulkhead) {
+                bulkhead = createBulkheadInterceptor({
+                    ...defaultConfig,
+                    ...procedures[procedure],
+                });
+                bulkheads.set(procedure, bulkhead);
+            }
+            return bulkhead(envelope, ctx, next);
+        }
+        // Check for pattern match
+        for (const [pattern, procedureConfig] of Object.entries(procedures)) {
+            const regex = pattern
+                .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                .replace(/\*\*/g, '{{DOUBLE_STAR}}')
+                .replace(/\*/g, '[^.]*')
+                .replace(/{{DOUBLE_STAR}}/g, '.*');
+            if (new RegExp(`^${regex}$`).test(procedure)) {
+                let bulkhead = bulkheads.get(pattern);
+                if (!bulkhead) {
+                    bulkhead = createBulkheadInterceptor({
+                        ...defaultConfig,
+                        ...procedureConfig,
+                    });
+                    bulkheads.set(pattern, bulkhead);
+                }
+                // Use pattern as procedure key to share state across matching procedures
+                const patternedEnvelope = { ...envelope, procedure: pattern };
+                return bulkhead(patternedEnvelope, ctx, next);
+            }
+        }
+        // Use default bulkhead
+        return defaultBulkhead(envelope, ctx, next);
+    };
+}
+/**
+ * Create a bulkhead manager for monitoring
+ *
+ * @example
+ * ```typescript
+ * const manager = createBulkheadManager({ concurrency: 5, maxQueueSize: 100 })
+ *
+ * server.use(manager.interceptor)
+ *
+ * // Monitor stats
+ * setInterval(() => {
+ *   const stats = manager.getStats()
+ *   for (const [procedure, { active, queued }] of stats) {
+ *     metrics.gauge('bulkhead.active', active, { procedure })
+ *     metrics.gauge('bulkhead.queued', queued, { procedure })
+ *   }
+ * }, 1000)
+ * ```
+ */
+export function createBulkheadManager(config) {
+    const stats = new Map();
+    const interceptor = createBulkheadInterceptor({
+        ...config,
+        onQueued: () => {
+            // Stats are managed internally by the interceptor
+            config.onQueued?.();
+        },
+        onDequeued: () => {
+            config.onDequeued?.();
+        },
+        onReject: (procedure) => {
+            config.onReject?.(procedure);
+        },
+    });
+    // Note: For accurate stats, we'd need to expose internal state
+    // This is a simplified version - consider enhancing if needed
+    return {
+        getStats() {
+            return new Map(stats);
+        },
+        getStatsFor(procedure) {
+            return stats.get(procedure);
+        },
+        interceptor,
+    };
+}
+//# sourceMappingURL=bulkhead.js.map

package/dist/middleware/interceptors/bulkhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.js","sourceRoot":"","sources":["../../../src/middleware/interceptors/bulkhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAqBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAsB;IAC9D,MAAM,EACJ,WAAW,EACX,YAAY,GAAG,CAAC,EAChB,YAAY,GAAG,CAAC,EAChB,QAAQ,EACR,QAAQ,EACR,UAAU,GACX,GAAG,MAAM,CAAA;IAEV,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAC5D,CAAC;IAED,sBAAsB;IACtB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAA;IAE/C;;OAEG;IACH,MAAM,QAAQ,GAAG,CAAC,SAAiB,EAAiB,EAAE;QACpD,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAEjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG;gBACN,MAAM,EAAE,CAAC;gBACT,KAAK,EAAE,EAAE;aACV,CAAA;YACD,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QAC9B,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED;;;OAGG;IACH,MAAM,UAAU,GAAG,CAAC,KAAoB,EAAW,EAAE;QACnD,IAAI,KAAK,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YAC/B,KAAK,CAAC,MAAM,EAAE,CAAA;YACd,OAAO,IAAI,CAAA;QACb,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED;;OAEG;IACH,MAAM,OAAO,GAAG,CAAC,KAAoB,EAAQ,EAAE;QAC7C,KAAK,CAAC,MAAM,EAAE,CAAA;QAEd,qCAAqC;QACrC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YACzD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAG,CAAA;YACjC,KAAK,CAAC,MAAM,EAAE,CAAA;YACd,UAAU,EAAE,EAAE,CAAA;YACd,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;IACH,CAAC,CAAA;IAED;;OAEG;IACH,MAAM,WAAW,GAAG,CAClB,KAAoB,EACpB,SAAiB,EACF,EAAE;QACjB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,OAAO,GAAkB;gBAC7B,OAAO;gBACP,MAAM;gBACN,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;aACvB,CAAA;YAED,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACzB,QAAQ,EAAE,EAAE,CAAA;YAEZ,+BAA+B;YAC/B,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBACrB,UAAU,CAAC,GAAG,EAAE;oBACd,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;oBAC1C,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;wBACjB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;wBAC5B,MAAM,CACJ,IAAI,WAAW,CACb,wBAAwB,EACxB,qDAAqD,YAAY,IAAI,EACrE;4BACE,SAAS;4BACT,YAAY;4BACZ,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;4BAC7B,WAAW,EAAE,KAAK,CAAC,MAAM;yBAC1B,EACD,GAAG,CACJ,CACF,CAAA;oBACH,CAAC;gBACH,CAAC,EAAE,YAAY,CAAC,CAAA;YAClB,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,OAAO,KAAK,EAAE,QAAkB,EAAE,GAAY,EAAE,IAA4B,EAAE,EAAE;QAC9E,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAA;QAEjC,kCAAkC;QAClC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,EAAE,CAAA;YACrB,CAAC;oBAAS,CAAC;gBACT,OAAO,CAAC,KAAK,CAAC,CAAA;YAChB,CAAC;QACH,CAAC;QAED,wBAAwB;QACxB,IAAI,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YAC1D,gBAAgB;YAChB,MAAM,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;YAEnC,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,EAAE,CAAA;YACrB,CAAC;oBAAS,CAAC;gBACT,OAAO,CAAC,KAAK,CAAC,CAAA;YAChB,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAA;QAErB,MAAM,IAAI,WAAW,CACnB,mBAAmB,EACnB,6CAA6C,SAAS,GAAG,EACzD;YACE,SAAS;YACT,WAAW;YACX,WAAW,EAAE,KAAK,CAAC,MAAM;YACzB,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;YAC7B,YAAY;SACb,EACD,GAAG,CACJ,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAGvC;IACC,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,MAAM,CAAA;IAE3E,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAA;IAEhD,mBAAmB;IACnB,MAAM,eAAe,GAAG,yBAAyB,CAAC,aAAa,CAAC,CAAA;IAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACnC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QAEpC,wBAAwB;QACxB,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,yBAAyB,CAAC;oBACnC,GAAG,aAAa;oBAChB,GAAG,UAAU,CAAC,SAAS,CAAC;iBACzB,CAAC,CAAA;gBACF,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;QACtC,CAAC;QAED,0BAA0B;QAC1B,KAAK,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACpE,MAAM,KAAK,GAAG,OAAO;iBAClB,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC;iBACpC,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC;iBACnC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;iBACvB,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAA;YAEpC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7C,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;gBACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,yBAAyB,CAAC;wBACnC,GAAG,aAAa;wBAChB,GAAG,eAAe;qBACnB,CAAC,CAAA;oBACF,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;gBAClC,CAAC;gBACD,yEAAyE;gBACzE,MAAM,iBAAiB,GAAG,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;gBAC7D,OAAO,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;QAED,uBAAuB;QACvB,OAAO,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC,CAAA;AACH,CAAC;AAgBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsB;IAC1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAA8C,CAAA;IAEnE,MAAM,WAAW,GAAG,yBAAyB,CAAC;QAC5C,GAAG,MAAM;QACT,QAAQ,EAAE,GAAG,EAAE;YACb,kDAAkD;YAClD,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAA;QACrB,CAAC;QACD,UAAU,EAAE,GAAG,EAAE;YACf,MAAM,CAAC,UAAU,EAAE,EAAE,CAAA;QACvB,CAAC;QACD,QAAQ,EAAE,CAAC,SAAS,EAAE,EAAE;YACtB,MAAM,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAA;QAC9B,CAAC;KACF,CAAC,CAAA;IAEF,+DAA+D;IAC/D,8DAA8D;IAE9D,OAAO;QACL,QAAQ;YACN,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;QACvB,CAAC;QAED,WAAW,CAAC,SAAiB;YAC3B,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAC7B,CAAC;QAED,WAAW;KACZ,CAAA;AACH,CAAC"}

package/dist/middleware/interceptors/cache.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Cache Interceptor
+ *
+ * Protocol-agnostic response caching for procedures.
+ * Reduces latency and load on downstream services by caching responses.
+ *
+ * Features:
+ * - Pluggable driver system (memory, file, redis, s3db)
+ * - In-memory LRU cache with TTL (default)
+ * - Container-aware memory limits (Docker/K8s)
+ * - Procedure pattern matching
+ * - Custom key generation
+ * - Stale-while-revalidate support
+ * - Cache statistics and callbacks
+ */
+import type { Interceptor } from '../../types/index.js';
+import type { CacheConfig, CacheStore } from '../types.js';
+import type { CacheDriver, CacheDriverType, MemoryDriverOptions } from '../../cache/types.js';
+/**
+ * Cache event context for callbacks
+ */
+export interface CacheEventContext {
+    /** The cache key */
+    key: string;
+    /** The procedure name */
+    procedure: string;
+    /** Request ID if available */
+    requestId?: string;
+    /** Whether it was a cache hit */
+    hit: boolean;
+    /** TTL in milliseconds (for sets) */
+    ttlMs?: number;
+    /** Whether the cached value is stale (stale-while-revalidate) */
+    stale?: boolean;
+}
+/**
+ * Extended cache configuration with callbacks and driver support
+ */
+export interface ExtendedCacheConfig extends CacheConfig {
+    /**
+     * Callback when cache is accessed
+     * Useful for metrics and debugging
+     */
+    onAccess?: (info: CacheEventContext) => void;
+    /**
+     * Procedure patterns to exclude from caching
+     */
+    excludeProcedures?: string[];
+    /**
+     * Only cache successful responses (default: true)
+     */
+    cacheSuccessOnly?: boolean;
+    /**
+     * Grace period for stale-while-revalidate in ms (default: ttlMs / 2)
+     */
+    staleGraceMs?: number;
+    /**
+     * Cache driver instance (new driver-based API)
+     * Takes precedence over `store` if both are provided
+     */
+    driver?: CacheDriver;
+    /**
+     * Driver type to use (creates driver automatically)
+     * Only used if neither `store` nor `driver` is provided
+     * @default 'memory'
+     */
+    driverType?: CacheDriverType;
+    /**
+     * Options for the memory driver (when using driverType: 'memory')
+     * For other drivers, use the `driver` option with a pre-configured driver
+     */
+    driverOptions?: MemoryDriverOptions;
+}
+/**
+ * Create an in-memory LRU cache store
+ */
+export declare function createMemoryCacheStore(maxEntries?: number): CacheStore & {
+    stats(): {
+        size: number;
+        maxEntries: number;
+    };
+};
+/**
+ * Create a cache interceptor
+ *
+ * Caches procedure responses to reduce latency and downstream load.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - cache everything for 1 minute
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ * })
+ *
+ * // Cache specific procedures
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   procedures: ['users.get', 'products.list', 'config.**'],
+ * })
+ *
+ * // With custom key generation (e.g., per-user caching)
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   keyGenerator: (envelope) => {
+ *     const userId = envelope.metadata['x-user-id'] ?? 'anonymous'
+ *     return `${userId}:${envelope.procedure}:${JSON.stringify(envelope.payload)}`
+ *   },
+ * })
+ *
+ * // With stale-while-revalidate
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   staleWhileRevalidate: true,
+ *   staleGraceMs: 30000, // Serve stale data for 30s while revalidating
+ * })
+ *
+ * // With Redis driver (new API)
+ * import { createDriver } from 'raffel/cache'
+ * const redisDriver = await createDriver('redis', { client: redisClient })
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driver: redisDriver,
+ * })
+ *
+ * // With advanced memory driver
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driverOptions: {
+ *     maxSize: 5000,
+ *     maxMemoryPercent: 0.1,  // 10% of system RAM
+ *     evictionPolicy: 'lru',
+ *     compression: true,
+ *   },
+ * })
+ *
+ * // With metrics
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   onAccess: ({ hit, procedure }) => {
+ *     metrics.increment(hit ? 'cache.hit' : 'cache.miss', { procedure })
+ *   },
+ * })
+ *
+ * server.use(cache)
+ * ```
+ */
+export declare function createCacheInterceptor(config?: ExtendedCacheConfig): Interceptor;
+/**
+ * Create a read-through cache interceptor
+ *
+ * Convenience wrapper that only caches read operations
+ * (procedures matching common read patterns).
+ *
+ * @example
+ * ```typescript
+ * const cache = createReadThroughCacheInterceptor({
+ *   ttlMs: 60000,
+ * })
+ * server.use(cache)
+ * ```
+ */
+export declare function createReadThroughCacheInterceptor(config?: Omit<ExtendedCacheConfig, 'procedures'>): Interceptor;
+/**
+ * Create cache presets for common use cases
+ */
+export declare const CachePresets: {
+    /**
+     * Short-lived cache (5 seconds) for frequently changing data
+     */
+    short: ExtendedCacheConfig;
+    /**
+     * Standard cache (1 minute) for general purpose
+     */
+    standard: ExtendedCacheConfig;
+    /**
+     * Long-lived cache (5 minutes) for stable data
+     */
+    long: ExtendedCacheConfig;
+    /**
+     * Aggressive cache (1 hour) for rarely changing data
+     */
+    aggressive: ExtendedCacheConfig;
+    /**
+     * No stale - strict TTL without SWR
+     */
+    strict: ExtendedCacheConfig;
+};
+/**
+ * Cache invalidation helper
+ *
+ * Use this to manually invalidate cache entries.
+ *
+ * @example
+ * ```typescript
+ * const store = createMemoryCacheStore(1000)
+ * const cache = createCacheInterceptor({ store })
+ * const invalidator = createCacheInvalidator(store)
+ *
+ * // In a mutation handler:
+ * async function updateUser(input, ctx) {
+ *   await db.users.update(input)
+ *   // Invalidate related cache entries
+ *   await invalidator.invalidatePattern('cache:users.get:*')
+ *   return { success: true }
+ * }
+ * ```
+ */
+export declare function createCacheInvalidator(store: CacheStore): {
+    /**
+     * Invalidate a specific cache key
+     */
+    invalidate(key: string): Promise<void>;
+    /**
+     * Clear all cache entries
+     */
+    invalidateAll(): Promise<void>;
+};
+//# sourceMappingURL=cache.d.ts.map

package/dist/middleware/interceptors/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/middleware/interceptors/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,sBAAsB,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE7F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,GAAG,EAAE,OAAO,CAAA;IACZ,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAE5C;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE5B;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAE1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAA;IAE5B;;;OAGG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAA;CACpC;AAYD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,GAAE,MAAa,GAAG,UAAU,GAAG;IAC9E,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C,CA0EA;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,mBAAwB,GAAG,WAAW,CAsHpF;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,GAAE,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAM,GACnD,WAAW,CAmCb;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;WAKE,mBAAmB;IAExB;;OAEG;cAKE,mBAAmB;IAExB;;OAEG;UAKE,mBAAmB;IAExB;;OAEG;gBAKE,mBAAmB;IAExB;;OAEG;YAKE,mBAAmB;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU;IAEpD;;OAEG;oBACmB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;OAEG;qBACoB,OAAO,CAAC,IAAI,CAAC;EAUvC"}

package/dist/middleware/interceptors/cache.int.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache Interceptor Tests
+ */
+export {};
+//# sourceMappingURL=cache.int.test.d.ts.map

package/dist/middleware/interceptors/cache.int.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.int.test.d.ts","sourceRoot":"","sources":["../../../src/middleware/interceptors/cache.int.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}