{"id":48376987,"url":"https://github.com/mcking-07/safe-wrapper","last_synced_at":"2026-04-05T18:35:13.400Z","repository":{"id":259734417,"uuid":"879086996","full_name":"mcking-07/safe-wrapper","owner":"mcking-07","description":"a lightweight utility for typescript/javascript that simplifies error handling for both synchronous and asynchronous functions.","archived":false,"fork":false,"pushed_at":"2025-05-31T22:17:41.000Z","size":48,"stargazers_count":31,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-13T13:44:13.694Z","etag":null,"topics":["error-handling","safe-assignment","try-catch"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/safe-wrapper","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcking-07.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-26T23:50:35.000Z","updated_at":"2025-10-12T07:48:28.000Z","dependencies_parsed_at":"2024-10-27T17:43:11.815Z","dependency_job_id":"b2c60d4c-8a1e-4714-a6d8-bb434bab3a88","html_url":"https://github.com/mcking-07/safe-wrapper","commit_stats":null,"previous_names":["mcking-07/safe-wrapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mcking-07/safe-wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcking-07%2Fsafe-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcking-07%2Fsafe-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcking-07%2Fsafe-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcking-07%2Fsafe-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcking-07","download_url":"https://codeload.github.com/mcking-07/safe-wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcking-07%2Fsafe-wrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31446529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-handling","safe-assignment","try-catch"],"created_at":"2026-04-05T18:35:11.943Z","updated_at":"2026-04-05T18:35:13.392Z","avatar_url":"https://github.com/mcking-07.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## safe-wrapper\n\n[![npm version](https://img.shields.io/npm/v/safe-wrapper.svg)](https://www.npmjs.com/package/safe-wrapper)\n[![License](https://img.shields.io/npm/l/safe-wrapper.svg)](https://github.com/mcking-07/safe-wrapper/blob/main/LICENSE)\n[![Build Status](https://github.com/mcking-07/safe-wrapper/workflows/publish/badge.svg)](https://github.com/mcking-07/safe-wrapper/actions)\n[![npm downloads](https://img.shields.io/npm/dm/safe-wrapper.svg)](https://www.npmjs.com/package/safe-wrapper)\n\nsafe-wrapper is a lightweight, typescript-first utility that simplifies error handling for both synchronous and asynchronous functions. inspired by the [safe assignment operator proposal](https://github.com/arthurfiorette/proposal-safe-assignment-operator), this utility allows for graceful error management by wrapping functions in a way that enables error handling without the need for explicit `try-catch` blocks.\n\nin modern javascript and typescript, dealing with functions that might throw errors (especially in asynchronous operations or third-party libraries) often leads to repetitive boilerplate. safe-wrapper offers a cleaner and a more functional approach by reducing boilerplate, enabling full typescript support for type inference, and allowing for flexible error handling by letting you filter specific error types, or transform them into custom formats.\n\n### Features\n\n- handles synchronous and asynchronous functions.\n- supports specifying error types to control which errors are caught and handled.\n- returns a consistent response in `[error, result]` format,\n  - `error`: null if successful, else an error (or transformed object).\n  - `result`: return value (sync) or resolved value (async) when successful, else null.\n- supports custom error transformation for advanced error handling.\n- written in typescript with comprehensive type definitions, enabling full type inference support.\n\n### Installation\n\n```sh\nnpm install safe-wrapper\n```\n\n### Usage\n\nimport `safe` from `safe-wrapper` to use it with any function. the types for `error` and `result` are automatically inferred.\n\nthe `safe` function takes a target function (synchronous or asynchronous) and returns a function which handles errors and returns a response in a consistent way. the function returns an array `[error, result]`, where `error` is an instance of the specified error type or `null` if successful, and `result` is the result of the function when there is no error.\n\n#### directly wrapping functions\n\nwe can directly wrap any function definition with safe.\n\n```javascript\nimport { safe } from 'safe-wrapper';\n\nconst safeSync = safe((args) =\u003e {\n  throw new Error('sync error occurred');\n});\n\nconst safeAsync = safe(async (args) =\u003e {\n  throw new Error('async error occurred');\n});\n\nconst [error, result] = await safeAsync(args);\n```\n\n#### wrapping existing functions\n\nsafe can be applied to pre-existing functions, including ones from third-party libraries.\n\n```javascript\nimport { safe } from 'safe-wrapper';\n\nconst sync = (args) =\u003e {\n  throw new Error('sync error occurred');\n}\n\nconst safeSync = safe(sync);\nconst [error, result] = safeSync(args);\n```\n\n#### handling specific error types\n\nwe can specify error types to catch, allowing other errors to throw.\n\n```javascript\nimport { safe } from 'safe-wrapper';\n\nconst safeAsync = safe(async (args) =\u003e {\n  throw new TypeError('async type error occurred');\n}, [TypeError]);\n\nconst [error, result] = await safeAsync(args);\n```\n\n#### handling multiple error types\n\nwe can specify multiple error types when wrapping a function, enabling safe to catch any of the specified errors.\n\n```typescript\nimport { safe } from 'safe-wrapper';\n\nconst sync = (args: boolean): string =\u003e {\n  if (args) {\n    throw new TypeError('sync type error occurred');\n  } else {\n    throw new RangeError('sync range error occurred');\n  }\n}\n\nconst safeSync = safe(sync, [TypeError, RangeError]);\nconst [error, result] = safeSync(args);\n```\n\n#### using synchronous custom error transformer\n\nyou can provide a custom error transformer function to modify how errors are handled:\n\n```typescript\nimport { safe } from 'safe-wrapper';\n\ntype TransformedError = { code: string, message: string, timestamp: Date };\n\nconst transformer = (error: Error): TransformedError =\u003e ({\n  code: error.name,\n  message: error.message,\n  timestamp: new Date()\n});\n\nconst safeWithTransform = safe(\n  () =\u003e { throw new Error('custom sync error'); },\n  [Error],\n  transformer\n);\n\nconst [error, result] = safeWithTransform();\n// error will be of type TransformedError as: { code: 'Error', message: 'custom sync error', timestamp: Date }\n```\n\n#### using asynchronous custom error transformer\n\nyou can provide an asynchronous custom error transformer to modify how errors are handled.\n\n```typescript\nimport { safe } from 'safe-wrapper';\n\ntype AsyncTransformedError = { code: string, message: string, timestamp: Date };\n\nconst transformer = async (error: Error): Promise\u003cAsyncTransformedError\u003e =\u003e {\n  await report(error);\n\n  return {\n    code: error.name,\n    message: error.message,\n    timestamp: new Date()\n  }\n}\n\nconst safeWithTransform = safe(\n  async () =\u003e { throw new Error('custom async error'); },\n  [Error],\n  transformer\n);\n\nconst [error, result] = await safeWithTransform();\n// error will be of type AsyncTransformedError as: { code: 'Error', message: 'custom async error', timestamp: Date }\n```\n\n#### wrapping built-in functions\n\nwe can also wrap built-in functions, like `JSON.parse`, `Object.keys`, and more.\n\n```javascript\nimport { safe } from 'safe-wrapper';\n\nconst safeJsonParse = safe(JSON.parse);\nconst [error, result] = safeJsonParse('invalid_json');\n\nconst [error, result] = safe(Object.keys, [TypeError])(null);\n```\n\n### API Reference\n\n`safe(action, types, transformer)`\n\n- parameters\n  - action (function): function to be wrapped. it can either be synchronous or asynchronous.\n  - types (array, optional): an array of error types to catch. if no types are specified, all errors are caught. each element must be a valid error constructor.\n  - transformer (function, optional): a function that takes an error object and returns a transformed version of it. if not provided, the original error is used.\n- returns `[error, result]`\n  - error (error | null): the error object if error occurred, otherwise null. if an transformer is provided, this will be the transformed error.\n  - result (result | null): the result of the action function if no error occurred, otherwise null.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcking-07%2Fsafe-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcking-07%2Fsafe-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcking-07%2Fsafe-wrapper/lists"}