flowshield 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [1.0.0] - 2026-03-30
+
+### 🎉 Initial Release
+
+#### Policies
+- **Retry** — Exponential, linear, constant, and decorrelated jitter backoff strategies. Supports `shouldRetry` predicates, `onRetry` callbacks, and `AbortSignal` cancellation.
+- **Circuit Breaker** — Closed/open/half-open state machine with configurable failure/success thresholds, reset timeout, and event callbacks (`onOpen`, `onClose`, `onHalfOpen`).
+- **Timeout** — AbortSignal-based timeout with configurable deadline in milliseconds.
+- **Bulkhead** — Semaphore-based concurrency limiter with configurable max concurrent executions and queue size.
+- **Fallback** — Type-safe fallback values or async fallback functions with `shouldFallback` predicate.
+- **Rate Limiter** — Token bucket algorithm with configurable tokens per interval, reject-on-limit mode, and manual reset.
+- **Hedge** — Hedged requests pattern — sends a parallel request after a configurable delay; first to resolve wins.
+- **Cache** — TTL-based memoization with stale-while-revalidate, custom key generation, and eviction callbacks.
+
+#### Composition
+- **`pipe(...policies)`** — Compose policies left-to-right (outermost first).
+- **`wrap(outer, inner)`** — Nest an inner policy within an outer policy.
+
+#### Error Types
+- `FlowShieldError` — Base error class with cause support.
+- `TimeoutError`, `CircuitOpenError`, `BulkheadRejectedError`, `RateLimitExceededError`, `RetryExhaustedError`.
+
+#### Infrastructure
+- Zero dependencies.
+- Dual ESM/CJS output with TypeScript declarations.
+- 100% test coverage (statements, branches, functions, lines).
+- Tree-shakable — only import what you use.
+- Node.js ≥ 18.0.0, compatible with Bun, Deno, and edge runtimes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avinash Velu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# FlowShield
+
+> **Zero-dependency, TypeScript-first resilience & fault-tolerance toolkit.**
+
+[![npm version](https://img.shields.io/npm/v/flowshield.svg)](https://www.npmjs.com/package/flowshield)
+[![npm downloads](https://img.shields.io/npm/dm/flowshield.svg)](https://www.npmjs.com/package/flowshield)
+[![license](https://img.shields.io/npm/l/flowshield.svg)](https://github.com/Avinashvelu03/flowshield/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/Avinashvelu03/flowshield)
+
+Composable fault-tolerance policies for any async operation. Ship resilient microservices, API clients, and distributed systems with **retry**, **circuit breaker**, **timeout**, **bulkhead**, **fallback**, **rate limiter**, **hedge**, and **cache** — all in a lightweight, tree-shakable package.
+
+---
+
+## ✨ Features
+
+- 🔁 **Retry** — Exponential backoff, jitter, configurable strategies
+- ⚡ **Circuit Breaker** — Half-open/open/closed with auto-recovery
+- ⏱️ **Timeout** — AbortSignal-based deadlines
+- 🚧 **Bulkhead** — Concurrency limiting (semaphore pattern)
+- 🛡️ **Fallback** — Type-safe fallback chains
+- 🚦 **Rate Limiter** — Token bucket algorithm
+- 🏎️ **Hedge** — Hedged (parallel) requests for latency reduction
+- 💾 **Cache** — TTL-based memoization with stale-while-revalidate
+- 🔗 **Composable** — Chain any policies together with `pipe()` or `wrap()`
+- 📦 **Zero dependencies** — No supply chain risk
+- 🌳 **Tree-shakable** — Only pay for what you use
+- 🌐 **Edge-ready** — Works in Node.js, Bun, Deno, Cloudflare Workers
+- 🎯 **100% test coverage** — Statements, branches, functions, lines
+
+## 📦 Installation
+
+```bash
+npm install flowshield
+```
+
+```bash
+yarn add flowshield
+```
+
+```bash
+pnpm add flowshield
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { retry, circuitBreaker, timeout, pipe } from 'flowshield';
+
+// Simple retry with exponential backoff
+const data = await retry({ maxAttempts: 3, backoff: 'exponential' })(
+  () => fetch('/api/data').then(r => r.json()),
+);
+
+// Compose multiple policies
+const resilientFetch = pipe(
+  timeout({ ms: 5000 }),
+  retry({ maxAttempts: 3, backoff: 'exponential' }),
+);
+
+const result = await resilientFetch(() => fetch('/api/data'));
+```
+
+---
+
+## 📖 API Reference
+
+### Retry
+
+Re-executes a failed operation with configurable backoff strategies.
+
+```typescript
+import { retry } from 'flowshield';
+
+const result = await retry({
+  maxAttempts: 5,           // Default: 3
+  delay: 200,               // Base delay in ms. Default: 200
+  backoff: 'exponential',   // 'constant' | 'linear' | 'exponential' | 'decorrelatedJitter'
+  maxDelay: 30000,          // Cap delay at 30s. Default: 30000
+  shouldRetry: (err, attempt) => attempt < 3,  // Conditional retry
+  onRetry: (err, attempt, delay) => console.log(`Retry ${attempt} in ${delay}ms`),
+  signal: controller.signal, // AbortSignal for cancellation
+})(
+  () => fetch('/api/data'),
+);
+```
+
+### Circuit Breaker
+
+Prevents calls to a failing service, allowing it time to recover.
+
+```typescript
+import { circuitBreaker } from 'flowshield';
+
+const cb = circuitBreaker({
+  failureThreshold: 5,    // Failures before opening. Default: 5
+  successThreshold: 1,    // Successes in half-open to close. Default: 1
+  resetTimeout: 30000,    // Time in open state before half-open. Default: 30000
+  onOpen: () => console.log('Circuit opened!'),
+  onClose: () => console.log('Circuit closed!'),
+  onHalfOpen: () => console.log('Circuit half-open...'),
+});
+
+const result = await cb.execute(() => fetch('/api/health'));
+console.log(cb.handle.state); // 'closed' | 'open' | 'half-open'
+cb.handle.reset();             // Manually reset
+```
+
+### Timeout
+
+Rejects if an operation doesn't complete within a deadline.
+
+```typescript
+import { timeout } from 'flowshield';
+
+const result = await timeout({ ms: 5000 })(
+  () => fetch('/api/slow-endpoint'),
+);
+// Throws TimeoutError if not resolved within 5 seconds
+```
+
+### Bulkhead
+
+Limits concurrent executions to prevent resource exhaustion.
+
+```typescript
+import { bulkhead } from 'flowshield';
+
+const bh = bulkhead({
+  maxConcurrent: 10,  // Max parallel executions. Default: 10
+  maxQueue: 100,      // Max queued requests. Default: 0 (no queue)
+});
+
+const result = await bh.execute(() => fetch('/api/data'));
+console.log(bh.handle.running); // Current active count
+console.log(bh.handle.queued);  // Current queue size
+```
+
+### Fallback
+
+Returns a fallback value when an operation fails.
+
+```typescript
+import { fallback } from 'flowshield';
+
+// Static fallback
+const result = await fallback({ fallback: [] })(
+  () => fetch('/api/items').then(r => r.json()),
+);
+
+// Dynamic fallback
+const result2 = await fallback({
+  fallback: async (error) => fetchFromCache(error),
+  shouldFallback: (err) => err instanceof NetworkError,
+})(
+  () => fetch('/api/data'),
+);
+```
+
+### Rate Limiter
+
+Controls how many operations can execute within a time window.
+
+```typescript
+import { rateLimiter } from 'flowshield';
+
+const rl = rateLimiter({
+  tokensPerInterval: 10,  // Requests per interval. Default: 10
+  interval: 1000,         // Interval in ms. Default: 1000
+  rejectOnLimit: false,   // Queue or reject. Default: false (queue)
+});
+
+const result = await rl.execute(() => fetch('/api/data'));
+console.log(rl.handle.availableTokens); // Check remaining tokens
+rl.handle.reset();                       // Reset the bucket
+```
+
+### Hedge
+
+Sends a parallel request if the primary is too slow — first to resolve wins.
+
+```typescript
+import { hedge } from 'flowshield';
+
+const result = await hedge({ hedgeDelay: 2000 })(
+  () => fetch('/api/data').then(r => r.json()),
+);
+// If primary doesn't resolve in 2s, a second request is sent.
+// The fastest response wins.
+```
+
+### Cache
+
+Memoizes async operation results with TTL and stale-while-revalidate support.
+
+```typescript
+import { cache } from 'flowshield';
+
+const c = cache({
+  ttl: 60000,                    // Time-to-live in ms. Default: 60000
+  staleWhileRevalidate: true,    // Return stale, refresh in background
+  keyFn: () => 'custom-key',    // Custom cache key
+  onEvict: (key, value) => {},   // Eviction callback
+});
+
+const result = await c.execute(() => fetch('/api/data').then(r => r.json()));
+c.handle.invalidate('custom-key'); // Invalidate specific key
+c.handle.clear();                   // Clear all
+```
+
+### Composing Policies
+
+Combine multiple policies with `pipe()` (left-to-right) or `wrap()`.
+
+```typescript
+import { pipe, wrap, retry, timeout, circuitBreaker, fallback } from 'flowshield';
+
+// pipe: policies applied left-to-right (outermost first)
+const resilient = pipe(
+  timeout({ ms: 10000 }),
+  retry({ maxAttempts: 3, backoff: 'exponential' }),
+);
+
+const data = await resilient(() => fetch('/api/data'));
+
+// wrap: explicit outer/inner nesting
+const policy = wrap(
+  timeout({ ms: 5000 }),
+  retry({ maxAttempts: 3 }),
+);
+```
+
+---
+
+## 🛡️ Error Types
+
+FlowShield provides typed errors for each failure mode:
+
+```typescript
+import {
+  FlowShieldError,       // Base error class
+  TimeoutError,          // Operation timed out
+  CircuitOpenError,      // Circuit breaker is open
+  BulkheadRejectedError, // Bulkhead capacity exceeded
+  RateLimitExceededError, // Rate limit exceeded
+  RetryExhaustedError,   // All retry attempts failed
+} from 'flowshield';
+
+try {
+  await resilientFetch(() => fetch('/api'));
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    // Handle timeout
+  } else if (error instanceof CircuitOpenError) {
+    // Handle circuit open
+  } else if (error instanceof RetryExhaustedError) {
+    console.log(`Failed after ${error.attempts} attempts`);
+    console.log(`Last error:`, error.cause);
+  }
+}
+```
+
+---
+
+## 🔧 Requirements
+
+- **Node.js** ≥ 18.0.0
+- **TypeScript** ≥ 5.0 (for type inference)
+
+## 📄 License
+
+[MIT](./LICENSE) © [Avinash Velu](https://github.com/Avinashvelu03)

package/dist/cjs/compose.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pipe = pipe;
+exports.wrap = wrap;
+/**
+ * Composes multiple policies into a single policy.
+ * Policies are applied **left-to-right** (outermost first).
+ *
+ * `pipe(a, b, c)(fn)` is equivalent to `a(()=> b(()=> c(fn)))`.
+ *
+ * @example
+ * ```ts
+ * const resilient = pipe(
+ *   timeout({ ms: 5000 }),
+ *   retry({ maxAttempts: 3 }),
+ * );
+ * const result = await resilient(() => fetch('/api'));
+ * ```
+ */
+function pipe(...policies) {
+    if (policies.length === 0) {
+        return (fn) => fn();
+    }
+    return (fn) => {
+        // Build from right to left: the innermost policy wraps fn directly
+        let composed = fn;
+        for (let i = policies.length - 1; i >= 0; i--) {
+            const policy = policies[i];
+            const next = composed;
+            composed = () => policy(next);
+        }
+        return composed();
+    };
+}
+/**
+ * Wraps an inner policy with an outer policy.
+ * `wrap(outer, inner)(fn)` is equivalent to `outer(() => inner(fn))`.
+ *
+ * @example
+ * ```ts
+ * const policy = wrap(
+ *   timeout({ ms: 5000 }),
+ *   retry({ maxAttempts: 3 }),
+ * );
+ * const result = await policy(() => fetch('/api'));
+ * ```
+ */
+function wrap(outer, inner) {
+    return (fn) => {
+        return outer(() => inner(fn));
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/cjs/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/compose.ts"],"names":[],"mappings":";;AAiBA,oBAiBC;AAeD,oBAIC;AAnDD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,IAAI,CAAC,GAAG,QAAkB;IACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAI,EAAoB,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO,CAAI,EAAoB,EAAc,EAAE;QAC7C,mEAAmE;QACnE,IAAI,QAAQ,GAAqB,EAAE,CAAC;QAEpC,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC;YACtB,QAAQ,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,QAAQ,EAAE,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,IAAI,CAAC,KAAa,EAAE,KAAa;IAC/C,OAAO,CAAI,EAAoB,EAAc,EAAE;QAC7C,OAAO,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryExhaustedError = exports.RateLimitExceededError = exports.BulkheadRejectedError = exports.CircuitOpenError = exports.TimeoutError = exports.FlowShieldError = exports.wrap = exports.pipe = exports.cache = exports.hedge = exports.rateLimiter = exports.fallback = exports.bulkhead = exports.timeout = exports.circuitBreaker = exports.retry = void 0;
+// ─── Policies ───────────────────────────────────────────────────────────────
+var retry_js_1 = require("./policies/retry.js");
+Object.defineProperty(exports, "retry", { enumerable: true, get: function () { return retry_js_1.retry; } });
+var circuit_breaker_js_1 = require("./policies/circuit-breaker.js");
+Object.defineProperty(exports, "circuitBreaker", { enumerable: true, get: function () { return circuit_breaker_js_1.circuitBreaker; } });
+var timeout_js_1 = require("./policies/timeout.js");
+Object.defineProperty(exports, "timeout", { enumerable: true, get: function () { return timeout_js_1.timeout; } });
+var bulkhead_js_1 = require("./policies/bulkhead.js");
+Object.defineProperty(exports, "bulkhead", { enumerable: true, get: function () { return bulkhead_js_1.bulkhead; } });
+var fallback_js_1 = require("./policies/fallback.js");
+Object.defineProperty(exports, "fallback", { enumerable: true, get: function () { return fallback_js_1.fallback; } });
+var rate_limiter_js_1 = require("./policies/rate-limiter.js");
+Object.defineProperty(exports, "rateLimiter", { enumerable: true, get: function () { return rate_limiter_js_1.rateLimiter; } });
+var hedge_js_1 = require("./policies/hedge.js");
+Object.defineProperty(exports, "hedge", { enumerable: true, get: function () { return hedge_js_1.hedge; } });
+var cache_js_1 = require("./policies/cache.js");
+Object.defineProperty(exports, "cache", { enumerable: true, get: function () { return cache_js_1.cache; } });
+// ─── Composition ────────────────────────────────────────────────────────────
+var compose_js_1 = require("./compose.js");
+Object.defineProperty(exports, "pipe", { enumerable: true, get: function () { return compose_js_1.pipe; } });
+Object.defineProperty(exports, "wrap", { enumerable: true, get: function () { return compose_js_1.wrap; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "FlowShieldError", { enumerable: true, get: function () { return types_js_1.FlowShieldError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return types_js_1.TimeoutError; } });
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return types_js_1.CircuitOpenError; } });
+Object.defineProperty(exports, "BulkheadRejectedError", { enumerable: true, get: function () { return types_js_1.BulkheadRejectedError; } });
+Object.defineProperty(exports, "RateLimitExceededError", { enumerable: true, get: function () { return types_js_1.RateLimitExceededError; } });
+Object.defineProperty(exports, "RetryExhaustedError", { enumerable: true, get: function () { return types_js_1.RetryExhaustedError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,+EAA+E;AAC/E,gDAA4C;AAAnC,iGAAA,KAAK,OAAA;AACd,oEAA+D;AAAtD,oHAAA,cAAc,OAAA;AACvB,oDAAgD;AAAvC,qGAAA,OAAO,OAAA;AAChB,sDAAkD;AAAzC,uGAAA,QAAQ,OAAA;AACjB,sDAAkD;AAAzC,uGAAA,QAAQ,OAAA;AACjB,8DAAyD;AAAhD,8GAAA,WAAW,OAAA;AACpB,gDAA4C;AAAnC,iGAAA,KAAK,OAAA;AACd,gDAA4C;AAAnC,iGAAA,KAAK,OAAA;AAEd,+EAA+E;AAC/E,2CAA0C;AAAjC,kGAAA,IAAI,OAAA;AAAE,kGAAA,IAAI,OAAA;AAqBnB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,wGAAA,YAAY,OAAA;AACZ,4GAAA,gBAAgB,OAAA;AAChB,iHAAA,qBAAqB,OAAA;AACrB,kHAAA,sBAAsB,OAAA;AACtB,+GAAA,mBAAmB,OAAA"}

package/dist/cjs/policies/bulkhead.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bulkhead = bulkhead;
+const types_js_1 = require("../types.js");
+const utils_js_1 = require("../utils.js");
+const DEFAULTS = {
+    maxConcurrent: 10,
+    maxQueue: 0,
+};
+/**
+ * Creates a bulkhead (concurrency limiter) policy that limits the number
+ * of concurrent executions of the wrapped operation.
+ *
+ * Returns an object with `execute` (the policy function) and `handle`
+ * (an interface to inspect the bulkhead's running / queued counts).
+ *
+ * @example
+ * ```ts
+ * const bh = bulkhead({ maxConcurrent: 5, maxQueue: 10 });
+ * const result = await bh.execute(() => fetch('/api/data'));
+ * console.log(bh.handle.running); // number of active calls
+ * ```
+ */
+function bulkhead(options = {}) {
+    const maxConcurrent = options.maxConcurrent ?? DEFAULTS.maxConcurrent;
+    const maxQueue = options.maxQueue ?? DEFAULTS.maxQueue;
+    (0, utils_js_1.assertPositiveInteger)(maxConcurrent, 'maxConcurrent');
+    (0, utils_js_1.assertNonNegative)(maxQueue, 'maxQueue');
+    let running = 0;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const queue = [];
+    function dequeue() {
+        while (running < maxConcurrent && queue.length > 0) {
+            const entry = queue.shift();
+            run(entry);
+        }
+    }
+    function run(entry) {
+        running++;
+        entry
+            .fn()
+            .then((value) => {
+            entry.resolve(value);
+        }, (error) => {
+            entry.reject(error);
+        })
+            .finally(() => {
+            running--;
+            dequeue();
+        });
+    }
+    const handle = {
+        get running() {
+            return running;
+        },
+        get queued() {
+            return queue.length;
+        },
+    };
+    function execute(fn) {
+        if (running < maxConcurrent) {
+            return new Promise((resolve, reject) => {
+                run({ fn, resolve, reject });
+            });
+        }
+        if (queue.length >= maxQueue) {
+            return Promise.reject(new types_js_1.BulkheadRejectedError());
+        }
+        return new Promise((resolve, reject) => {
+            queue.push({ fn, resolve, reject });
+        });
+    }
+    return { execute, handle };
+}
+//# sourceMappingURL=bulkhead.js.map

package/dist/cjs/policies/bulkhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.js","sourceRoot":"","sources":["../../../src/policies/bulkhead.ts"],"names":[],"mappings":";;AA6BA,4BAiEC;AA7FD,0CAAoD;AACpD,0CAAuE;AAEvE,MAAM,QAAQ,GAAG;IACf,aAAa,EAAE,EAAE;IACjB,QAAQ,EAAE,CAAC;CACZ,CAAC;AAQF;;;;;;;;;;;;;GAaG;AACH,SAAgB,QAAQ,CAAC,UAA2B,EAAE;IAIpD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC;IACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAEvD,IAAA,gCAAqB,EAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IACtD,IAAA,4BAAiB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAExC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,8DAA8D;IAC9D,MAAM,KAAK,GAAsB,EAAE,CAAC;IAEpC,SAAS,OAAO;QACd,OAAO,OAAO,GAAG,aAAa,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAC7B,GAAG,CAAC,KAAK,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IAED,SAAS,GAAG,CAAI,KAAoB;QAClC,OAAO,EAAE,CAAC;QACV,KAAK;aACF,EAAE,EAAE;aACJ,IAAI,CACH,CAAC,KAAK,EAAE,EAAE;YACR,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACR,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CACF;aACA,OAAO,CAAC,GAAG,EAAE;YACZ,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACP,CAAC;IAED,MAAM,MAAM,GAAmB;QAC7B,IAAI,OAAO;YACT,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;KACF,CAAC;IAEF,SAAS,OAAO,CAAI,EAAoB;QACtC,IAAI,OAAO,GAAG,aAAa,EAAE,CAAC;YAC5B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACxC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,gCAAqB,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC"}

package/dist/cjs/policies/cache.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cache = cache;
+const utils_js_1 = require("../utils.js");
+const DEFAULTS = {
+    ttl: 60_000,
+    staleWhileRevalidate: false,
+};
+/**
+ * Creates a TTL-based cache policy that memoizes the result of the wrapped
+ * async operation. Supports stale-while-revalidate for background refresh.
+ *
+ * Returns an object with `execute` (the policy function) and `handle`
+ * (an interface to inspect / invalidate the cache).
+ *
+ * @example
+ * ```ts
+ * const c = cache({ ttl: 10_000 });
+ * const result = await c.execute(() => fetch('/api/data').then(r => r.json()));
+ * ```
+ */
+function cache(options = {}) {
+    const ttl = options.ttl ?? DEFAULTS.ttl;
+    const staleWhileRevalidate = options.staleWhileRevalidate ?? DEFAULTS.staleWhileRevalidate;
+    const keyFn = options.keyFn ?? (() => 'default');
+    const onEvict = options.onEvict;
+    (0, utils_js_1.assertPositive)(ttl, 'ttl');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const store = new Map();
+    function evict(key) {
+        const entry = store.get(key);
+        if (entry) {
+            store.delete(key);
+            onEvict?.(key, entry.value);
+        }
+    }
+    const handle = {
+        get size() {
+            return store.size;
+        },
+        invalidate(key) {
+            if (key !== undefined) {
+                evict(key);
+            }
+            else {
+                // Invalidate default key
+                evict(keyFn());
+            }
+        },
+        clear() {
+            if (onEvict) {
+                for (const [k, v] of store) {
+                    onEvict(k, v.value);
+                }
+            }
+            store.clear();
+        },
+    };
+    async function execute(fn) {
+        const key = keyFn();
+        const now = Date.now();
+        const entry = store.get(key);
+        if (entry) {
+            if (now < entry.expiresAt) {
+                // Fresh cache hit
+                return entry.value;
+            }
+            if (staleWhileRevalidate && !entry.stale) {
+                // Return stale value and revalidate in background
+                entry.stale = true;
+                fn()
+                    .then((value) => {
+                    store.set(key, {
+                        value,
+                        expiresAt: Date.now() + ttl,
+                        stale: false,
+                    });
+                })
+                    .catch(() => {
+                    // Revalidation failed — keep stale value, lift stale flag
+                    // so next request tries again
+                    entry.stale = false;
+                });
+                return entry.value;
+            }
+            // Expired and not SWR — evict and re-fetch
+            evict(key);
+        }
+        const value = await fn();
+        store.set(key, {
+            value,
+            expiresAt: now + ttl,
+            stale: false,
+        });
+        return value;
+    }
+    return { execute, handle };
+}
+//# sourceMappingURL=cache.js.map

package/dist/cjs/policies/cache.js.map

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