error-message-utils 1.2.8 → 1.2.10

package/README.md

@@ -1,192 +1,268 @@
 # Error Message Utils
 
-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.
+`error-message-utils` helps TypeScript and JavaScript apps turn unknown errors into a
+consistent shape:
 
+- a readable message
+- a stable error code
+- optional extra data
 
+Use `Exception` for most application code. Use `encodeError` and `decodeError` when you need to
+send or receive an error code inside a plain string.
 
+## Install
 
+```bash
+npm i -S error-message-utils
+```
 
-</br>
+## Recommended Usage: Exception
 
-## Getting Started
+`Exception` is an `Error` subclass that stores a normalized message, a code, and optional data.
 
-Install the package:
-```bash
-npm i -S error-message-utils
+```typescript
+import { Exception } from 'error-message-utils';
+
+throw new Exception('The provided email is already in use.', 'EMAIL_EXISTS', {
+  field: 'email',
+});
 ```
 
-### Examples
+```typescript
+const exception = new Exception('Request failed', 'REQUEST_FAILED');
 
-Encode an error:
+exception instanceof Error; // true
+exception instanceof Exception; // true
+exception.name; // 'Exception'
+exception.message; // 'Request failed'
+exception.code; // 'REQUEST_FAILED'
+exception.data; // null
+exception.toString(); // 'Request failed{(REQUEST_FAILED)}'
+exception.toRecord();
+// {
+//   message: 'Request failed',
+//   code: 'REQUEST_FAILED',
+//   data: null,
+// }
+```
+
+### Wrap Unknown Errors
+
+When you catch an unknown error, pass it to `Exception`. The package will extract the best message
+and code it can find.
 
 ```typescript
-import { encodeError } from 'error-message-utils';
-
-if (emailExists()) {
-  throw new Error(encodeError(
-    'The provided email is already in use.', 
-    'EMAIL_EXISTS'
-  ));
-  // 'The provided email is already in use.{(EMAIL_EXISTS)}'
+import { Exception } from 'error-message-utils';
+
+try {
+  await sendReceiptEmail();
+} catch (error) {
+  throw new Exception(error, 'RECEIPT_EMAIL_FAILED', {
+    operation: 'sendReceiptEmail',
+  });
 }
 ```
 
+### Extend Exception
 
-<br/>
-
-Decode an error:
+Create small domain-specific exception classes when your app has a stable set of error codes.
 
 ```typescript
-import { decodeError } from 'error-message-utils';
+import { Exception } from 'error-message-utils';
 
-decodeError('The provided email is already in use.{(EMAIL_EXISTS)}');
-// {
-//   message: 'The provided email is already in use.',
-//   code: 'EMAIL_EXISTS'
-// }
+const USER_ERROR_CODES = {
+  EmailTaken: 'USER_EMAIL_TAKEN',
+  Unauthorized: 'USER_UNAUTHORIZED',
+} as const;
+
+type IUserErrorCode = (typeof USER_ERROR_CODES)[keyof typeof USER_ERROR_CODES];
+
+export class UserException extends Exception {
+  public constructor(message: string, code: IUserErrorCode, data?: unknown) {
+    super(message, code, data);
+    this.name = 'UserException';
+  }
+}
+
+throw new UserException(
+  'The provided email is already in use.',
+  USER_ERROR_CODES.EmailTaken,
+  { field: 'email' },
+);
 ```
 
+## Common Tasks
 
-<br/>
+### Extract a Message
 
-Error messages can be extracted recursively from complex structures, including nested `cause` data properties from `Error` instances:
+`extractMessage` accepts any value and returns the best readable message it can find.
 
 ```typescript
 import { extractMessage } from 'error-message-utils';
 
-extractMessage(new Error('Top level error', {
-  cause: new Error('First nested cause', {
-    cause: new Error('Second nested cause'),
+extractMessage(
+  new Error('Top level error', {
+    cause: new Error('First nested cause', {
+      cause: new Error('Second nested cause'),
+    }),
   }),
-}));
+);
 // 'Top level error; [CAUSE]: First nested cause; [CAUSE]: Second nested cause'
 
-
-extractMessage({ 
-  message: { 
-    err: { 
-      message: 'This error message is nested deeply!'
-    } 
-  } 
+extractMessage({
+  message: {
+    err: {
+      message: 'This error message is nested deeply!',
+    },
+  },
 });
 // 'This error message is nested deeply!'
 ```
 
-
-<br/>
-
-Extract detailed error messages from [Zod](https://zod.dev/basics) parsing errors.
+Zod errors are formatted with their first issue message and path.
 
 ```typescript
-import { z } from "zod";
+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)
+const result = z.object({ name: z.string() }).safeParse({ name: 123 });
 
-z.object({ 
-  name: z.object({ age: z.number() }) 
-}).parse({ name: { age: 'not a number' } })
-// Invalid input: expected string, received number (someDict.innerList.0.someProp)
+if (!result.success) {
+  extractMessage(result.error);
+  // 'Invalid input: expected string, received number (name)'
+}
 ```
 
+### Get an Error Code
 
-<br/>
-
-Identify encoded errors:
+Use `getErrorCode` when you only need the resolved code.
 
 ```typescript
-import { isEncodedError, encodeError, hasErrorCode } from 'error-message-utils';
+import { Exception, getErrorCode } from 'error-message-utils';
+
+const exception = new Exception('Access denied', 'ACCESS_DENIED');
 
-isEncodedError('Some random unencoded error');
-// false
+getErrorCode(exception); // 'ACCESS_DENIED'
+getErrorCode('Access denied'); // null
+```
 
-isEncodedError(new Error('Some random unencoded error'));
-// false
+Use `hasErrorCode` when you want a direct boolean check.
 
-isEncodedError(encodeError('Some unknown error.', 'NASTY_ERROR'));
-// true
+```typescript
+import { Exception, hasErrorCode } from 'error-message-utils';
 
-isEncodedError(encodeError(new Error('Some unknown error.'), 'NASTY_ERROR'));
-// true
+const exception = new Exception('Access denied', 'ACCESS_DENIED');
 
-hasErrorCode(new Error('Oops, something went wrong.'), 'MY_ERROR_CODE'); // false
-hasErrorCode(
-  new Exception('Oops, something went wrong.', 'MY_ERROR_CODE'), 
-  'MY_ERROR_CODE'
-); 
-// true
+hasErrorCode(exception, 'ACCESS_DENIED'); // true
+hasErrorCode(exception, 'PAYMENT_FAILED'); // false
 ```
 
+### Encode and Decode Plain Strings
 
-<br/>
-
-In some cases, you may want to check whether the extracted error matches the default message provided by this package:
+`encodeError` and `decodeError` are lower-level helpers for systems that can only pass string
+messages.
 
 ```typescript
-import { isDefaultErrorMessage } from 'error-message-utils';
+import { decodeError, encodeError } from 'error-message-utils';
 
-const DEFAULT_MESSAGE: string = 'The error message could not be extracted, check the logs for more information.';
+const encodedError = encodeError(
+  'The provided email is already in use.',
+  'EMAIL_EXISTS',
+);
 
-isDefaultErrorMessage(DEFAULT_MESSAGE);
-// true
+encodedError;
+// 'The provided email is already in use.{(EMAIL_EXISTS)}'
 
-isDefaultErrorMessage(`${DEFAULT_MESSAGE} and something else...`);
-// false
-
-isDefaultErrorMessage(`${DEFAULT_MESSAGE} and something else...`, true);
-// true
+decodeError(encodedError);
+// {
+//   message: 'The provided email is already in use.',
+//   code: 'EMAIL_EXISTS',
+//   data: null,
+// }
 ```
 
+### Detect Resolved Codes with isEncodedError
 
+`isEncodedError` returns `true` when an error resolves to a non-default code. For direct code
+inspection, prefer `getErrorCode` or `hasErrorCode`.
 
+```typescript
+import { encodeError, isEncodedError } from 'error-message-utils';
+
+isEncodedError('Some random unencoded error'); // false
+isEncodedError(new Error('Some random unencoded error')); // false
+isEncodedError(encodeError('Some unknown error.', 'UNKNOWN_ERROR')); // true
+```
 
-<br/>
+### Check the Default Message
 
-Improve code consistency by handling errors with the `Exception` utility class:
+Use `isDefaultErrorMessage` to detect the fallback message returned when no useful message can be
+extracted.
 
 ```typescript
-import { Exception } from 'error-message-utils';
+import { DEFAULT_MESSAGE, isDefaultErrorMessage } 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)}"
-exception.toRecord();
-// {
-//   message: "Request failed",
-//   code: "SOME_ERROR_CODE",
-//   data: null,
-// }
+isDefaultErrorMessage(DEFAULT_MESSAGE); // true
+isDefaultErrorMessage(`${DEFAULT_MESSAGE} More details.`); // true
+isDefaultErrorMessage(`${DEFAULT_MESSAGE} More details.`, true); // false
+```
+
+## Public API
+
+Import public items from the package root:
+
+```typescript
+import {
+  DEFAULT_CODE,
+  DEFAULT_MESSAGE,
+  Exception,
+  decodeError,
+  encodeError,
+  extractMessage,
+  getErrorCode,
+  hasErrorCode,
+  isDefaultErrorMessage,
+  isEncodedError,
+  type IDecodedError,
+  type IErrorCode,
+  type IErrorCodeCarrier,
+  type IExceptionRecord,
+} from 'error-message-utils';
 ```
 
+### Classes
+
+| Export | Description |
+| --- | --- |
+| `Exception` | An `Error` subclass that normalizes an unknown error into `message`, `code`, and `data`. It can also serialize itself with `toString()` or `toRecord()`. |
 
-<br/>
+### Functions
 
-## Types
+| Export | Signature | Description |
+| --- | --- | --- |
+| `extractMessage` | `(error: unknown) => string` | Extracts the best readable message from strings, `Error` instances, nested error-like objects, `Error.cause` chains, arrays, plain objects, and Zod errors. Returns `DEFAULT_MESSAGE` when no useful message can be extracted. |
+| `encodeError` | `(error: unknown, code: IErrorCode) => string` | Extracts a message from `error` and appends the wrapped code at the end of the message. |
+| `decodeError` | `(error: unknown) => IDecodedError` | Extracts a message, resolves a code from an encoded message or code-carrying object, and returns `{ message, code, data }`. |
+| `isEncodedError` | `(error: unknown) => boolean` | Returns `true` when `decodeError(error).code` resolves to a non-default code. |
+| `getErrorCode` | `(error: unknown) => IErrorCode \| null` | Returns the resolved non-default code, or `null` when no non-default code is found. |
+| `hasErrorCode` | `(error: unknown, code: IErrorCode) => boolean` | Checks whether an error resolves to the provided code. Raw code values are compared with strict equality. |
+| `isDefaultErrorMessage` | `(value: string, fullMatch?: boolean) => boolean` | Checks whether a string contains `DEFAULT_MESSAGE`. Pass `true` as the second argument to require an exact match. |
+
+### Types
 
 ```typescript
-/**
- * Error Code
- * 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;
 
-/**
- * Decoded Error
- * 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 = {
-  message: string,
-  code: IErrorCode,
+  message: string;
+  code: IErrorCode;
+  data: unknown | null;
 };
 
-/**
- * Exception Record
- * The record type for the Exception class.
-*/
+type IErrorCodeCarrier = {
+  code: IErrorCode;
+} & Record<string, unknown>;
+
 type IExceptionRecord = {
   message: string;
   code: IErrorCode;
@@ -194,45 +270,33 @@ type IExceptionRecord = {
 };
 ```
 
+| Export | Description |
+| --- | --- |
+| `IErrorCode` | The supported type for application error codes. |
+| `IDecodedError` | The object returned by `decodeError`. |
+| `IErrorCodeCarrier` | A plain object shape that can provide a code to `decodeError`, `getErrorCode`, `hasErrorCode`, and `Exception`. |
+| `IExceptionRecord` | The serializable object returned by `Exception.toRecord()`. |
 
-<br/>
-
-## Constants
+### Constants
 
 ```typescript
-// the default message if none can be extracted
-const DEFAULT_MESSAGE: string =
-  'The error message could not be extracted, check the logs for more information.';
+const DEFAULT_CODE = -1;
 
-// the default code if none was provided or could not be extracted
-const DEFAULT_CODE: IErrorCode = -1;
+const DEFAULT_MESSAGE =
+  'The error message could not be extracted, check the logs for more information.';
 ```
 
+| Export | Description |
+| --- | --- |
+| `DEFAULT_CODE` | The fallback code used when no code can be resolved. |
+| `DEFAULT_MESSAGE` | The fallback message used when no readable message can be extracted. |
 
-
-<br/>
-
-## Built With
-
-- TypeScript
-
-
-
-
-<br/>
-
-## Running the Tests
+## Running Tests
 
 ```bash
-npm run test
+npm test
 ```
 
-
-
-
-
-<br/>
-
 ## License
 
 [MIT](https://choosealicense.com/licenses/mit/)

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

@@ -1,7 +1,4 @@
-import { IErrorCode, IDecodedError } from '../shared/types.js';
-/**
- * General errors
- */
+import type { IErrorCode, IDecodedError } from '../shared/types.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.
@@ -26,6 +23,9 @@ export declare const encodeError: (error: any, code: IErrorCode) => string;
  * @returns The decoded error, containing the message and the code.
  */
 export declare const decodeError: (error: any) => IDecodedError;
+/**
+ * Misc helpers
+ */
 /**
  * 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.
@@ -33,8 +33,11 @@ export declare const decodeError: (error: any) => IDecodedError;
  */
 export declare const isEncodedError: (error: any) => boolean;
 /**
- * Misc helpers
+ * Retrieves the error code from a given error, or null if it matches the default code.
+ * @param error The error to extract the code from.
+ * @returns The error code or null if it matches the default code.
  */
+export declare const getErrorCode: (error: any) => IErrorCode | null;
 /**
  * Checks if the given error matches the specified error code.
  * @param error The error to be checked, can be of any type.

package/dist/error-handler/index.js

@@ -1 +1 @@
-import{ZodError}from"zod";import{DEFAULT_CODE,DEFAULT_MESSAGE}from"../shared/constants.js";import{wrapCode,unwrapCode}from"../utils/index.js";import{extractZodErrorMessage}from"./utilities.js";export const 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};export const encodeError=(r,e)=>`${extractMessage(r)}${wrapCode(e)}`;export const decodeError=r=>{const e=extractMessage(r),{code:s,startsAt:t}=unwrapCode(e);return{message:t>0?e.slice(0,t):e,code:s}};export const isEncodedError=r=>decodeError(r).code!==DEFAULT_CODE;export const hasErrorCode=(r,e)=>null!==r&&(r===e||"object"==typeof r&&"code"in r&&r.code===e||decodeError(r).code===e);export const isDefaultErrorMessage=(r,e=!1)=>e?r===DEFAULT_MESSAGE:"string"==typeof r&&r.includes(DEFAULT_MESSAGE);
+import{ZodError}from"zod";import{DEFAULT_CODE,DEFAULT_MESSAGE}from"../shared/constants.js";import{wrapCode,unwrapCode}from"../utils/index.js";import{extractZodErrorMessage,getDecodedErrorCode}from"./utilities.js";const __extractMessage=(r,e)=>{if("string"==typeof r&&r.length)return r;if(r instanceof ZodError)return extractZodErrorMessage(r);if(r&&"object"==typeof r){if(e.has(r))return DEFAULT_MESSAGE;e.add(r)}if(r instanceof Error&&r.message)return r.cause?`${r.message}; [CAUSE]: ${__extractMessage(r.cause,e)}`:r.message;if(r&&"object"==typeof r){if(r.message)return __extractMessage(r.message,e);if(r.msg)return __extractMessage(r.msg,e);if(r.error)return __extractMessage(r.error,e);if(r.err)return __extractMessage(r.err,e);if(r.errors)return __extractMessage(r.errors,e);if(r.errs)return __extractMessage(r.errs,e);if(r.reason)return __extractMessage(r.reason,e);if(r.reasons)return __extractMessage(r.reasons,e);if(r.issue)return __extractMessage(r.issue,e);if(r.issues)return __extractMessage(r.issues,e);if(r.data)return __extractMessage(r.data,e);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};export const extractMessage=r=>__extractMessage(r,new WeakSet);export const encodeError=(r,e)=>`${extractMessage(r)}${wrapCode(e)}`;export const decodeError=r=>{const e=extractMessage(r),{code:t,startsAt:s}=unwrapCode(e);return{message:s>0?e.slice(0,s):e,code:getDecodedErrorCode(r,t),data:null!==r&&"object"==typeof r&&"data"in r?r.data:null}};export const isEncodedError=r=>decodeError(r).code!==DEFAULT_CODE;export const getErrorCode=r=>{const{code:e}=decodeError(r);return e!==DEFAULT_CODE?e:null};export const hasErrorCode=(r,e)=>null!==r&&(r===e||decodeError(r).code===e);export const isDefaultErrorMessage=(r,e=!1)=>e?r===DEFAULT_MESSAGE:"string"==typeof r&&r.includes(DEFAULT_MESSAGE);

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

@@ -1,4 +1,5 @@
 import { ZodError } from 'zod';
+import { IErrorCode } from '../shared/types.js';
 /**
  * Attempts to extract a Zod error message from a ZodError instance. If unable to do so, it returns
  * the default error message.
@@ -6,3 +7,10 @@ import { ZodError } from 'zod';
  * @returns The extracted error message or the default message.
  */
 export declare const extractZodErrorMessage: (error: ZodError) => string;
+/**
+ * Resolves the decoded error code from the unwrapped message code or an Exception-style object.
+ * @param error The unknown error object to inspect.
+ * @param unwrappedCode The code unwrapped from the extracted error message.
+ * @returns The decoded error code or the default code.
+ */
+export declare const getDecodedErrorCode: (error: unknown, unwrappedCode: IErrorCode) => IErrorCode;

package/dist/error-handler/utilities.js

@@ -1 +1 @@
-import{DEFAULT_MESSAGE}from"../shared/constants.js";const __extractPathFromZodError=s=>s&&Array.isArray(s.issues)&&s.issues.length&&Array.isArray(s.issues[0].path)&&s.issues[0].path.length?s.issues[0].path.join("."):"Unknown path";export const extractZodErrorMessage=s=>s&&Array.isArray(s.issues)&&s.issues.length&&Array.isArray(s.issues[0].path)&&s.issues[0].message?`${s.issues[0].message} (${__extractPathFromZodError(s)})`:DEFAULT_MESSAGE;
+import{DEFAULT_CODE,DEFAULT_MESSAGE}from"../shared/constants.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";export const 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;const __isErrorCodeCarrier=r=>"object"==typeof r&&null!==r&&"code"in r&&("string"==typeof r.code||"number"==typeof r.code);export const getDecodedErrorCode=(r,s)=>s!==DEFAULT_CODE?s:__isErrorCodeCarrier(r)?r.code:DEFAULT_CODE;

package/dist/exception/exception.d.ts

@@ -1,8 +1,17 @@
 import { type IErrorCode } from '../shared/types.js';
-import { IExceptionRecord } from './types.js';
+import { type IExceptionRecord } from './types.js';
+/**
+ * Error subclass that normalizes unknown errors into a message, code, and optional data payload.
+ */
 export declare class Exception extends Error {
     readonly code: IErrorCode;
     readonly data: unknown;
+    /**
+     * Creates an exception from any supported error input.
+     * @param error The unknown error or message to normalize.
+     * @param code The optional code that overrides any decoded code.
+     * @param data The optional data payload that overrides any decoded data.
+     */
     constructor(error: unknown, code?: IErrorCode, data?: unknown);
     /**
      * Override the default toString method to return a formatted error message with the code.

package/dist/exception/exception.js

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { IErrorCode, IDecodedError } from './shared/types.js';
+export type { IErrorCode, IDecodedError, IErrorCodeCarrier } from './shared/types.js';
 export { DEFAULT_CODE, DEFAULT_MESSAGE } from './shared/constants.js';
-export { extractMessage, encodeError, decodeError, isEncodedError, hasErrorCode, isDefaultErrorMessage, } from './error-handler/index.js';
+export { extractMessage, encodeError, decodeError, isEncodedError, getErrorCode, hasErrorCode, isDefaultErrorMessage, } from './error-handler/index.js';
 export { type IExceptionRecord, Exception } from './exception/index.js';

package/dist/index.js

@@ -1 +1 @@
-export{DEFAULT_CODE,DEFAULT_MESSAGE}from"./shared/constants.js";export{extractMessage,encodeError,decodeError,isEncodedError,hasErrorCode,isDefaultErrorMessage}from"./error-handler/index.js";export{Exception}from"./exception/index.js";
+export{DEFAULT_CODE,DEFAULT_MESSAGE}from"./shared/constants.js";export{extractMessage,encodeError,decodeError,isEncodedError,getErrorCode,hasErrorCode,isDefaultErrorMessage}from"./error-handler/index.js";export{Exception}from"./exception/index.js";

package/dist/shared/types.d.ts

@@ -29,4 +29,13 @@ export type IUnwrappedErrorCode = {
 export type IDecodedError = {
     message: string;
     code: IErrorCode;
+    data: unknown | null;
 };
+/**
+ * Error Code Carrier
+ * An object that carries an error code, typically used to identify errors programmatically. Extra
+ * fields are allowed because provider and application errors often carry metadata.
+ */
+export type IErrorCodeCarrier = {
+    code: IErrorCode;
+} & Record<string, unknown>;

package/dist/utils/index.js

@@ -1 +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=>"string"==typeof r&&/^[-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(r);export const unwrapCode=r=>{if(__isEncodedError(r)){const E=r.lastIndexOf(CODE_WRAPPER.prefix),e=r.substring(E+CODE_WRAPPER.prefix.length,r.lastIndexOf(CODE_WRAPPER.suffix));return{code:__isNumeric(e)?Number(e):e,startsAt:E}}return{code:DEFAULT_CODE,startsAt:-1}};
+import{CODE_WRAPPER,DEFAULT_CODE}from"../shared/constants.js";export const wrapCode=t=>`${CODE_WRAPPER.prefix}${t??DEFAULT_CODE}${CODE_WRAPPER.suffix}`;const __isEncodedError=t=>{const e=t.lastIndexOf(CODE_WRAPPER.prefix),r=e+CODE_WRAPPER.prefix.length,E=t.length-CODE_WRAPPER.suffix.length;return e>=0&&r<E&&t.endsWith(CODE_WRAPPER.suffix)},__isNumeric=t=>"string"==typeof t&&/^[-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(t);export const unwrapCode=t=>{if(__isEncodedError(t)){const e=t.lastIndexOf(CODE_WRAPPER.prefix),r=t.substring(e+CODE_WRAPPER.prefix.length,t.lastIndexOf(CODE_WRAPPER.suffix));return{code:__isNumeric(r)?Number(r):r,startsAt:e}}return{code:DEFAULT_CODE,startsAt:-1}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "error-message-utils",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "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",