safe-wrapper 1.0.7 → 2.0.1

package/README.md

@@ -1,107 +1,141 @@
 ## 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 returning a tuple of the result and error, making it easy to handle various error types.
+[![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)
 
-#### Installation
+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
+
+- 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
+
+```sh
 npm install safe-wrapper
 ```
 
-#### Usage
+### Usage
 
-import `safe` from `safe-wrapper` to use it with any function. it takes the result of a function as its first argument and an optional array of `error types` to catch as the second argument. 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.
+import `safe` from `safe-wrapper` to use it with any function.
 
-#### synchronous example
+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.
 
-in this example, we handle a synchronous function that may return an error.
+#### directly wrapping functions
+
+we can directly wrap any function definition with safe.
 
 ```javascript
 import { safe } from 'safe-wrapper';
 
-const sync = () => {
-  return new Error('sync error occurred');
-}
-
-const [error, result] = safe(sync());
+const safeSync = safe((args) => {
+  throw new Error('sync error occurred');
+});
 
-if (error) {
-  return handle(error);
-}
+const safeAsync = safe(async (args) => {
+  throw new Error('async error occurred');
+});
 
-return handle(result);
+const [error, result] = await safeAsync(args);
 ```
 
-#### synchronous example with error type check
+#### wrapping existing functions
 
-we can specify error types to catch specific errors. if an unknown error type occurs, it will be thrown instead.
+safe can be applied to pre-existing functions, including ones from third-party libraries.
 
 ```javascript
 import { safe } from 'safe-wrapper';
 
-const sync = () => {
-  return new TypeError('sync type error occurred');
-}
-
-const [error, result] = safe(sync(), [TypeError]);
-
-if (error) {
-  return handle(error);
+const sync = (args) => {
+  throw new Error('sync error occurred');
 }
 
-return handle(result);
+const safeSync = safe(sync);
+const [error, result] = safeSync(args);
 ```
 
-#### asynchronous example
+#### handling specific error types
 
-in this example, we handle a synchronous function that may throw an error.
+we can specify error types to catch, allowing other errors to throw.
 
 ```javascript
 import { safe } from 'safe-wrapper';
 
-const async = () => {
-  throw new Error('async error occurred');
-}
+const safeAsync = safe(async (args) => {
+  throw new TypeError('async type error occurred');
+}, [TypeError]);
 
-const [error, result] = await safe(async());
+const [error, result] = await safeAsync(args);
+```
 
-if (error) {
-  return handle(error);
+#### handling multiple error types
+
+we can specify multiple error types when wrapping a function, enabling safe to catch any of the specified errors.
+
+```javascript
+import { safe } from 'safe-wrapper';
+
+const sync = (args) => {
+  if (args) {
+    throw new TypeError('sync type error occurred');
+  } else {
+    throw new RangeError('sync range error occurred');
+  }
 }
 
-return handle(result);
+const safeSync = safe(sync, [TypeError, RangeError]);
+const [error, result] = safeSync(args);
 ```
 
-#### asynchronous example with error type check
+#### using custom error transformer
 
-we can specify error types with asynchronous functions as well.
+you can provide a custom error transformer function to modify how errors are handled:
 
 ```javascript
 import { safe } from 'safe-wrapper';
 
-const async = () => {
-  throw new TypeError('async type error occurred');
-}
+const transformer = (error) => ({
+  code: error.name,
+  message: error.message,
+  timestamp: new Date()
+});
 
-const [error, result] = await safe(async(), [TypeError]);
+const safeWithTransform = safe(
+  () => { throw new Error('custom error'); },
+  [Error],
+  transformer
+);
 
-if (error) {
-  return handle(error);
-}
+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.
+
+```javascript
+import { safe } from 'safe-wrapper';
+
+const safeJsonParse = safe(JSON.parse);
+const [error, result] = safeJsonParse('invalid_json');
 
-return handle(result);
+const [error, result] = safe(Object.keys, [TypeError])(null);
 ```
 
-#### Important Notes
-- async operations: should throw errors when they fail.
-- sync operations: should return errors instead of throwing them.
+### API Reference
 
-#### API
+`safe(action, types, transformer)`
 
-```safe(response, types)```
 - parameters
-  - response (any): result of the function call, either synchronous or asynchronous.
-  - types (array, optional): an array of error types to catch specifically. if an error does not match any of these types, it will be thrown.
+  - 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. 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 caught from the function, if any.
-  - result (any): the result of the function, if no error occurs.
+  - 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.

package/lib/index.cjs

@@ -1 +1 @@
-"use strict";var c=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var o=Object.prototype.hasOwnProperty;var r=(n,t)=>{for(var u in t)c(n,u,{get:t[u],enumerable:!0})},g=(n,t,u,f)=>{if(t&&typeof t=="object"||typeof t=="function")for(let l of h(t))!o.call(n,l)&&l!==u&&c(n,l,{get:()=>t[l],enumerable:!(f=a(t,l))||f.enumerable});return n};var m=n=>g(c({},"__esModule",{value:!0}),n);var w={};r(w,{safe:()=>e});module.exports=m(w);var i=(n,t=[])=>{if(!t.length)return[n,null];if(t.some(u=>n instanceof u))return[n,null];throw n},e=(n,t=[])=>n instanceof Promise?n.then(u=>[null,u]).catch(u=>i(u,t)):n instanceof Error?i(n,t):[null,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,8 +1,9 @@
 /**
- * safely executes the result of a function or a promise and handles any errors that occur.
+ * safely executes a synchronous or asynchronous action, handles any errors that occur and returns the result in a consistent response structure.
  *
- * @param {any} response - the result of a synchronous or asynchronous function, or a promise to execute.
- * @param {Array<ErrorConstructor>} [types=[]] - an optional array of error classes to check against.
- * @returns {Promise<[null, any]|[Error, null]>|[null, any]|[Error, null]} - returns an array where the first element is null if successful, or an error if it fails. if the input is a promise, it resolves to that array; otherwise, it returns the array directly.
+ * @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(response: any, types?: ErrorConstructor[] | undefined): Promise<[null, any] | [Error, null]> | [null, any] | [Error, null];
+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 l=(n,t=[])=>{if(!t.length)return[n,null];if(t.some(u=>n instanceof u))return[n,null];throw n},c=(n,t=[])=>n instanceof Promise?n.then(u=>[null,u]).catch(u=>l(u,t)):n instanceof Error?l(n,t):[null,n];export{c 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": "1.0.7",
+  "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",
@@ -40,4 +40,4 @@
     "esbuild": "^0.24.0",
     "typescript": "^5.6.3"
   }
-}
+}