@julr/tenace 1.0.0-next.0

package/build/src/errors/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Base error class for all tenace errors
+ */
+export declare class TenaceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when an operation times out
+ */
+export declare class TimeoutError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an operation is cancelled (e.g., via AbortController)
+ */
+export declare class CancelledError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when circuit breaker is open and rejecting calls
+ */
+export declare class CircuitOpenError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when circuit breaker is isolated (manually opened)
+ */
+export declare class CircuitIsolatedError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when bulkhead rejects a call due to capacity limits
+ */
+export declare class BulkheadFullError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an abort signal is triggered
+ */
+export declare class AbortError extends TenaceError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+export declare class RateLimitError extends TenaceError {
+    /**
+     * Time in milliseconds to wait before retrying
+     */
+    retryAfterMs: number;
+    /**
+     * Number of remaining calls (0 when rate limited)
+     */
+    remaining: number;
+    constructor(options: {
+        message?: string;
+        retryAfterMs: number;
+        remaining?: number;
+    });
+}
+/**
+ * Thrown when a distributed lock cannot be acquired
+ */
+export declare class LockNotAcquiredError extends TenaceError {
+    /**
+     * The key that was being locked
+     */
+    key: string;
+    constructor(options: {
+        key: string;
+        message?: string;
+    });
+}
+/**
+ * Thrown when waitFor times out before the condition becomes true
+ */
+export declare class WaitForTimeoutError extends TenaceError {
+    constructor(message?: string);
+}

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

@@ -0,0 +1 @@
+export { TenaceError, TimeoutError, CancelledError, CircuitOpenError, CircuitIsolatedError, BulkheadFullError, AbortError, RateLimitError, LockNotAcquiredError, WaitForTimeoutError, } from './errors.ts';

package/build/src/errors/main.js

@@ -0,0 +1,2 @@
+import { a as CircuitOpenError, c as TenaceError, i as CircuitIsolatedError, l as TimeoutError, n as BulkheadFullError, o as LockNotAcquiredError, r as CancelledError, s as RateLimitError, t as AbortError, u as WaitForTimeoutError } from "../errors-BODHnryv.js";
+export { AbortError, BulkheadFullError, CancelledError, CircuitIsolatedError, CircuitOpenError, LockNotAcquiredError, RateLimitError, TenaceError, TimeoutError, WaitForTimeoutError };

package/build/src/errors-BODHnryv.js

@@ -0,0 +1,67 @@
+var TenaceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TenaceError";
+	}
+};
+var TimeoutError = class extends TenaceError {
+	constructor(message = "Operation timed out") {
+		super(message);
+		this.name = "TimeoutError";
+	}
+};
+var CancelledError = class extends TenaceError {
+	constructor(message = "Operation was cancelled") {
+		super(message);
+		this.name = "CancelledError";
+	}
+};
+var CircuitOpenError = class extends TenaceError {
+	constructor(message = "Circuit breaker is open") {
+		super(message);
+		this.name = "CircuitOpenError";
+	}
+};
+var CircuitIsolatedError = class extends TenaceError {
+	constructor(message = "Circuit breaker is isolated") {
+		super(message);
+		this.name = "CircuitIsolatedError";
+	}
+};
+var BulkheadFullError = class extends TenaceError {
+	constructor(message = "Bulkhead capacity exceeded") {
+		super(message);
+		this.name = "BulkheadFullError";
+	}
+};
+var AbortError = class extends TenaceError {
+	constructor(message = "Operation aborted") {
+		super(message);
+		this.name = "AbortError";
+	}
+};
+var RateLimitError = class extends TenaceError {
+	retryAfterMs;
+	remaining;
+	constructor(options) {
+		super(options.message ?? `Rate limit exceeded. Retry after ${options.retryAfterMs}ms`);
+		this.name = "RateLimitError";
+		this.retryAfterMs = options.retryAfterMs;
+		this.remaining = options.remaining ?? 0;
+	}
+};
+var LockNotAcquiredError = class extends TenaceError {
+	key;
+	constructor(options) {
+		super(options.message ?? `Failed to acquire lock for key "${options.key}"`);
+		this.name = "LockNotAcquiredError";
+		this.key = options.key;
+	}
+};
+var WaitForTimeoutError = class extends TenaceError {
+	constructor(message = "Condition was not met within the timeout period") {
+		super(message);
+		this.name = "WaitForTimeoutError";
+	}
+};
+export { CircuitOpenError as a, TenaceError as c, CircuitIsolatedError as i, TimeoutError as l, BulkheadFullError as n, LockNotAcquiredError as o, CancelledError as r, RateLimitError as s, AbortError as t, WaitForTimeoutError as u };

package/build/src/internal/adapter_policies.d.ts

@@ -0,0 +1,31 @@
+import type { IPolicy } from 'cockatiel';
+import type { CacheOptions } from '../adapters/cache/types.ts';
+import type { RateLimitOptions } from '../adapters/rate_limiter/types.ts';
+import type { DistributedLockOptions } from '../adapters/lock/types.ts';
+export interface CachePolicyOptions extends CacheOptions {
+    optional?: boolean;
+}
+export interface RateLimitPolicyOptions extends RateLimitOptions {
+    optional?: boolean;
+}
+export interface LockPolicyOptions extends DistributedLockOptions {
+    optional?: boolean;
+}
+/**
+ * Creates a cache policy that integrates into the cockatiel pipeline.
+ * - On entry: check cache, return if hit
+ * - On exit (success): store in cache
+ */
+export declare function createCachePolicy<T>(options: CachePolicyOptions): IPolicy;
+/**
+ * Creates a rate limit policy that integrates into the cockatiel pipeline.
+ * - Check rate limit before execution
+ * - Throw RateLimitError if exceeded
+ */
+export declare function createRateLimitPolicy<T>(options: RateLimitPolicyOptions): IPolicy;
+/**
+ * Creates a distributed lock policy that integrates into the cockatiel pipeline.
+ * - Acquire lock before execution
+ * - Release lock after execution (success or failure)
+ */
+export declare function createLockPolicy<T>(options: LockPolicyOptions): IPolicy;

package/build/src/internal/cockatiel_factories.d.ts

@@ -0,0 +1,18 @@
+import { ConsecutiveBreaker, CountBreaker, type IPolicy, SamplingBreaker } from 'cockatiel';
+import type { BreakerConfig, CircuitBreakerConfig, RetryConfig } from '../types/types.ts';
+/**
+ * Wraps cockatiel errors into tenace errors
+ */
+export declare function wrapError(error: unknown): Error;
+/**
+ * Creates a breaker instance from config
+ */
+export declare function createBreaker(config: BreakerConfig): ConsecutiveBreaker | CountBreaker | SamplingBreaker;
+/**
+ * Creates a circuit breaker cockatiel policy with hooks and telemetry
+ */
+export declare function createCircuitBreakerPolicy(config: CircuitBreakerConfig): IPolicy;
+/**
+ * Creates a retry cockatiel policy with telemetry
+ */
+export declare function createRetryPolicy(config: RetryConfig): IPolicy;

package/build/src/internal/telemetry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Telemetry utilities for emitting span events.
+ * Only emits events if OpenTelemetry is available and a span is active.
+ * Zero overhead if OTel is not installed or no span is active.
+ */
+/**
+ * Try to load OpenTelemetry API. Safe to call multiple times.
+ */
+export declare function loadOtelApi(): Promise<typeof import('@opentelemetry/api') | undefined>;
+/**
+ * Get the currently active span, if any.
+ */
+export declare function getActiveSpan(): import("@opentelemetry/api").Span | undefined;
+/**
+ * Check if telemetry is available (OTel loaded and span active).
+ */
+export declare function hasTelemetry(): boolean;
+/**
+ * Emit a span event with attributes.
+ */
+export declare function emitEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Set span attributes.
+ */
+export declare function setAttributes(attributes: Record<string, string | number | boolean>): void;
+type SpanAttributes = Record<string, string | number | boolean>;
+/**
+ * Create a child span and execute the callback within it.
+ * Handles both sync and async callbacks, sets proper status, and records exceptions.
+ * No-op if OTel is not loaded.
+ */
+export declare function recordSpan<T>(name: string, fn: () => T | Promise<T>, attributes?: SpanAttributes): T | Promise<T>;
+export declare const TelemetryEvents: {
+    readonly RETRY_ATTEMPT: "tenace.retry";
+    readonly RETRY_SUCCESS: "tenace.retry.success";
+    readonly RETRY_EXHAUSTED: "tenace.retry.exhausted";
+    readonly TIMEOUT: "tenace.timeout";
+    readonly CIRCUIT_OPEN: "tenace.circuit_breaker.open";
+    readonly CIRCUIT_CLOSE: "tenace.circuit_breaker.close";
+    readonly CIRCUIT_HALF_OPEN: "tenace.circuit_breaker.half_open";
+    readonly BULKHEAD_REJECTED: "tenace.bulkhead.rejected";
+    readonly CACHE_HIT: "tenace.cache.hit";
+    readonly CACHE_MISS: "tenace.cache.miss";
+    readonly RATE_LIMIT_REJECTED: "tenace.rate_limit.rejected";
+    readonly LOCK_ACQUIRED: "tenace.lock.acquired";
+    readonly LOCK_NOT_ACQUIRED: "tenace.lock.not_acquired";
+    readonly LOCK_RELEASED: "tenace.lock.released";
+    readonly FALLBACK_TRIGGERED: "tenace.fallback";
+};
+export {};

package/build/src/main.d.ts

@@ -0,0 +1,176 @@
+import type { TenaceFunction, WaitForOptions } from './types/types.ts';
+import type { GlobalChaosConfig } from './chaos/types.ts';
+import type { TenacePlugin } from './plugin.ts';
+import { TenacePolicy } from './tenace_policy.ts';
+import { TenaceBuilder } from './tenace_builder.ts';
+import { CollectionBuilder } from './collection.ts';
+export { Semaphore, semaphore } from './semaphore.ts';
+export { CollectionBuilder } from './collection.ts';
+export { configStore } from './config.ts';
+export { backoff } from './backoff.ts';
+export { use, getPlugins, clearPlugins, registerHook } from './plugin.ts';
+/**
+ * Main entry point for creating resilient operations
+ *
+ * @example
+ * ```ts
+ * // Simple call with chained methods
+ * const result = await Tenace
+ *   .call(() => myService.doThing())
+ *   .withTimeout(1000)
+ *   .withRetry(3)
+ *   .withExponentialBackoff(100, 2000)
+ *   .withCircuitBreaker(5, 10000)
+ *   .withFallback(() => defaultValue)
+ *   .execute()
+ *
+ * // Reusable policy
+ * const policy = Tenace.policy()
+ *   .withTimeout(1000)
+ *   .withRetry(3)
+ *   .withCircuitBreaker(5, 10000)
+ *
+ * await policy.call(() => fetchUser())
+ * await policy.call(() => fetchPosts())
+ *
+ * // Execute collection of tasks with concurrency
+ * const results = await Tenace.all([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ * ])
+ *   .withConcurrency(5)
+ *   .withRetryPerTask(2)
+ *   .execute()
+ *
+ * // Map over items with concurrency
+ * const users = await Tenace.map([1, 2, 3], (id) => fetchUser(id))
+ *   .withConcurrency(5)
+ *   .execute()
+ * ```
+ */
+export declare const Tenace: {
+    /**
+     * Creates a resilience builder for the given function
+     */
+    call<T>(fn: TenaceFunction<T>): TenaceBuilder<T>;
+    /**
+     * Creates a reusable resilience policy
+     */
+    policy(): TenacePolicy;
+    /**
+     * Convenience method to wrap a function with a policy
+     */
+    wrap<T>(fn: TenaceFunction<T>, policy: TenacePolicy): () => Promise<T>;
+    /**
+     * Execute a collection of async tasks with concurrency control.
+     *
+     * @example
+     * ```ts
+     * const results = await Tenace.all([
+     *   () => fetchUser(1),
+     *   () => fetchUser(2),
+     *   () => fetchUser(3),
+     * ])
+     *   .withConcurrency(2)
+     *   .withRetryPerTask(3)
+     *   .withTimeoutPerTask(5000)
+     *   .execute()
+     * ```
+     */
+    all<T>(tasks: Array<() => Promise<T>>): CollectionBuilder<T>;
+    /**
+     * Map over items and execute with concurrency control.
+     *
+     * @example
+     * ```ts
+     * const users = await Tenace.map([1, 2, 3], async (id) => {
+     *   return fetchUser(id)
+     * })
+     *   .withConcurrency(5)
+     *   .execute()
+     * ```
+     */
+    map<TInput, TOutput>(items: Iterable<TInput>, mapper: (item: TInput, index: number) => Promise<TOutput>): CollectionBuilder<TOutput>;
+    /**
+     * Wait for a condition to become true by polling at regular intervals.
+     *
+     * @example
+     * ```ts
+     * // Wait for a service to be healthy
+     * await Tenace.waitFor(() => isServiceHealthy(), {
+     *   interval: '1s',
+     *   timeout: '30s',
+     * })
+     *
+     * // Wait for a database to be ready
+     * await Tenace.waitFor(async () => {
+     *   try {
+     *     await db.ping()
+     *     return true
+     *   } catch {
+     *     return false
+     *   }
+     * }, { timeout: '1m' })
+     * ```
+     */
+    waitFor(condition: () => boolean | Promise<boolean>, options?: WaitForOptions): Promise<void>;
+    /**
+     * Chaos engineering utilities for testing resilience.
+     *
+     * @example
+     * ```ts
+     * // Enable global chaos (affects all Tenace calls)
+     * Tenace.chaos.enable({ fault: 1 })  // 100% fault rate
+     * Tenace.chaos.enable({ latency: 500 })  // 500ms delay
+     * Tenace.chaos.enable({
+     *   fault: { rate: 0.1, error: new Error('Random') },
+     *   latency: { rate: 0.2, delay: { min: 100, max: 2000 } }
+     * })
+     *
+     * // Disable chaos
+     * Tenace.chaos.disable()
+     * ```
+     */
+    chaos: {
+        /**
+         * Enable global chaos injection.
+         * Supports shorthands:
+         * - `{ fault: 1 }` = 100% fault rate with default error
+         * - `{ latency: 500 }` = 500ms fixed delay with rate=1
+         */
+        enable: (config: GlobalChaosConfig) => void;
+        /**
+         * Disable global chaos injection
+         */
+        disable: () => void;
+        /**
+         * Check if global chaos is currently enabled
+         */
+        isEnabled: () => boolean;
+    };
+    /**
+     * Register global hooks for resilience events.
+     * Each method returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = Tenace.hooks.onRetry((e) => console.log(`Retry ${e.attempt}`))
+     * // Later: unsubscribe()
+     * ```
+     */
+    hooks: {
+        onRetry: (fn: NonNullable<TenacePlugin["onRetry"]>) => () => void;
+        onRetryExhausted: (fn: NonNullable<TenacePlugin["onRetryExhausted"]>) => () => void;
+        onTimeout: (fn: NonNullable<TenacePlugin["onTimeout"]>) => () => void;
+        onCircuitOpened: (fn: NonNullable<TenacePlugin["onCircuitOpened"]>) => () => void;
+        onCircuitClosed: (fn: NonNullable<TenacePlugin["onCircuitClosed"]>) => () => void;
+        onCircuitHalfOpened: (fn: NonNullable<TenacePlugin["onCircuitHalfOpened"]>) => () => void;
+        onBulkheadRejected: (fn: NonNullable<TenacePlugin["onBulkheadRejected"]>) => () => void;
+        onCacheHit: (fn: NonNullable<TenacePlugin["onCacheHit"]>) => () => void;
+        onCacheMiss: (fn: NonNullable<TenacePlugin["onCacheMiss"]>) => () => void;
+        onRateLimitRejected: (fn: NonNullable<TenacePlugin["onRateLimitRejected"]>) => () => void;
+        onFallback: (fn: NonNullable<TenacePlugin["onFallback"]>) => () => void;
+        onLockAcquired: (fn: NonNullable<TenacePlugin["onLockAcquired"]>) => () => void;
+        onLockRejected: (fn: NonNullable<TenacePlugin["onLockRejected"]>) => () => void;
+    };
+};