safe-await-lib 0.1.4 → 0.2.1

package/LICENCE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Chelohub Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -4,33 +4,39 @@
 [![npm version](https://img.shields.io/npm/v/safe-await-lib.svg)](https://www.npmjs.com/package/safe-await-lib)
 [![License](https://img.shields.io/npm/l/safe-await-lib.svg)](https://github.com/chelohubinc/safe-await-lib/blob/main/LICENSE)
 
-Safe async/await utility for handling promises without try/catch.  
+Safe async/await utility for handling promises **without try/catch**.  
 Designed for **Node.js**, **TypeScript**, **React**, **React Native**, and **Expo**.
 
 ---
 
 ## 📌 Why SAFE-AWAIT-LIB?
 
-Traditional async/await patterns require `try/catch` blocks, which can clutter code and make error handling inconsistent.  
+Traditional `async / await` requires repetitive `try/catch` blocks, which:
 
-**SAFE-AWAIT-LIB solves this problem by:**
+- clutter business logic
+- encourage inconsistent error handling
+- hide error intent
 
-- Returning a consistent `[SafeError | null, T | null]` tuple for every async operation
-- Normalizing errors into a predictable format
-- Eliminating boilerplate `try/catch` blocks
-- Making code cleaner, safer, and easier to maintain
+**SAFE-AWAIT-LIB** solves this by enforcing a predictable, explicit error-handling pattern.
+
+### Core idea
+
+> **Async code should never throw — it should return.**
 
 ---
 
-## 🚀 Features
+## 🚀 Features (v0.2.0)
 
 - Safe execution of async functions and promises
-- Standardized error handling with `SafeError` objects
-- Fully TypeScript-typed for modern development
+- Always returns a predictable tuple: `[SafeError | null, T | null]`
+- Standardized error normalization
+- Fully typed with TypeScript
 - Compatible with Node.js, React, React Native, and Expo
-- Supports dual module output (ESM + CJS)
-- Tree-shakable for modern bundlers
-- Future-ready with planned modules: `withTimeout`, `retry`, `all`, `allSettled`, `once`, `strict`, `map`, `unwrap`, `mockSuccess`, `mockError`, `debug`
+- Dual output: **ESM + CJS**
+- Tree-shakable
+- Built-in utilities:
+  - `safe.withTimeout` — timeout control for async operations
+  - `safe.retry` — retry logic for unstable operations
 
 ---
 
@@ -54,121 +60,160 @@ pnpm add safe-await-lib
 ```ts
 import safe from 'safe-await-lib';
 
-// Async function
 async function fetchData() {
-  return Promise.resolve('Hello World!');
+  return 'Hello World';
 }
 
-// Using safe
 const [err, data] = await safe(fetchData);
 
 if (err) {
-  console.error(err.message);
+  console.error(err.message, err.code);
 } else {
-  console.log(data); // 'Hello World!'
+  console.log(data); // "Hello World"
 }
+```
+
+### Using a direct promise
 
-// Direct promise usage
-const [err2, result] = await safe(Promise.resolve(42));
+```ts
+const [err, result] = await safe(Promise.resolve(42));
 ```
 
 ---
 
-## 🛠️ API Overview
+## 🛠️ API
+
+### `safe(input)`
 
-### `safe(input: SafeInput<T>): SafeResult<T>`
+```ts
+safe<T>(input: Promise<T> | (() => T | Promise<T>))
+  → Promise<[SafeError | null, T | null]>
+```
 
-- **input**: `Promise<T>` or `() => T | Promise<T>`
-- **returns**: `[SafeError | null, T | null]`
+---
 
-### `SafeError` Structure
+### `SafeError` structure
 
 ```ts
 interface SafeError {
   message: string;   // Human-readable message
   code: string;      // Standardized error code
-  cause?: unknown;   // Original error or additional context
+  cause?: unknown;   // Original error or context
 }
 ```
 
 ---
 
-## 🌱 Advanced Usage Examples
+## 🌱 Advanced Usage (v0.2.0)
 
-### Handling multiple async operations
+### ⏱️ Timeout handling — `safe.withTimeout`
 
 ```ts
-// Future module: safe.all
-const [err, results] = await safe.all([fetchData(), Promise.resolve(10)]);
+const [err, data] = await safe.withTimeout(fetchData(), 1000);
+
+if (err?.code === 'TIMEOUT_ERROR') {
+  console.error('Operation timed out');
+}
 ```
 
-### Using retry (planned in v0.2.0)
+---
+
+### 🔁 Retry logic — `safe.retry`
 
 ```ts
-const [err, data] = await safe.retry(() => fetchData(), { attempts: 3, delay: 500 });
+const [err, data] = await safe.retry(
+  () => fetchData(),
+  {
+    retries: 3,
+    delayMs: 500,
+    onRetry: (error, attempt) => {
+      console.log(`Retry ${attempt} failed`, error);
+    }
+  }
+);
+
+if (err) {
+  console.error(err.code); // RETRY_FAILED
+}
 ```
 
 ---
 
-## 📊 Roadmap
+## ✅ Available Today (v0.2.0)
+
+SAFE-AWAIT-LIB currently provides:
 
-| Version | Features Planned       |
-| ------- | ---------------------- |
-| v0.2.0  | withTimeout, retry     |
-| v0.3.0  | all, allSettled        |
-| v0.4.0  | withContext            |
-| v0.5.0  | once                   |
-| v0.6.0  | strict                 |
-| v0.7.0  | map, unwrap            |
-| v0.8.0  | mockSuccess, mockError |
-| v0.9.0  | debug                  |
+- `safe()` — core safe async execution
+- `safe.withTimeout()` — timeout control
+- `safe.retry()` — retry mechanism
+
+More utilities will be added incrementally.
 
 ---
 
 ## 🧪 Development
 
 ```bash
-# Install dev dependencies
+# Install dependencies
 npm install
 
-# Run development build with watch
+# Development build (watch mode)
 npm run dev
 
-# Type check
+# Type checking
 npm run typecheck
 
 # Run tests
 npm test
 
-# Build for distribution
+# Build for production
 npm run build
 ```
 
 ---
 
+## 📊 Roadmap
+
+| Version | Features               |
+| ------: | ---------------------- |
+|  v0.2.0 | withTimeout, retry ✅  |
+|  v0.3.0 | all, allSettled        |
+|  v0.4.0 | withContext            |
+|  v0.5.0 | once                   |
+|  v0.6.0 | strict                 |
+|  v0.7.0 | map, unwrap            |
+|  v0.8.0 | mockSuccess, mockError |
+|  v0.9.0 | debug                  |
+
+---
+
 ## 📝 Contributing
 
-SAFE-AWAIT-LIB welcomes contributions!
+Contributions are welcome.
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/your-feature`)
-3. Run tests locally (`npm test`)
-4. Submit a pull request
+2. Create a feature branch
+3. Add tests for your changes
+4. Ensure `npm test` passes
+5. Submit a pull request
 
-Please adhere to the existing **TypeScript typings** and **code style**.
+Please respect the existing **TypeScript typings** and **error model**.
 
 ---
 
-## ❓ FAQ / Tips
+## ❓ FAQ
+
+### Why return a tuple instead of throwing?
+
+It enforces explicit error handling and removes runtime surprises.
+
+### Can I use this in React Native or Expo?
 
-- **Why use `[SafeError | null, T | null]` instead of try/catch?**
-  It ensures consistent error handling and makes async code more readable.
+Yes. SAFE-AWAIT-LIB is runtime-agnostic and fully compatible.
 
-- **Can I use this in React Native / Expo?**
-  Yes. SAFE-AWAIT-LIB is fully compatible.
+### Is this production-ready?
 
-- **How do I handle retries or timeouts?**
-  Future modules like `retry` and `withTimeout` will handle these cases cleanly.
+Yes. The core API is stable and versioned.
 
 ---
 

package/dist/index.d.mts

@@ -36,18 +36,89 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 /**
  * Internal execution engine for SAFE-AWAIT-LIB.
  *
- * This function executes a promise or a function safely and converts
- * any thrown or rejected value into a standardized `SafeResult` tuple.
+ * Safely executes a promise, synchronous value, or a function returning a value or promise,
+ * converting any thrown or rejected value into a standardized `SafeResult` tuple.
  *
- * It is intentionally minimal and side-effect free, serving as the
- * foundation for all higher-level modules (retry, timeout, etc.).
+ * ## Behavior
+ * - Resolves with `[null, result]` if the operation succeeds.
+ * - Resolves with `[SafeError, null]` if the operation throws or rejects.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
  *
- * @param input - A promise or a function returning a value or a promise
+ * @param input - A promise, a synchronous value, or a function returning a value or promise
  *
  * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple
  */
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
+/**
+ * Configuration options for the `retry` function.
+ */
+interface RetryOptions {
+    /**
+     * Number of retry attempts (default: 3)
+     */
+    retries?: number;
+    /**
+     * Delay in milliseconds between attempts (default: 0)
+     */
+    delayMs?: number;
+    /**
+     * Callback invoked after each failed attempt
+     */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * Retries a failing operation multiple times before giving up.
+ *
+ * Useful for unstable or flaky operations such as network requests.
+ *
+ * ## Usage
+ * ```ts
+ * const [err, data] = await safe.retry(
+ *   () => fetchData(),
+ *   { retries: 3, delayMs: 500 }
+ * );
+ * ```
+ *
+ * ## Behavior
+ * - Retries the operation up to `retries` times
+ * - Optional `delayMs` between attempts.
+ * - Invokes `onRetry` after each failed attempt.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
+ * - Returns a `SafeError` with code `RETRY_FAILED` if all attempts fail
+ * - Use `err?.code === ERROR_CODES.RETRY_FAILED` to detect a complete retry failure.
+ *
+ * @param input A function or promise to retry
+ * @param options Retry configuration
+ */
+declare function retry<T>(input: SafeInput<T>, options?: RetryOptions): SafeResult<T>;
+
+/**
+ * Executes an operation with a time limit.
+ *
+ * If the operation does not resolve within the given duration,
+ * it fails with a `TIMEOUT_ERROR`.
+ *
+ * ## Usage
+ * ```ts
+ * const [err, data] = await safe.withTimeout(fetchData(), 1000);
+ *
+ * if (err?.code === ERROR_CODES.TIMEOUT) {
+ *   console.error("Operation timed out");
+ * }
+ * ```
+ *
+ * ## Behavior
+ * - Resolves with `[null, result]` if the operation completes within the timeout.
+ * - Resolves with `[SafeError, null]` if the operation throws or exceeds the timeout.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
+ * - Use `err?.code === ERROR_CODES.TIMEOUT` to detect timeout errors specifically.
+ *
+ * @param input A promise or a function returning a value or a promise
+ * @param input A promise, a synchronous value, or a function returning a value or a promise
+ */
+declare function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T>;
+
 /**
  * Standardized error codes used across the SAFE-AWAIT-LIB package.
  *
@@ -91,44 +162,34 @@ interface ErrorWithCause extends Error {
 }
 
 /**
- * `safe` is the core function of the SAFE-AWAIT-LIB package.
+ * Executes a synchronous or asynchronous operation safely.
  *
- * It safely executes any synchronous or asynchronous operation and
- * always returns a predictable tuple instead of throwing errors.
+ * `safe` wraps any function, promise, or value and always returns a predictable tuple
+ * instead of throwing errors.
  *
- * ## Basic usage
+ * ## Usage
  * ```ts
- * import safe from "safe-await-lib";
- *
- * const [err, data] = await safe(async () => fetchData());
+ * const [err, data] = await safe(() => doSomething());
+ * const [err2, data2] = await safe(fetchData()); // promise directly
+ * const [err3, value] = await safe(42);          // synchronous value
  *
  * if (err) {
- *   console.error(err.message, err.code);
- * } else {
- *   console.log(data);
+ *   console.error(err.code, err.message);
  * }
  * ```
  *
- * ## Philosophy
- * - No try/catch pollution
- * - No unhandled promise rejections
- * - Explicit error handling
- *
- * ## Planned extensions
- * - v0.2.0: withTimeout, retry
- * - v0.3.0: all, allSettled
- * - v0.4.0: withContext
- * - v0.5.0: once
- * - v0.6.0: strict
- * - v0.7.0: map, unwrap
- * - v0.8.0: mockSuccess, mockError
- * - v0.9.0: debug
- *
- * ## Return value
- * Always returns a tuple:
+ * ## Behavior
+ * - Never throws — always returns `[SafeError | null, T | null]`
+ * - Normalizes any thrown or rejected value into a `SafeError`
+ * - Supports promises, synchronous values, or functions returning a value or promise
+ *
+ * ## Return
  * - `[null, result]` on success
- * - `[SafeError, null]` on failure
+ * - `[SafeError, null]` on failure — use `err.code` to identify the error type
  */
-declare const safe: typeof coreSafe;
+declare const safe: typeof coreSafe & {
+    withTimeout: typeof withTimeout;
+    retry: typeof retry;
+};
 
-export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type SafeError, type SafeInput, type SafeResult, safe as default, safe };
+export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type RetryOptions, type SafeError, type SafeInput, type SafeResult, safe as default, safe };

package/dist/index.d.ts

@@ -36,18 +36,89 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 /**
  * Internal execution engine for SAFE-AWAIT-LIB.
  *
- * This function executes a promise or a function safely and converts
- * any thrown or rejected value into a standardized `SafeResult` tuple.
+ * Safely executes a promise, synchronous value, or a function returning a value or promise,
+ * converting any thrown or rejected value into a standardized `SafeResult` tuple.
  *
- * It is intentionally minimal and side-effect free, serving as the
- * foundation for all higher-level modules (retry, timeout, etc.).
+ * ## Behavior
+ * - Resolves with `[null, result]` if the operation succeeds.
+ * - Resolves with `[SafeError, null]` if the operation throws or rejects.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
  *
- * @param input - A promise or a function returning a value or a promise
+ * @param input - A promise, a synchronous value, or a function returning a value or promise
  *
  * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple
  */
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
+/**
+ * Configuration options for the `retry` function.
+ */
+interface RetryOptions {
+    /**
+     * Number of retry attempts (default: 3)
+     */
+    retries?: number;
+    /**
+     * Delay in milliseconds between attempts (default: 0)
+     */
+    delayMs?: number;
+    /**
+     * Callback invoked after each failed attempt
+     */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * Retries a failing operation multiple times before giving up.
+ *
+ * Useful for unstable or flaky operations such as network requests.
+ *
+ * ## Usage
+ * ```ts
+ * const [err, data] = await safe.retry(
+ *   () => fetchData(),
+ *   { retries: 3, delayMs: 500 }
+ * );
+ * ```
+ *
+ * ## Behavior
+ * - Retries the operation up to `retries` times
+ * - Optional `delayMs` between attempts.
+ * - Invokes `onRetry` after each failed attempt.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
+ * - Returns a `SafeError` with code `RETRY_FAILED` if all attempts fail
+ * - Use `err?.code === ERROR_CODES.RETRY_FAILED` to detect a complete retry failure.
+ *
+ * @param input A function or promise to retry
+ * @param options Retry configuration
+ */
+declare function retry<T>(input: SafeInput<T>, options?: RetryOptions): SafeResult<T>;
+
+/**
+ * Executes an operation with a time limit.
+ *
+ * If the operation does not resolve within the given duration,
+ * it fails with a `TIMEOUT_ERROR`.
+ *
+ * ## Usage
+ * ```ts
+ * const [err, data] = await safe.withTimeout(fetchData(), 1000);
+ *
+ * if (err?.code === ERROR_CODES.TIMEOUT) {
+ *   console.error("Operation timed out");
+ * }
+ * ```
+ *
+ * ## Behavior
+ * - Resolves with `[null, result]` if the operation completes within the timeout.
+ * - Resolves with `[SafeError, null]` if the operation throws or exceeds the timeout.
+ * - Never throws — always returns `[SafeError | null, T | null]`.
+ * - Use `err?.code === ERROR_CODES.TIMEOUT` to detect timeout errors specifically.
+ *
+ * @param input A promise or a function returning a value or a promise
+ * @param input A promise, a synchronous value, or a function returning a value or a promise
+ */
+declare function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T>;
+
 /**
  * Standardized error codes used across the SAFE-AWAIT-LIB package.
  *
@@ -91,44 +162,34 @@ interface ErrorWithCause extends Error {
 }
 
 /**
- * `safe` is the core function of the SAFE-AWAIT-LIB package.
+ * Executes a synchronous or asynchronous operation safely.
  *
- * It safely executes any synchronous or asynchronous operation and
- * always returns a predictable tuple instead of throwing errors.
+ * `safe` wraps any function, promise, or value and always returns a predictable tuple
+ * instead of throwing errors.
  *
- * ## Basic usage
+ * ## Usage
  * ```ts
- * import safe from "safe-await-lib";
- *
- * const [err, data] = await safe(async () => fetchData());
+ * const [err, data] = await safe(() => doSomething());
+ * const [err2, data2] = await safe(fetchData()); // promise directly
+ * const [err3, value] = await safe(42);          // synchronous value
  *
  * if (err) {
- *   console.error(err.message, err.code);
- * } else {
- *   console.log(data);
+ *   console.error(err.code, err.message);
  * }
  * ```
  *
- * ## Philosophy
- * - No try/catch pollution
- * - No unhandled promise rejections
- * - Explicit error handling
- *
- * ## Planned extensions
- * - v0.2.0: withTimeout, retry
- * - v0.3.0: all, allSettled
- * - v0.4.0: withContext
- * - v0.5.0: once
- * - v0.6.0: strict
- * - v0.7.0: map, unwrap
- * - v0.8.0: mockSuccess, mockError
- * - v0.9.0: debug
- *
- * ## Return value
- * Always returns a tuple:
+ * ## Behavior
+ * - Never throws — always returns `[SafeError | null, T | null]`
+ * - Normalizes any thrown or rejected value into a `SafeError`
+ * - Supports promises, synchronous values, or functions returning a value or promise
+ *
+ * ## Return
  * - `[null, result]` on success
- * - `[SafeError, null]` on failure
+ * - `[SafeError, null]` on failure — use `err.code` to identify the error type
  */
-declare const safe: typeof coreSafe;
+declare const safe: typeof coreSafe & {
+    withTimeout: typeof withTimeout;
+    retry: typeof retry;
+};
 
-export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type SafeError, type SafeInput, type SafeResult, safe as default, safe };
+export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type RetryOptions, type SafeError, type SafeInput, type SafeResult, safe as default, safe };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ERROR_CODES: () => ERROR_CODES,
   default: () => index_default,
   safe: () => safe
 });
@@ -69,18 +70,60 @@ function formatError(err, defaultCode = ERROR_CODES.UNKNOWN) {
 async function coreSafe(input) {
   try {
     const promise = typeof input === "function" ? input() : input;
-    const data = await promise;
-    return [null, data];
+    const result = await promise;
+    return [null, result];
   } catch (error) {
     return [formatError(error), null];
   }
 }
 
+// src/modules/retry.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retry(input, options = {}) {
+  const {
+    retries = 3,
+    delayMs = 0,
+    onRetry
+  } = options;
+  let lastError;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const result = typeof input === "function" ? await input() : await input;
+      return [null, result];
+    } catch (err) {
+      lastError = err;
+      onRetry == null ? void 0 : onRetry(err, attempt);
+      if (attempt < retries && delayMs > 0) {
+        await sleep(delayMs);
+      }
+    }
+  }
+  return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];
+}
+
+// src/modules/timeout.ts
+async function withTimeout(input, ms) {
+  let timer;
+  try {
+    const promise = typeof input === "function" ? input() : input;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);
+    });
+    const result = await Promise.race([promise, timeoutPromise]);
+    return [null, result];
+  } catch (error) {
+    return [error, null];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/index.ts
 var safe = Object.assign(coreSafe, {
-  // v0.2.0
-  // withTimeout,
-  // retry,
+  withTimeout,
+  retry
   // v0.3.0
   // all,
   // allSettled,
@@ -102,6 +145,7 @@ var safe = Object.assign(coreSafe, {
 var index_default = safe;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ERROR_CODES,
   safe
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors/codes.ts","../src/errors/formatter.ts","../src/core/safe.ts"],"sourcesContent":["import { coreSafe } from \"./core/safe\";\n\n/**\n * `safe` is the core function of the SAFE-AWAIT-LIB package.\n *\n * It safely executes any synchronous or asynchronous operation and\n * always returns a predictable tuple instead of throwing errors.\n *\n * ## Basic usage\n * ```ts\n * import safe from \"safe-await-lib\";\n *\n * const [err, data] = await safe(async () => fetchData());\n *\n * if (err) {\n *   console.error(err.message, err.code);\n * } else {\n *   console.log(data);\n * }\n * ```\n *\n * ## Philosophy\n * - No try/catch pollution\n * - No unhandled promise rejections\n * - Explicit error handling\n *\n * ## Planned extensions\n * - v0.2.0: withTimeout, retry\n * - v0.3.0: all, allSettled\n * - v0.4.0: withContext\n * - v0.5.0: once\n * - v0.6.0: strict\n * - v0.7.0: map, unwrap\n * - v0.8.0: mockSuccess, mockError\n * - v0.9.0: debug\n *\n * ## Return value\n * Always returns a tuple:\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure\n */\nexport const safe = Object.assign(coreSafe, {\n    // v0.2.0\n    // withTimeout,\n    // retry,\n\n    // v0.3.0\n    // all,\n    // allSettled,\n\n    // v0.4.0\n    // withContext,\n\n    // v0.5.0\n    // once,\n\n    // v0.6.0\n    // strict,\n\n    // v0.7.0\n    // map,\n    // unwrap,\n\n    // v0.8.0\n    // mockSuccess,\n    // mockError,\n\n    // v0.9.0\n    // debug,\n});\n\nexport type { SafeError, SafeResult, SafeInput } from \"./core/type\";\n\nexport type { ERROR_CODES, ErrorCode, ErrorWithCause } from \"./errors/codes\";\n\nexport default safe;","/**\n * Standardized error codes used across the SAFE-AWAIT-LIB package.\n *\n * These codes allow consumers to reliably identify the nature\n * of an error without relying on string comparison of messages.\n *\n * Each module of the package should use one of these codes\n * when returning or normalizing an error.\n */\nexport const ERROR_CODES = {\n    /** Fallback error for unknown or unhandled failures */\n    UNKNOWN: 'UNKNOWN_ERROR',\n\n    /** Thrown when an operation exceeds a configured timeout */\n    TIMEOUT: 'TIMEOUT_ERROR',\n\n    /** Used when all retry attempts have failed */\n    RETRY_FAILED: 'RETRY_FAILED',\n\n    /** Used when an operation is explicitly aborted or cancelled */\n    ABORTED: 'ABORT_ERROR',\n\n    /** Used when input validation fails */\n    VALIDATION: 'VALIDATION_ERROR',\n\n    /** Used when a function guarded by `once()` is called more than once */\n    EXECUTION_ONCE: 'ALREADY_EXECUTED'\n} as const;\n\n/**\n * Union type of all supported error codes.\n *\n * This type ensures strong typing and prevents the use\n * of unsupported or custom error codes across the package.\n */\nexport type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];\n\n/**\n * Internal helper interface to support the `cause` property\n * on Error objects in environments where it is not\n * yet fully supported or typed.\n *\n * This allows SAFE-AWAIT-LIB to preserve the original error\n * while still returning a normalized SafeError object.\n */\nexport interface ErrorWithCause extends Error {\n    cause?: unknown;\n}\n","import { SafeError } from '../core/type';\nimport { ERROR_CODES, ErrorCode, ErrorWithCause } from './codes';\n\n/**\n * Normalizes any thrown value into a `SafeError`.\n *\n * This function is the foundation of SAFE-AWAIT-LIB's error-handling strategy.\n * It guarantees that all errors returned by the library follow the same\n * predictable structure, regardless of what was originally thrown.\n *\n * Supported inputs:\n * - `Error` instances (native or custom)\n * - string errors\n * - unknown or non-error values\n *\n * ## Normalization rules\n * - Preserves the original error message when possible\n * - Uses a standardized error code\n * - Keeps the original error in the `cause` field when available\n *\n * @param err - Any value thrown or rejected by an operation\n * @param defaultCode - Fallback error code when none is provided\n *\n * @returns A normalized `SafeError` object\n */\nexport function formatError(\n    err: unknown,\n    defaultCode: ErrorCode = ERROR_CODES.UNKNOWN\n): SafeError {\n    if (err instanceof Error) {\n        const errorWithCause = err as ErrorWithCause;\n\n        return {\n            message: err.message,\n            code: (err as any).code || defaultCode,\n            cause: errorWithCause.cause ?? err\n        };\n    }\n\n    if (typeof err === 'string') {\n        return {\n            message: err,\n            code: defaultCode,\n        };\n    }\n\n    return {\n        message: 'An unexpected error occurred',\n        code: defaultCode,\n        cause: err\n    };\n}\n","import { formatError } from \"../errors/formatter\";\nimport { SafeInput, SafeResult } from \"./type\";\n\n/**\n * Internal execution engine for SAFE-AWAIT-LIB.\n *\n * This function executes a promise or a function safely and converts\n * any thrown or rejected value into a standardized `SafeResult` tuple.\n *\n * It is intentionally minimal and side-effect free, serving as the\n * foundation for all higher-level modules (retry, timeout, etc.).\n *\n * @param input - A promise or a function returning a value or a promise\n *\n * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple\n */\nexport async function coreSafe<T>(input: SafeInput<T>): SafeResult<T> {\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n        const data = await promise;\n\n        return [null, data];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,cAAc;AAAA;AAAA,EAEvB,SAAS;AAAA;AAAA,EAGT,SAAS;AAAA;AAAA,EAGT,cAAc;AAAA;AAAA,EAGd,SAAS;AAAA;AAAA,EAGT,YAAY;AAAA;AAAA,EAGZ,gBAAgB;AACpB;;;ACFO,SAAS,YACZ,KACA,cAAyB,YAAY,SAC5B;AA5Bb;AA6BI,MAAI,eAAe,OAAO;AACtB,UAAM,iBAAiB;AAEvB,WAAO;AAAA,MACH,SAAS,IAAI;AAAA,MACb,MAAO,IAAY,QAAQ;AAAA,MAC3B,QAAO,oBAAe,UAAf,YAAwB;AAAA,IACnC;AAAA,EACJ;AAEA,MAAI,OAAO,QAAQ,UAAU;AACzB,WAAO;AAAA,MACH,SAAS;AAAA,MACT,MAAM;AAAA,IACV;AAAA,EACJ;AAEA,SAAO;AAAA,IACH,SAAS;AAAA,IACT,MAAM;AAAA,IACN,OAAO;AAAA,EACX;AACJ;;;ACnCA,eAAsB,SAAY,OAAoC;AAClE,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AACxD,UAAM,OAAO,MAAM;AAEnB,WAAO,CAAC,MAAM,IAAI;AAAA,EACtB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;AHgBO,IAAM,OAAO,OAAO,OAAO,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4B5C,CAAC;AAMD,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors/codes.ts","../src/errors/formatter.ts","../src/core/safe.ts","../src/modules/retry.ts","../src/modules/timeout.ts"],"sourcesContent":["import { coreSafe } from \"./core/safe\";\nimport { retry } from \"./modules/retry\";\nimport { withTimeout } from \"./modules/timeout\";\n\n/**\n * Executes a synchronous or asynchronous operation safely.\n *\n * `safe` wraps any function, promise, or value and always returns a predictable tuple\n * instead of throwing errors.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe(() => doSomething());\n * const [err2, data2] = await safe(fetchData()); // promise directly\n * const [err3, value] = await safe(42);          // synchronous value\n *\n * if (err) {\n *   console.error(err.code, err.message);\n * }\n * ```\n *\n * ## Behavior\n * - Never throws — always returns `[SafeError | null, T | null]`\n * - Normalizes any thrown or rejected value into a `SafeError`\n * - Supports promises, synchronous values, or functions returning a value or promise\n *\n * ## Return\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure — use `err.code` to identify the error type\n */\nexport const safe = Object.assign(coreSafe, {\n    withTimeout,\n    retry,\n\n    // v0.3.0\n    // all,\n    // allSettled,\n\n    // v0.4.0\n    // withContext,\n\n    // v0.5.0\n    // once,\n\n    // v0.6.0\n    // strict,\n\n    // v0.7.0\n    // map,\n    // unwrap,\n\n    // v0.8.0\n    // mockSuccess,\n    // mockError,\n\n    // v0.9.0\n    // debug,\n});\n\nexport type {\n    SafeError,\n    SafeResult,\n    SafeInput\n} from \"./core/type\";\n\nexport type {\n    ErrorCode,\n    ErrorWithCause\n} from \"./errors/codes\";\n\nexport type {\n    RetryOptions\n} from \"./modules/retry\";\n\nexport { ERROR_CODES } from \"./errors/codes\";\n\nexport default safe;","/**\n * Standardized error codes used across the SAFE-AWAIT-LIB package.\n *\n * These codes allow consumers to reliably identify the nature\n * of an error without relying on string comparison of messages.\n *\n * Each module of the package should use one of these codes\n * when returning or normalizing an error.\n */\nexport const ERROR_CODES = {\n    /** Fallback error for unknown or unhandled failures */\n    UNKNOWN: 'UNKNOWN_ERROR',\n\n    /** Thrown when an operation exceeds a configured timeout */\n    TIMEOUT: 'TIMEOUT_ERROR',\n\n    /** Used when all retry attempts have failed */\n    RETRY_FAILED: 'RETRY_FAILED',\n\n    /** Used when an operation is explicitly aborted or cancelled */\n    ABORTED: 'ABORT_ERROR',\n\n    /** Used when input validation fails */\n    VALIDATION: 'VALIDATION_ERROR',\n\n    /** Used when a function guarded by `once()` is called more than once */\n    EXECUTION_ONCE: 'ALREADY_EXECUTED'\n} as const;\n\n/**\n * Union type of all supported error codes.\n *\n * This type ensures strong typing and prevents the use\n * of unsupported or custom error codes across the package.\n */\nexport type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];\n\n/**\n * Internal helper interface to support the `cause` property\n * on Error objects in environments where it is not\n * yet fully supported or typed.\n *\n * This allows SAFE-AWAIT-LIB to preserve the original error\n * while still returning a normalized SafeError object.\n */\nexport interface ErrorWithCause extends Error {\n    cause?: unknown;\n}\n","import { SafeError } from '../core/type';\nimport { ERROR_CODES, ErrorCode, ErrorWithCause } from './codes';\n\n/**\n * Normalizes any thrown value into a `SafeError`.\n *\n * This function is the foundation of SAFE-AWAIT-LIB's error-handling strategy.\n * It guarantees that all errors returned by the library follow the same\n * predictable structure, regardless of what was originally thrown.\n *\n * Supported inputs:\n * - `Error` instances (native or custom)\n * - string errors\n * - unknown or non-error values\n *\n * ## Normalization rules\n * - Preserves the original error message when possible\n * - Uses a standardized error code\n * - Keeps the original error in the `cause` field when available\n *\n * @param err - Any value thrown or rejected by an operation\n * @param defaultCode - Fallback error code when none is provided\n *\n * @returns A normalized `SafeError` object\n */\nexport function formatError(\n    err: unknown,\n    defaultCode: ErrorCode = ERROR_CODES.UNKNOWN\n): SafeError {\n    if (err instanceof Error) {\n        const errorWithCause = err as ErrorWithCause;\n\n        return {\n            message: err.message,\n            code: (err as any).code || defaultCode,\n            cause: errorWithCause.cause ?? err\n        };\n    }\n\n    if (typeof err === 'string') {\n        return {\n            message: err,\n            code: defaultCode,\n        };\n    }\n\n    return {\n        message: 'An unexpected error occurred',\n        code: defaultCode,\n        cause: err\n    };\n}\n","import { formatError } from \"../errors/formatter\";\nimport { SafeInput, SafeResult } from \"./type\";\n\n/**\n * Internal execution engine for SAFE-AWAIT-LIB.\n *\n * Safely executes a promise, synchronous value, or a function returning a value or promise,\n * converting any thrown or rejected value into a standardized `SafeResult` tuple.\n *\n * ## Behavior\n * - Resolves with `[null, result]` if the operation succeeds.\n * - Resolves with `[SafeError, null]` if the operation throws or rejects.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n *\n * @param input - A promise, a synchronous value, or a function returning a value or promise\n *\n * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple\n */\nexport async function coreSafe<T>(input: SafeInput<T>): SafeResult<T> {\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n        const result = await promise;\n        return [null, result];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n","import { SafeInput, SafeResult } from \"../core/type\";\nimport { ERROR_CODES } from \"../errors/codes\";\nimport { formatError } from \"../errors/formatter\";\n\n/**\n * Configuration options for the `retry` function.\n */\nexport interface RetryOptions {\n    /**\n     * Number of retry attempts (default: 3)\n     */\n    retries?: number;\n\n    /**\n     * Delay in milliseconds between attempts (default: 0)\n     */\n    delayMs?: number;\n\n    /**\n     * Callback invoked after each failed attempt\n     */\n    onRetry?: (error: unknown, attempt: number) => void;\n}\n\n\nfunction sleep(ms: number) {\n    return new Promise(resolve => setTimeout(resolve, ms));\n}\n\n/**\n * Retries a failing operation multiple times before giving up.\n *\n * Useful for unstable or flaky operations such as network requests.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe.retry(\n *   () => fetchData(),\n *   { retries: 3, delayMs: 500 }\n * );\n * ```\n *\n * ## Behavior\n * - Retries the operation up to `retries` times\n * - Optional `delayMs` between attempts.\n * - Invokes `onRetry` after each failed attempt.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n * - Returns a `SafeError` with code `RETRY_FAILED` if all attempts fail\n * - Use `err?.code === ERROR_CODES.RETRY_FAILED` to detect a complete retry failure.\n *\n * @param input A function or promise to retry\n * @param options Retry configuration\n */\nexport async function retry<T>(input: SafeInput<T>, options: RetryOptions = {}): SafeResult<T> {\n    const {\n        retries = 3,\n        delayMs = 0,\n        onRetry\n    } = options;\n\n    let lastError: unknown;\n\n    for (let attempt = 1; attempt <= retries; attempt++) {\n        try {\n            const result = typeof input === 'function' ? await input() : await input;\n            return [null, result];\n        } catch (err) {\n            lastError = err;\n            onRetry?.(err, attempt);\n            if (attempt < retries && delayMs > 0) {\n                await sleep(delayMs);\n            }\n        }\n    }\n\n    return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];\n}","import { ERROR_CODES } from '../errors/codes';\nimport { formatError } from '../errors/formatter';\nimport { SafeInput, SafeResult } from './../core/type';\n\n/**\n * Executes an operation with a time limit.\n *\n * If the operation does not resolve within the given duration,\n * it fails with a `TIMEOUT_ERROR`.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe.withTimeout(fetchData(), 1000);\n *\n * if (err?.code === ERROR_CODES.TIMEOUT) {\n *   console.error(\"Operation timed out\");\n * }\n * ```\n *\n * ## Behavior\n * - Resolves with `[null, result]` if the operation completes within the timeout.\n * - Resolves with `[SafeError, null]` if the operation throws or exceeds the timeout.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n * - Use `err?.code === ERROR_CODES.TIMEOUT` to detect timeout errors specifically.\n *\n * @param input A promise or a function returning a value or a promise\n * @param input A promise, a synchronous value, or a function returning a value or a promise\n */\nexport async function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T> {\n    let timer: ReturnType<typeof setTimeout>;\n\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n\n        const timeoutPromise = new Promise<never>((_, reject) => {\n            timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);\n        });\n\n        const result = await Promise.race([promise, timeoutPromise]);\n        return [null, result];\n    } catch (error: any) {\n        return [error, null];\n    } finally {\n        clearTimeout(timer!);\n    }\n}"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,cAAc;AAAA;AAAA,EAEvB,SAAS;AAAA;AAAA,EAGT,SAAS;AAAA;AAAA,EAGT,cAAc;AAAA;AAAA,EAGd,SAAS;AAAA;AAAA,EAGT,YAAY;AAAA;AAAA,EAGZ,gBAAgB;AACpB;;;ACFO,SAAS,YACZ,KACA,cAAyB,YAAY,SAC5B;AA5Bb;AA6BI,MAAI,eAAe,OAAO;AACtB,UAAM,iBAAiB;AAEvB,WAAO;AAAA,MACH,SAAS,IAAI;AAAA,MACb,MAAO,IAAY,QAAQ;AAAA,MAC3B,QAAO,oBAAe,UAAf,YAAwB;AAAA,IACnC;AAAA,EACJ;AAEA,MAAI,OAAO,QAAQ,UAAU;AACzB,WAAO;AAAA,MACH,SAAS;AAAA,MACT,MAAM;AAAA,IACV;AAAA,EACJ;AAEA,SAAO;AAAA,IACH,SAAS;AAAA,IACT,MAAM;AAAA,IACN,OAAO;AAAA,EACX;AACJ;;;ACjCA,eAAsB,SAAY,OAAoC;AAClE,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AACxD,UAAM,SAAS,MAAM;AACrB,WAAO,CAAC,MAAM,MAAM;AAAA,EACxB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;ACDA,SAAS,MAAM,IAAY;AACvB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACzD;AA0BA,eAAsB,MAAS,OAAqB,UAAwB,CAAC,GAAkB;AAC3F,QAAM;AAAA,IACF,UAAU;AAAA,IACV,UAAU;AAAA,IACV;AAAA,EACJ,IAAI;AAEJ,MAAI;AAEJ,WAAS,UAAU,GAAG,WAAW,SAAS,WAAW;AACjD,QAAI;AACA,YAAM,SAAS,OAAO,UAAU,aAAa,MAAM,MAAM,IAAI,MAAM;AACnE,aAAO,CAAC,MAAM,MAAM;AAAA,IACxB,SAAS,KAAK;AACV,kBAAY;AACZ,yCAAU,KAAK;AACf,UAAI,UAAU,WAAW,UAAU,GAAG;AAClC,cAAM,MAAM,OAAO;AAAA,MACvB;AAAA,IACJ;AAAA,EACJ;AAEA,SAAO,CAAC,YAAY,WAAW,YAAY,YAAY,GAAG,IAAI;AAClE;;;AChDA,eAAsB,YAAe,OAAqB,IAA2B;AACjF,MAAI;AAEJ,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AAExD,UAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACrD,cAAQ,WAAW,MAAM,OAAO,YAAY,IAAI,MAAM,iBAAiB,EAAE,IAAI,GAAG,YAAY,OAAO,CAAC,GAAG,EAAE;AAAA,IAC7G,CAAC;AAED,UAAM,SAAS,MAAM,QAAQ,KAAK,CAAC,SAAS,cAAc,CAAC;AAC3D,WAAO,CAAC,MAAM,MAAM;AAAA,EACxB,SAAS,OAAY;AACjB,WAAO,CAAC,OAAO,IAAI;AAAA,EACvB,UAAE;AACE,iBAAa,KAAM;AAAA,EACvB;AACJ;;;ALfO,IAAM,OAAO,OAAO,OAAO,UAAU;AAAA,EACxC;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBJ,CAAC;AAmBD,IAAO,gBAAQ;","names":[]}

package/dist/index.mjs

@@ -42,18 +42,60 @@ function formatError(err, defaultCode = ERROR_CODES.UNKNOWN) {
 async function coreSafe(input) {
   try {
     const promise = typeof input === "function" ? input() : input;
-    const data = await promise;
-    return [null, data];
+    const result = await promise;
+    return [null, result];
   } catch (error) {
     return [formatError(error), null];
   }
 }
 
+// src/modules/retry.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retry(input, options = {}) {
+  const {
+    retries = 3,
+    delayMs = 0,
+    onRetry
+  } = options;
+  let lastError;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const result = typeof input === "function" ? await input() : await input;
+      return [null, result];
+    } catch (err) {
+      lastError = err;
+      onRetry == null ? void 0 : onRetry(err, attempt);
+      if (attempt < retries && delayMs > 0) {
+        await sleep(delayMs);
+      }
+    }
+  }
+  return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];
+}
+
+// src/modules/timeout.ts
+async function withTimeout(input, ms) {
+  let timer;
+  try {
+    const promise = typeof input === "function" ? input() : input;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);
+    });
+    const result = await Promise.race([promise, timeoutPromise]);
+    return [null, result];
+  } catch (error) {
+    return [error, null];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/index.ts
 var safe = Object.assign(coreSafe, {
-  // v0.2.0
-  // withTimeout,
-  // retry,
+  withTimeout,
+  retry
   // v0.3.0
   // all,
   // allSettled,
@@ -74,6 +116,7 @@ var safe = Object.assign(coreSafe, {
 });
 var index_default = safe;
 export {
+  ERROR_CODES,
   index_default as default,
   safe
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors/codes.ts","../src/errors/formatter.ts","../src/core/safe.ts","../src/index.ts"],"sourcesContent":["/**\n * Standardized error codes used across the SAFE-AWAIT-LIB package.\n *\n * These codes allow consumers to reliably identify the nature\n * of an error without relying on string comparison of messages.\n *\n * Each module of the package should use one of these codes\n * when returning or normalizing an error.\n */\nexport const ERROR_CODES = {\n    /** Fallback error for unknown or unhandled failures */\n    UNKNOWN: 'UNKNOWN_ERROR',\n\n    /** Thrown when an operation exceeds a configured timeout */\n    TIMEOUT: 'TIMEOUT_ERROR',\n\n    /** Used when all retry attempts have failed */\n    RETRY_FAILED: 'RETRY_FAILED',\n\n    /** Used when an operation is explicitly aborted or cancelled */\n    ABORTED: 'ABORT_ERROR',\n\n    /** Used when input validation fails */\n    VALIDATION: 'VALIDATION_ERROR',\n\n    /** Used when a function guarded by `once()` is called more than once */\n    EXECUTION_ONCE: 'ALREADY_EXECUTED'\n} as const;\n\n/**\n * Union type of all supported error codes.\n *\n * This type ensures strong typing and prevents the use\n * of unsupported or custom error codes across the package.\n */\nexport type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];\n\n/**\n * Internal helper interface to support the `cause` property\n * on Error objects in environments where it is not\n * yet fully supported or typed.\n *\n * This allows SAFE-AWAIT-LIB to preserve the original error\n * while still returning a normalized SafeError object.\n */\nexport interface ErrorWithCause extends Error {\n    cause?: unknown;\n}\n","import { SafeError } from '../core/type';\nimport { ERROR_CODES, ErrorCode, ErrorWithCause } from './codes';\n\n/**\n * Normalizes any thrown value into a `SafeError`.\n *\n * This function is the foundation of SAFE-AWAIT-LIB's error-handling strategy.\n * It guarantees that all errors returned by the library follow the same\n * predictable structure, regardless of what was originally thrown.\n *\n * Supported inputs:\n * - `Error` instances (native or custom)\n * - string errors\n * - unknown or non-error values\n *\n * ## Normalization rules\n * - Preserves the original error message when possible\n * - Uses a standardized error code\n * - Keeps the original error in the `cause` field when available\n *\n * @param err - Any value thrown or rejected by an operation\n * @param defaultCode - Fallback error code when none is provided\n *\n * @returns A normalized `SafeError` object\n */\nexport function formatError(\n    err: unknown,\n    defaultCode: ErrorCode = ERROR_CODES.UNKNOWN\n): SafeError {\n    if (err instanceof Error) {\n        const errorWithCause = err as ErrorWithCause;\n\n        return {\n            message: err.message,\n            code: (err as any).code || defaultCode,\n            cause: errorWithCause.cause ?? err\n        };\n    }\n\n    if (typeof err === 'string') {\n        return {\n            message: err,\n            code: defaultCode,\n        };\n    }\n\n    return {\n        message: 'An unexpected error occurred',\n        code: defaultCode,\n        cause: err\n    };\n}\n","import { formatError } from \"../errors/formatter\";\nimport { SafeInput, SafeResult } from \"./type\";\n\n/**\n * Internal execution engine for SAFE-AWAIT-LIB.\n *\n * This function executes a promise or a function safely and converts\n * any thrown or rejected value into a standardized `SafeResult` tuple.\n *\n * It is intentionally minimal and side-effect free, serving as the\n * foundation for all higher-level modules (retry, timeout, etc.).\n *\n * @param input - A promise or a function returning a value or a promise\n *\n * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple\n */\nexport async function coreSafe<T>(input: SafeInput<T>): SafeResult<T> {\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n        const data = await promise;\n\n        return [null, data];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n","import { coreSafe } from \"./core/safe\";\n\n/**\n * `safe` is the core function of the SAFE-AWAIT-LIB package.\n *\n * It safely executes any synchronous or asynchronous operation and\n * always returns a predictable tuple instead of throwing errors.\n *\n * ## Basic usage\n * ```ts\n * import safe from \"safe-await-lib\";\n *\n * const [err, data] = await safe(async () => fetchData());\n *\n * if (err) {\n *   console.error(err.message, err.code);\n * } else {\n *   console.log(data);\n * }\n * ```\n *\n * ## Philosophy\n * - No try/catch pollution\n * - No unhandled promise rejections\n * - Explicit error handling\n *\n * ## Planned extensions\n * - v0.2.0: withTimeout, retry\n * - v0.3.0: all, allSettled\n * - v0.4.0: withContext\n * - v0.5.0: once\n * - v0.6.0: strict\n * - v0.7.0: map, unwrap\n * - v0.8.0: mockSuccess, mockError\n * - v0.9.0: debug\n *\n * ## Return value\n * Always returns a tuple:\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure\n */\nexport const safe = Object.assign(coreSafe, {\n    // v0.2.0\n    // withTimeout,\n    // retry,\n\n    // v0.3.0\n    // all,\n    // allSettled,\n\n    // v0.4.0\n    // withContext,\n\n    // v0.5.0\n    // once,\n\n    // v0.6.0\n    // strict,\n\n    // v0.7.0\n    // map,\n    // unwrap,\n\n    // v0.8.0\n    // mockSuccess,\n    // mockError,\n\n    // v0.9.0\n    // debug,\n});\n\nexport type { SafeError, SafeResult, SafeInput } from \"./core/type\";\n\nexport type { ERROR_CODES, ErrorCode, ErrorWithCause } from \"./errors/codes\";\n\nexport default safe;"],"mappings":";AASO,IAAM,cAAc;AAAA;AAAA,EAEvB,SAAS;AAAA;AAAA,EAGT,SAAS;AAAA;AAAA,EAGT,cAAc;AAAA;AAAA,EAGd,SAAS;AAAA;AAAA,EAGT,YAAY;AAAA;AAAA,EAGZ,gBAAgB;AACpB;;;ACFO,SAAS,YACZ,KACA,cAAyB,YAAY,SAC5B;AA5Bb;AA6BI,MAAI,eAAe,OAAO;AACtB,UAAM,iBAAiB;AAEvB,WAAO;AAAA,MACH,SAAS,IAAI;AAAA,MACb,MAAO,IAAY,QAAQ;AAAA,MAC3B,QAAO,oBAAe,UAAf,YAAwB;AAAA,IACnC;AAAA,EACJ;AAEA,MAAI,OAAO,QAAQ,UAAU;AACzB,WAAO;AAAA,MACH,SAAS;AAAA,MACT,MAAM;AAAA,IACV;AAAA,EACJ;AAEA,SAAO;AAAA,IACH,SAAS;AAAA,IACT,MAAM;AAAA,IACN,OAAO;AAAA,EACX;AACJ;;;ACnCA,eAAsB,SAAY,OAAoC;AAClE,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AACxD,UAAM,OAAO,MAAM;AAEnB,WAAO,CAAC,MAAM,IAAI;AAAA,EACtB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;ACgBO,IAAM,OAAO,OAAO,OAAO,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4B5C,CAAC;AAMD,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/errors/codes.ts","../src/errors/formatter.ts","../src/core/safe.ts","../src/modules/retry.ts","../src/modules/timeout.ts","../src/index.ts"],"sourcesContent":["/**\n * Standardized error codes used across the SAFE-AWAIT-LIB package.\n *\n * These codes allow consumers to reliably identify the nature\n * of an error without relying on string comparison of messages.\n *\n * Each module of the package should use one of these codes\n * when returning or normalizing an error.\n */\nexport const ERROR_CODES = {\n    /** Fallback error for unknown or unhandled failures */\n    UNKNOWN: 'UNKNOWN_ERROR',\n\n    /** Thrown when an operation exceeds a configured timeout */\n    TIMEOUT: 'TIMEOUT_ERROR',\n\n    /** Used when all retry attempts have failed */\n    RETRY_FAILED: 'RETRY_FAILED',\n\n    /** Used when an operation is explicitly aborted or cancelled */\n    ABORTED: 'ABORT_ERROR',\n\n    /** Used when input validation fails */\n    VALIDATION: 'VALIDATION_ERROR',\n\n    /** Used when a function guarded by `once()` is called more than once */\n    EXECUTION_ONCE: 'ALREADY_EXECUTED'\n} as const;\n\n/**\n * Union type of all supported error codes.\n *\n * This type ensures strong typing and prevents the use\n * of unsupported or custom error codes across the package.\n */\nexport type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];\n\n/**\n * Internal helper interface to support the `cause` property\n * on Error objects in environments where it is not\n * yet fully supported or typed.\n *\n * This allows SAFE-AWAIT-LIB to preserve the original error\n * while still returning a normalized SafeError object.\n */\nexport interface ErrorWithCause extends Error {\n    cause?: unknown;\n}\n","import { SafeError } from '../core/type';\nimport { ERROR_CODES, ErrorCode, ErrorWithCause } from './codes';\n\n/**\n * Normalizes any thrown value into a `SafeError`.\n *\n * This function is the foundation of SAFE-AWAIT-LIB's error-handling strategy.\n * It guarantees that all errors returned by the library follow the same\n * predictable structure, regardless of what was originally thrown.\n *\n * Supported inputs:\n * - `Error` instances (native or custom)\n * - string errors\n * - unknown or non-error values\n *\n * ## Normalization rules\n * - Preserves the original error message when possible\n * - Uses a standardized error code\n * - Keeps the original error in the `cause` field when available\n *\n * @param err - Any value thrown or rejected by an operation\n * @param defaultCode - Fallback error code when none is provided\n *\n * @returns A normalized `SafeError` object\n */\nexport function formatError(\n    err: unknown,\n    defaultCode: ErrorCode = ERROR_CODES.UNKNOWN\n): SafeError {\n    if (err instanceof Error) {\n        const errorWithCause = err as ErrorWithCause;\n\n        return {\n            message: err.message,\n            code: (err as any).code || defaultCode,\n            cause: errorWithCause.cause ?? err\n        };\n    }\n\n    if (typeof err === 'string') {\n        return {\n            message: err,\n            code: defaultCode,\n        };\n    }\n\n    return {\n        message: 'An unexpected error occurred',\n        code: defaultCode,\n        cause: err\n    };\n}\n","import { formatError } from \"../errors/formatter\";\nimport { SafeInput, SafeResult } from \"./type\";\n\n/**\n * Internal execution engine for SAFE-AWAIT-LIB.\n *\n * Safely executes a promise, synchronous value, or a function returning a value or promise,\n * converting any thrown or rejected value into a standardized `SafeResult` tuple.\n *\n * ## Behavior\n * - Resolves with `[null, result]` if the operation succeeds.\n * - Resolves with `[SafeError, null]` if the operation throws or rejects.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n *\n * @param input - A promise, a synchronous value, or a function returning a value or promise\n *\n * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple\n */\nexport async function coreSafe<T>(input: SafeInput<T>): SafeResult<T> {\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n        const result = await promise;\n        return [null, result];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n","import { SafeInput, SafeResult } from \"../core/type\";\nimport { ERROR_CODES } from \"../errors/codes\";\nimport { formatError } from \"../errors/formatter\";\n\n/**\n * Configuration options for the `retry` function.\n */\nexport interface RetryOptions {\n    /**\n     * Number of retry attempts (default: 3)\n     */\n    retries?: number;\n\n    /**\n     * Delay in milliseconds between attempts (default: 0)\n     */\n    delayMs?: number;\n\n    /**\n     * Callback invoked after each failed attempt\n     */\n    onRetry?: (error: unknown, attempt: number) => void;\n}\n\n\nfunction sleep(ms: number) {\n    return new Promise(resolve => setTimeout(resolve, ms));\n}\n\n/**\n * Retries a failing operation multiple times before giving up.\n *\n * Useful for unstable or flaky operations such as network requests.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe.retry(\n *   () => fetchData(),\n *   { retries: 3, delayMs: 500 }\n * );\n * ```\n *\n * ## Behavior\n * - Retries the operation up to `retries` times\n * - Optional `delayMs` between attempts.\n * - Invokes `onRetry` after each failed attempt.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n * - Returns a `SafeError` with code `RETRY_FAILED` if all attempts fail\n * - Use `err?.code === ERROR_CODES.RETRY_FAILED` to detect a complete retry failure.\n *\n * @param input A function or promise to retry\n * @param options Retry configuration\n */\nexport async function retry<T>(input: SafeInput<T>, options: RetryOptions = {}): SafeResult<T> {\n    const {\n        retries = 3,\n        delayMs = 0,\n        onRetry\n    } = options;\n\n    let lastError: unknown;\n\n    for (let attempt = 1; attempt <= retries; attempt++) {\n        try {\n            const result = typeof input === 'function' ? await input() : await input;\n            return [null, result];\n        } catch (err) {\n            lastError = err;\n            onRetry?.(err, attempt);\n            if (attempt < retries && delayMs > 0) {\n                await sleep(delayMs);\n            }\n        }\n    }\n\n    return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];\n}","import { ERROR_CODES } from '../errors/codes';\nimport { formatError } from '../errors/formatter';\nimport { SafeInput, SafeResult } from './../core/type';\n\n/**\n * Executes an operation with a time limit.\n *\n * If the operation does not resolve within the given duration,\n * it fails with a `TIMEOUT_ERROR`.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe.withTimeout(fetchData(), 1000);\n *\n * if (err?.code === ERROR_CODES.TIMEOUT) {\n *   console.error(\"Operation timed out\");\n * }\n * ```\n *\n * ## Behavior\n * - Resolves with `[null, result]` if the operation completes within the timeout.\n * - Resolves with `[SafeError, null]` if the operation throws or exceeds the timeout.\n * - Never throws — always returns `[SafeError | null, T | null]`.\n * - Use `err?.code === ERROR_CODES.TIMEOUT` to detect timeout errors specifically.\n *\n * @param input A promise or a function returning a value or a promise\n * @param input A promise, a synchronous value, or a function returning a value or a promise\n */\nexport async function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T> {\n    let timer: ReturnType<typeof setTimeout>;\n\n    try {\n        const promise = typeof input === 'function' ? input() : input;\n\n        const timeoutPromise = new Promise<never>((_, reject) => {\n            timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);\n        });\n\n        const result = await Promise.race([promise, timeoutPromise]);\n        return [null, result];\n    } catch (error: any) {\n        return [error, null];\n    } finally {\n        clearTimeout(timer!);\n    }\n}","import { coreSafe } from \"./core/safe\";\nimport { retry } from \"./modules/retry\";\nimport { withTimeout } from \"./modules/timeout\";\n\n/**\n * Executes a synchronous or asynchronous operation safely.\n *\n * `safe` wraps any function, promise, or value and always returns a predictable tuple\n * instead of throwing errors.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe(() => doSomething());\n * const [err2, data2] = await safe(fetchData()); // promise directly\n * const [err3, value] = await safe(42);          // synchronous value\n *\n * if (err) {\n *   console.error(err.code, err.message);\n * }\n * ```\n *\n * ## Behavior\n * - Never throws — always returns `[SafeError | null, T | null]`\n * - Normalizes any thrown or rejected value into a `SafeError`\n * - Supports promises, synchronous values, or functions returning a value or promise\n *\n * ## Return\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure — use `err.code` to identify the error type\n */\nexport const safe = Object.assign(coreSafe, {\n    withTimeout,\n    retry,\n\n    // v0.3.0\n    // all,\n    // allSettled,\n\n    // v0.4.0\n    // withContext,\n\n    // v0.5.0\n    // once,\n\n    // v0.6.0\n    // strict,\n\n    // v0.7.0\n    // map,\n    // unwrap,\n\n    // v0.8.0\n    // mockSuccess,\n    // mockError,\n\n    // v0.9.0\n    // debug,\n});\n\nexport type {\n    SafeError,\n    SafeResult,\n    SafeInput\n} from \"./core/type\";\n\nexport type {\n    ErrorCode,\n    ErrorWithCause\n} from \"./errors/codes\";\n\nexport type {\n    RetryOptions\n} from \"./modules/retry\";\n\nexport { ERROR_CODES } from \"./errors/codes\";\n\nexport default safe;"],"mappings":";AASO,IAAM,cAAc;AAAA;AAAA,EAEvB,SAAS;AAAA;AAAA,EAGT,SAAS;AAAA;AAAA,EAGT,cAAc;AAAA;AAAA,EAGd,SAAS;AAAA;AAAA,EAGT,YAAY;AAAA;AAAA,EAGZ,gBAAgB;AACpB;;;ACFO,SAAS,YACZ,KACA,cAAyB,YAAY,SAC5B;AA5Bb;AA6BI,MAAI,eAAe,OAAO;AACtB,UAAM,iBAAiB;AAEvB,WAAO;AAAA,MACH,SAAS,IAAI;AAAA,MACb,MAAO,IAAY,QAAQ;AAAA,MAC3B,QAAO,oBAAe,UAAf,YAAwB;AAAA,IACnC;AAAA,EACJ;AAEA,MAAI,OAAO,QAAQ,UAAU;AACzB,WAAO;AAAA,MACH,SAAS;AAAA,MACT,MAAM;AAAA,IACV;AAAA,EACJ;AAEA,SAAO;AAAA,IACH,SAAS;AAAA,IACT,MAAM;AAAA,IACN,OAAO;AAAA,EACX;AACJ;;;ACjCA,eAAsB,SAAY,OAAoC;AAClE,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AACxD,UAAM,SAAS,MAAM;AACrB,WAAO,CAAC,MAAM,MAAM;AAAA,EACxB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;ACDA,SAAS,MAAM,IAAY;AACvB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACzD;AA0BA,eAAsB,MAAS,OAAqB,UAAwB,CAAC,GAAkB;AAC3F,QAAM;AAAA,IACF,UAAU;AAAA,IACV,UAAU;AAAA,IACV;AAAA,EACJ,IAAI;AAEJ,MAAI;AAEJ,WAAS,UAAU,GAAG,WAAW,SAAS,WAAW;AACjD,QAAI;AACA,YAAM,SAAS,OAAO,UAAU,aAAa,MAAM,MAAM,IAAI,MAAM;AACnE,aAAO,CAAC,MAAM,MAAM;AAAA,IACxB,SAAS,KAAK;AACV,kBAAY;AACZ,yCAAU,KAAK;AACf,UAAI,UAAU,WAAW,UAAU,GAAG;AAClC,cAAM,MAAM,OAAO;AAAA,MACvB;AAAA,IACJ;AAAA,EACJ;AAEA,SAAO,CAAC,YAAY,WAAW,YAAY,YAAY,GAAG,IAAI;AAClE;;;AChDA,eAAsB,YAAe,OAAqB,IAA2B;AACjF,MAAI;AAEJ,MAAI;AACA,UAAM,UAAU,OAAO,UAAU,aAAa,MAAM,IAAI;AAExD,UAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACrD,cAAQ,WAAW,MAAM,OAAO,YAAY,IAAI,MAAM,iBAAiB,EAAE,IAAI,GAAG,YAAY,OAAO,CAAC,GAAG,EAAE;AAAA,IAC7G,CAAC;AAED,UAAM,SAAS,MAAM,QAAQ,KAAK,CAAC,SAAS,cAAc,CAAC;AAC3D,WAAO,CAAC,MAAM,MAAM;AAAA,EACxB,SAAS,OAAY;AACjB,WAAO,CAAC,OAAO,IAAI;AAAA,EACvB,UAAE;AACE,iBAAa,KAAM;AAAA,EACvB;AACJ;;;ACfO,IAAM,OAAO,OAAO,OAAO,UAAU;AAAA,EACxC;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBJ,CAAC;AAmBD,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safe-await-lib",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Safe async/await utility for handling promises without try/catch.",
   "author": "Chelohub Inc. <npm@borislukrece.com>",
   "scripts": {