@julr/tenace 1.0.0-next.0

package/build/src/adapters/cache/memory.d.ts

@@ -0,0 +1,23 @@
+import type { CacheAdapter } from './types.ts';
+/**
+ * In-memory cache adapter using Bentocache.
+ */
+export declare class MemoryCacheAdapter implements CacheAdapter {
+    #private;
+    constructor(options?: {
+        maxSize?: string;
+        maxItems?: number;
+    });
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Disconnect from cache
+     */
+    disconnect(): Promise<void>;
+}

package/build/src/adapters/cache/memory.js

@@ -0,0 +1,2 @@
+import { t as MemoryCacheAdapter } from "../../memory-DWyezb1O.js";
+export { MemoryCacheAdapter };

package/build/src/adapters/cache/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Interface for cache adapters.
+ * Implement this to create custom cache backends (Redis, Memcached, etc.)
+ */
+export interface CacheAdapter {
+    /**
+     * Get a value from cache
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in cache with TTL
+     */
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Options for cache behavior
+ */
+export interface CacheOptions {
+    /**
+     * Custom cache adapter (uses default if not provided)
+     */
+    adapter?: CacheAdapter;
+    /**
+     * Cache key (required)
+     */
+    key: string;
+    /**
+     * Time to live in milliseconds
+     */
+    ttl: number;
+    /**
+     * If true, continue without cache when adapter fails (Redis down, etc.)
+     * @default false
+     */
+    optional?: boolean;
+    /**
+     * Called on cache hit
+     */
+    onHit?: (event: {
+        key: string;
+    }) => void;
+    /**
+     * Called on cache miss
+     */
+    onMiss?: (event: {
+        key: string;
+    }) => void;
+}

package/build/src/adapters/cache/types.js

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

package/build/src/adapters/lock/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Result of a lock acquisition attempt
+ */
+export interface LockAcquireResult {
+    /**
+     * Whether the lock was successfully acquired
+     */
+    acquired: boolean;
+}
+/**
+ * Options for acquiring a lock
+ */
+export interface LockAcquireOptions {
+    /**
+     * Retry policy for acquiring the lock
+     */
+    retry?: {
+        /**
+         * Maximum number of retry attempts (default: 0 - no retry)
+         */
+        attempts?: number;
+        /**
+         * Delay between retries in milliseconds (default: 250)
+         */
+        delay?: number;
+        /**
+         * Maximum time to wait before giving up in milliseconds
+         */
+        timeout?: number;
+    };
+}
+/**
+ * Adapter interface for distributed locks.
+ * Implementations can use Redis, PostgreSQL, or any other backend.
+ *
+ * @example
+ * ```ts
+ * // Using with Verrou
+ * import { Verrou } from '@verrou/core'
+ *
+ * class VerrouLockAdapter implements LockAdapter {
+ *   #verrou: Verrou
+ *
+ *   constructor(verrou: Verrou) {
+ *     this.#verrou = verrou
+ *   }
+ *
+ *   async run<T>(key: string, ttl: number, fn: () => Promise<T>, options?: LockAcquireOptions): Promise<[boolean, T | undefined]> {
+ *     const lock = this.#verrou.createLock(key, ttl)
+ *     return lock.run(fn, { retry: options?.retry })
+ *   }
+ * }
+ * ```
+ */
+export interface LockAdapter {
+    /**
+     * Acquires a lock and executes the function.
+     * Returns a tuple with [acquired, result].
+     *
+     * @param key - The resource key to lock
+     * @param ttl - Time-to-live in milliseconds (lock auto-releases after this duration)
+     * @param fn - The function to execute while holding the lock
+     * @param options - Options for acquiring the lock
+     * @returns A tuple of [wasAcquired, result]
+     */
+    run<T>(key: string, ttl: number, fn: () => Promise<T>, options?: LockAcquireOptions): Promise<[boolean, T | undefined]>;
+}
+/**
+ * Options for distributed lock
+ */
+export interface DistributedLockOptions {
+    /**
+     * The resource key to lock
+     */
+    key: string;
+    /**
+     * Time-to-live in milliseconds. Lock auto-releases after this duration.
+     * This prevents deadlocks if the process crashes.
+     */
+    ttl: number;
+    /**
+     * The lock adapter to use.
+     * Unlike cache and rate limiter, there is no built-in adapter.
+     * You must provide an adapter (e.g., from @verrou/core) either here
+     * or globally via configStore.configure({ lock: adapter }).
+     */
+    adapter?: LockAdapter;
+    /**
+     * Retry policy for acquiring the lock
+     */
+    retry?: LockAcquireOptions['retry'];
+    /**
+     * Called when lock is successfully acquired
+     */
+    onAcquired?: (event: {
+        key: string;
+    }) => void;
+    /**
+     * Called when lock acquisition fails
+     */
+    onRejected?: (event: {
+        key: string;
+    }) => void;
+}

package/build/src/adapters/lock/types.js

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

package/build/src/adapters/rate_limiter/memory.d.ts

@@ -0,0 +1,14 @@
+import type { RateLimiterAdapter, RateLimitConfig, RateLimitResult, RateLimitState } from './types.ts';
+/**
+ * In-memory rate limiter adapter using rate-limiter-flexible.
+ */
+export declare class MemoryRateLimiterAdapter implements RateLimiterAdapter {
+    #private;
+    acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult>;
+    getState(key: string): Promise<RateLimitState>;
+    reset(key: string): Promise<void>;
+    /**
+     * Clear all rate limit state
+     */
+    clear(): void;
+}

package/build/src/adapters/rate_limiter/memory.js

@@ -0,0 +1,2 @@
+import { t as MemoryRateLimiterAdapter } from "../../memory-DXkg8s6y.js";
+export { MemoryRateLimiterAdapter };

package/build/src/adapters/rate_limiter/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Interface for rate limiter adapters.
+ * Implement this to create distributed rate limiters (Redis, etc.)
+ */
+export interface RateLimiterAdapter {
+    /**
+     * Try to acquire a permit. Returns true if allowed, false if rate limited.
+     */
+    acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult>;
+    /**
+     * Get current state for a key
+     */
+    getState(key: string): Promise<RateLimitState>;
+    /**
+     * Reset the rate limiter for a key
+     */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /**
+     * Maximum number of calls allowed in the window
+     */
+    maxCalls: number;
+    /**
+     * Time window in milliseconds
+     */
+    windowMs: number;
+    /**
+     * Strategy for rate limiting
+     * - fixed-window: Simple counter that resets at window boundaries
+     * - sliding-window: Smoother rate limiting with sliding time window
+     * @default 'sliding-window'
+     */
+    strategy?: 'fixed-window' | 'sliding-window';
+}
+/**
+ * Result of a rate limit check
+ */
+export interface RateLimitResult {
+    /**
+     * Whether the request is allowed
+     */
+    allowed: boolean;
+    /**
+     * Number of remaining calls in current window
+     */
+    remaining: number;
+    /**
+     * Time in ms until the rate limit resets
+     */
+    resetInMs: number;
+    /**
+     * If not allowed, time in ms to wait before retrying
+     */
+    retryAfterMs?: number;
+}
+/**
+ * Current state of a rate limiter
+ */
+export interface RateLimitState {
+    /**
+     * Number of calls made in current window
+     */
+    calls: number;
+    /**
+     * Number of remaining calls
+     */
+    remaining: number;
+    /**
+     * Time in ms until reset
+     */
+    resetInMs: number;
+}
+/**
+ * Options for rate limiting behavior
+ */
+export interface RateLimitOptions extends RateLimitConfig {
+    /**
+     * Custom rate limiter adapter (uses default if not provided)
+     */
+    adapter?: RateLimiterAdapter;
+    /**
+     * Key to identify the rate limit bucket
+     */
+    key: string;
+    /**
+     * If true, continue without rate limiting when adapter fails (Redis down, etc.)
+     * @default false
+     */
+    optional?: boolean;
+    /**
+     * Called when rate limit is exceeded
+     */
+    onRejected?: (event: {
+        key: string;
+        retryAfterMs?: number;
+    }) => void;
+}

package/build/src/adapters/rate_limiter/types.js

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

package/build/src/backoff.d.ts

@@ -0,0 +1,79 @@
+import type { ExponentialBackoffOptions, ExponentialJitterBackoffOptions, LinearBackoffOptions } from './types/backoff.ts';
+import { type Duration, type RetryDelayFunction } from './types/types.ts';
+/**
+ * Backoff strategies for retry delays.
+ *
+ * @example
+ * ```ts
+ * import { backoff, tenace } from '@julr/tenace'
+ *
+ * // Constant delay
+ * tenace()
+ *   .withRetry({ times: 3, delay: backoff.constant('1s') })
+ *   .execute(fn)
+ *
+ * // Exponential backoff
+ * tenace()
+ *   .withRetry({ times: 5, delay: backoff.exponential({ initial: 100, max: 30_000 }) })
+ *   .execute(fn)
+ *
+ * // Exponential with jitter (prevents thundering herd)
+ * tenace()
+ *   .withRetry({ times: 5, delay: backoff.exponentialWithJitter({ initial: 100, max: 30_000 }) })
+ *   .execute(fn)
+ * ```
+ */
+export declare const backoff: {
+    /**
+     * Constant delay between retries.
+     *
+     * @example
+     * backoff.constant(1000)
+     * backoff.constant('1s')
+     */
+    constant(delay: Duration): RetryDelayFunction;
+    /**
+     * Exponential backoff: initial * exponent^attempt
+     * Delay doubles (by default) with each attempt, capped at max.
+     *
+     * @example
+     * // 100ms, 200ms, 400ms, 800ms, 1600ms...
+     * backoff.exponential({ initial: 100 })
+     *
+     * // With custom max
+     * backoff.exponential({ initial: 100, max: 10_000 })
+     *
+     * // With custom exponent (triple each time)
+     * backoff.exponential({ initial: 100, exponent: 3 })
+     */
+    exponential(options?: ExponentialBackoffOptions): RetryDelayFunction;
+    /**
+     * Exponential backoff with jitter to prevent thundering herd.
+     *
+     * Jitter strategies:
+     * - 'full': Random delay between 0 and calculated exponential delay
+     * - 'decorrelated': AWS-style decorrelated jitter (recommended)
+     *
+     * @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+     *
+     * @example
+     * // Full jitter (random between 0 and exponential delay)
+     * backoff.exponentialWithJitter({ initial: 100, max: 30_000 })
+     *
+     * // Decorrelated jitter (better distribution)
+     * backoff.exponentialWithJitter({ initial: 100, max: 30_000, jitter: 'decorrelated' })
+     */
+    exponentialWithJitter(options?: ExponentialJitterBackoffOptions): RetryDelayFunction;
+    /**
+     * Linear backoff: initial + (step * attempt)
+     * Delay increases linearly with each attempt, capped at max.
+     *
+     * @example
+     * // 100ms, 200ms, 300ms, 400ms...
+     * backoff.linear({ initial: 100, step: 100 })
+     *
+     * // With max cap
+     * backoff.linear({ initial: 100, step: 500, max: 5_000 })
+     */
+    linear(options?: LinearBackoffOptions): RetryDelayFunction;
+};

package/build/src/chaos/manager.d.ts

@@ -0,0 +1,29 @@
+import type { GlobalChaosConfig, NormalizedGlobalChaosConfig } from './types.ts';
+/**
+ * Manages global chaos configuration.
+ * Singleton that can be enabled/disabled to affect all Tenace calls.
+ */
+declare class ChaosManager {
+    #private;
+    /**
+     * Enable global chaos with the given configuration.
+     * 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
+     */
+    disable(): void;
+    /**
+     * Check if global chaos is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the normalized global chaos config
+     */
+    getConfig(): NormalizedGlobalChaosConfig | null;
+}
+export declare const chaosManager: ChaosManager;
+export {};

package/build/src/chaos/policies.d.ts

@@ -0,0 +1,10 @@
+import type { IPolicy } from 'cockatiel';
+import type { NormalizedChaosFaultConfig, NormalizedChaosLatencyConfig } from './types.ts';
+/**
+ * Creates a chaos fault policy that randomly throws errors
+ */
+export declare function createChaosFaultPolicy(config: NormalizedChaosFaultConfig): IPolicy;
+/**
+ * Creates a chaos latency policy that adds random delays
+ */
+export declare function createChaosLatencyPolicy(config: NormalizedChaosLatencyConfig): IPolicy;

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

@@ -0,0 +1,75 @@
+/**
+ * Configuration for chaos fault injection
+ */
+export interface ChaosFaultConfig {
+    /**
+     * Injection rate (0-1). 1 means 100% of calls will throw an error.
+     */
+    rate: number;
+    /**
+     * Error to throw. Defaults to Error('Chaos fault') if not specified.
+     */
+    error?: Error;
+    /**
+     * Multiple errors to randomly pick from
+     */
+    errors?: Error[];
+}
+/**
+ * Configuration for chaos latency injection
+ */
+export interface ChaosLatencyConfig {
+    /**
+     * Injection rate (0-1). 1 means 100% of calls will have latency added.
+     */
+    rate: number;
+    /**
+     * Delay in milliseconds, or a range { min, max } for random delay
+     */
+    delay: number | {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Normalized chaos fault config (always has rate and error/errors)
+ */
+export interface NormalizedChaosFaultConfig {
+    rate: number;
+    error?: Error;
+    errors?: Error[];
+}
+/**
+ * Normalized chaos latency config (always has rate and delay object)
+ */
+export interface NormalizedChaosLatencyConfig {
+    rate: number;
+    delay: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Global chaos configuration with shorthand support
+ */
+export interface GlobalChaosConfig {
+    /**
+     * Fault injection config.
+     * - number: injection rate (0-1) with default error
+     * - ChaosFaultConfig: full configuration
+     */
+    fault?: ChaosFaultConfig | number;
+    /**
+     * Latency injection config.
+     * - number: fixed delay in ms with rate=1
+     * - ChaosLatencyConfig: full configuration
+     */
+    latency?: ChaosLatencyConfig | number;
+}
+/**
+ * Normalized global chaos config (after shorthand expansion)
+ */
+export interface NormalizedGlobalChaosConfig {
+    fault?: NormalizedChaosFaultConfig;
+    latency?: NormalizedChaosLatencyConfig;
+}

package/build/src/collection.d.ts

@@ -0,0 +1,81 @@
+import type { SettledResult, TaskProgress, TaskRetryOptions } from './types/main.ts';
+import { type Duration } from './types/types.ts';
+/**
+ * Builder for executing collections of async tasks with concurrency control
+ * and per-task tenace policies.
+ *
+ * @example
+ * ```ts
+ * // Execute tasks with limited concurrency
+ * const results = await Tenace.all([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3),
+ * ])
+ *   .withConcurrency(2)
+ *   .withRetryPerTask(3)
+ *   .execute()
+ *
+ * // Map over items
+ * const users = await Tenace.map([1, 2, 3], (id) => fetchUser(id))
+ *   .withConcurrency(5)
+ *   .execute()
+ *
+ * // Get all results (success and failures)
+ * const settled = await Tenace.all(tasks)
+ *   .withConcurrency(5)
+ *   .settle()
+ * ```
+ */
+export declare class CollectionBuilder<T> {
+    #private;
+    constructor(tasks: Array<() => Promise<T>>);
+    /**
+     * Set the maximum number of concurrent tasks.
+     * Default is Infinity (no limit).
+     */
+    withConcurrency(limit: number): this;
+    /**
+     * Add retry logic to each task individually.
+     * Each task will be retried up to `attempts` times on failure.
+     */
+    withRetryPerTask(attempts: number, options?: TaskRetryOptions): this;
+    /**
+     * Add timeout to each task individually.
+     */
+    withTimeoutPerTask(duration: Duration, strategy?: 'aggressive' | 'cooperative'): this;
+    /**
+     * Whether to stop execution when a task fails.
+     * Default is true (stop on first error).
+     * Set to false to continue executing remaining tasks.
+     */
+    stopOnError(stop: boolean): this;
+    /**
+     * Provide an AbortSignal to cancel all pending tasks.
+     */
+    withSignal(signal: AbortSignal): this;
+    /**
+     * Callback when a task completes successfully.
+     */
+    onTaskComplete(callback: (value: T, progress: TaskProgress) => void): this;
+    /**
+     * Callback when a task fails (after all retries).
+     */
+    onTaskError(callback: (error: Error, progress: TaskProgress) => void): this;
+    /**
+     * Callback for progress updates (called after each task completes or fails).
+     */
+    onProgress(callback: (progress: TaskProgress) => void): this;
+    /**
+     * Execute all tasks and return results.
+     * Throws on first error by default (unless stopOnError(false) is set).
+     * Results are in the same order as input tasks.
+     */
+    execute(): Promise<T[]>;
+    /**
+     * Execute all tasks and return settled results (never throws).
+     * Each result indicates success or failure with the value/error.
+     * Results are in the same order as input tasks.
+     */
+    settle(): Promise<SettledResult<T>[]>;
+}

package/build/src/config.d.ts

@@ -0,0 +1,38 @@
+import type { RateLimiterAdapter } from './adapters/rate_limiter/types.ts';
+import type { LockAdapter } from './adapters/lock/types.ts';
+import type { CacheAdapter } from './adapters/cache/types.ts';
+/**
+ * Global configuration for Tenace
+ */
+export interface TenaceConfig {
+    /**
+     * Default cache adapter
+     */
+    cache?: CacheAdapter;
+    /**
+     * Default rate limiter adapter
+     */
+    rateLimiter?: RateLimiterAdapter;
+    /**
+     * Default lock adapter for distributed locks.
+     * Unlike cache and rate limiter, there is no built-in memory adapter.
+     * You must provide an adapter (e.g., from @verrou/core).
+     */
+    lock?: LockAdapter;
+}
+/**
+ * Internal configuration state
+ */
+declare class ConfigStore {
+    #private;
+    configure(config: TenaceConfig): void;
+    getCache(): CacheAdapter;
+    getRateLimiter(): RateLimiterAdapter;
+    getLock(): LockAdapter | undefined;
+    /**
+     * Reset configuration (useful for testing)
+     */
+    reset(): void;
+}
+export declare const configStore: ConfigStore;
+export {};