safe-wrapper 2.0.0 → 2.0.1

package/README.md

@@ -1,22 +1,28 @@
 ## safe-wrapper
 
+[![npm version](https://img.shields.io/npm/v/safe-wrapper.svg)](https://www.npmjs.com/package/safe-wrapper)
+[![License](https://img.shields.io/npm/l/safe-wrapper.svg)](https://github.com/mcking-07/safe-wrapper/blob/main/LICENSE)
+[![Build Status](https://github.com/mcking-07/safe-wrapper/workflows/publish/badge.svg)](https://github.com/mcking-07/safe-wrapper/actions)
+[![npm downloads](https://img.shields.io/npm/dm/safe-wrapper.svg)](https://www.npmjs.com/package/safe-wrapper)
+
 safe-wrapper is a lightweight utility for javascript 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.
 
-#### Features
+### Features
 
 - handles synchronous and asynchronous functions.
 - supports specifying error types to control which errors are caught and handled.
 - returns consistent responses in `[error, result]` format where error is null if no error occurred.
+- supports custom error transformation for advanced error handling.
 
-#### Installation
+### Installation
 
-```
+```sh
 npm install safe-wrapper
 ```
 
-#### Usage
+### Usage
 
-import `safe` from `safe-wrapper` to use it with any function. 
+import `safe` from `safe-wrapper` to use it with any function.
 
 the `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.
 
@@ -86,6 +92,29 @@ const safeSync = safe(sync, [TypeError, RangeError]);
 const [error, result] = safeSync(args);
 ```
 
+#### using custom error transformer
+
+you can provide a custom error transformer function to modify how errors are handled:
+
+```javascript
+import { safe } from 'safe-wrapper';
+
+const transformer = (error) => ({
+  code: error.name,
+  message: error.message,
+  timestamp: new Date()
+});
+
+const safeWithTransform = safe(
+  () => { throw new Error('custom error'); },
+  [Error],
+  transformer
+);
+
+const [error, result] = safeWithTransform();
+// error will be: { code: 'Error', message: 'custom error', timestamp: Date }
+```
+
 #### wrapping built-in functions
 
 we can also wrap built-in functions, like `JSON.parse`, `Object.keys`, and more.
@@ -99,14 +128,14 @@ const [error, result] = safeJsonParse('invalid_json');
 const [error, result] = safe(Object.keys, [TypeError])(null);
 ```
 
-#### API Reference
+### API Reference
+
+`safe(action, types, transformer)`
 
-`safe(action, types)`
 - parameters
   - action (function): function to be wrapped. it can either be synchronous or asynchronous.
-  - types (array, optional): an array of error types to catch. if no types are specified, all errors are caught.
+  - 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.
+  - 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.
 - returns `[error, result]`
-  - error (error | null): the error object if error occurred, otherwise null.
+  - error (error | null): the error object if error occurred, otherwise null. if an transformer is provided, this will be the transformed error.
   - result (any): the result of the action function if no error occurred, otherwise null.
-
-this structure keeps it concise, approachable, and clear for all levels of users.

package/lib/index.cjs

@@ -1 +1 @@
-"use strict";var o=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var f=(t,n)=>{for(var r in n)o(t,r,{get:n[r],enumerable:!0})},i=(t,n,r,e)=>{if(n&&typeof n=="object"||typeof n=="function")for(let c of a(n))!h.call(t,c)&&c!==r&&o(t,c,{get:()=>n[c],enumerable:!(e=l(n,c))||e.enumerable});return t};var b=t=>i(o({},"__esModule",{value:!0}),t);var m={};f(m,{safe:()=>g});module.exports=b(m);var s=({error:t=null,data:n=null,result:r=null})=>[t,r||n],u=(t,n=[])=>{if(!n.length||n.some(e=>t instanceof e))return s({error:t});throw t},g=(t,n=[])=>(...r)=>{try{let e=t(...r);return e instanceof Promise?e.then(c=>s({data:c})).catch(c=>u(c,n)):s({result:e})}catch(e){return u(e,n)}};
+"use strict";var s=Object.defineProperty;var i=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var h=(e,n)=>{for(var t in n)s(e,t,{get:n[t],enumerable:!0})},d=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let c of a(n))!l.call(e,c)&&c!==t&&s(e,c,{get:()=>n[c],enumerable:!(r=i(n,c))||r.enumerable});return e};var m=e=>d(s({},"__esModule",{value:!0}),e);var P={};h(P,{safe:()=>g});module.exports=m(P);var o=({error:e=null,data:n=null,result:t=null})=>[e,t||n],b=e=>(...n)=>{try{let t=e(...n);return t instanceof Promise?t.then(r=>o({error:r})).catch(r=>o({error:r})):o({error:t})}catch(t){return o({error:t})}},f=(e,n=[],t=void 0)=>{let r=!n.length||n.some(u=>e instanceof u),c=t!==void 0&&typeof t=="function";if(r)return c?b(t)(e):o({error:e});throw e},g=(e,n=[],t=void 0)=>(...r)=>{try{let c=e(...r);return c instanceof Promise?c.then(u=>o({data:u})).catch(u=>f(u,n,t)):o({result:c})}catch(c){return f(c,n,t)}};

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * safely executes a synchronous or asynchronous action, handles any errors that occur and returns the result in a consistent response structure.
+ *
  * @param {Function} action - the function to be wrapped, which can either be synchronous or asynchronous.
  * @param {Array<ErrorConstructor>} [types = []] - an optional array of error types to check against.
+ * @param {Function} [transformer = undefined] - an optional function to transform the error object.
  * @returns {Promise<[Error, null] | [null, any]> | [Error, null] | [null, any]} - a tuple where the first element is null, if the execution was successful, or an error object if an error occurred. the second element is the result of the action, if available.
  */
-export function safe(action: Function, types?: ErrorConstructor[] | undefined): Promise<[Error, null] | [null, any]> | [Error, null] | [null, any];
+export function safe(action: Function, types?: Array<ErrorConstructor>, transformer?: Function): Promise<[Error, null] | [null, any]> | [Error, null] | [null, any];

package/lib/index.mjs

@@ -1 +1 @@
-var o=({error:n=null,data:t=null,result:r=null})=>[n,r||t],s=(n,t=[])=>{if(!t.length||t.some(e=>n instanceof e))return o({error:n});throw n},u=(n,t=[])=>(...r)=>{try{let e=n(...r);return e instanceof Promise?e.then(c=>o({data:c})).catch(c=>s(c,t)):o({result:e})}catch(e){return s(e,t)}};export{u as safe};
+var o=({error:t=null,data:e=null,result:n=null})=>[t,n||e],f=t=>(...e)=>{try{let n=t(...e);return n instanceof Promise?n.then(c=>o({error:c})).catch(c=>o({error:c})):o({error:n})}catch(n){return o({error:n})}},s=(t,e=[],n=void 0)=>{let c=!e.length||e.some(u=>t instanceof u),r=n!==void 0&&typeof n=="function";if(c)return r?f(n)(t):o({error:t});throw t},i=(t,e=[],n=void 0)=>(...c)=>{try{let r=t(...c);return r instanceof Promise?r.then(u=>o({data:u})).catch(u=>s(u,e,n)):o({result:r})}catch(r){return s(r,e,n)}};export{i as safe};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safe-wrapper",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "a js-util for safely wrapping synchronous and asynchronous functions to handle errors based on specified types.",
   "type": "module",
   "main": "lib/index.cjs",