safe-await-lib 0.1.2 → 0.1.4

package/README.md

@@ -1,19 +1,19 @@
-# SAFE-AWAIT
+# SAFE-AWAIT-LIB
 
-[![Build Status](https://github.com/chelohubinc/safe-await/actions/workflows/ci.yml/badge.svg)](https://github.com/chelohubinc/safe-await/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/safe-await.svg)](https://www.npmjs.com/package/safe-await)
-[![License](https://img.shields.io/npm/l/safe-await.svg)](https://github.com/chelohubinc/safe-await/blob/main/LICENSE)
+[![Build Status](https://github.com/chelohubinc/safe-await-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/chelohubinc/safe-await-lib/actions/workflows/ci.yml)
+[![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.  
 Designed for **Node.js**, **TypeScript**, **React**, **React Native**, and **Expo**.
 
 ---
 
-## 📌 Why SAFE-AWAIT?
+## 📌 Why SAFE-AWAIT-LIB?
 
 Traditional async/await patterns require `try/catch` blocks, which can clutter code and make error handling inconsistent.  
 
-**SAFE-AWAIT solves this problem by:**
+**SAFE-AWAIT-LIB solves this problem by:**
 
 - Returning a consistent `[SafeError | null, T | null]` tuple for every async operation
 - Normalizing errors into a predictable format
@@ -38,13 +38,13 @@ Traditional async/await patterns require `try/catch` blocks, which can clutter c
 
 ```bash
 # npm
-npm install safe-await
+npm install safe-await-lib
 
 # yarn
-yarn add safe-await
+yarn add safe-await-lib
 
 # pnpm
-pnpm add safe-await
+pnpm add safe-await-lib
 ````
 
 ---
@@ -52,7 +52,7 @@ pnpm add safe-await
 ## ⚡ Basic Usage
 
 ```ts
-import safe from 'safe-await';
+import safe from 'safe-await-lib';
 
 // Async function
 async function fetchData() {
@@ -148,7 +148,7 @@ npm run build
 
 ## 📝 Contributing
 
-SAFE-AWAIT welcomes contributions!
+SAFE-AWAIT-LIB welcomes contributions!
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/your-feature`)
@@ -165,7 +165,7 @@ Please adhere to the existing **TypeScript typings** and **code style**.
   It ensures consistent error handling and makes async code more readable.
 
 - **Can I use this in React Native / Expo?**
-  Yes. SAFE-AWAIT is fully compatible.
+  Yes. SAFE-AWAIT-LIB is fully compatible.
 
 - **How do I handle retries or timeouts?**
   Future modules like `retry` and `withTimeout` will handle these cases cleanly.
@@ -180,5 +180,5 @@ ISC License © Chelohub Inc.
 
 ## 🌐 Links
 
-- **GitHub:** [https://github.com/chelohubinc/safe-await](https://github.com/chelohubinc/safe-await)
-- **NPM:** [https://www.npmjs.com/package/safe-await](https://www.npmjs.com/package/safe-await)
+- **GitHub:** [https://github.com/chelohubinc/safe-await-lib](https://github.com/chelohubinc/safe-await-lib)
+- **NPM:** [https://www.npmjs.com/package/safe-await-lib](https://www.npmjs.com/package/safe-await-lib)

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 /**
- * Standardized error object used throughout the SAFE-AWAIT package.
+ * Standardized error object used throughout the SAFE-AWAIT-LIB package.
  *
  * Every error returned by `safe()` or its extensions follows this shape,
  * ensuring consistent and predictable error handling.
@@ -13,7 +13,7 @@ interface SafeError {
     cause?: unknown;
 }
 /**
- * Standard return type for all SAFE-AWAIT operations.
+ * Standard return type for all SAFE-AWAIT-LIB operations.
  *
  * The result is always a tuple:
  * - `[null, T]` when the operation succeeds
@@ -34,7 +34,7 @@ type SafeResult<T> = Promise<[SafeError | null, T | null]>;
 type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 
 /**
- * Internal execution engine for SAFE-AWAIT.
+ * 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.
@@ -49,14 +49,56 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
 /**
- * `safe` is the core function of the SAFE-AWAIT package.
+ * Standardized error codes used across the SAFE-AWAIT-LIB package.
+ *
+ * These codes allow consumers to reliably identify the nature
+ * of an error without relying on string comparison of messages.
+ *
+ * Each module of the package should use one of these codes
+ * when returning or normalizing an error.
+ */
+declare const ERROR_CODES: {
+    /** Fallback error for unknown or unhandled failures */
+    readonly UNKNOWN: "UNKNOWN_ERROR";
+    /** Thrown when an operation exceeds a configured timeout */
+    readonly TIMEOUT: "TIMEOUT_ERROR";
+    /** Used when all retry attempts have failed */
+    readonly RETRY_FAILED: "RETRY_FAILED";
+    /** Used when an operation is explicitly aborted or cancelled */
+    readonly ABORTED: "ABORT_ERROR";
+    /** Used when input validation fails */
+    readonly VALIDATION: "VALIDATION_ERROR";
+    /** Used when a function guarded by `once()` is called more than once */
+    readonly EXECUTION_ONCE: "ALREADY_EXECUTED";
+};
+/**
+ * Union type of all supported error codes.
+ *
+ * This type ensures strong typing and prevents the use
+ * of unsupported or custom error codes across the package.
+ */
+type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+/**
+ * Internal helper interface to support the `cause` property
+ * on Error objects in environments where it is not
+ * yet fully supported or typed.
+ *
+ * This allows SAFE-AWAIT-LIB to preserve the original error
+ * while still returning a normalized SafeError object.
+ */
+interface ErrorWithCause extends Error {
+    cause?: unknown;
+}
+
+/**
+ * `safe` is the core function of the SAFE-AWAIT-LIB package.
  *
  * It safely executes any synchronous or asynchronous operation and
  * always returns a predictable tuple instead of throwing errors.
  *
  * ## Basic usage
  * ```ts
- * import safe from "safe-await";
+ * import safe from "safe-await-lib";
  *
  * const [err, data] = await safe(async () => fetchData());
  *
@@ -89,4 +131,4 @@ declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
  */
 declare const safe: typeof coreSafe;
 
-export { safe as default, safe };
+export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type SafeError, type SafeInput, type SafeResult, safe as default, safe };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Standardized error object used throughout the SAFE-AWAIT package.
+ * Standardized error object used throughout the SAFE-AWAIT-LIB package.
  *
  * Every error returned by `safe()` or its extensions follows this shape,
  * ensuring consistent and predictable error handling.
@@ -13,7 +13,7 @@ interface SafeError {
     cause?: unknown;
 }
 /**
- * Standard return type for all SAFE-AWAIT operations.
+ * Standard return type for all SAFE-AWAIT-LIB operations.
  *
  * The result is always a tuple:
  * - `[null, T]` when the operation succeeds
@@ -34,7 +34,7 @@ type SafeResult<T> = Promise<[SafeError | null, T | null]>;
 type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 
 /**
- * Internal execution engine for SAFE-AWAIT.
+ * 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.
@@ -49,14 +49,56 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
 /**
- * `safe` is the core function of the SAFE-AWAIT package.
+ * Standardized error codes used across the SAFE-AWAIT-LIB package.
+ *
+ * These codes allow consumers to reliably identify the nature
+ * of an error without relying on string comparison of messages.
+ *
+ * Each module of the package should use one of these codes
+ * when returning or normalizing an error.
+ */
+declare const ERROR_CODES: {
+    /** Fallback error for unknown or unhandled failures */
+    readonly UNKNOWN: "UNKNOWN_ERROR";
+    /** Thrown when an operation exceeds a configured timeout */
+    readonly TIMEOUT: "TIMEOUT_ERROR";
+    /** Used when all retry attempts have failed */
+    readonly RETRY_FAILED: "RETRY_FAILED";
+    /** Used when an operation is explicitly aborted or cancelled */
+    readonly ABORTED: "ABORT_ERROR";
+    /** Used when input validation fails */
+    readonly VALIDATION: "VALIDATION_ERROR";
+    /** Used when a function guarded by `once()` is called more than once */
+    readonly EXECUTION_ONCE: "ALREADY_EXECUTED";
+};
+/**
+ * Union type of all supported error codes.
+ *
+ * This type ensures strong typing and prevents the use
+ * of unsupported or custom error codes across the package.
+ */
+type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+/**
+ * Internal helper interface to support the `cause` property
+ * on Error objects in environments where it is not
+ * yet fully supported or typed.
+ *
+ * This allows SAFE-AWAIT-LIB to preserve the original error
+ * while still returning a normalized SafeError object.
+ */
+interface ErrorWithCause extends Error {
+    cause?: unknown;
+}
+
+/**
+ * `safe` is the core function of the SAFE-AWAIT-LIB package.
  *
  * It safely executes any synchronous or asynchronous operation and
  * always returns a predictable tuple instead of throwing errors.
  *
  * ## Basic usage
  * ```ts
- * import safe from "safe-await";
+ * import safe from "safe-await-lib";
  *
  * const [err, data] = await safe(async () => fetchData());
  *
@@ -89,4 +131,4 @@ declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
  */
 declare const safe: typeof coreSafe;
 
-export { safe as default, safe };
+export { ERROR_CODES, type ErrorCode, type ErrorWithCause, type SafeError, type SafeInput, type SafeResult, safe as default, safe };

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 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\";\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 default safe;","/**\n * Standardized error codes used across the SAFE-AWAIT 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 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'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.\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;AAED,IAAO,gBAAQ;","names":[]}
+{"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":[]}

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 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 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'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.\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 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\";\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 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;AAED,IAAO,gBAAQ;","names":[]}
+{"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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safe-await-lib",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Safe async/await utility for handling promises without try/catch.",
   "author": "Chelohub Inc. <npm@borislukrece.com>",
   "scripts": {
@@ -34,7 +34,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/chelohubinc/safe-await"
+    "url": "https://github.com/chelohubinc/safe-await-lib"
   },
   "keywords": [
     "async",