resilient-exec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GBB26
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# resilient-exec
+
+A tiny, deterministic utility for executing async functions with
+**retries, backoff, timeouts, abort signals, and fallbacks** --- without
+hidden magic.
+
+Built for Node.js & TypeScript. Works with both ESM and CommonJS.
+
+---
+
+## ✨ Features
+
+- ✅ Deterministic retries
+- ✅ Configurable backoff strategies (fixed, exponential, fibonacci,
+  custom)
+- ✅ Per-attempt timeouts
+- ✅ AbortSignal support
+- ✅ Fallback execution
+- ✅ Strong TypeScript typings
+- ✅ Works with ESM & CommonJS
+
+---
+
+## 📦 Install
+
+```bash
+npm install resilient-exec
+```
+
+---
+
+## 🚀 Basic Usage
+
+```ts
+import { attempt } from "resilient-exec";
+
+const result = await attempt(async () => {
+  return "hello";
+});
+
+if (result.ok) {
+  console.log("Success:", result.value);
+} else {
+  console.error("Failed:", result.error);
+}
+```
+
+---
+
+## 🔁 Retry
+
+```ts
+await attempt(
+  async () => {
+    return fetchData();
+  },
+  {
+    retry: { retries: 3 },
+  },
+);
+```
+
+---
+
+## ⏱ Timeout
+
+```ts
+await attempt(
+  async () => {
+    return slowTask();
+  },
+  {
+    timeout: 500, // milliseconds
+  },
+);
+```
+
+---
+
+## 🧯 Fallback
+
+```ts
+await attempt(primaryTask, {
+  retry: { retries: 2 },
+  fallback: async () => {
+    return "fallback-result";
+  },
+});
+```
+
+---
+
+## 🛑 Abort
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 100);
+
+const result = await attempt(
+  async () => {
+    return longRunningTask();
+  },
+  {
+    signal: controller.signal,
+  },
+);
+
+if (result.cancelled) {
+  console.log("Execution was cancelled");
+}
+```
+
+---
+
+## 🧠 Backoff Strategies
+
+### Fixed Backoff
+
+```ts
+await attempt(fn, {
+  retry: { retries: 3 },
+  backoff: { type: "fixed", delay: 200 },
+});
+```
+
+### Exponential Backoff
+
+```ts
+await attempt(fn, {
+  retry: { retries: 3 },
+  backoff: { type: "exponential", base: 100, max: 2000 },
+});
+```
+
+### Fibonacci Backoff
+
+```ts
+await attempt(fn, {
+  retry: { retries: 3 },
+  backoff: { type: "fibonacci", base: 100 },
+});
+```
+
+### Custom Backoff
+
+```ts
+await attempt(fn, {
+  retry: { retries: 3 },
+  backoff: {
+    type: "custom",
+    getDelay: (attempt) => attempt * 150,
+  },
+});
+```
+
+---
+
+## 📚 API
+
+### `attempt(fn, options?)`
+
+Executes the provided function with retry, timeout, abort, and fallback
+logic.
+
+#### Return Type
+
+```ts
+type AttemptResult<T> =
+  | {
+      ok: true;
+      value: T;
+      attempts: number;
+      usedFallback: boolean;
+      duration: number;
+    }
+  | {
+      ok: false;
+      error?: unknown;
+      attempts: number;
+      usedFallback: boolean;
+      cancelled?: boolean;
+      duration: number;
+    };
+```
+
+#### Options
+
+```ts
+type AttemptOptions = {
+  retry?: {
+    retries: number;
+    retryIf?: (error: unknown) => boolean;
+  };
+  backoff?: {
+    type: "fixed" | "exponential" | "fibonacci" | "custom";
+    delay?: number;
+    base?: number;
+    max?: number;
+    getDelay?: (attempt: number) => number;
+  };
+  timeout?: number;
+  fallback?: () => Promise<unknown> | unknown;
+  signal?: AbortSignal;
+  throwOnFail?: boolean;
+};
+```
+
+---
+
+## 🎯 Design Philosophy
+
+- No hidden retries
+- No global state
+- No monkey-patching
+- Explicit behavior
+- Predictable control flow
+- Works with real-world async edge cases
+
+---
+
+## 🧪 Testing
+
+This package is fully covered by:
+
+- Unit tests
+- Integration tests
+- Timeout & abort edge cases
+
+---
+
+## 📄 License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,382 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  attempt: () => attempt
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context/ExecutionContext.ts
+var ExecutionContext = class {
+  constructor() {
+    /** Total number of execution attempts (primary + retries) */
+    this.attemptCount = 0;
+    /** Number of retries performed */
+    this.retryCount = 0;
+    /** Index of the current fallback being executed */
+    this.fallbackIndex = 0;
+    /** Whether a fallback was used */
+    this.usedFallback = false;
+    /** Whether execution was cancelled */
+    this.cancelled = false;
+    /** Last encountered error */
+    this.lastError = null;
+    this.startTime = Date.now();
+  }
+  /** Mark that an execution attempt occurred */
+  recordAttempt() {
+    this.attemptCount++;
+  }
+  /** Mark that a retry occurred */
+  recordRetry() {
+    this.retryCount++;
+  }
+  /** Mark that fallback execution has started */
+  markFallbackUsed() {
+    this.usedFallback = true;
+  }
+  /** Mark execution as cancelled */
+  markCancelled() {
+    this.cancelled = true;
+  }
+  /** Store the last error */
+  setError(error) {
+    this.lastError = error;
+  }
+  /** Total execution duration in milliseconds */
+  get duration() {
+    return Date.now() - this.startTime;
+  }
+};
+
+// src/utils/timeout.ts
+async function withTimeout(fn, timeoutMs, signal) {
+  if (timeoutMs <= 0) {
+    return fn();
+  }
+  let timeoutId;
+  return Promise.race([
+    fn(),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(createTimeoutError(timeoutMs));
+      }, timeoutMs);
+      if (signal) {
+        signal.addEventListener(
+          "abort",
+          () => reject(createAbortError()),
+          { once: true }
+        );
+      }
+    })
+  ]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+function createTimeoutError(ms) {
+  const error = new Error(`Operation timed out after ${ms}ms`);
+  error.name = "TimeoutError";
+  return error;
+}
+function createAbortError() {
+  const error = new Error("Operation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+// src/utils/abort.ts
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.message.toLowerCase().includes("aborted"));
+}
+
+// src/engine/ExecutionEngine.ts
+var ExecutionEngine = class {
+  async execute(fn, context, options) {
+    if (options.signal?.aborted) {
+      context.markCancelled();
+      throw this.createAbortError();
+    }
+    context.recordAttempt();
+    try {
+      const result = await withTimeout(
+        () => Promise.resolve().then(fn),
+        options.timeout ?? 0,
+        options.signal
+      );
+      return result;
+    } catch (error) {
+      if (isAbortError(error)) {
+        context.markCancelled();
+      }
+      context.setError(error);
+      throw error;
+    }
+  }
+  createAbortError() {
+    const error = new Error("Operation aborted");
+    error.name = "AbortError";
+    return error;
+  }
+};
+
+// src/retry/RetryController.ts
+var RetryController = class {
+  constructor(options) {
+    this.retries = options?.retries ?? 0;
+    this.retryIf = options?.retryIf ?? (() => true);
+  }
+  /**
+   * Decide whether a retry should be attempted
+   */
+  shouldRetry(error, context) {
+    if (context.cancelled) {
+      return false;
+    }
+    if (context.retryCount >= this.retries) {
+      return false;
+    }
+    if (this.retryIf && !this.retryIf(error)) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Record that a retry is happening
+   */
+  recordRetry(context) {
+    context.recordRetry();
+  }
+};
+
+// src/retry/BackoffCalculator.ts
+var BackoffCalculator = class {
+  constructor(strategy) {
+    this.strategy = strategy ?? null;
+  }
+  /**
+   * Calculate delay (in ms) before the next retry
+   */
+  getDelay(attempt2) {
+    if (!this.strategy) {
+      return 0;
+    }
+    switch (this.strategy.type) {
+      case "fixed":
+        return this.strategy.delay;
+      case "exponential": {
+        const delay2 = this.strategy.base * Math.pow(2, attempt2);
+        return this.strategy.max ? Math.min(delay2, this.strategy.max) : delay2;
+      }
+      case "fibonacci":
+        return this.fibonacciDelay(this.strategy.base, attempt2);
+      case "custom":
+        return Math.max(0, this.strategy.getDelay(attempt2));
+      default:
+        return 0;
+    }
+  }
+  fibonacciDelay(base, attempt2) {
+    if (attempt2 <= 1) {
+      return base;
+    }
+    let prev = 0;
+    let curr = base;
+    for (let i = 2; i <= attempt2; i++) {
+      const next = prev + curr;
+      prev = curr;
+      curr = next;
+    }
+    return curr;
+  }
+};
+
+// src/fallback/FallbackController.ts
+var FallbackController = class {
+  constructor(fallback) {
+    if (!fallback) {
+      this.fallbacks = [];
+    } else if (Array.isArray(fallback)) {
+      this.fallbacks = fallback;
+    } else {
+      this.fallbacks = [fallback];
+    }
+  }
+  hasFallback() {
+    return this.fallbacks.length > 0;
+  }
+  /**
+   * Execute fallback operations sequentially.
+   * Stops at the first successful fallback.
+   */
+  async execute(engine, context, options) {
+    context.markFallbackUsed();
+    for (let i = 0; i < this.fallbacks.length; i++) {
+      context.fallbackIndex = i;
+      try {
+        const result = await engine.execute(
+          this.fallbacks[i],
+          context,
+          options
+        );
+        return result;
+      } catch (error) {
+        context.setError(error);
+        if (context.cancelled) {
+          throw error;
+        }
+      }
+    }
+    throw context.lastError;
+  }
+};
+
+// src/result/ResultAggregator.ts
+var ResultAggregator = class {
+  buildSuccess(value, context) {
+    return {
+      ok: true,
+      value,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration
+    };
+  }
+  buildFailure(error, context) {
+    return {
+      ok: false,
+      error,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration,
+      cancelled: context.cancelled
+    };
+  }
+  buildCancelled(context) {
+    return {
+      ok: false,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration,
+      cancelled: true
+    };
+  }
+  finalize(result, throwOnFail) {
+    if (!result.ok && throwOnFail) {
+      throw result.error;
+    }
+    return result;
+  }
+};
+
+// src/utils/delay.ts
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(createAbortError2());
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      cleanup();
+      reject(createAbortError2());
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort);
+    }
+  });
+}
+function createAbortError2() {
+  const error = new Error("Operation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+// src/attempt.ts
+async function attempt(fn, options = {}) {
+  const context = new ExecutionContext();
+  const engine = new ExecutionEngine();
+  const retryController = new RetryController(options.retry);
+  const backoffCalculator = new BackoffCalculator(options.backoff);
+  const fallbackController = new FallbackController(options.fallback);
+  const resultAggregator = new ResultAggregator();
+  const execOptions = {};
+  if (options.timeout !== void 0) execOptions.timeout = options.timeout;
+  if (options.signal !== void 0) execOptions.signal = options.signal;
+  try {
+    while (true) {
+      try {
+        const value = await engine.execute(fn, context, execOptions);
+        return resultAggregator.finalize(
+          resultAggregator.buildSuccess(value, context),
+          options.throwOnFail
+        );
+      } catch (error) {
+        context.setError(error);
+        if (retryController.shouldRetry(error, context)) {
+          retryController.recordRetry(context);
+          const waitTime = backoffCalculator.getDelay(context.retryCount);
+          if (waitTime > 0) {
+            await delay(waitTime, options.signal);
+          }
+          continue;
+        }
+        break;
+      }
+    }
+    if (fallbackController.hasFallback()) {
+      const value = await fallbackController.execute(
+        engine,
+        context,
+        execOptions
+      );
+      return resultAggregator.finalize(
+        resultAggregator.buildSuccess(value, context),
+        options.throwOnFail
+      );
+    }
+    return resultAggregator.finalize(
+      resultAggregator.buildFailure(context.lastError, context),
+      options.throwOnFail
+    );
+  } catch (error) {
+    context.setError(error);
+    if (context.cancelled) {
+      return resultAggregator.finalize(
+        resultAggregator.buildCancelled(context),
+        options.throwOnFail
+      );
+    }
+    return resultAggregator.finalize(
+      resultAggregator.buildFailure(error, context),
+      options.throwOnFail
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attempt
+});

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+type AttemptFn<T = any> = () => T | Promise<T>;
+interface RetryOptions {
+    retries?: number;
+    retryIf?: (error: unknown) => boolean;
+}
+type BackoffStrategy = {
+    type: "fixed";
+    delay: number;
+} | {
+    type: "exponential";
+    base: number;
+    max?: number;
+} | {
+    type: "fibonacci";
+    base: number;
+} | {
+    type: "custom";
+    getDelay: (attempt: number) => number;
+};
+interface AttemptOptions {
+    retry?: RetryOptions;
+    backoff?: BackoffStrategy;
+    timeout?: number;
+    fallback?: AttemptFn | AttemptFn[];
+    signal?: AbortSignal;
+    throwOnFail?: boolean;
+}
+interface AttemptResult<T = any> {
+    ok: boolean;
+    value?: T;
+    error?: unknown;
+    attempts: number;
+    usedFallback: boolean;
+    duration: number;
+    cancelled?: boolean;
+}
+
+declare function attempt<T>(fn: AttemptFn<T>, options?: AttemptOptions): Promise<AttemptResult<unknown>>;
+
+export { type AttemptFn, type AttemptOptions, type AttemptResult, type BackoffStrategy, type RetryOptions, attempt };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+type AttemptFn<T = any> = () => T | Promise<T>;
+interface RetryOptions {
+    retries?: number;
+    retryIf?: (error: unknown) => boolean;
+}
+type BackoffStrategy = {
+    type: "fixed";
+    delay: number;
+} | {
+    type: "exponential";
+    base: number;
+    max?: number;
+} | {
+    type: "fibonacci";
+    base: number;
+} | {
+    type: "custom";
+    getDelay: (attempt: number) => number;
+};
+interface AttemptOptions {
+    retry?: RetryOptions;
+    backoff?: BackoffStrategy;
+    timeout?: number;
+    fallback?: AttemptFn | AttemptFn[];
+    signal?: AbortSignal;
+    throwOnFail?: boolean;
+}
+interface AttemptResult<T = any> {
+    ok: boolean;
+    value?: T;
+    error?: unknown;
+    attempts: number;
+    usedFallback: boolean;
+    duration: number;
+    cancelled?: boolean;
+}
+
+declare function attempt<T>(fn: AttemptFn<T>, options?: AttemptOptions): Promise<AttemptResult<unknown>>;
+
+export { type AttemptFn, type AttemptOptions, type AttemptResult, type BackoffStrategy, type RetryOptions, attempt };

package/dist/index.js

@@ -0,0 +1,355 @@
+// src/context/ExecutionContext.ts
+var ExecutionContext = class {
+  constructor() {
+    /** Total number of execution attempts (primary + retries) */
+    this.attemptCount = 0;
+    /** Number of retries performed */
+    this.retryCount = 0;
+    /** Index of the current fallback being executed */
+    this.fallbackIndex = 0;
+    /** Whether a fallback was used */
+    this.usedFallback = false;
+    /** Whether execution was cancelled */
+    this.cancelled = false;
+    /** Last encountered error */
+    this.lastError = null;
+    this.startTime = Date.now();
+  }
+  /** Mark that an execution attempt occurred */
+  recordAttempt() {
+    this.attemptCount++;
+  }
+  /** Mark that a retry occurred */
+  recordRetry() {
+    this.retryCount++;
+  }
+  /** Mark that fallback execution has started */
+  markFallbackUsed() {
+    this.usedFallback = true;
+  }
+  /** Mark execution as cancelled */
+  markCancelled() {
+    this.cancelled = true;
+  }
+  /** Store the last error */
+  setError(error) {
+    this.lastError = error;
+  }
+  /** Total execution duration in milliseconds */
+  get duration() {
+    return Date.now() - this.startTime;
+  }
+};
+
+// src/utils/timeout.ts
+async function withTimeout(fn, timeoutMs, signal) {
+  if (timeoutMs <= 0) {
+    return fn();
+  }
+  let timeoutId;
+  return Promise.race([
+    fn(),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(createTimeoutError(timeoutMs));
+      }, timeoutMs);
+      if (signal) {
+        signal.addEventListener(
+          "abort",
+          () => reject(createAbortError()),
+          { once: true }
+        );
+      }
+    })
+  ]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+function createTimeoutError(ms) {
+  const error = new Error(`Operation timed out after ${ms}ms`);
+  error.name = "TimeoutError";
+  return error;
+}
+function createAbortError() {
+  const error = new Error("Operation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+// src/utils/abort.ts
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.message.toLowerCase().includes("aborted"));
+}
+
+// src/engine/ExecutionEngine.ts
+var ExecutionEngine = class {
+  async execute(fn, context, options) {
+    if (options.signal?.aborted) {
+      context.markCancelled();
+      throw this.createAbortError();
+    }
+    context.recordAttempt();
+    try {
+      const result = await withTimeout(
+        () => Promise.resolve().then(fn),
+        options.timeout ?? 0,
+        options.signal
+      );
+      return result;
+    } catch (error) {
+      if (isAbortError(error)) {
+        context.markCancelled();
+      }
+      context.setError(error);
+      throw error;
+    }
+  }
+  createAbortError() {
+    const error = new Error("Operation aborted");
+    error.name = "AbortError";
+    return error;
+  }
+};
+
+// src/retry/RetryController.ts
+var RetryController = class {
+  constructor(options) {
+    this.retries = options?.retries ?? 0;
+    this.retryIf = options?.retryIf ?? (() => true);
+  }
+  /**
+   * Decide whether a retry should be attempted
+   */
+  shouldRetry(error, context) {
+    if (context.cancelled) {
+      return false;
+    }
+    if (context.retryCount >= this.retries) {
+      return false;
+    }
+    if (this.retryIf && !this.retryIf(error)) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Record that a retry is happening
+   */
+  recordRetry(context) {
+    context.recordRetry();
+  }
+};
+
+// src/retry/BackoffCalculator.ts
+var BackoffCalculator = class {
+  constructor(strategy) {
+    this.strategy = strategy ?? null;
+  }
+  /**
+   * Calculate delay (in ms) before the next retry
+   */
+  getDelay(attempt2) {
+    if (!this.strategy) {
+      return 0;
+    }
+    switch (this.strategy.type) {
+      case "fixed":
+        return this.strategy.delay;
+      case "exponential": {
+        const delay2 = this.strategy.base * Math.pow(2, attempt2);
+        return this.strategy.max ? Math.min(delay2, this.strategy.max) : delay2;
+      }
+      case "fibonacci":
+        return this.fibonacciDelay(this.strategy.base, attempt2);
+      case "custom":
+        return Math.max(0, this.strategy.getDelay(attempt2));
+      default:
+        return 0;
+    }
+  }
+  fibonacciDelay(base, attempt2) {
+    if (attempt2 <= 1) {
+      return base;
+    }
+    let prev = 0;
+    let curr = base;
+    for (let i = 2; i <= attempt2; i++) {
+      const next = prev + curr;
+      prev = curr;
+      curr = next;
+    }
+    return curr;
+  }
+};
+
+// src/fallback/FallbackController.ts
+var FallbackController = class {
+  constructor(fallback) {
+    if (!fallback) {
+      this.fallbacks = [];
+    } else if (Array.isArray(fallback)) {
+      this.fallbacks = fallback;
+    } else {
+      this.fallbacks = [fallback];
+    }
+  }
+  hasFallback() {
+    return this.fallbacks.length > 0;
+  }
+  /**
+   * Execute fallback operations sequentially.
+   * Stops at the first successful fallback.
+   */
+  async execute(engine, context, options) {
+    context.markFallbackUsed();
+    for (let i = 0; i < this.fallbacks.length; i++) {
+      context.fallbackIndex = i;
+      try {
+        const result = await engine.execute(
+          this.fallbacks[i],
+          context,
+          options
+        );
+        return result;
+      } catch (error) {
+        context.setError(error);
+        if (context.cancelled) {
+          throw error;
+        }
+      }
+    }
+    throw context.lastError;
+  }
+};
+
+// src/result/ResultAggregator.ts
+var ResultAggregator = class {
+  buildSuccess(value, context) {
+    return {
+      ok: true,
+      value,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration
+    };
+  }
+  buildFailure(error, context) {
+    return {
+      ok: false,
+      error,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration,
+      cancelled: context.cancelled
+    };
+  }
+  buildCancelled(context) {
+    return {
+      ok: false,
+      attempts: context.attemptCount,
+      usedFallback: context.usedFallback,
+      duration: context.duration,
+      cancelled: true
+    };
+  }
+  finalize(result, throwOnFail) {
+    if (!result.ok && throwOnFail) {
+      throw result.error;
+    }
+    return result;
+  }
+};
+
+// src/utils/delay.ts
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(createAbortError2());
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      cleanup();
+      reject(createAbortError2());
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort);
+    }
+  });
+}
+function createAbortError2() {
+  const error = new Error("Operation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+// src/attempt.ts
+async function attempt(fn, options = {}) {
+  const context = new ExecutionContext();
+  const engine = new ExecutionEngine();
+  const retryController = new RetryController(options.retry);
+  const backoffCalculator = new BackoffCalculator(options.backoff);
+  const fallbackController = new FallbackController(options.fallback);
+  const resultAggregator = new ResultAggregator();
+  const execOptions = {};
+  if (options.timeout !== void 0) execOptions.timeout = options.timeout;
+  if (options.signal !== void 0) execOptions.signal = options.signal;
+  try {
+    while (true) {
+      try {
+        const value = await engine.execute(fn, context, execOptions);
+        return resultAggregator.finalize(
+          resultAggregator.buildSuccess(value, context),
+          options.throwOnFail
+        );
+      } catch (error) {
+        context.setError(error);
+        if (retryController.shouldRetry(error, context)) {
+          retryController.recordRetry(context);
+          const waitTime = backoffCalculator.getDelay(context.retryCount);
+          if (waitTime > 0) {
+            await delay(waitTime, options.signal);
+          }
+          continue;
+        }
+        break;
+      }
+    }
+    if (fallbackController.hasFallback()) {
+      const value = await fallbackController.execute(
+        engine,
+        context,
+        execOptions
+      );
+      return resultAggregator.finalize(
+        resultAggregator.buildSuccess(value, context),
+        options.throwOnFail
+      );
+    }
+    return resultAggregator.finalize(
+      resultAggregator.buildFailure(context.lastError, context),
+      options.throwOnFail
+    );
+  } catch (error) {
+    context.setError(error);
+    if (context.cancelled) {
+      return resultAggregator.finalize(
+        resultAggregator.buildCancelled(context),
+        options.throwOnFail
+      );
+    }
+    return resultAggregator.finalize(
+      resultAggregator.buildFailure(error, context),
+      options.throwOnFail
+    );
+  }
+}
+export {
+  attempt
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "resilient-exec",
+  "version": "1.0.0",
+  "description": "Deterministic retry, timeout, and fallback execution utility",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "retry",
+    "fallback",
+    "resilience",
+    "timeout",
+    "error-handling",
+    "typescript",
+    "async"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18",
+    "rimraf": "^5.0.5"
+  }
+}