safe-await-lib 0.2.0 → 0.2.2

package/README.md

@@ -5,7 +5,7 @@
 [![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**.  
-Designed for **Node.js**, **TypeScript**, **React**, **React Native**, and **Expo**.
+Designed for **JavaScript and TypeScript environments**.
 
 ---
 
@@ -21,17 +21,17 @@ Traditional `async / await` requires repetitive `try/catch` blocks, which:
 
 ### Core idea
 
-> **Async code should never throw — it should return.**
+> **Async code should never throw — it should return a predictable tuple.**
 
 ---
 
-## 🚀 Features (v0.2.0)
+## 🚀 Features (v0.2.1)
 
-- Safe execution of async functions and promises
+- Safe execution of async functions, promises, or synchronous values
 - 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
+- Compatible with all JavaScript and TypeScript environments
 - Dual output: **ESM + CJS**
 - Tree-shakable
 - Built-in utilities:
@@ -64,19 +64,20 @@ async function fetchData() {
   return 'Hello World';
 }
 
-const [err, data] = await safe(fetchData);
+// Using a function
+const [err, data] = await safe(() => fetchData());
 
 if (err) {
   console.error(err.message, err.code);
 } else {
   console.log(data); // "Hello World"
 }
-```
 
-### Using a direct promise
+// Using a direct promise
+const [err2, result] = await safe(Promise.resolve(42));
 
-```ts
-const [err, result] = await safe(Promise.resolve(42));
+// Using a synchronous value
+const [err3, value] = await safe(10);
 ```
 
 ---
@@ -86,10 +87,21 @@ const [err, result] = await safe(Promise.resolve(42));
 ### `safe(input)`
 
 ```ts
-safe<T>(input: Promise<T> | (() => T | Promise<T>))
+safe<T>(input: Promise<T> | T | (() => T | Promise<T>))
   → Promise<[SafeError | null, T | null]>
 ```
 
+#### 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 — use `err.code` to identify the error type
+
 ---
 
 ### `SafeError` structure
@@ -104,7 +116,7 @@ interface SafeError {
 
 ---
 
-## 🌱 Advanced Usage (v0.2.0)
+## 🌱 Advanced Usage (v0.2.1)
 
 ### ⏱️ Timeout handling — `safe.withTimeout`
 
@@ -116,6 +128,13 @@ if (err?.code === 'TIMEOUT_ERROR') {
 }
 ```
 
+#### Behavior
+
+- Resolves with `[null, result]` if completed 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 === 'TIMEOUT_ERROR'` to detect timeout errors
+
 ---
 
 ### 🔁 Retry logic — `safe.retry`
@@ -137,17 +156,24 @@ if (err) {
 }
 ```
 
----
+#### Behavior
 
-## ✅ Available Today (v0.2.0)
+- Tries the operation up to `retries` times
+- Optional delay 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 === 'RETRY_FAILED'` to detect a complete retry failure
+
+---
 
-SAFE-AWAIT-LIB currently provides:
+## ✅ Available Today (v0.2.1)
 
 - `safe()` — core safe async execution
 - `safe.withTimeout()` — timeout control
 - `safe.retry()` — retry mechanism
 
-More utilities will be added incrementally.
+More utilities will be added incrementally according to the roadmap.
 
 ---
 
@@ -176,7 +202,7 @@ npm run build
 
 | Version | Features               |
 | ------: | ---------------------- |
-|  v0.2.0 | withTimeout, retry ✅  |
+|  v0.2.0 | withTimeout, retry ✅   |
 |  v0.3.0 | all, allSettled        |
 |  v0.4.0 | withContext            |
 |  v0.5.0 | once                   |
@@ -207,7 +233,7 @@ Please respect the existing **TypeScript typings** and **error model**.
 
 It enforces explicit error handling and removes runtime surprises.
 
-### Can I use this in React Native or Expo?
+### Can I use this in browser, Node.js, or other JS environments?
 
 Yes. SAFE-AWAIT-LIB is runtime-agnostic and fully compatible.
 

package/dist/index.d.mts

@@ -36,13 +36,15 @@ 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
  */
@@ -80,9 +82,11 @@ interface RetryOptions {
  *
  * ## Behavior
  * - Retries the operation up to `retries` times
- * - Optional delay between attempts
- * - Calls `onRetry` after each failure
- * - Returns `RETRY_FAILED` if all attempts fail
+ * - 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
@@ -105,14 +109,15 @@ declare function retry<T>(input: SafeInput<T>, options?: RetryOptions): SafeResu
  * ```
  *
  * ## Behavior
- * - Resolves with `[null, result]` if completed in time
- * - Resolves with `[SafeError, null]` on timeout or failure
- * - Never throws
+ * - 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 synchronous value
- * @param ms Timeout duration in milliseconds
+ * @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: T | Promise<T>, ms: number): SafeResult<T>;
+declare function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T>;
 
 /**
  * Standardized error codes used across the SAFE-AWAIT-LIB package.
@@ -159,12 +164,14 @@ interface ErrorWithCause extends Error {
 /**
  * Executes a synchronous or asynchronous operation safely.
  *
- * `safe` wraps any function or promise and always returns a predictable tuple
+ * `safe` wraps any function, promise, or value and always returns a predictable tuple
  * instead of throwing errors.
  *
  * ## Usage
  * ```ts
  * 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.code, err.message);
@@ -172,13 +179,13 @@ interface ErrorWithCause extends Error {
  * ```
  *
  * ## Behavior
- * - Never throws
- * - Always resolves
- * - Normalizes all errors into `SafeError`
+ * - 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 & {
     withTimeout: typeof withTimeout;

package/dist/index.d.ts

@@ -36,13 +36,15 @@ 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
  */
@@ -80,9 +82,11 @@ interface RetryOptions {
  *
  * ## Behavior
  * - Retries the operation up to `retries` times
- * - Optional delay between attempts
- * - Calls `onRetry` after each failure
- * - Returns `RETRY_FAILED` if all attempts fail
+ * - 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
@@ -105,14 +109,15 @@ declare function retry<T>(input: SafeInput<T>, options?: RetryOptions): SafeResu
  * ```
  *
  * ## Behavior
- * - Resolves with `[null, result]` if completed in time
- * - Resolves with `[SafeError, null]` on timeout or failure
- * - Never throws
+ * - 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 synchronous value
- * @param ms Timeout duration in milliseconds
+ * @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: T | Promise<T>, ms: number): SafeResult<T>;
+declare function withTimeout<T>(input: SafeInput<T>, ms: number): SafeResult<T>;
 
 /**
  * Standardized error codes used across the SAFE-AWAIT-LIB package.
@@ -159,12 +164,14 @@ interface ErrorWithCause extends Error {
 /**
  * Executes a synchronous or asynchronous operation safely.
  *
- * `safe` wraps any function or promise and always returns a predictable tuple
+ * `safe` wraps any function, promise, or value and always returns a predictable tuple
  * instead of throwing errors.
  *
  * ## Usage
  * ```ts
  * 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.code, err.message);
@@ -172,13 +179,13 @@ interface ErrorWithCause extends Error {
  * ```
  *
  * ## Behavior
- * - Never throws
- * - Always resolves
- * - Normalizes all errors into `SafeError`
+ * - 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 & {
     withTimeout: typeof withTimeout;

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,8 +70,8 @@ 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];
   }
@@ -89,8 +90,8 @@ async function retry(input, options = {}) {
   let lastError;
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
-      const data = typeof input === "function" ? await input() : await input;
-      return [null, data];
+      const result = typeof input === "function" ? await input() : await input;
+      return [null, result];
     } catch (err) {
       lastError = err;
       onRetry == null ? void 0 : onRetry(err, attempt);
@@ -99,7 +100,7 @@ async function retry(input, options = {}) {
       }
     }
   }
-  return [formatError(lastError, "RETRY_FAILED"), null];
+  return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];
 }
 
 // src/modules/timeout.ts
@@ -108,7 +109,7 @@ async function withTimeout(input, ms) {
   try {
     const promise = typeof input === "function" ? input() : input;
     const timeoutPromise = new Promise((_, reject) => {
-      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), "TIMEOUT_ERROR")), ms);
+      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);
     });
     const result = await Promise.race([promise, timeoutPromise]);
     return [null, result];
@@ -144,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","../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 or promise and always returns a predictable tuple\n * instead of throwing errors.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe(() => doSomething());\n *\n * if (err) {\n *   console.error(err.code, err.message);\n * }\n * ```\n *\n * ## Behavior\n * - Never throws\n * - Always resolves\n * - Normalizes all errors into `SafeError`\n *\n * ## Return\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure\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    ERROR_CODES,\n    ErrorCode,\n    ErrorWithCause\n} from \"./errors/codes\";\n\nexport type {\n    RetryOptions\n} from \"./modules/retry\";\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        return [null, data];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n","import { SafeInput, SafeResult } from \"../core/type\";\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 delay between attempts\n * - Calls `onRetry` after each failure\n * - Returns `RETRY_FAILED` if all attempts fail\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 data = typeof input === 'function' ? (await input()) : (await input);\n            return [null, data];\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, 'RETRY_FAILED'), null];\n}","import { ERROR_CODES } from '../errors/codes';\nimport { formatError } from '../errors/formatter';\nimport { 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 completed in time\n * - Resolves with `[SafeError, null]` on timeout or failure\n * - Never throws\n *\n * @param input A promise or synchronous value\n * @param ms Timeout duration in milliseconds\n */\nexport async function withTimeout<T>(input: T | Promise<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`), 'TIMEOUT_ERROR')), 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;;;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;AACnB,WAAO,CAAC,MAAM,IAAI;AAAA,EACtB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;ACAA,SAAS,MAAM,IAAY;AACvB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACzD;AAwBA,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,OAAO,OAAO,UAAU,aAAc,MAAM,MAAM,IAAM,MAAM;AACpE,aAAO,CAAC,MAAM,IAAI;AAAA,IACtB,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,cAAc,GAAG,IAAI;AACxD;;;AC9CA,eAAsB,YAAe,OAAuB,IAA2B;AACnF,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,eAAe,CAAC,GAAG,EAAE;AAAA,IACzG,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;;;ALhBO,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;AAkBD,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,8 +42,8 @@ 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];
   }
@@ -62,8 +62,8 @@ async function retry(input, options = {}) {
   let lastError;
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
-      const data = typeof input === "function" ? await input() : await input;
-      return [null, data];
+      const result = typeof input === "function" ? await input() : await input;
+      return [null, result];
     } catch (err) {
       lastError = err;
       onRetry == null ? void 0 : onRetry(err, attempt);
@@ -72,7 +72,7 @@ async function retry(input, options = {}) {
       }
     }
   }
-  return [formatError(lastError, "RETRY_FAILED"), null];
+  return [formatError(lastError, ERROR_CODES.RETRY_FAILED), null];
 }
 
 // src/modules/timeout.ts
@@ -81,7 +81,7 @@ async function withTimeout(input, ms) {
   try {
     const promise = typeof input === "function" ? input() : input;
     const timeoutPromise = new Promise((_, reject) => {
-      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), "TIMEOUT_ERROR")), ms);
+      timer = setTimeout(() => reject(formatError(new Error(`Timeout after ${ms}ms`), ERROR_CODES.TIMEOUT)), ms);
     });
     const result = await Promise.race([promise, timeoutPromise]);
     return [null, result];
@@ -116,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/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 * 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        return [null, data];\n    } catch (error) {\n        return [formatError(error), null];\n    }\n}\n","import { SafeInput, SafeResult } from \"../core/type\";\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 delay between attempts\n * - Calls `onRetry` after each failure\n * - Returns `RETRY_FAILED` if all attempts fail\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 data = typeof input === 'function' ? (await input()) : (await input);\n            return [null, data];\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, 'RETRY_FAILED'), null];\n}","import { ERROR_CODES } from '../errors/codes';\nimport { formatError } from '../errors/formatter';\nimport { 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 completed in time\n * - Resolves with `[SafeError, null]` on timeout or failure\n * - Never throws\n *\n * @param input A promise or synchronous value\n * @param ms Timeout duration in milliseconds\n */\nexport async function withTimeout<T>(input: T | Promise<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`), 'TIMEOUT_ERROR')), 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 or promise and always returns a predictable tuple\n * instead of throwing errors.\n *\n * ## Usage\n * ```ts\n * const [err, data] = await safe(() => doSomething());\n *\n * if (err) {\n *   console.error(err.code, err.message);\n * }\n * ```\n *\n * ## Behavior\n * - Never throws\n * - Always resolves\n * - Normalizes all errors into `SafeError`\n *\n * ## Return\n * - `[null, result]` on success\n * - `[SafeError, null]` on failure\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    ERROR_CODES,\n    ErrorCode,\n    ErrorWithCause\n} from \"./errors/codes\";\n\nexport type {\n    RetryOptions\n} from \"./modules/retry\";\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;AACnB,WAAO,CAAC,MAAM,IAAI;AAAA,EACtB,SAAS,OAAO;AACZ,WAAO,CAAC,YAAY,KAAK,GAAG,IAAI;AAAA,EACpC;AACJ;;;ACAA,SAAS,MAAM,IAAY;AACvB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACzD;AAwBA,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,OAAO,OAAO,UAAU,aAAc,MAAM,MAAM,IAAM,MAAM;AACpE,aAAO,CAAC,MAAM,IAAI;AAAA,IACtB,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,cAAc,GAAG,IAAI;AACxD;;;AC9CA,eAAsB,YAAe,OAAuB,IAA2B;AACnF,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,eAAe,CAAC,GAAG,EAAE;AAAA,IACzG,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;;;AChBO,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;AAkBD,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.2.0",
+  "version": "0.2.2",
   "description": "Safe async/await utility for handling promises without try/catch.",
   "author": "Chelohub Inc. <npm@borislukrece.com>",
   "scripts": {