{"_id":"@arctics/graceful-executor","_rev":"3-4ec338181d24b41fefbfbdbfff752c56","name":"@arctics/graceful-executor","dist-tags":{"latest":"1.1.0"},"versions":{"0.0.1-dev":{"name":"@arctics/graceful-executor","version":"0.0.1-dev","keywords":["safe-execute","error-handling","async-await","typescript","utility"],"author":{"name":"Rajat Ninawe"},"license":"MIT","_id":"@arctics/graceful-executor@0.0.1-dev","maintainers":[{"name":"rajatninawe","email":"rajatninawe123@gmail.com"}],"homepage":"https://github.com/tyrog07/graceful-executor","bugs":{"url":"https://github.com/tyrog07/graceful-executor/issues"},"dist":{"shasum":"d789cfc4c8923bc17052a9a4cbfd51bdc5e53642","tarball":"https://registry.npmjs.org/@arctics/graceful-executor/-/graceful-executor-0.0.1-dev.tgz","fileCount":14,"integrity":"sha512-bWFZXq+Vt0McQzepzz3odBEjmwajQyAJGpdAjPqyugYY1PHgft1+AISRnPsQJs9mMktoAOEmICDOi6uloO4JTQ==","signatures":[{"sig":"MEUCIAc6Gj6plSazj3MYrJ0jNej/7sXY9ZqtUuTL2M5udFZrAiEA/rTSoHv+1ChAzeNNzCivTmifpEU7LP6+r8DYrf1eYD4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11236},"main":"dist/cjs/index.js","type":"module","types":"dist/types/index.d.ts","module":"dist/esm/index.js","gitHead":"e0a5d22d3728ea84ebdd24d8a86fe51c4eae2b6e","scripts":{"lint":"eslint . --ext .ts","test":"jest","build":"node build/build.js","prepare":"husky","prettify":"prettier --write ."},"_npmUser":{"name":"rajatninawe","email":"rajatninawe123@gmail.com"},"repository":{"url":"git+https://github.com/tyrog07/graceful-executor.git","type":"git"},"_npmVersion":"10.8.2","description":"A robust utility for safely executing async functions with centralized error handling and fallback values.","directories":{},"lint-staged":{"src/**/*.{js,jsx,ts,tsx}":["eslint --fix","prettier --write"]},"_nodeVersion":"20.18.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","zlib":"^1.0.5","husky":"^9.1.7","eslint":"^9.17.0","esbuild":"^0.25.0","ts-jest":"^29.2.5","prettier":"^3.4.2","typescript":"^5.7.2","@types/jest":"^29.5.14","lint-staged":"^15.4.3","esbuild-plugin-ts":"^0.1.1-rev-1.0","eslint-config-prettier":"^10.0.1","eslint-plugin-prettier":"^5.2.1","@typescript-eslint/parser":"^8.19.1","@typescript-eslint/eslint-plugin":"^8.19.1"},"_npmOperationalInternal":{"tmp":"tmp/graceful-executor_0.0.1-dev_1756283056157_0.15015449037443562","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@arctics/graceful-executor","version":"1.0.0","keywords":["safe-execute","error-handling","async-await","typescript","utility","error-handling-utility","try-catch-wrapper","promise-wrapper","typescript-library","error-management","async-error-handling","function-wrapper","safe-function-execution","error-recovery","graceful-error-handling","fallback-values","utility-library","typescript-utility","robust-error-handling","error-handler"],"author":{"name":"Rajat Ninawe"},"license":"MIT","_id":"@arctics/graceful-executor@1.0.0","maintainers":[{"name":"rajatninawe","email":"rajatninawe123@gmail.com"}],"homepage":"https://github.com/tyrog07/graceful-executor","bugs":{"url":"https://github.com/tyrog07/graceful-executor/issues"},"dist":{"shasum":"50c4ec5622842c22fc371354e6197b008a81c1ac","tarball":"https://registry.npmjs.org/@arctics/graceful-executor/-/graceful-executor-1.0.0.tgz","fileCount":14,"integrity":"sha512-3mRl42gCKhSjgejIMJF1Y66JV7dQdZnAFzu75vbSdyilhpOwk60/yn9GQSEAY1dHEZi0eiUoJkd2S2C00bGorQ==","signatures":[{"sig":"MEQCIE+W9xFoEu/3I+QgibiREBqRqCRq9GmRau44pxG1bfBnAiA1yfi5REQzTlqMa4069Grl2O2wYPdrM9cnLNHYsR90sw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14960},"main":"dist/cjs/index.js","type":"module","types":"dist/types/index.d.ts","module":"dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"gitHead":"087c0daac63930128ef725c34f7d367045a0d195","scripts":{"lint":"eslint . --ext .ts","test":"jest","build":"node build/build.js","prepare":"husky","prettify":"prettier --write ."},"_npmUser":{"name":"rajatninawe","email":"rajatninawe123@gmail.com"},"repository":{"url":"git+https://github.com/tyrog07/graceful-executor.git","type":"git"},"_npmVersion":"10.8.2","description":"A robust utility for safely executing async functions with centralized error handling and fallback values.","directories":{},"lint-staged":{"src/**/*.{js,jsx,ts,tsx}":["eslint --fix","prettier --write"]},"_nodeVersion":"20.18.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","zlib":"^1.0.5","husky":"^9.1.7","eslint":"^9.17.0","esbuild":"^0.25.0","ts-jest":"^29.2.5","prettier":"^3.4.2","typescript":"^5.7.2","@types/jest":"^29.5.14","lint-staged":"^15.4.3","esbuild-plugin-ts":"^0.1.1-rev-1.0","eslint-config-prettier":"^10.0.1","eslint-plugin-prettier":"^5.2.1","@typescript-eslint/parser":"^8.19.1","@typescript-eslint/eslint-plugin":"^8.19.1"},"_npmOperationalInternal":{"tmp":"tmp/graceful-executor_1.0.0_1756286330098_0.2385206394320103","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@arctics/graceful-executor","description":"A robust utility for safely executing async functions with centralized error handling and fallback values.","author":{"name":"Rajat Ninawe"},"version":"1.1.0","homepage":"https://github.com/tyrog07/graceful-executor","repository":{"type":"git","url":"git+https://github.com/tyrog07/graceful-executor.git"},"type":"module","main":"dist/cjs/index.js","module":"dist/esm/index.js","types":"dist/types/index.d.ts","exports":{".":{"require":"./dist/cjs/index.js","import":"./dist/esm/index.js"}},"license":"MIT","dependencies":{},"devDependencies":{"@types/jest":"^29.5.14","@typescript-eslint/eslint-plugin":"^8.19.1","@typescript-eslint/parser":"^8.19.1","esbuild":"^0.25.0","esbuild-plugin-ts":"^0.1.1-rev-1.0","eslint":"^9.17.0","eslint-config-prettier":"^10.0.1","eslint-plugin-prettier":"^5.2.1","husky":"^9.1.7","jest":"^29.7.0","lint-staged":"^15.4.3","prettier":"^3.4.2","ts-jest":"^29.2.5","typescript":"^5.7.2","zlib":"^1.0.5"},"scripts":{"build":"node build/build.js","lint":"eslint . --ext .ts","prettify":"prettier --write .","test":"jest","prepare":"husky"},"lint-staged":{"src/**/*.{js,jsx,ts,tsx}":["eslint --fix","prettier --write"]},"keywords":["safe-execute","error-handling","async-await","typescript","utility","error-handling-utility","try-catch-wrapper","promise-wrapper","typescript-library","error-management","async-error-handling","function-wrapper","safe-function-execution","error-recovery","graceful-error-handling","fallback-values","utility-library","typescript-utility","robust-error-handling","error-handler"],"_id":"@arctics/graceful-executor@1.1.0","gitHead":"b9d4cb77a16cd93af6ffbc9628364c7a3269ed0f","bugs":{"url":"https://github.com/tyrog07/graceful-executor/issues"},"_nodeVersion":"20.18.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-vNnQbeIX1TOYsy+NGo8A10+Fuvqnvlp79D+7C60yNuBbnAvo9iKdN8icJ50AIUlUlRcUH0i6tHSU/KAi4pzFYA==","shasum":"cac8dc77084b2420507834df13f0f132c2f56533","tarball":"https://registry.npmjs.org/@arctics/graceful-executor/-/graceful-executor-1.1.0.tgz","fileCount":19,"unpackedSize":23608,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDEbv6W/ZkYhg5d1ID1MZea4FtxV951AgqEkls4hQ1XmAiEAj2hQG8wtD6uKWooaRLtTuUmp4+nMsL6TavBwLu49xLA="}]},"_npmUser":{"name":"rajatninawe","email":"rajatninawe123@gmail.com"},"directories":{},"maintainers":[{"name":"rajatninawe","email":"rajatninawe123@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/graceful-executor_1.1.0_1757157486242_0.899682615744702"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-27T08:24:16.051Z","modified":"2025-09-06T11:18:06.638Z","0.0.1-dev":"2025-08-27T08:24:16.337Z","1.0.0":"2025-08-27T09:18:50.268Z","1.1.0":"2025-09-06T11:18:06.412Z"},"bugs":{"url":"https://github.com/tyrog07/graceful-executor/issues"},"author":{"name":"Rajat Ninawe"},"license":"MIT","homepage":"https://github.com/tyrog07/graceful-executor","keywords":["safe-execute","error-handling","async-await","typescript","utility","error-handling-utility","try-catch-wrapper","promise-wrapper","typescript-library","error-management","async-error-handling","function-wrapper","safe-function-execution","error-recovery","graceful-error-handling","fallback-values","utility-library","typescript-utility","robust-error-handling","error-handler"],"repository":{"type":"git","url":"git+https://github.com/tyrog07/graceful-executor.git"},"description":"A robust utility for safely executing async functions with centralized error handling and fallback values.","maintainers":[{"name":"rajatninawe","email":"rajatninawe123@gmail.com"}],"readme":"# @arctics/graceful-executor\n\n<div align=\"center\">\n\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/tyrog07/@arctics/graceful-executor/blob/HEAD/LICENSE)\n[![npm latest package](https://img.shields.io/npm/v/@arctics/graceful-executor/latest.svg)](https://www.npmjs.com/package/@arctics/graceful-executor)\n[![npm downloads](https://img.shields.io/npm/dm/@arctics/graceful-executor.svg)](https://www.npmjs.com/package/@arctics/graceful-executor)\n[![Checks](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/test.yml/badge.svg)](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/test.yml)\n[![Build](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/build.yml/badge.svg)](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/build.yml)\n[![CI](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/tyrog07/arctics-graceful-executor/actions/workflows/CI.yml)\n[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=@arctics/graceful-executor&query=$.install.pretty&label=install%20size)](https://packagephobia.now.sh/result?p=@arctics/graceful-executor)\n[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@arctics/graceful-executor)](https://bundlephobia.com/package/@arctics/graceful-executor@latest)\n[![Known Vulnerabilities](https://snyk.io/test/npm/@arctics/graceful-executor/badge.svg)](https://snyk.io/test/npm/@arctics/graceful-executor)\n\n</div>\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Features](#features)\n3. [Installation](#installation)\n4. [Usage](#usage)\n5. [Examples](#examples)\n6. [API Reference](#api-reference)\n7. [Contributing](#contributing)\n8. [License](#license)\n\n## Introduction\n\nTired of writing repetitive try...catch blocks? 😫 `@arctics/graceful-executor` is a lightweight, zero-dependency TypeScript utility that simplifies error handling for both synchronous and asynchronous functions.\n\nIt provides a clean, consistent way to execute functions, returning a predictable `[error, result]` tuple that eliminates boilerplate code and makes your logic cleaner and more robust.\n\n## Features\n\n- **Centralized Error Handling**: Configure a global error handler and a default return value for your entire application.\n- **Retries with Delay**: Automatically retry failed operations with configurable retry counts and delays.\n- **Timeout Support**: Abort long-running operations with a configurable timeout.\n- **Logging**: Enable detailed logs for successful executions, errors, and retries.\n- **Batch Execution**: Execute multiple functions in parallel and handle their results collectively.\n- **Per-Call Overrides**: Easily override global settings with specific options for individual function calls.\n- **Built-in Finally**: Use the optional `finally` callback for guaranteed cleanup actions.\n- **TypeScript-First**: Built with strong types to provide a safe and predictable development experience.\n- **Universal**: Works seamlessly with both async and synchronous functions.\n\n## Installation\n\n```bash\nnpm install @arctics/graceful-executor\n```\n\nor\n\n```bash\nyarn add @arctics/graceful-executor\n```\n\n## Usage\n\n### Importing the Library\n\nThe library supports both CommonJS and ES Modules:\n\n- **CommonJS**:\n\n  ```javascript\n  const {\n    safeExecute,\n    configureSafeExecute,\n  } = require('@arctics/graceful-executor');\n  ```\n\n- **ES Modules**:\n  ```javascript\n  import {\n    safeExecute,\n    configureSafeExecute,\n  } from '@arctics/graceful-executor';\n  ```\n\n### Configuration\n\nYou can configure global behavior for `safeExecute` using `configureSafeExecute`. This allows you to set a global error handler and a default fallback value.\n\n```javascript\nimport { configureSafeExecute } from '@arctics/graceful-executor';\n\nconfigureSafeExecute({\n  errorHandler: (error) => console.error('Global Error:', error),\n  defaultValue: 'default value',\n});\n```\n\n## Examples\n\n### Synchronous Example\n\n```javascript\nimport { safeExecute } from '@arctics/graceful-executor';\n\nfunction syncFunction() {\n  if (Math.random() > 0.5) {\n    throw new Error('Random sync error');\n  }\n  return 'Sync success';\n}\n\nconst [error, result] = safeExecute(syncFunction);\n\nif (error) {\n  console.error('Sync Error:', error.message);\n} else {\n  console.log('Sync Result:', result);\n}\n```\n\n### Asynchronous Example\n\n```javascript\nimport { safeExecute } from '@arctics/graceful-executor';\n\nasync function asyncFunction() {\n  if (Math.random() > 0.5) {\n    throw new Error('Random async error');\n  }\n  return 'Async success';\n}\n\n(async () => {\n  const [error, result] = await safeExecute(asyncFunction);\n\n  if (error) {\n    console.error('Async Error:', error.message);\n  } else {\n    console.log('Async Result:', result);\n  }\n})();\n```\n\n### Retry Logic\n\n```javascript\nimport { safeExecute } from '@arctics/graceful-executor';\n\nlet attempt = 0;\nfunction retryFunction() {\n  attempt++;\n  if (attempt < 3) {\n    throw new Error('Retry error');\n  }\n  return 'Success after retries';\n}\n\nconst [error, result] = await safeExecute(retryFunction, {\n  retries: 2,\n  retryDelay: 1000, // 1 second delay between retries\n});\n\nconsole.log('Error:', error);\nconsole.log('Result:', result);\n```\n\n### Timeout Support\n\n```javascript\nimport { safeExecute } from '@arctics/graceful-executor';\n\nasync function longRunningFunction() {\n  await new Promise((resolve) => setTimeout(resolve, 5000)); // Simulate a 5-second delay\n  return 'Completed';\n}\n\nconst [error, result] = await safeExecute(longRunningFunction, {\n  timeout: 3000, // 3-second timeout\n});\n\nconsole.log('Error:', error); // Logs timeout error\nconsole.log('Result:', result); // Logs null\n```\n\n### Logging\n\n```javascript\nimport { safeExecute } from '@arctics/graceful-executor';\n\nfunction exampleFunction() {\n  return 'Logging example success';\n}\n\nconst [error, result] = await safeExecute(exampleFunction, {\n  logging: true, // Enable logging\n});\n```\n\n### Batch Execution\n\n```javascript\nimport { safeExecuteBatch } from '@arctics/graceful-executor';\n\nasync function task1() {\n  return 'Task 1 completed';\n}\n\nasync function task2() {\n  throw new Error('Task 2 failed');\n}\n\nasync function task3() {\n  return 'Task 3 completed';\n}\n\nconst results = await safeExecuteBatch([task1, task2, task3]);\n\nconsole.log(results);\n// Output:\n// [\n//   [null, 'Task 1 completed'],\n//   [Error: Task 2 failed, null],\n//   [null, 'Task 3 completed']\n// ]\n```\n\n## API Reference\n\n### `safeExecute(fn, options?)`\n\nSafely executes a function and returns a tuple `[error, result]`.\n\n- **Parameters**:\n  - `fn`: The function to execute (can be synchronous or asynchronous).\n  - `options` (optional): An object with the following properties:\n    - `errorHandler`: A custom error handler for this specific call.\n    - `defaultValue`: A fallback value to return if an error occurs.\n    - `finally`: A callback function to execute after the operation.\n    - `retries`: Number of retry attempts if the function fails.\n    - `retryDelay`: Delay (in milliseconds) between retries.\n    - `timeout`: Maximum time (in milliseconds) to wait for the function to complete.\n    - `logging`: Enable logging for the execution process.\n    - `context`: Additional metadata to pass to the error handler.\n\n- **Returns**: A tuple `[error, result]`.\n\n### `safeExecuteBatch(fns, options?)`\n\nExecutes multiple functions in parallel and returns an array of `[error, result]` tuples.\n\n- **Parameters**:\n  - `fns`: Array of functions to execute.\n  - `options`: Configuration options for each execution.\n\n- **Returns**: An array of `[error, result]` tuples.\n\n### `configureSafeExecute(config)`\n\nConfigures global behavior for `safeExecute`.\n\n- **Parameters**:\n  - `config`: An object with the following properties:\n    - `errorHandler`: A global error handler.\n    - `defaultValue`: A global fallback value.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/tyrog07/arctics-graceful-executor/blob/HEAD/LICENSE).\n","readmeFilename":"README.md"}