error-message-utils 1.1.6 → 1.2.2

package/README.md

@@ -17,7 +17,7 @@ npm i -S error-message-utils
 
 ### Examples
 
-Encoding an error:
+Encode an error:
 
 ```typescript
 import { encodeError } from 'error-message-utils';
@@ -34,7 +34,7 @@ if (emailExists()) {
 
 <br/>
 
-Decoding an error:
+Decode an error:
 
 ```typescript
 import { decodeError } from 'error-message-utils';
@@ -75,7 +75,25 @@ extractMessage({
 
 <br/>
 
-Identifying encoded errors:
+Extract detailed error messages from [Zod](https://zod.dev/basics) parsing errors.
+
+```typescript
+import { z } from "zod";
+import { extractMessage } from 'error-message-utils';
+
+z.object({ name: z.string() }).parse({ name: 123 });
+// Invalid input: expected string, received number (name)
+
+z.object({ 
+  name: z.object({ age: z.number() }) 
+}).parse({ name: { age: 'not a number' } })
+// Invalid input: expected string, received number (someDict.innerList.0.someProp)
+```
+
+
+<br/>
+
+Identify encoded errors:
 
 ```typescript
 import { isEncodedError, encodeError } from 'error-message-utils';
@@ -99,7 +117,7 @@ isEncodedError(encodeError(new Error('Some unknown error.'), 'NASTY_ERROR'));
 In some cases, you may want to check whether the extracted error matches the default message provided by this package:
 
 ```typescript
-import { isDefaultErrorMessage} from 'error-message-utils';
+import { isDefaultErrorMessage } from 'error-message-utils';
 
 const DEFAULT_MESSAGE: string = 'The error message could not be extracted, check the logs for more information.';
 
@@ -116,6 +134,22 @@ isDefaultErrorMessage(`${DEFAULT_MESSAGE} and something else...`, true);
 
 
 
+<br/>
+
+Improve code consistency by handling errors with the `Exception` utility class:
+
+```typescript
+import { Exception } from 'error-message-utils';
+
+const exception = new Exception('Request failed', 'SOME_ERROR_CODE');
+exception instanceof Error; // true
+exception instanceof Exception; // true
+exception.message; // "Request failed"
+exception.code; // "SOME_ERROR_CODE"
+exception.toString(); // "Request failed{(SOME_ERROR_CODE)}"
+```
+
+
 <br/>
 
 ## Types

package/dist/error-handler/index.d.ts

@@ -0,0 +1,45 @@
+import { IErrorCode, IDecodedError } from '../shared/types.js';
+/**------------------------------------------------------------------------------------------------
+ * General errors
+ -------------------------------------------------------------------------------------------------*/
+/**
+ * Attempts to extract an error message from an error that could be anything. If it fails to do so,
+ * it returns the default message.
+ * @param error The error to extract the message from.
+ * @returns A string containing the extracted message or the default message if extraction fails.
+ */
+declare const extractMessage: (error: any) => string;
+/**------------------------------------------------------------------------------------------------
+ * Encoding
+ -------------------------------------------------------------------------------------------------*/
+/**
+ * Given an error in any format, it extracts the message and inserts the code at the end.
+ * @param error The error to be encoded, can be of any type.
+ * @param code The error code to be wrapped and appended to the message.
+ * @returns A string containing the encoded error message.
+ */
+declare const encodeError: (error: any, code: IErrorCode) => string;
+/**
+ * Given an error, it will extract the encoded message and attempt to decode it. If successful,
+ * it separates the error message from the code so it can be shown directly to the user.
+ * @param error The error to be decoded, can be of any type.
+ * @returns The decoded error, containing the message and the code.
+ */
+declare const decodeError: (error: any) => IDecodedError;
+/**
+ * Determines if a given error (in any format) is an error encoded by this package.
+ * @param error The error to be checked, can be of any type.
+ * @returns A boolean indicating whether the error is an encoded error or not.
+ */
+declare const isEncodedError: (error: any) => boolean;
+/**------------------------------------------------------------------------------------------------
+ * Misc helpers
+ -------------------------------------------------------------------------------------------------*/
+/**
+ * Verifies if a value matches the default error message used by this package.
+ * @param value The value to be checked.
+ * @param fullMatch Whether to check for an exact match or a partial match.
+ * @returns A boolean indicating whether the value matches the default error message.
+ */
+declare const isDefaultErrorMessage: (value: string, fullMatch?: boolean) => value is string;
+export { type IErrorCode, type IDecodedError, extractMessage, encodeError, decodeError, isEncodedError, isDefaultErrorMessage, };

package/dist/error-handler/index.js

@@ -0,0 +1 @@
+import{ZodError}from"zod";import{DEFAULT_CODE,DEFAULT_MESSAGE}from"../shared/constants.js";import{wrapCode,unwrapCode}from"../utils/index.js";const __extractPathFromZodError=r=>r&&Array.isArray(r.issues)&&r.issues.length&&Array.isArray(r.issues[0].path)&&r.issues[0].path.length?r.issues[0].path.join("."):"Unknown path",__extractZodErrorMessage=r=>r&&Array.isArray(r.issues)&&r.issues.length&&Array.isArray(r.issues[0].path)&&r.issues[0].message?`${r.issues[0].message} (${__extractPathFromZodError(r)})`:DEFAULT_MESSAGE,extractMessage=r=>{if("string"==typeof r&&r.length)return r;if(r instanceof ZodError)return __extractZodErrorMessage(r);if(r instanceof Error&&r.message)return r.cause?`${r.message}; [CAUSE]: ${extractMessage(r.cause)}`:r.message;if(r&&"object"==typeof r){if(r.message)return extractMessage(r.message);if(r.msg)return extractMessage(r.msg);if(r.error)return extractMessage(r.error);if(r.err)return extractMessage(r.err);if(r.errors)return extractMessage(r.errors);if(r.errs)return extractMessage(r.errs);if(r.reason)return extractMessage(r.reason);if(r.reasons)return extractMessage(r.reasons);if(r.issue)return extractMessage(r.issue);if(r.issues)return extractMessage(r.issues);if(r.data)return extractMessage(r.data);try{return JSON.stringify(r)}catch(e){console.error("Error during extractMessage:"),console.error("Original Error: ",r),console.error("JSON.stringify Error:",e)}}return DEFAULT_MESSAGE},encodeError=(r,e)=>`${extractMessage(r)}${wrapCode(e)}`,decodeError=r=>{const e=extractMessage(r),{code:s,startsAt:t}=unwrapCode(e);return{message:t>0?e.slice(0,t):e,code:s}},isEncodedError=r=>decodeError(r).code!==DEFAULT_CODE,isDefaultErrorMessage=(r,e=!1)=>e?r===DEFAULT_MESSAGE:"string"==typeof r&&r.includes(DEFAULT_MESSAGE);export{extractMessage,encodeError,decodeError,isEncodedError,isDefaultErrorMessage};

package/dist/exception/index.d.ts

@@ -0,0 +1,16 @@
+import { type IErrorCode } from '../shared/types.js';
+export declare class Exception extends Error {
+    readonly code: IErrorCode;
+    constructor(error: unknown, code: IErrorCode);
+    /**
+     * Override the default toString method to return a formatted error message with the code.
+     * @returns A string representation of the error with the code.
+     */
+    toString(): string;
+    /**
+     * Override the default behavior for type conversion to return a formatted error message with the code.
+     * @param hint The type hint for the conversion.
+     * @returns A string representation of the error with the code or null for other types.
+     */
+    [Symbol.toPrimitive](hint: string): string | null;
+}

package/dist/exception/index.js

@@ -0,0 +1 @@
+import{encodeError,extractMessage}from"../error-handler/index.js";export class Exception extends Error{code;constructor(e,r){super(extractMessage(e)),this.name="Exception",this.code=r}toString(){return encodeError(this.message,this.code)}[Symbol.toPrimitive](e){return"string"===e||"default"===e?this.toString():null}}

package/dist/index.d.ts

@@ -1,36 +1,7 @@
 import { IErrorCode, IDecodedError } from './shared/types.js';
+import { decodeError, encodeError, extractMessage, isDefaultErrorMessage, isEncodedError } from './error-handler/index.js';
+import { Exception } from './exception/index.js';
 /**
- * Attempts to extract an error message from an error that could be anything. If it fails to do so,
- * it returns the default message.
- * @param error
- * @returns string
+ * Module exports
  */
-declare const extractMessage: (error: any) => string;
-/**
- * Verifies if a value matches the default error message used by this package.
- * @param value
- * @param fullMatch?
- * @returns boolean
- */
-declare const isDefaultErrorMessage: (value: string, fullMatch?: boolean) => value is string;
-/**
- * Given an error in any format, it extracts the message and inserts the code at the end.
- * @param error
- * @param code
- * @returns string
- */
-declare const encodeError: (error: any, code: IErrorCode) => string;
-/**
- * Given an error, it will extract the encoded message and attempt to decode it. If successful,
- * it separates the error message from the code so it can be shown directly to the user.
- * @param error
- * @returns IDecodedError
- */
-declare const decodeError: (error: any) => IDecodedError;
-/**
- * Determines if a given error (in any format) is an error encoded by this package.
- * @param error
- * @returns boolean
- */
-declare const isEncodedError: (error: any) => boolean;
-export { type IErrorCode, type IDecodedError, extractMessage, isDefaultErrorMessage, encodeError, decodeError, isEncodedError, };
+export { type IErrorCode, type IDecodedError, extractMessage, encodeError, decodeError, isEncodedError, isDefaultErrorMessage, Exception, };

package/dist/index.js

@@ -1 +1 @@
-import{DEFAULT_MESSAGE,DEFAULT_CODE,wrapCode,unwrapCode}from"./utils/utils.js";const extractMessage=r=>{if("string"==typeof r&&r.length)return r;if(r instanceof Error&&r.message)return r.cause?`${r.message}; [CAUSE]: ${extractMessage(r.cause)}`:r.message;if(r&&"object"==typeof r){if(r.message)return extractMessage(r.message);if(r.msg)return extractMessage(r.msg);if(r.error)return extractMessage(r.error);if(r.err)return extractMessage(r.err);if(r.errors)return extractMessage(r.errors);if(r.errs)return extractMessage(r.errs);try{return JSON.stringify(r)}catch(e){console.error("Error during extractMessage:"),console.error("Original Error: ",r),console.error("JSON.stringify Error:",e)}}return DEFAULT_MESSAGE},isDefaultErrorMessage=(r,e=!1)=>e?r===DEFAULT_MESSAGE:"string"==typeof r&&r.includes(DEFAULT_MESSAGE),encodeError=(r,e)=>`${extractMessage(r)}${wrapCode(e)}`,decodeError=r=>{const e=extractMessage(r),{code:s,startsAt:t}=unwrapCode(e);return{message:t>0?e.slice(0,t):e,code:s}},isEncodedError=r=>decodeError(r).code!==DEFAULT_CODE;export{extractMessage,isDefaultErrorMessage,encodeError,decodeError,isEncodedError};
+import{decodeError,encodeError,extractMessage,isDefaultErrorMessage,isEncodedError}from"./error-handler/index.js";import{Exception}from"./exception/index.js";export{extractMessage,encodeError,decodeError,isEncodedError,isDefaultErrorMessage,Exception};

package/dist/shared/constants.d.ts

@@ -0,0 +1,4 @@
+import { IErrorCode, IErrorCodeWrapper } from './types.js';
+export declare const CODE_WRAPPER: IErrorCodeWrapper;
+export declare const DEFAULT_MESSAGE: string;
+export declare const DEFAULT_CODE: IErrorCode;

package/dist/shared/constants.js

@@ -0,0 +1 @@
+export const CODE_WRAPPER={prefix:"{(",suffix:")}"};export const DEFAULT_MESSAGE="The error message could not be extracted, check the logs for more information.";export const DEFAULT_CODE=-1;

package/dist/shared/types.d.ts

@@ -3,7 +3,7 @@
  * When an error code is inserted into a message (encoding a message), it must be wrapped first so
  * it can be decoded later.
  */
-type IErrorCodeWrapper = {
+export type IErrorCodeWrapper = {
     prefix: string;
     suffix: string;
 };
@@ -12,12 +12,12 @@ type IErrorCodeWrapper = {
  * The code that is inserted when encoding an error. If none is provided or none can be extracted,
  * it defaults to -1.
  */
-type IErrorCode = string | number;
+export type IErrorCode = string | number;
 /**
  * Unwrapped Error Code
  * In order to decode an error, the code must be first unwrapped.
  */
-type IUnwrappedErrorCode = {
+export type IUnwrappedErrorCode = {
     code: IErrorCode;
     startsAt: number;
 };
@@ -26,8 +26,7 @@ type IUnwrappedErrorCode = {
  * The object obtained when an error is decoded. Keep in mind that if the error message or the code
  * cannot be extracted for any reason, the default values will be set instead.
  */
-type IDecodedError = {
+export type IDecodedError = {
     message: string;
     code: IErrorCode;
 };
-export type { IErrorCodeWrapper, IErrorCode, IUnwrappedErrorCode, IDecodedError };

package/dist/utils/index.d.ts

@@ -0,0 +1,14 @@
+import { IErrorCode, IUnwrappedErrorCode } from '../shared/types.js';
+/**
+ * Wraps a given error code. If none is provided, it wraps the default code.
+ * @param code The error code to wrap.
+ * @returns A string containing the wrapped error code.
+ */
+export declare const wrapCode: (code: IErrorCode) => string;
+/**
+ * Verifies if a message is an encoded error and if so, attempts to extract the code.
+ * If unsuccessful, both code and startsAt values will be -1.
+ * @param message The message to unwrap.
+ * @returns An object containing the unwrapped error code and its starting position.
+ */
+export declare const unwrapCode: (message: string) => IUnwrappedErrorCode;

package/dist/utils/index.js

@@ -0,0 +1 @@
+import{CODE_WRAPPER,DEFAULT_CODE}from"../shared/constants.js";export const wrapCode=r=>`${CODE_WRAPPER.prefix}${r??DEFAULT_CODE}${CODE_WRAPPER.suffix}`;const __isEncodedError=r=>new RegExp(`${CODE_WRAPPER.prefix}.+${CODE_WRAPPER.suffix}$`).test(r),__isNumeric=r=>!Number.isNaN(Number.parseFloat(r));export const unwrapCode=r=>{if(__isEncodedError(r)){const s=r.lastIndexOf(CODE_WRAPPER.prefix),e=r.substring(s+2,r.lastIndexOf(CODE_WRAPPER.suffix));return{code:__isNumeric(e)?Number(e):e,startsAt:s}}return{code:DEFAULT_CODE,startsAt:-1}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "error-message-utils",
-  "version": "1.1.6",
+  "version": "1.2.2",
   "description": "The error-message-utils package simplifies error management in your web applications and RESTful APIs. It ensures consistent and scalable handling of error messages, saving you time and effort. Moreover, it gives you the ability to assign custom error codes so all possible cases can be handled accordingly.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,5 +48,9 @@
     "ts-jest": "29.2.5",
     "ts-lib-builder": "1.0.8",
     "typescript": "5.7.2"
+  },
+  "dependencies": {
+    "@jest/globals": "30.3.0",
+    "zod": "4.3.6"
   }
 }

package/dist/utils/utils.d.ts

@@ -1,18 +0,0 @@
-import { IErrorCodeWrapper, IErrorCode, IUnwrappedErrorCode } from '../shared/types.js';
-declare const CODE_WRAPPER: IErrorCodeWrapper;
-declare const DEFAULT_MESSAGE: string;
-declare const DEFAULT_CODE: IErrorCode;
-/**
- * Wraps a given error code. If none is provided, it wraps the default code.
- * @param code
- * @returns string
- */
-declare const wrapCode: (code: IErrorCode) => string;
-/**
- * Verifies if a message is an encoded error and if so, attempts to extract the code.
- * If unsuccessful, both code and startsAt values will be -1.
- * @param message
- * @returns IUnwrappedErrorCode
- */
-declare const unwrapCode: (message: string) => IUnwrappedErrorCode;
-export { CODE_WRAPPER, DEFAULT_MESSAGE, DEFAULT_CODE, wrapCode, unwrapCode, };

package/dist/utils/utils.js

@@ -1 +0,0 @@
-const CODE_WRAPPER={prefix:"{(",suffix:")}"},DEFAULT_MESSAGE="The error message could not be extracted, check the logs for more information.",DEFAULT_CODE=-1,wrapCode=e=>`${CODE_WRAPPER.prefix}${e??-1}${CODE_WRAPPER.suffix}`,__isEncodedError=e=>new RegExp(`${CODE_WRAPPER.prefix}.+${CODE_WRAPPER.suffix}$`).test(e),__isNumeric=e=>!Number.isNaN(Number.parseFloat(e)),unwrapCode=e=>{if(__isEncodedError(e)){const r=e.lastIndexOf(CODE_WRAPPER.prefix),E=e.substring(r+2,e.lastIndexOf(CODE_WRAPPER.suffix));return{code:__isNumeric(E)?Number(E):E,startsAt:r}}return{code:-1,startsAt:-1}};export{CODE_WRAPPER,DEFAULT_MESSAGE,DEFAULT_CODE,wrapCode,unwrapCode};