safe-wrapper 2.0.1 → 2.1.0

package/README.md

@@ -11,7 +11,9 @@ safe-wrapper is a lightweight utility for javascript that simplifies error handl
 
 - 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.
+- returns a consistent response in `[error, result]` format,
+  - `error`: null if successful, else an error (or transformed object).
+  - `result`: return value (sync) or resolved value (async) when successful, else null.
 - supports custom error transformation for advanced error handling.
 
 ### Installation
@@ -92,7 +94,7 @@ const safeSync = safe(sync, [TypeError, RangeError]);
 const [error, result] = safeSync(args);
 ```
 
-#### using custom error transformer
+#### using synchronous custom error transformer
 
 you can provide a custom error transformer function to modify how errors are handled:
 
@@ -106,13 +108,40 @@ const transformer = (error) => ({
 });
 
 const safeWithTransform = safe(
-  () => { throw new Error('custom error'); },
+  () => { throw new Error('custom sync error'); },
   [Error],
   transformer
 );
 
 const [error, result] = safeWithTransform();
-// error will be: { code: 'Error', message: 'custom error', timestamp: Date }
+// error will be: { code: 'Error', message: 'custom sync error', timestamp: Date }
+```
+
+#### using asynchronous custom error transformer
+
+you can provide an asynchronous custom error transformer to modify how errors are handled.
+
+```javascript
+import { safe } from 'safe-wrapper';
+
+const transformer = async (error) => {
+  await report(error);
+
+  return {
+    code: error.name,
+    message: error.message,
+    timestamp: new Date()
+  }
+}
+
+const safeWithTransform = safe(
+  async () => { throw new Error('custom async error'); },
+  [Error],
+  transformer
+);
+
+const [error, result] = await safeWithTransform();
+// error will be: { code: 'Error', message: 'custom async error', timestamp: Date }
 ```
 
 #### wrapping built-in functions
@@ -138,4 +167,4 @@ const [error, result] = safe(Object.keys, [TypeError])(null);
   - 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. 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.
+  - result (result | null): the result of the action function if no error occurred, otherwise null.

package/lib/index.cjs

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

package/lib/index.d.ts

@@ -1,9 +1,13 @@
 /**
  * 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.
+ * @template R,
+ * @template [T = Error]
+ *
+ * @param {(...args: any[]) => R} action - the function to be wrapped.
+ * @param {Array<ErrorConstructor>} [types = []] - an optional array of error types to catch.
+ * @param {(error: Error) => Promise<T> | T} [transformer] - an optional function to transform the error object.
+ *
+ * @returns {(...args: Parameters<typeof action>) => R extends Promise<infer U> ? Promise<[T, null] | [null, U]> : [T, null] | [null, R]} - a tuple where the first element is the error object, if available, or the transformed error object, if a transformer function is provided. the second element is the result of the action, if available.
  */
-export function safe(action: Function, types?: Array<ErrorConstructor>, transformer?: Function): Promise<[Error, null] | [null, any]> | [Error, null] | [null, any];
+export function safe<R, T = Error>(action: (...args: any[]) => R, types?: Array<ErrorConstructor>, transformer?: (error: Error) => Promise<T> | T): (...args: Parameters<typeof action>) => R extends Promise<infer U> ? Promise<[T, null] | [null, U]> : [T, null] | [null, R];

package/lib/index.mjs

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

package/package.json

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