safe-await-lib 0.1.3 → 0.1.4

package/dist/index.d.mts

@@ -48,6 +48,48 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
  */
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
+/**
+ * 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.
  *
@@ -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

@@ -48,6 +48,48 @@ type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
  */
 declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
 
+/**
+ * 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.
  *
@@ -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-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 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;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-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 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.3",
+  "version": "0.1.4",
   "description": "Safe async/await utility for handling promises without try/catch.",
   "author": "Chelohub Inc. <npm@borislukrece.com>",
   "scripts": {