safe-wrapper 2.1.0 → 3.0.0

package/README.md

@@ -5,7 +5,9 @@
 [![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.
+safe-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.
+
+in 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.
 
 ### Features
 
@@ -15,6 +17,7 @@ safe-wrapper is a lightweight utility for javascript that simplifies error handl
   - `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.
+- written in typescript with comprehensive type definitions, enabling full type inference support.
 
 ### Installation
 
@@ -24,7 +27,7 @@ npm install safe-wrapper
 
 ### Usage
 
-import `safe` from `safe-wrapper` to use it with any function.
+import `safe` from `safe-wrapper` to use it with any function. the types for `error` and `result` are automatically inferred.
 
 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.
 
@@ -79,10 +82,10 @@ const [error, result] = await safeAsync(args);
 
 we can specify multiple error types when wrapping a function, enabling safe to catch any of the specified errors.
 
-```javascript
+```typescript
 import { safe } from 'safe-wrapper';
 
-const sync = (args) => {
+const sync = (args: boolean): string => {
   if (args) {
     throw new TypeError('sync type error occurred');
   } else {
@@ -98,10 +101,12 @@ const [error, result] = safeSync(args);
 
 you can provide a custom error transformer function to modify how errors are handled:
 
-```javascript
+```typescript
 import { safe } from 'safe-wrapper';
 
-const transformer = (error) => ({
+type TransformedError = { code: string, message: string, timestamp: Date };
+
+const transformer = (error: Error): TransformedError => ({
   code: error.name,
   message: error.message,
   timestamp: new Date()
@@ -114,17 +119,19 @@ const safeWithTransform = safe(
 );
 
 const [error, result] = safeWithTransform();
-// error will be: { code: 'Error', message: 'custom sync error', timestamp: Date }
+// error will be of type TransformedError as: { 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
+```typescript
 import { safe } from 'safe-wrapper';
 
-const transformer = async (error) => {
+type AsyncTransformedError = { code: string, message: string, timestamp: Date };
+
+const transformer = async (error: Error): Promise<AsyncTransformedError> => {
   await report(error);
 
   return {
@@ -141,7 +148,7 @@ const safeWithTransform = safe(
 );
 
 const [error, result] = await safeWithTransform();
-// error will be: { code: 'Error', message: 'custom async error', timestamp: Date }
+// error will be of type AsyncTransformedError as: { code: 'Error', message: 'custom async error', timestamp: Date }
 ```
 
 #### wrapping built-in functions

package/lib/index.cjs

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

package/lib/index.d.ts

@@ -1,13 +1,4 @@
-/**
- * safely executes a synchronous or asynchronous action, handles any errors that occur and returns the result in a consistent response structure.
- *
- * @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<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];
+type Result<ResponseType, ErrorType> = [ErrorType, null] | [null, ResponseType];
+type Safe<ActionType extends (...args: unknown[]) => unknown, ErrorType = Error> = ReturnType<ActionType> extends Promise<infer ResponseType> ? (...args: Parameters<ActionType>) => Promise<Result<ResponseType, ErrorType>> : (...args: Parameters<ActionType>) => Result<ReturnType<ActionType>, ErrorType>;
+declare const safe: <ActionType extends (...args: unknown[]) => unknown, ErrorType = Error>(action: ActionType, types?: ErrorConstructor[], transformer?: (error: Error) => Promise<ErrorType> | ErrorType) => Safe<ActionType, ErrorType>;
+export { safe };

package/lib/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safe-wrapper",
-  "version": "2.1.0",
+  "version": "3.0.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",
@@ -9,8 +9,8 @@
   "scripts": {
     "build": "rm -rf lib && node esbuild.config.js",
     "ci": "npm install --clean-install && npm test && npm run build",
-    "start": "node src/index.js",
-    "test": "node --test"
+    "start": "tsx src/index.ts",
+    "test": "tsx test/*.test.js"
   },
   "exports": {
     ".": {
@@ -37,7 +37,8 @@
   },
   "homepage": "https://github.com/mcking-07/safe-wrapper#readme",
   "devDependencies": {
-    "esbuild": "^0.24.0",
-    "typescript": "^5.6.3"
+    "esbuild": "^0.25.5",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
   }
 }