safe-await-lib 0.1.2

package/README.md

@@ -0,0 +1,184 @@
+# SAFE-AWAIT
+
+[![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)
+
+Safe async/await utility for handling promises without try/catch.  
+Designed for **Node.js**, **TypeScript**, **React**, **React Native**, and **Expo**.
+
+---
+
+## 📌 Why SAFE-AWAIT?
+
+Traditional async/await patterns require `try/catch` blocks, which can clutter code and make error handling inconsistent.  
+
+**SAFE-AWAIT solves this problem by:**
+
+- Returning a consistent `[SafeError | null, T | null]` tuple for every async operation
+- Normalizing errors into a predictable format
+- Eliminating boilerplate `try/catch` blocks
+- Making code cleaner, safer, and easier to maintain
+
+---
+
+## 🚀 Features
+
+- Safe execution of async functions and promises
+- Standardized error handling with `SafeError` objects
+- Fully TypeScript-typed for modern development
+- Compatible with Node.js, React, React Native, and Expo
+- Supports dual module output (ESM + CJS)
+- Tree-shakable for modern bundlers
+- Future-ready with planned modules: `withTimeout`, `retry`, `all`, `allSettled`, `once`, `strict`, `map`, `unwrap`, `mockSuccess`, `mockError`, `debug`
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install safe-await
+
+# yarn
+yarn add safe-await
+
+# pnpm
+pnpm add safe-await
+````
+
+---
+
+## ⚡ Basic Usage
+
+```ts
+import safe from 'safe-await';
+
+// Async function
+async function fetchData() {
+  return Promise.resolve('Hello World!');
+}
+
+// Using safe
+const [err, data] = await safe(fetchData);
+
+if (err) {
+  console.error(err.message);
+} else {
+  console.log(data); // 'Hello World!'
+}
+
+// Direct promise usage
+const [err2, result] = await safe(Promise.resolve(42));
+```
+
+---
+
+## 🛠️ API Overview
+
+### `safe(input: SafeInput<T>): SafeResult<T>`
+
+- **input**: `Promise<T>` or `() => T | Promise<T>`
+- **returns**: `[SafeError | null, T | null]`
+
+### `SafeError` Structure
+
+```ts
+interface SafeError {
+  message: string;   // Human-readable message
+  code: string;      // Standardized error code
+  cause?: unknown;   // Original error or additional context
+}
+```
+
+---
+
+## 🌱 Advanced Usage Examples
+
+### Handling multiple async operations
+
+```ts
+// Future module: safe.all
+const [err, results] = await safe.all([fetchData(), Promise.resolve(10)]);
+```
+
+### Using retry (planned in v0.2.0)
+
+```ts
+const [err, data] = await safe.retry(() => fetchData(), { attempts: 3, delay: 500 });
+```
+
+---
+
+## 📊 Roadmap
+
+| Version | Features Planned       |
+| ------- | ---------------------- |
+| v0.2.0  | withTimeout, retry     |
+| v0.3.0  | all, allSettled        |
+| v0.4.0  | withContext            |
+| v0.5.0  | once                   |
+| v0.6.0  | strict                 |
+| v0.7.0  | map, unwrap            |
+| v0.8.0  | mockSuccess, mockError |
+| v0.9.0  | debug                  |
+
+---
+
+## 🧪 Development
+
+```bash
+# Install dev dependencies
+npm install
+
+# Run development build with watch
+npm run dev
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+
+# Build for distribution
+npm run build
+```
+
+---
+
+## 📝 Contributing
+
+SAFE-AWAIT welcomes contributions!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Run tests locally (`npm test`)
+4. Submit a pull request
+
+Please adhere to the existing **TypeScript typings** and **code style**.
+
+---
+
+## ❓ FAQ / Tips
+
+- **Why use `[SafeError | null, T | null]` instead of try/catch?**
+  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.
+
+- **How do I handle retries or timeouts?**
+  Future modules like `retry` and `withTimeout` will handle these cases cleanly.
+
+---
+
+## 📖 License
+
+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)

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Standardized error object used throughout the SAFE-AWAIT package.
+ *
+ * Every error returned by `safe()` or its extensions follows this shape,
+ * ensuring consistent and predictable error handling.
+ */
+interface SafeError {
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code */
+    code: string;
+    /** Original error or additional context, if available */
+    cause?: unknown;
+}
+/**
+ * Standard return type for all SAFE-AWAIT operations.
+ *
+ * The result is always a tuple:
+ * - `[null, T]` when the operation succeeds
+ * - `[SafeError, null]` when the operation fails
+ *
+ * This pattern eliminates the need for try/catch blocks.
+ */
+type SafeResult<T> = Promise<[SafeError | null, T | null]>;
+/**
+ * Accepted input type for the `safe()` function.
+ *
+ * Allows passing either:
+ * - a Promise
+ * - a function returning a value or a Promise
+ *
+ * This enables lazy execution and consistent error handling.
+ */
+type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
+
+/**
+ * Internal execution engine for SAFE-AWAIT.
+ *
+ * This function executes a promise or a function safely and converts
+ * 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.).
+ *
+ * @param input - A promise or a function returning a value or a promise
+ *
+ * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple
+ */
+declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
+
+/**
+ * `safe` is the core function of the SAFE-AWAIT 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";
+ *
+ * const [err, data] = await safe(async () => fetchData());
+ *
+ * if (err) {
+ *   console.error(err.message, err.code);
+ * } else {
+ *   console.log(data);
+ * }
+ * ```
+ *
+ * ## Philosophy
+ * - No try/catch pollution
+ * - No unhandled promise rejections
+ * - Explicit error handling
+ *
+ * ## Planned extensions
+ * - v0.2.0: withTimeout, retry
+ * - v0.3.0: all, allSettled
+ * - v0.4.0: withContext
+ * - v0.5.0: once
+ * - v0.6.0: strict
+ * - v0.7.0: map, unwrap
+ * - v0.8.0: mockSuccess, mockError
+ * - v0.9.0: debug
+ *
+ * ## Return value
+ * Always returns a tuple:
+ * - `[null, result]` on success
+ * - `[SafeError, null]` on failure
+ */
+declare const safe: typeof coreSafe;
+
+export { safe as default, safe };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Standardized error object used throughout the SAFE-AWAIT package.
+ *
+ * Every error returned by `safe()` or its extensions follows this shape,
+ * ensuring consistent and predictable error handling.
+ */
+interface SafeError {
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code */
+    code: string;
+    /** Original error or additional context, if available */
+    cause?: unknown;
+}
+/**
+ * Standard return type for all SAFE-AWAIT operations.
+ *
+ * The result is always a tuple:
+ * - `[null, T]` when the operation succeeds
+ * - `[SafeError, null]` when the operation fails
+ *
+ * This pattern eliminates the need for try/catch blocks.
+ */
+type SafeResult<T> = Promise<[SafeError | null, T | null]>;
+/**
+ * Accepted input type for the `safe()` function.
+ *
+ * Allows passing either:
+ * - a Promise
+ * - a function returning a value or a Promise
+ *
+ * This enables lazy execution and consistent error handling.
+ */
+type SafeInput<T> = Promise<T> | (() => T | Promise<T>);
+
+/**
+ * Internal execution engine for SAFE-AWAIT.
+ *
+ * This function executes a promise or a function safely and converts
+ * 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.).
+ *
+ * @param input - A promise or a function returning a value or a promise
+ *
+ * @returns A Promise resolving to a `[SafeError | null, T | null]` tuple
+ */
+declare function coreSafe<T>(input: SafeInput<T>): SafeResult<T>;
+
+/**
+ * `safe` is the core function of the SAFE-AWAIT 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";
+ *
+ * const [err, data] = await safe(async () => fetchData());
+ *
+ * if (err) {
+ *   console.error(err.message, err.code);
+ * } else {
+ *   console.log(data);
+ * }
+ * ```
+ *
+ * ## Philosophy
+ * - No try/catch pollution
+ * - No unhandled promise rejections
+ * - Explicit error handling
+ *
+ * ## Planned extensions
+ * - v0.2.0: withTimeout, retry
+ * - v0.3.0: all, allSettled
+ * - v0.4.0: withContext
+ * - v0.5.0: once
+ * - v0.6.0: strict
+ * - v0.7.0: map, unwrap
+ * - v0.8.0: mockSuccess, mockError
+ * - v0.9.0: debug
+ *
+ * ## Return value
+ * Always returns a tuple:
+ * - `[null, result]` on success
+ * - `[SafeError, null]` on failure
+ */
+declare const safe: typeof coreSafe;
+
+export { safe as default, safe };

package/dist/index.js

@@ -0,0 +1,107 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  safe: () => safe
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/codes.ts
+var ERROR_CODES = {
+  /** Fallback error for unknown or unhandled failures */
+  UNKNOWN: "UNKNOWN_ERROR",
+  /** Thrown when an operation exceeds a configured timeout */
+  TIMEOUT: "TIMEOUT_ERROR",
+  /** Used when all retry attempts have failed */
+  RETRY_FAILED: "RETRY_FAILED",
+  /** Used when an operation is explicitly aborted or cancelled */
+  ABORTED: "ABORT_ERROR",
+  /** Used when input validation fails */
+  VALIDATION: "VALIDATION_ERROR",
+  /** Used when a function guarded by `once()` is called more than once */
+  EXECUTION_ONCE: "ALREADY_EXECUTED"
+};
+
+// src/errors/formatter.ts
+function formatError(err, defaultCode = ERROR_CODES.UNKNOWN) {
+  var _a;
+  if (err instanceof Error) {
+    const errorWithCause = err;
+    return {
+      message: err.message,
+      code: err.code || defaultCode,
+      cause: (_a = errorWithCause.cause) != null ? _a : err
+    };
+  }
+  if (typeof err === "string") {
+    return {
+      message: err,
+      code: defaultCode
+    };
+  }
+  return {
+    message: "An unexpected error occurred",
+    code: defaultCode,
+    cause: err
+  };
+}
+
+// src/core/safe.ts
+async function coreSafe(input) {
+  try {
+    const promise = typeof input === "function" ? input() : input;
+    const data = await promise;
+    return [null, data];
+  } catch (error) {
+    return [formatError(error), null];
+  }
+}
+
+// src/index.ts
+var safe = Object.assign(coreSafe, {
+  // v0.2.0
+  // withTimeout,
+  // retry,
+  // v0.3.0
+  // all,
+  // allSettled,
+  // v0.4.0
+  // withContext,
+  // v0.5.0
+  // once,
+  // v0.6.0
+  // strict,
+  // v0.7.0
+  // map,
+  // unwrap,
+  // v0.8.0
+  // mockSuccess,
+  // mockError,
+  // v0.9.0
+  // debug,
+});
+var index_default = safe;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  safe
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/dist/index.mjs

@@ -0,0 +1,80 @@
+// src/errors/codes.ts
+var ERROR_CODES = {
+  /** Fallback error for unknown or unhandled failures */
+  UNKNOWN: "UNKNOWN_ERROR",
+  /** Thrown when an operation exceeds a configured timeout */
+  TIMEOUT: "TIMEOUT_ERROR",
+  /** Used when all retry attempts have failed */
+  RETRY_FAILED: "RETRY_FAILED",
+  /** Used when an operation is explicitly aborted or cancelled */
+  ABORTED: "ABORT_ERROR",
+  /** Used when input validation fails */
+  VALIDATION: "VALIDATION_ERROR",
+  /** Used when a function guarded by `once()` is called more than once */
+  EXECUTION_ONCE: "ALREADY_EXECUTED"
+};
+
+// src/errors/formatter.ts
+function formatError(err, defaultCode = ERROR_CODES.UNKNOWN) {
+  var _a;
+  if (err instanceof Error) {
+    const errorWithCause = err;
+    return {
+      message: err.message,
+      code: err.code || defaultCode,
+      cause: (_a = errorWithCause.cause) != null ? _a : err
+    };
+  }
+  if (typeof err === "string") {
+    return {
+      message: err,
+      code: defaultCode
+    };
+  }
+  return {
+    message: "An unexpected error occurred",
+    code: defaultCode,
+    cause: err
+  };
+}
+
+// src/core/safe.ts
+async function coreSafe(input) {
+  try {
+    const promise = typeof input === "function" ? input() : input;
+    const data = await promise;
+    return [null, data];
+  } catch (error) {
+    return [formatError(error), null];
+  }
+}
+
+// src/index.ts
+var safe = Object.assign(coreSafe, {
+  // v0.2.0
+  // withTimeout,
+  // retry,
+  // v0.3.0
+  // all,
+  // allSettled,
+  // v0.4.0
+  // withContext,
+  // v0.5.0
+  // once,
+  // v0.6.0
+  // strict,
+  // v0.7.0
+  // map,
+  // unwrap,
+  // v0.8.0
+  // mockSuccess,
+  // mockError,
+  // v0.9.0
+  // debug,
+});
+var index_default = safe;
+export {
+  index_default as default,
+  safe
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "safe-await-lib",
+  "version": "0.1.2",
+  "description": "Safe async/await utility for handling promises without try/catch.",
+  "author": "Chelohub Inc. <npm@borislukrece.com>",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "release:patch": "npm version patch && git push origin HEAD --follow-tags",
+    "release:minor": "npm version minor && git push origin HEAD --follow-tags",
+    "release:major": "npm version major && git push origin HEAD --follow-tags",
+    "test": "vitest"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chelohubinc/safe-await"
+  },
+  "keywords": [
+    "async",
+    "await",
+    "promise",
+    "error-handling",
+    "try-catch",
+    "result",
+    "typescript",
+    "react-native",
+    "expo"
+  ],
+  "license": "ISC",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  }
+}