@julr/tenace 1.0.0-next.0

package/build/src/memory-DWyezb1O.js

@@ -0,0 +1,37 @@
+import { memoryDriver } from "bentocache/drivers/memory";
+import { BentoCache, bentostore } from "bentocache";
+var MemoryCacheAdapter = class {
+	#bento;
+	constructor(options = {}) {
+		this.#bento = new BentoCache({
+			default: "cache",
+			stores: { cache: bentostore().useL1Layer(memoryDriver({
+				maxSize: options.maxSize ?? "10mb",
+				maxItems: options.maxItems ?? 1e3
+			})) }
+		});
+	}
+	async get(key) {
+		return this.#bento.get({ key });
+	}
+	async set(key, value, ttlMs) {
+		await this.#bento.set({
+			key,
+			value,
+			ttl: `${ttlMs}ms`
+		});
+	}
+	async delete(key) {
+		await this.#bento.delete({ key });
+	}
+	async has(key) {
+		return this.#bento.has({ key });
+	}
+	async clear() {
+		await this.#bento.clear();
+	}
+	async disconnect() {
+		await this.#bento.disconnect();
+	}
+};
+export { MemoryCacheAdapter as t };

package/build/src/memory-DXkg8s6y.js

@@ -0,0 +1,60 @@
+import { RateLimiterMemory } from "rate-limiter-flexible";
+var MemoryRateLimiterAdapter = class {
+	#limiters = /* @__PURE__ */ new Map();
+	#getLimiter(options) {
+		const cacheKey = `${options.key}:${options.config.maxCalls}:${options.config.windowMs}`;
+		let limiter = this.#limiters.get(cacheKey);
+		if (!limiter) {
+			limiter = new RateLimiterMemory({
+				points: options.config.maxCalls,
+				duration: Math.ceil(options.config.windowMs / 1e3)
+			});
+			this.#limiters.set(cacheKey, limiter);
+		}
+		return limiter;
+	}
+	async acquire(key, options) {
+		const limiter = this.#getLimiter({
+			key,
+			config: options
+		});
+		try {
+			const result = await limiter.consume(key, 1);
+			return {
+				allowed: true,
+				remaining: result.remainingPoints,
+				resetInMs: result.msBeforeNext
+			};
+		} catch (error) {
+			const result = error;
+			return {
+				allowed: false,
+				remaining: result.remainingPoints,
+				resetInMs: result.msBeforeNext,
+				retryAfterMs: result.msBeforeNext
+			};
+		}
+	}
+	async getState(key) {
+		for (const [cacheKey, limiter] of this.#limiters) if (cacheKey.startsWith(`${key}:`)) {
+			const result = await limiter.get(key);
+			if (result) return {
+				calls: result.consumedPoints,
+				remaining: result.remainingPoints,
+				resetInMs: result.msBeforeNext
+			};
+		}
+		return {
+			calls: 0,
+			remaining: Infinity,
+			resetInMs: 0
+		};
+	}
+	async reset(key) {
+		for (const [cacheKey, limiter] of this.#limiters) if (cacheKey.startsWith(`${key}:`)) await limiter.delete(key);
+	}
+	clear() {
+		this.#limiters.clear();
+	}
+};
+export { MemoryRateLimiterAdapter as t };

package/build/src/plugin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plugin system for Tenace.
+ * Allows external packages (like @julr/tenace-otel) to hook into resilience events.
+ */
+import type { TenacePlugin } from './types/plugin.ts';
+export type { TenacePlugin } from './types/plugin.ts';
+/**
+ * Register a plugin to receive resilience events.
+ */
+export declare function use(plugin: TenacePlugin): void;
+/**
+ * Get all registered plugins.
+ */
+export declare function getPlugins(): TenacePlugin[];
+/**
+ * Clear all registered plugins (useful for testing).
+ */
+export declare function clearPlugins(): void;
+/**
+ * Register a single hook and return an unsubscribe function.
+ */
+export declare function registerHook<K extends keyof TenacePlugin>(hook: K, fn: NonNullable<TenacePlugin[K]>): () => void;
+/**
+ * Notify all plugins of an event.
+ */
+export declare function notifyPlugins<K extends keyof TenacePlugin>(hook: K, event: TenacePlugin[K] extends ((e: infer E) => void) | undefined ? E : never): void;
+/**
+ * Wrap execution with span if any plugin supports it.
+ */
+export declare function wrapWithPluginSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: () => Promise<T>): Promise<T>;

package/build/src/policy_configurator.d.ts

@@ -0,0 +1,108 @@
+import type { ChaosFaultConfig, ChaosLatencyConfig } from './chaos/types.ts';
+import type { RateLimitOptions } from './adapters/rate_limiter/types.ts';
+import type { DistributedLockOptions } from './adapters/lock/types.ts';
+import type { CacheOptions } from './adapters/cache/types.ts';
+import { type CircuitBreakerHooks, type Duration, type PolicyLayer, type RetryConfig } from './types/types.ts';
+/**
+ * Abstract base class for resilience configuration.
+ * Provides all the `.withX()` methods that add layers to the policy stack.
+ * The order of `.withX()` calls determines the execution order.
+ */
+export declare abstract class PolicyConfigurator<T, TSelf extends PolicyConfigurator<T, TSelf>> {
+    #private;
+    protected layers: PolicyLayer[];
+    protected abstract createInstance(layers: PolicyLayer[]): TSelf;
+    /**
+     * Adds a timeout to the operation.
+     * Position in the chain determines behavior:
+     * - Before retry: timeout applies to each attempt
+     * - After retry: timeout applies to the whole operation including retries
+     */
+    withTimeout(duration: Duration, strategyOrOptions?: 'aggressive' | 'cooperative' | {
+        strategy?: 'aggressive' | 'cooperative';
+        onTimeout?: () => void;
+    }): TSelf;
+    /**
+     * Adds retry logic with customizable delay.
+     * Position in the chain determines what gets retried.
+     *
+     * @example
+     * // Simple retry with 3 attempts
+     * .withRetry()
+     *
+     * @example
+     * // Retry 5 times with 1 second delay
+     * .withRetry({ times: 5, delay: 1000 })
+     *
+     * @example
+     * // Exponential backoff
+     * .withRetry({ times: 5, delay: (attempt) => Math.min(1000 * 2 ** attempt, 30000) })
+     */
+    withRetry(options?: RetryConfig): TSelf;
+    /**
+     * Adds circuit breaker protection with consecutive failure threshold.
+     * The circuit breaker instance is created immediately and shared across all executions.
+     */
+    withCircuitBreaker(options: {
+        failureThreshold: number;
+        halfOpenAfter: Duration;
+        hooks?: CircuitBreakerHooks;
+    }): TSelf;
+    /**
+     * Adds circuit breaker with sampling strategy.
+     */
+    withSamplingCircuitBreaker(options: {
+        threshold: number;
+        duration: Duration;
+        halfOpenAfter: Duration;
+        minimumRps?: number;
+        hooks?: CircuitBreakerHooks;
+    }): TSelf;
+    /**
+     * Adds a fallback function that provides a default value on failure.
+     * Typically placed at the outermost position to catch all errors.
+     */
+    withFallback(fn: () => T | Promise<T>, options?: {
+        onFallback?: () => void;
+    }): TSelf;
+    /**
+     * Adds OpenTelemetry span tracing.
+     */
+    withSpan(name: string, attributes?: Record<string, string | number | boolean>): TSelf;
+    /**
+     * Adds bulkhead isolation (concurrency limiter).
+     * The bulkhead instance is created immediately and shared across all executions.
+     */
+    withBulkhead(limit: number, queueOrOptions?: number | {
+        queue?: number;
+        onRejected?: () => void;
+    }): TSelf;
+    /**
+     * Adds caching for the operation.
+     */
+    withCache(options: CacheOptions): TSelf;
+    /**
+     * Adds rate limiting for the operation.
+     */
+    withRateLimit(options: RateLimitOptions): TSelf;
+    /**
+     * Adds distributed lock protection.
+     */
+    withDistributedLock(options: DistributedLockOptions): TSelf;
+    /**
+     * Adds chaos fault injection (throws random errors).
+     * Place at the end of the chain (innermost) to test resilience patterns.
+     *
+     * @example
+     * .withChaosFault({ rate: 0.1, error: new Error('Random failure') })
+     */
+    withChaosFault(options: ChaosFaultConfig): TSelf;
+    /**
+     * Adds chaos latency injection (adds random delays).
+     * Place at the end of the chain (innermost) to test resilience patterns.
+     *
+     * @example
+     * .withChaosLatency({ rate: 0.2, delay: { min: 100, max: 2000 } })
+     */
+    withChaosLatency(options: ChaosLatencyConfig): TSelf;
+}

package/build/src/semaphore.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A semaphore for limiting concurrent operations.
+ * Inspired by Effect's Semaphore and p-limit.
+ *
+ * @example
+ * ```ts
+ * const sem = new Semaphore(3) // max 3 concurrent operations
+ *
+ * // Option 1: Use run() for individual calls
+ * const result = await sem.run(() => fetchData())
+ *
+ * // Option 2: Use wrap() to create a limited function
+ * const limitedFetch = sem.wrap(fetchData)
+ * await limitedFetch()
+ *
+ * // Option 3: Use withPermit() for manual control
+ * const release = await sem.acquire()
+ * try {
+ *   await doSomething()
+ * } finally {
+ *   release()
+ * }
+ * ```
+ */
+export declare class Semaphore {
+    #private;
+    constructor(permits: number);
+    /**
+     * Current number of available permits
+     */
+    get availablePermits(): number;
+    /**
+     * Number of currently running operations
+     */
+    get activeCount(): number;
+    /**
+     * Number of operations waiting in queue
+     */
+    get pendingCount(): number;
+    /**
+     * Maximum number of concurrent operations
+     */
+    get permits(): number;
+    /**
+     * Acquire a permit. Returns a release function.
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Run a function with a permit.
+     * Automatically acquires and releases the permit.
+     */
+    run<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Wrap a function to automatically use this semaphore.
+     */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * Process an array of items with limited concurrency.
+     * Similar to p-limit's map() or p-map.
+     */
+    map<TInput, TOutput>(items: Iterable<TInput>, fn: (item: TInput, index: number) => TOutput | Promise<TOutput>): Promise<TOutput[]>;
+    /**
+     * Clear all pending operations in the queue.
+     * Does not affect currently running operations.
+     */
+    clearQueue(): void;
+}
+/**
+ * Create a semaphore with the given number of permits.
+ */
+export declare function semaphore(permits: number): Semaphore;

package/build/src/tenace_builder.d.ts

@@ -0,0 +1,22 @@
+import { type PolicyLayer, type TenaceFunction } from './types/types.ts';
+import { PolicyConfigurator } from './policy_configurator.ts';
+/**
+ * Fluent builder for Tenace policies.
+ * Each `.withX()` call adds a layer to the execution chain in order.
+ */
+export declare class TenaceBuilder<T> extends PolicyConfigurator<T, TenaceBuilder<T>> {
+    #private;
+    constructor(options?: {
+        fn?: TenaceFunction<T> | undefined;
+        layers?: PolicyLayer[];
+    });
+    protected createInstance(layers: PolicyLayer[]): TenaceBuilder<T>;
+    /**
+     * Executes the function with the configured policies.
+     */
+    execute(fn?: TenaceFunction<T>): Promise<T>;
+    /**
+     * Creates a wrapped function that applies the policy when called.
+     */
+    wrap(fn: TenaceFunction<T>): () => Promise<T>;
+}

package/build/src/tenace_policy.d.ts

@@ -0,0 +1,41 @@
+import { type CircuitBreakerAccessor, type PolicyLayer, type TenaceFunction } from './types/types.ts';
+import { TenaceBuilder } from './tenace_builder.ts';
+import { PolicyConfigurator } from './policy_configurator.ts';
+/**
+ * Reusable policy that can be applied to multiple functions.
+ * Circuit breaker and bulkhead state is shared across all calls.
+ */
+export declare class TenacePolicy extends PolicyConfigurator<unknown, TenacePolicy> {
+    #private;
+    constructor(layers?: PolicyLayer[]);
+    protected createInstance(layers: PolicyLayer[]): TenacePolicy;
+    /**
+     * Access the circuit breaker state and controls.
+     * Returns null if no circuit breaker is configured.
+     *
+     * @example
+     * ```ts
+     * const policy = Tenace.policy()
+     *   .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+     *
+     * // Check state
+     * if (policy.circuitBreaker?.isOpen) {
+     *   console.log('Circuit is open, service might be down')
+     * }
+     *
+     * // Manual isolation (maintenance mode)
+     * const handle = policy.circuitBreaker?.isolate()
+     * // ... all calls now fail with CircuitIsolatedError
+     * handle?.dispose() // release isolation
+     * ```
+     */
+    get circuitBreaker(): CircuitBreakerAccessor | null;
+    /**
+     * Creates a wrapped function.
+     */
+    wrap<T>(fn: TenaceFunction<T>): () => Promise<T>;
+    /**
+     * Creates a builder for the given function with the policy's shared state.
+     */
+    call<T>(fn: TenaceFunction<T>): TenaceBuilder<T>;
+}

package/build/src/types/backoff.d.ts

@@ -0,0 +1,57 @@
+import type { Duration } from './types.ts';
+/**
+ * Options for exponential backoff
+ */
+export interface ExponentialBackoffOptions {
+    /**
+     * Initial delay in ms or as a duration string
+     * @default 100
+     */
+    initial?: Duration;
+    /**
+     * Maximum delay in ms or as a duration string
+     * @default 30000
+     */
+    max?: Duration;
+    /**
+     * Exponential factor
+     * @default 2
+     */
+    exponent?: number;
+}
+/**
+ * Jitter strategy for exponential backoff
+ * - 'full': Random delay between 0 and calculated delay
+ * - 'decorrelated': AWS-style decorrelated jitter (better distribution)
+ */
+export type JitterStrategy = 'full' | 'decorrelated';
+/**
+ * Options for exponential backoff with jitter
+ */
+export interface ExponentialJitterBackoffOptions extends ExponentialBackoffOptions {
+    /**
+     * Jitter strategy
+     * @default 'full'
+     */
+    jitter?: JitterStrategy;
+}
+/**
+ * Options for linear backoff
+ */
+export interface LinearBackoffOptions {
+    /**
+     * Initial delay in ms or as a duration string
+     * @default 100
+     */
+    initial?: Duration;
+    /**
+     * Step to add for each attempt in ms or as a duration string
+     * @default 100
+     */
+    step?: Duration;
+    /**
+     * Maximum delay in ms or as a duration string
+     * @default 30000
+     */
+    max?: Duration;
+}

package/build/src/types/collection.d.ts

@@ -0,0 +1,46 @@
+import type { Duration, RetryDelayFunction } from './types.ts';
+/**
+ * Result of a settled task
+ */
+export type SettledResult<T> = {
+    status: 'fulfilled';
+    value: T;
+    index: number;
+} | {
+    status: 'rejected';
+    reason: Error;
+    index: number;
+};
+/**
+ * Progress info passed to callbacks
+ */
+export interface TaskProgress {
+    completed: number;
+    failed: number;
+    total: number;
+    index: number;
+}
+/**
+ * Options for retry per task
+ */
+export interface TaskRetryOptions {
+    /**
+     * Only retry if this function returns true
+     */
+    retryIf?: (error: Error) => boolean;
+    /**
+     * Abort retrying if this function returns true
+     */
+    abortIf?: (error: Error) => boolean;
+    /**
+     * Delay between retries in ms, or a function that returns the delay.
+     * Can be a number, a string duration ('1s', '500ms'), or a function.
+     * Use backoff helpers for common patterns.
+     *
+     * @example
+     * delay: 1000
+     * delay: '1s'
+     * delay: backoff.exponential({ initial: 100, max: 30_000 })
+     */
+    delay?: Duration | RetryDelayFunction;
+}

package/build/src/types/main.d.ts

@@ -0,0 +1,5 @@
+export type * from './collection.ts';
+export type * from './backoff.ts';
+export type * from './plugin.ts';
+export type { BreakerConfig, CircuitBreakerAccessor, CircuitBreakerConfig, CircuitBreakerHooks, CircuitState, Duration, IsolationHandle, TenaceContext, TenaceFunction, RetryConfig, RetryDelayFunction, SpanConfig, TimeoutStrategy, WaitForOptions, } from './types.ts';
+export type { ChaosFaultConfig, ChaosLatencyConfig, GlobalChaosConfig } from '../chaos/types.ts';

package/build/src/types/main.js

@@ -0,0 +1 @@
+export {};

package/build/src/types/plugin.d.ts

@@ -0,0 +1,61 @@
+export interface RetryEvent {
+    attempt: number;
+    delay: number;
+    error: Error;
+    operationName?: string;
+}
+export interface RetryExhaustedEvent {
+    error: Error;
+    operationName?: string;
+}
+export interface TimeoutEvent {
+    operationName?: string;
+}
+export interface CircuitEvent {
+    operationName?: string;
+}
+export interface BulkheadEvent {
+    operationName?: string;
+}
+export interface RateLimitEvent {
+    key: string;
+    retryAfterMs?: number | undefined;
+    operationName?: string;
+}
+export interface CacheEvent {
+    key: string;
+    operationName?: string;
+}
+export interface FallbackEvent {
+    operationName?: string;
+}
+export interface LockEvent {
+    key: string;
+    operationName?: string;
+}
+export interface PipelineEvent {
+    operationName?: string;
+    duration?: number;
+    error?: Error;
+}
+export interface TenacePlugin {
+    /**
+     * Wrapper for creating spans (used by withSpan and retry attempts)
+     */
+    wrapWithSpan?<T>(name: string, attributes: Record<string, string | number | boolean>, fn: () => Promise<T>): Promise<T>;
+    onRetry?(event: RetryEvent): void;
+    onRetryExhausted?(event: RetryExhaustedEvent): void;
+    onTimeout?(event: TimeoutEvent): void;
+    onCircuitOpened?(event: CircuitEvent): void;
+    onCircuitClosed?(event: CircuitEvent): void;
+    onCircuitHalfOpened?(event: CircuitEvent): void;
+    onBulkheadRejected?(event: BulkheadEvent): void;
+    onRateLimitRejected?(event: RateLimitEvent): void;
+    onCacheHit?(event: CacheEvent): void;
+    onCacheMiss?(event: CacheEvent): void;
+    onFallback?(event: FallbackEvent): void;
+    onLockAcquired?(event: LockEvent): void;
+    onLockRejected?(event: LockEvent): void;
+    onPipelineStart?(event: PipelineEvent): void;
+    onPipelineEnd?(event: PipelineEvent): void;
+}