@julr/tenace 1.0.0-next.0

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

@@ -0,0 +1,241 @@
+/**
+ * Duration can be specified as milliseconds (number) or as a string like '5s', '1m', '500ms'
+ */
+export type Duration = string | number;
+/**
+ * Parse a duration value to milliseconds
+ */
+export declare function parseDuration(duration: Duration): number;
+/**
+ * Context passed to the function being executed
+ */
+export interface TenaceContext {
+    signal: AbortSignal;
+    /**
+     * Current attempt number (starts at 0, increments on each retry)
+     */
+    attempt: number;
+}
+/**
+ * Function that can be executed with resilience patterns
+ */
+export type TenaceFunction<T> = (context: TenaceContext) => T | Promise<T>;
+/**
+ * Delay function for retry - receives attempt number (starting at 1) and the error, returns delay in ms
+ */
+export type RetryDelayFunction = (attempt: number, error: Error) => number;
+/**
+ * Event passed to retry hooks
+ */
+export interface RetryEvent {
+    attempt: number;
+    delay: number;
+    error: Error;
+}
+/**
+ * Configuration for retry behavior
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    times?: number;
+    /**
+     * Delay between retries in ms, or a function that returns the delay.
+     * Can be a number, a string duration ('1s', '500ms'), or a function.
+     * The function receives the attempt number (starting at 1) and the error.
+     *
+     * @example
+     * // Fixed delay (number)
+     * delay: 1000
+     *
+     * @example
+     * // Fixed delay (string)
+     * delay: '1s'
+     *
+     * @example
+     * // Exponential backoff
+     * delay: (attempt) => Math.min(1000 * 2 ** attempt, 30000)
+     *
+     * @example
+     * // Dynamic delay based on error (e.g., retry-after header)
+     * delay: (attempt, error) => error instanceof RateLimitError ? error.retryAfter : 1000
+     */
+    delay?: Duration | RetryDelayFunction;
+    /**
+     * Only retry if this function returns true
+     */
+    retryIf?: (error: Error) => boolean;
+    /**
+     * Abort retrying if this function returns true
+     */
+    abortIf?: (error: Error) => boolean;
+    /**
+     * Called when a retry is triggered
+     */
+    onRetry?: (event: RetryEvent) => void;
+    /**
+     * Called when all retries are exhausted
+     */
+    onRetryExhausted?: (event: {
+        error: Error;
+    }) => void;
+}
+/**
+ * Hooks for circuit breaker events
+ */
+export interface CircuitBreakerHooks {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onHalfOpen?: () => void;
+    onStateChange?: (state: 'open' | 'closed' | 'half-open') => void;
+}
+/**
+ * Configuration for circuit breaker
+ */
+export interface CircuitBreakerConfig {
+    halfOpenAfterMs: number;
+    breaker: BreakerConfig;
+    hooks?: CircuitBreakerHooks;
+}
+/**
+ * Breaker strategy configuration
+ */
+export type BreakerConfig = {
+    kind: 'consecutive';
+    threshold: number;
+} | {
+    kind: 'count';
+    threshold: number;
+    size: number;
+    minimumNumberOfCalls?: number;
+} | {
+    kind: 'sampling';
+    threshold: number;
+    durationMs: number;
+    minimumRps?: number;
+};
+/**
+ * Configuration for OpenTelemetry span
+ */
+export interface SpanConfig {
+    name: string;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Timeout strategy
+ */
+export type TimeoutStrategy = 'aggressive' | 'cooperative';
+/**
+ * Circuit breaker state
+ */
+export type CircuitState = 'open' | 'closed' | 'half-open';
+/**
+ * Handle returned by circuit breaker isolation.
+ * Call dispose() to release the isolation.
+ */
+export interface IsolationHandle {
+    dispose(): void;
+}
+/**
+ * Accessor for circuit breaker state and control.
+ * Allows querying state, manual isolation, and reset.
+ */
+export interface CircuitBreakerAccessor {
+    /**
+     * Current state of the circuit breaker
+     */
+    readonly state: CircuitState;
+    /**
+     * Whether the circuit is currently open (failing fast)
+     */
+    readonly isOpen: boolean;
+    /**
+     * Whether the circuit is currently closed (allowing requests)
+     */
+    readonly isClosed: boolean;
+    /**
+     * Whether the circuit is currently half-open (testing recovery)
+     */
+    readonly isHalfOpen: boolean;
+    /**
+     * Manually isolate (force open) the circuit breaker.
+     * All calls will fail with CircuitIsolatedError until disposed.
+     * Returns a handle that must be disposed to release isolation.
+     *
+     * @example
+     * ```ts
+     * const handle = policy.circuitBreaker.isolate()
+     * // ... circuit is now forced open
+     * handle.dispose() // release isolation
+     * ```
+     */
+    isolate(): IsolationHandle;
+}
+/**
+ * Types of policy layers that can be added to the resilience pipeline
+ */
+export type PolicyLayerType = 'timeout' | 'retry' | 'circuitBreaker' | 'bulkhead' | 'fallback' | 'span' | 'cache' | 'rateLimit' | 'distributedLock' | 'chaosFault' | 'chaosLatency';
+/**
+ * Configuration for timeout layer
+ */
+export interface TimeoutLayerConfig {
+    durationMs: number;
+    strategy: 'aggressive' | 'cooperative';
+    onTimeout?: () => void;
+}
+/**
+ * Configuration for bulkhead layer
+ */
+export interface BulkheadLayerConfig {
+    limit: number;
+    queue?: number;
+    onRejected?: () => void;
+}
+/**
+ * Configuration for fallback layer
+ */
+export interface FallbackLayerConfig<T> {
+    fn: () => T | Promise<T>;
+    onFallback?: () => void;
+}
+/**
+ * A layer in the resilience policy stack.
+ * Layers are executed in order (first added = outermost).
+ */
+export interface PolicyLayer {
+    type: PolicyLayerType;
+    config: unknown;
+    /**
+     * Pre-created cockatiel policy instance (used for shared CB/Bulkhead in ResiliencePolicy)
+     */
+    instance?: unknown;
+}
+/**
+ * Options for waitFor polling
+ */
+export interface WaitForOptions {
+    /**
+     * Interval between checks (default: 100ms)
+     */
+    interval?: Duration;
+    /**
+     * Maximum time to wait before throwing WaitForTimeoutError (default: 10s)
+     */
+    timeout?: Duration;
+    /**
+     * Custom message for timeout error
+     */
+    message?: string;
+    /**
+     * Whether to run the check immediately rather than starting by waiting `interval` milliseconds.
+     * Useful for when the check, if run immediately, would likely return `false`.
+     * In this scenario, set `before` to `false`.
+     * (default: true)
+     */
+    before?: boolean;
+    /**
+     * An AbortSignal to cancel the wait operation
+     */
+    signal?: AbortSignal;
+}

package/build/src/wait_for.d.ts

@@ -0,0 +1,23 @@
+import { type WaitForOptions } from './types/types.ts';
+/**
+ * Wait for a condition to become true by polling at regular intervals.
+ *
+ * @example
+ * ```ts
+ * // Wait for a service to be healthy
+ * await waitFor(() => isServiceHealthy(), {
+ *   interval: '1s',
+ *   timeout: '30s',
+ * })
+ *
+ * // Wait for a resource with custom message
+ * await waitFor(
+ *   async () => {
+ *     const status = await checkDatabase()
+ *     return status === 'ready'
+ *   },
+ *   { timeout: '1m', message: 'Database did not become ready' }
+ * )
+ * ```
+ */
+export declare function waitFor(condition: () => boolean | Promise<boolean>, options?: WaitForOptions): Promise<void>;

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "@julr/tenace",
+  "type": "module",
+  "version": "1.0.0-next.0",
+  "packageManager": "pnpm@10.24.0",
+  "description": "A Node.js library to make any call resilient with a fluent and simple API",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "license": "MIT",
+  "keywords": [
+    "resilience",
+    "tenace",
+    "retry",
+    "timeout",
+    "circuit-breaker",
+    "backoff",
+    "fault-tolerance"
+  ],
+  "exports": {
+    ".": "./build/src/main.js",
+    "./types": "./build/src/types/main.js",
+    "./errors": "./build/src/errors/main.js",
+    "./adapters/cache/types": "./build/src/adapters/cache/types.js",
+    "./adapters/cache/memory": "./build/src/adapters/cache/memory.js",
+    "./adapters/rate-limiter/types": "./build/src/adapters/rate_limiter/types.js",
+    "./adapters/rate-limiter/memory": "./build/src/adapters/rate_limiter/memory.js",
+    "./adapters/lock/types": "./build/src/adapters/lock/types.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests",
+    "!build/examples"
+  ],
+  "scripts": {
+    "clean": "del-cli build",
+    "typecheck": "tsc --noEmit",
+    "precompile": "pnpm lint && pnpm clean",
+    "compile": "tsdown && tsc --emitDeclarationOnly --declaration",
+    "build": "pnpm compile",
+    "test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "format": "oxfmt",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "checks": "pnpm typecheck && pnpm test && pnpm lint",
+    "release": "release-it",
+    "version": "pnpm build",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "prettier": "@julr/tooling-configs/prettier",
+  "dependencies": {
+    "@julr/utils": "^1.9.0",
+    "bentocache": "^1.5.0",
+    "cockatiel": "^3.2.1",
+    "p-wait-for": "^6.0.0",
+    "rate-limiter-flexible": "^9.0.0"
+  },
+  "devDependencies": {
+    "@japa/assert": "^4.1.1",
+    "@japa/runner": "^4.4.0",
+    "@julr/tooling-configs": "^3.3.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@poppinss/ts-exec": "^1.4.1",
+    "@release-it/conventional-changelog": "^10.0.3",
+    "@types/node": "^24.10.1",
+    "@verrou/core": "^0.5.2",
+    "del-cli": "^7.0.0",
+    "neverthrow": "^8.2.0",
+    "oxfmt": "^0.17.0",
+    "oxlint": "^1.32.0",
+    "oxlint-tsgolint": "^0.9.0",
+    "release-it": "^19.1.0",
+    "tsdown": "^0.17.4",
+    "typescript": "^5.9.3"
+  },
+  "tsdown": {
+    "entry": [
+      "./src/main.ts",
+      "./src/types/main.ts",
+      "./src/errors/main.ts",
+      "./src/adapters/cache/types.ts",
+      "./src/adapters/cache/memory.ts",
+      "./src/adapters/rate_limiter/types.ts",
+      "./src/adapters/rate_limiter/memory.ts",
+      "./src/adapters/lock/types.ts"
+    ],
+    "outDir": "./build/src",
+    "clean": true,
+    "format": "esm",
+    "minify": "dce-only",
+    "fixedExtension": false,
+    "dts": false,
+    "treeshake": false,
+    "sourcemaps": false,
+    "target": "esnext"
+  },
+  "release-it": {
+    "git": {
+      "requireCleanWorkingDir": true,
+      "requireUpstream": true,
+      "commitMessage": "chore(release): ${version}",
+      "tagAnnotation": "v${version}",
+      "push": true,
+      "tagName": "v${version}"
+    },
+    "github": {
+      "release": true
+    },
+    "npm": {
+      "publish": true,
+      "skipChecks": true,
+      "tag": "beta"
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}