flowshield 1.0.0

package/dist/esm/types.js

@@ -0,0 +1,46 @@
+// ─── Core Types ─────────────────────────────────────────────────────────────
+// ─── Errors ─────────────────────────────────────────────────────────────────
+export class FlowShieldError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'FlowShieldError';
+        // Fix prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+export class TimeoutError extends FlowShieldError {
+    constructor(ms) {
+        super(`Operation timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+export class CircuitOpenError extends FlowShieldError {
+    constructor() {
+        super('Circuit breaker is open — request rejected');
+        this.name = 'CircuitOpenError';
+    }
+}
+export class BulkheadRejectedError extends FlowShieldError {
+    constructor() {
+        super('Bulkhead capacity exceeded — request rejected');
+        this.name = 'BulkheadRejectedError';
+    }
+}
+export class RateLimitExceededError extends FlowShieldError {
+    constructor() {
+        super('Rate limit exceeded — request rejected');
+        this.name = 'RateLimitExceededError';
+    }
+}
+export class RetryExhaustedError extends FlowShieldError {
+    attempts;
+    constructor(attempts, lastError) {
+        super(`All ${attempts} retry attempts exhausted`, lastError);
+        this.name = 'RetryExhaustedError';
+        this.attempts = attempts;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAkJ/E,+EAA+E;AAE/E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,4CAA4C;QAC5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACvB,IAA4B,CAAC,KAAK,GAAG,KAAK,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C,YAAY,EAAU;QACpB,KAAK,CAAC,6BAA6B,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACnD;QACE,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD;QACE,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACzD;QACE,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IACtC,QAAQ,CAAS;IACjC,YAAY,QAAgB,EAAE,SAAkB;QAC9C,KAAK,CAAC,OAAO,QAAQ,2BAA2B,EAAE,SAAS,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/esm/utils.js

@@ -0,0 +1,77 @@
+/**
+ * Sleep for `ms` milliseconds. Supports cooperative cancellation via AbortSignal.
+ */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let done = false;
+        const timer = setTimeout(() => {
+            done = true;
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            if (!done) {
+                done = true;
+                clearTimeout(timer);
+                reject(signal.reason);
+            }
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+/**
+ * Calculate the delay for a given attempt using the specified backoff strategy.
+ */
+export function calculateDelay(attempt, baseDelay, strategy, maxDelay, previousDelay) {
+    let delay;
+    switch (strategy) {
+        case 'constant':
+            delay = baseDelay;
+            break;
+        case 'linear':
+            delay = baseDelay * attempt;
+            break;
+        case 'exponential':
+            delay = baseDelay * Math.pow(2, attempt - 1);
+            break;
+        case 'decorrelatedJitter': {
+            const prev = previousDelay ?? baseDelay;
+            delay = Math.random() * (prev * 3 - baseDelay) + baseDelay;
+            break;
+        }
+    }
+    return Math.min(delay, maxDelay);
+}
+/**
+ * Validate that a number is a positive integer.
+ */
+export function assertPositiveInteger(value, name) {
+    if (!Number.isFinite(value) || value < 1 || Math.floor(value) !== value) {
+        throw new RangeError(`${name} must be a positive integer, got ${value}`);
+    }
+}
+/**
+ * Validate that a number is a positive finite number.
+ */
+export function assertPositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive number, got ${value}`);
+    }
+}
+/**
+ * Validate that a number is a non-negative finite number.
+ */
+export function assertNonNegative(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative number, got ${value}`);
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,GAAG,KAAK,CAAC;QAEjB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QAEP,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,IAAI,GAAG,IAAI,CAAC;gBACZ,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,MAAO,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,SAAiB,EACjB,QAAsE,EACtE,QAAgB,EAChB,aAAsB;IAEtB,IAAI,KAAa,CAAC;IAElB,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,KAAK,GAAG,SAAS,CAAC;YAClB,MAAM;QACR,KAAK,QAAQ;YACX,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC;YAC5B,MAAM;QACR,KAAK,aAAa;YAChB,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YAC7C,MAAM;QACR,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC1B,MAAM,IAAI,GAAG,aAAa,IAAI,SAAS,CAAC;YACxC,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;YAC3D,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,IAAY;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC;QACxE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,oCAAoC,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,IAAY;IACxD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,mCAAmC,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,IAAY;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,uCAAuC,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}

package/dist/types/compose.d.ts

@@ -0,0 +1,32 @@
+import type { Policy } from './types.js';
+/**
+ * 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'));
+ * ```
+ */
+export declare function pipe(...policies: Policy[]): Policy;
+/**
+ * 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'));
+ * ```
+ */
+export declare function wrap(outer: Policy, inner: Policy): Policy;
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/compose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAiBlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzD"}

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export { retry } from './policies/retry.js';
+export { circuitBreaker } from './policies/circuit-breaker.js';
+export { timeout } from './policies/timeout.js';
+export { bulkhead } from './policies/bulkhead.js';
+export { fallback } from './policies/fallback.js';
+export { rateLimiter } from './policies/rate-limiter.js';
+export { hedge } from './policies/hedge.js';
+export { cache } from './policies/cache.js';
+export { pipe, wrap } from './compose.js';
+export type { Policy, RetryOptions, BackoffStrategy, CircuitBreakerOptions, CircuitBreakerHandle, CircuitState, TimeoutOptions, BulkheadOptions, BulkheadHandle, FallbackOptions, RateLimiterOptions, RateLimiterHandle, HedgeOptions, CacheOptions, CacheHandle, } from './types.js';
+export { FlowShieldError, TimeoutError, CircuitOpenError, BulkheadRejectedError, RateLimitExceededError, RetryExhaustedError, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG5C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAG1C,YAAY,EACV,MAAM,EACN,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/types/policies/bulkhead.d.ts

@@ -0,0 +1,20 @@
+import type { BulkheadOptions, BulkheadHandle } from '../types.js';
+/**
+ * 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
+ * ```
+ */
+export declare function bulkhead(options?: BulkheadOptions): {
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    handle: BulkheadHandle;
+};
+//# sourceMappingURL=bulkhead.d.ts.map

package/dist/types/policies/bulkhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulkhead.d.ts","sourceRoot":"","sources":["../../../src/policies/bulkhead.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAenE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG;IACvD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,EAAE,cAAc,CAAC;CACxB,CA8DA"}

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

@@ -0,0 +1,19 @@
+import type { CacheOptions, CacheHandle } from '../types.js';
+/**
+ * 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()));
+ * ```
+ */
+export declare function cache<V = unknown>(options?: CacheOptions<V>): {
+    execute: <T extends V>(fn: () => Promise<T>) => Promise<T>;
+    handle: CacheHandle;
+};
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAE,YAAY,CAAC,CAAC,CAAM,GAAG;IACjE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,EAAE,WAAW,CAAC;CACrB,CAqFA"}

package/dist/types/policies/circuit-breaker.d.ts

@@ -0,0 +1,19 @@
+import type { CircuitBreakerOptions, CircuitBreakerHandle } from '../types.js';
+/**
+ * Creates a circuit breaker policy that prevents calls to a failing service.
+ *
+ * Returns an object with `execute` (the policy function) and `handle`
+ * (an interface to inspect / reset the breaker state).
+ *
+ * @example
+ * ```ts
+ * const cb = circuitBreaker({ failureThreshold: 3, resetTimeout: 10_000 });
+ * const result = await cb.execute(() => fetch('/api/health'));
+ * console.log(cb.handle.state); // 'closed'
+ * ```
+ */
+export declare function circuitBreaker(options?: CircuitBreakerOptions): {
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    handle: CircuitBreakerHandle;
+};
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/types/policies/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/policies/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAgB,MAAM,aAAa,CAAC;AAU7F;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG;IACnE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,EAAE,oBAAoB,CAAC;CAC9B,CA+FA"}

package/dist/types/policies/fallback.d.ts

@@ -0,0 +1,14 @@
+import type { FallbackOptions } from '../types.js';
+/**
+ * Creates a fallback policy that returns a fallback value (or the result
+ * of a fallback function) when the wrapped operation fails.
+ *
+ * @example
+ * ```ts
+ * const result = await fallback({ fallback: [] })(
+ *   () => fetch('/api/items').then(r => r.json()),
+ * );
+ * ```
+ */
+export declare function fallback<F>(options: FallbackOptions<F>): <T>(fn: () => Promise<T>) => Promise<T | F>;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/types/policies/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../src/policies/fallback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,IAGvC,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAevD"}

package/dist/types/policies/hedge.d.ts

@@ -0,0 +1,15 @@
+import type { HedgeOptions } from '../types.js';
+/**
+ * Creates a hedge policy that sends a parallel (hedged) request if the
+ * primary request doesn't resolve within the configured delay.
+ * The first request to resolve wins; the other's result is discarded.
+ *
+ * @example
+ * ```ts
+ * const result = await hedge({ hedgeDelay: 1000 })(
+ *   () => fetch('/api/data').then(r => r.json()),
+ * );
+ * ```
+ */
+export declare function hedge(options?: HedgeOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=hedge.d.ts.map

package/dist/types/policies/hedge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedge.d.ts","sourceRoot":"","sources":["../../../src/policies/hedge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,IAKhC,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAyDnD"}

package/dist/types/policies/rate-limiter.d.ts

@@ -0,0 +1,19 @@
+import type { RateLimiterOptions, RateLimiterHandle } from '../types.js';
+/**
+ * Creates a token-bucket rate limiter policy that limits how many times
+ * the wrapped operation can be executed within a time interval.
+ *
+ * Returns an object with `execute` (the policy function) and `handle`
+ * (an interface to inspect / reset the bucket).
+ *
+ * @example
+ * ```ts
+ * const rl = rateLimiter({ tokensPerInterval: 5, interval: 1000 });
+ * const result = await rl.execute(() => fetch('/api/data'));
+ * ```
+ */
+export declare function rateLimiter(options?: RateLimiterOptions): {
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    handle: RateLimiterHandle;
+};
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/types/policies/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/policies/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAczE;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG;IAC7D,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAgFA"}

package/dist/types/policies/retry.d.ts

@@ -0,0 +1,14 @@
+import type { RetryOptions } from '../types.js';
+/**
+ * Creates a retry policy that re-executes the wrapped operation on failure
+ * using the configured backoff strategy.
+ *
+ * @example
+ * ```ts
+ * const result = await retry({ maxAttempts: 5, backoff: 'exponential' })(
+ *   () => fetch('/api/data'),
+ * );
+ * ```
+ */
+export declare function retry(options?: RetryOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/types/policies/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAWhD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,IAahC,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAiCnD"}

package/dist/types/policies/timeout.d.ts

@@ -0,0 +1,15 @@
+import type { TimeoutOptions } from '../types.js';
+/**
+ * Creates a timeout policy that rejects if the wrapped operation
+ * does not resolve within the specified deadline.
+ *
+ * Uses AbortController for cooperative cancellation when the
+ * wrapped function supports it.
+ *
+ * @example
+ * ```ts
+ * const result = await timeout({ ms: 5000 })(() => fetch('/api/data'));
+ * ```
+ */
+export declare function timeout(options: TimeoutOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/types/policies/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,IAG/B,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CA6BnD"}

package/dist/types/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * A policy is a higher-order function that wraps an async operation
+ * with fault-tolerance behaviour.
+ */
+export type Policy = <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * A policy factory returns a Policy and, optionally, a handle to
+ * inspect / control the policy at runtime (e.g. circuit-breaker state).
+ */
+export type PolicyFactory<H = void> = H extends void ? Policy : {
+    execute: Policy;
+    handle: H;
+};
+export type BackoffStrategy = 'constant' | 'linear' | 'exponential' | 'decorrelatedJitter';
+export interface RetryOptions {
+    /** Maximum number of attempts (including the initial call). Default: 3 */
+    maxAttempts?: number;
+    /** Base delay in ms between retries. Default: 200 */
+    delay?: number;
+    /** Backoff strategy. Default: 'exponential' */
+    backoff?: BackoffStrategy;
+    /** Maximum delay cap in ms. Default: 30 000 */
+    maxDelay?: number;
+    /** Predicate – return `true` to retry on this error. Default: always retry */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Called before each retry */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** AbortSignal for cooperative cancellation */
+    signal?: AbortSignal;
+}
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures to trip the breaker. Default: 5 */
+    failureThreshold?: number;
+    /** Number of successes in half-open to close the breaker. Default: 1 */
+    successThreshold?: number;
+    /** Time in ms the breaker stays open before moving to half-open. Default: 30 000 */
+    resetTimeout?: number;
+    /** Called when the circuit opens */
+    onOpen?: () => void;
+    /** Called when the circuit closes */
+    onClose?: () => void;
+    /** Called when the circuit transitions to half-open */
+    onHalfOpen?: () => void;
+}
+export interface CircuitBreakerHandle {
+    /** Current state of the circuit */
+    readonly state: CircuitState;
+    /** Current consecutive failure count */
+    readonly failureCount: number;
+    /** Current consecutive success count (in half-open) */
+    readonly successCount: number;
+    /** Manually reset the breaker to closed */
+    reset(): void;
+}
+export interface TimeoutOptions {
+    /** Timeout deadline in milliseconds */
+    ms: number;
+}
+export interface BulkheadOptions {
+    /** Maximum concurrent executions. Default: 10 */
+    maxConcurrent?: number;
+    /** Maximum queue size. Default: 0 (no queue) */
+    maxQueue?: number;
+}
+export interface BulkheadHandle {
+    /** Number of currently running executions */
+    readonly running: number;
+    /** Number of queued executions */
+    readonly queued: number;
+}
+export interface FallbackOptions<T> {
+    /** The fallback value or async function producing one */
+    fallback: T | ((error: unknown) => T) | ((error: unknown) => Promise<T>);
+    /** Predicate – return `true` to use fallback for this error. Default: always */
+    shouldFallback?: (error: unknown) => boolean;
+}
+export interface RateLimiterOptions {
+    /** Maximum number of tokens (requests) per interval. Default: 10 */
+    tokensPerInterval?: number;
+    /** Interval duration in ms. Default: 1000 */
+    interval?: number;
+    /** If true, reject immediately when no tokens. If false, queue. Default: false */
+    rejectOnLimit?: boolean;
+}
+export interface RateLimiterHandle {
+    /** Number of tokens currently available */
+    readonly availableTokens: number;
+    /** Reset the bucket to full */
+    reset(): void;
+}
+export interface HedgeOptions {
+    /** Delay in ms before sending the hedged (parallel) request. Default: 2000 */
+    hedgeDelay?: number;
+}
+export interface CacheOptions<T> {
+    /** Time-to-live in ms. Default: 60 000 */
+    ttl?: number;
+    /** If true, return stale value while revalidating in the background. Default: false */
+    staleWhileRevalidate?: boolean;
+    /** Custom cache key generator. Default: 'default' */
+    keyFn?: () => string;
+    /** Called when a cache entry is evicted */
+    onEvict?: (key: string, value: T) => void;
+}
+export interface CacheHandle {
+    /** Number of entries currently in cache */
+    readonly size: number;
+    /** Invalidate a specific cache key */
+    invalidate(key?: string): void;
+    /** Clear all cache entries */
+    clear(): void;
+}
+export declare class FlowShieldError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export declare class TimeoutError extends FlowShieldError {
+    constructor(ms: number);
+}
+export declare class CircuitOpenError extends FlowShieldError {
+    constructor();
+}
+export declare class BulkheadRejectedError extends FlowShieldError {
+    constructor();
+}
+export declare class RateLimitExceededError extends FlowShieldError {
+    constructor();
+}
+export declare class RetryExhaustedError extends FlowShieldError {
+    readonly attempts: number;
+    constructor(attempts: number, lastError: unknown);
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/types/utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sleep for `ms` milliseconds. Supports cooperative cancellation via AbortSignal.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Calculate the delay for a given attempt using the specified backoff strategy.
+ */
+export declare function calculateDelay(attempt: number, baseDelay: number, strategy: 'constant' | 'linear' | 'exponential' | 'decorrelatedJitter', maxDelay: number, previousDelay?: number): number;
+/**
+ * Validate that a number is a positive integer.
+ */
+export declare function assertPositiveInteger(value: number, name: string): void;
+/**
+ * Validate that a number is a positive finite number.
+ */
+export declare function assertPositive(value: number, name: string): void;
+/**
+ * Validate that a number is a non-negative finite number.
+ */
+export declare function assertNonNegative(value: number, name: string): void;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,oBAAoB,EACtE,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIvE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAInE"}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "flowshield",
+  "version": "1.0.0",
+  "description": "Zero-dependency, TypeScript-first resilience & fault-tolerance toolkit. Composable policies: retry, circuit breaker, timeout, bulkhead, fallback, rate limiter, hedge, cache.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:types",
+    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "resilience",
+    "fault-tolerance",
+    "retry",
+    "circuit-breaker",
+    "timeout",
+    "bulkhead",
+    "fallback",
+    "rate-limiter",
+    "hedge",
+    "cache",
+    "typescript",
+    "zero-dependency",
+    "composable",
+    "microservices",
+    "error-handling",
+    "exponential-backoff",
+    "polly",
+    "cockatiel",
+    "fault-tolerant",
+    "resilient",
+    "policies",
+    "edge-runtime"
+  ],
+  "author": "Avinash Velu <avinashvelu03@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Avinashvelu03/flowshield.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Avinashvelu03/flowshield/issues"
+  },
+  "homepage": "https://github.com/Avinashvelu03/flowshield#readme",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.1.1",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false
+}