error-message-utils 1.2.12 → 1.2.14

package/README.md

@@ -6,6 +6,7 @@ consistent shape:
 - a readable message
 - a stable error code
 - optional extra data
+- an optional native error cause
 
 Use `Exception` for most application code. Use `encodeError` and `decodeError` when you need to
 send or receive an error code inside a plain string.
@@ -18,7 +19,8 @@ npm i -S error-message-utils
 
 ## Recommended Usage: Exception
 
-`Exception` is an `Error` subclass that stores a normalized message, a code, and optional data.
+`Exception` is an `Error` subclass that stores a normalized message, a code, optional data, and an
+optional native cause.
 
 ```typescript
 import { Exception } from 'error-message-utils';
@@ -37,6 +39,7 @@ exception.name; // 'Exception'
 exception.message; // 'Request failed'
 exception.code; // 'REQUEST_FAILED'
 exception.data; // null
+exception.cause; // undefined
 exception.toString(); // 'Request failed{(REQUEST_FAILED)}'
 exception.toRecord();
 // {
@@ -46,29 +49,51 @@ exception.toRecord();
 // }
 ```
 
-### Wrap Unknown Errors
+### Preserve an Error Cause
 
-When you catch an unknown error, pass it to `Exception`. The package will extract the best message
-and code it can find.
+When wrapping an error, provide a stable contextual message and pass the original value through the
+fourth `IErrorOptions` argument. This keeps the top-level message predictable while preserving the
+original error for debugging.
 
 ```typescript
-import { Exception } from 'error-message-utils';
+import { Exception, extractMessage } from 'error-message-utils';
 
 try {
   await sendReceiptEmail();
-} catch (error) {
-  throw new Exception(error, 'RECEIPT_EMAIL_FAILED', {
-    operation: 'sendReceiptEmail',
-  });
+} catch (cause) {
+  const exception = new Exception(
+    'Unable to send the receipt email.',
+    'RECEIPT_EMAIL_FAILED',
+    { operation: 'sendReceiptEmail' },
+    { cause },
+  );
+
+  exception.message; // 'Unable to send the receipt email.'
+  exception.cause === cause; // true
+  extractMessage(exception); // combines the message with a truthy cause chain
+
+  throw exception;
 }
 ```
 
+`IErrorOptions` is a direct alias of the native `ErrorOptions` type. This API requires the ES2022
+TypeScript `lib` and a runtime that supports `Error` causes.
+
+The existing `new Exception(error, code, data)` form remains supported. It normalizes the first
+argument into the exception message but does not infer or store that argument as `cause`. Avoid
+also appending the cause message to the top-level message because `extractMessage` already combines
+truthy cause chains. Native `Error` semantics still retain falsy causes such as `false`, `0`, an
+empty string, or `null`, but `extractMessage` does not append them.
+
+`toString()` and `toRecord()` intentionally omit `cause`. A cause can contain internal or sensitive
+details, so inspect or expose it only at an appropriate boundary.
+
 ### Extend Exception
 
 Create small domain-specific exception classes when your app has a stable set of error codes.
 
 ```typescript
-import { Exception } from 'error-message-utils';
+import { Exception, type IErrorOptions } from 'error-message-utils';
 
 const USER_ERROR_CODES = {
   EmailTaken: 'USER_EMAIL_TAKEN',
@@ -78,8 +103,13 @@ const USER_ERROR_CODES = {
 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);
+  public constructor(
+    message: string,
+    code: IUserErrorCode,
+    data?: unknown,
+    options?: IErrorOptions,
+  ) {
+    super(message, code, data, options);
     this.name = 'UserException';
   }
 }
@@ -133,6 +163,29 @@ if (!result.success) {
 }
 ```
 
+### Redact Sensitive Values
+
+`extractRedactedMessage` extracts a message using the same rules as `extractMessage`, then replaces
+every exact sensitive value with `[redacted]`.
+
+```typescript
+import { extractRedactedMessage } from 'error-message-utils';
+
+const error = new Error('Request failed for token abc123.', {
+  cause: new Error('The provider rejected abc123.'),
+});
+
+extractRedactedMessage(error, ['abc123']);
+// 'Request failed for token [redacted].; [CAUSE]: The provider rejected [redacted].'
+
+extractRedactedMessage(error, ['different-value']);
+// 'Request failed for token abc123.; [CAUSE]: The provider rejected abc123.'
+```
+
+Matching is literal and case-sensitive. Empty values are ignored. The function does not
+automatically identify secrets, so transformed or encoded versions must be supplied separately if
+they also need redaction.
+
 ### Get an Error Code
 
 Use `getErrorCode` when you only need the resolved code.
@@ -232,6 +285,7 @@ import {
   decodeError,
   encodeError,
   extractMessage,
+  extractRedactedMessage,
   getErrorCode,
   hasErrorCode,
   hasErrorCodePrefix,
@@ -240,6 +294,7 @@ import {
   type IDecodedError,
   type IErrorCode,
   type IErrorCodeCarrier,
+  type IErrorOptions,
   type IExceptionRecord,
 } from 'error-message-utils';
 ```
@@ -248,13 +303,14 @@ import {
 
 | 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()`. |
+| `Exception` | An `Error` subclass that normalizes an unknown error into `message`, `code`, and `data`, and accepts native error options such as `cause`. It can also serialize itself with `toString()` or `toRecord()`, which omit the cause. |
 
 ### Functions
 
 | 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. |
+| `extractRedactedMessage` | `(error: unknown, sensitiveValues: readonly string[]) => string` | Extracts a message and replaces every exact, case-sensitive occurrence of each non-empty sensitive value with `[redacted]`. Returns the extracted message unchanged when no value matches. |
 | `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. |
@@ -268,6 +324,8 @@ import {
 ```typescript
 type IErrorCode = string | number;
 
+type IErrorOptions = ErrorOptions;
+
 type IDecodedError = {
   message: string;
   code: IErrorCode;
@@ -288,9 +346,10 @@ type IExceptionRecord = {
 | Export | Description |
 | --- | --- |
 | `IErrorCode` | The supported type for application error codes. |
+| `IErrorOptions` | A direct alias of the native `ErrorOptions` type accepted by the `Exception` constructor. |
 | `IDecodedError` | The object returned by `decodeError`. |
 | `IErrorCodeCarrier` | A plain object shape that can provide a code to `decodeError`, `getErrorCode`, `hasErrorCode`, `hasErrorCodePrefix`, and `Exception`. |
-| `IExceptionRecord` | The serializable object returned by `Exception.toRecord()`. |
+| `IExceptionRecord` | The serializable object returned by `Exception.toRecord()`. It does not include `cause`. |
 
 ### Constants
 

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

@@ -6,6 +6,13 @@ import type { IErrorCode, IDecodedError } from '../shared/types.js';
  * @returns A string containing the extracted message or the default message if extraction fails.
  */
 export declare const extractMessage: (error: any) => string;
+/**
+ * Extracts an error message and replaces exact sensitive values with a redaction marker.
+ * @param error The error to extract the message from.
+ * @param sensitiveValues The exact case-sensitive values to redact.
+ * @returns The extracted message with matching sensitive values redacted.
+ */
+export declare const extractRedactedMessage: (error: unknown, sensitiveValues: string[]) => string;
 /**
  * Encoding / Decoding
  */

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

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

@@ -1,5 +1,12 @@
 import { ZodError } from 'zod';
 import { IErrorCode } from '../shared/types.js';
+/**
+ * Replaces every literal sensitive value in a message with the redaction marker.
+ * @param message The message to redact.
+ * @param sensitiveValues The exact case-sensitive values to redact.
+ * @returns The message with matching sensitive values redacted.
+ */
+export declare const redactSensitiveValues: (message: string, sensitiveValues: string[]) => string;
 /**
  * Attempts to extract a Zod error message from a ZodError instance. If unable to do so, it returns
  * the default error message.

package/dist/error-handler/utilities.js

@@ -1 +1 @@
-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;
+import{DEFAULT_CODE,DEFAULT_MESSAGE}from"../shared/constants.js";const REDACTION_REPLACEMENT="[redacted]",__collectSensitiveRanges=(e,r)=>{const s=[];return r.forEach((r=>{let t=e.indexOf(r);for(;-1!==t;)s.push({start:t,end:t+r.length}),t=e.indexOf(r,t+1)})),s},__mergeOverlappingRanges=e=>{const r=[...e].sort(((e,r)=>e.start-r.start||r.end-e.end)),s=[];return r.forEach((e=>{const r=s.at(-1);!r||e.start>=r.end?s.push({...e}):e.end>r.end&&(r.end=e.end)})),s};export const redactSensitiveValues=(e,r)=>{const s=[...new Set(r.filter((e=>e.length>0)))];if(!s.length)return e;const t=__mergeOverlappingRanges(__collectSensitiveRanges(e,s));if(!t.length)return e;const n=[];let o=0;return t.forEach((r=>{n.push(e.slice(o,r.start),"[redacted]"),o=r.end})),n.push(e.slice(o)),n.join("")};const __extractPathFromZodError=e=>e&&Array.isArray(e.issues)&&e.issues.length&&Array.isArray(e.issues[0].path)&&e.issues[0].path.length?e.issues[0].path.join("."):"Unknown path";export const extractZodErrorMessage=e=>e&&Array.isArray(e.issues)&&e.issues.length&&Array.isArray(e.issues[0].path)&&e.issues[0].message?`${e.issues[0].message} (${__extractPathFromZodError(e)})`:DEFAULT_MESSAGE;const __isErrorCodeCarrier=e=>"object"==typeof e&&null!==e&&"code"in e&&("string"==typeof e.code||"number"==typeof e.code);export const getDecodedErrorCode=(e,r)=>r!==DEFAULT_CODE?r:__isErrorCodeCarrier(e)?e.code:DEFAULT_CODE;

package/dist/exception/exception.d.ts

@@ -1,7 +1,7 @@
-import { type IErrorCode } from '../shared/types.js';
-import { type IExceptionRecord } from './types.js';
+import type { IErrorCode } from '../shared/types.js';
+import type { IErrorOptions, IExceptionRecord } from './types.js';
 /**
- * Error subclass that normalizes unknown errors into a message, code, and optional data payload.
+ * Error subclass that normalizes unknown errors and supports native error options.
  */
 export declare class Exception extends Error {
     readonly code: IErrorCode;
@@ -11,8 +11,9 @@ export declare class Exception extends Error {
      * @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.
+     * @param options The native error options, including an optional cause.
      */
-    constructor(error: unknown, code?: IErrorCode, data?: unknown);
+    constructor(error: unknown, code?: IErrorCode, data?: unknown, options?: IErrorOptions);
     /**
      * Override the default toString method to return a formatted error message with the code.
      * @returns A string representation of the error 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=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}}}
+import{decodeError,encodeError}from"../error-handler/index.js";export class Exception extends Error{code;data;constructor(e,r,t,o){const s=decodeError(e);super(s.message,o),this.name="Exception",this.code=r??s.code,this.data=void 0===t?s.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/exception/index.d.ts

@@ -1,2 +1,2 @@
-export type { IExceptionRecord } from './types.js';
+export type { IErrorOptions, IExceptionRecord } from './types.js';
 export { Exception } from './exception.js';

package/dist/exception/types.d.ts

@@ -1,4 +1,5 @@
-import { IErrorCode } from '../shared/types.js';
+import type { IErrorCode } from '../shared/types.js';
+export type IErrorOptions = ErrorOptions;
 export type IExceptionRecord = {
     message: string;
     code: IErrorCode;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export type { IErrorCode, IDecodedError, IErrorCodeCarrier } from './shared/types.js';
 export { DEFAULT_CODE, DEFAULT_MESSAGE } from './shared/constants.js';
-export { extractMessage, encodeError, decodeError, isEncodedError, getErrorCode, hasErrorCodePrefix, hasErrorCode, isDefaultErrorMessage, } from './error-handler/index.js';
-export { type IExceptionRecord, Exception } from './exception/index.js';
+export { extractMessage, extractRedactedMessage, encodeError, decodeError, isEncodedError, getErrorCode, hasErrorCodePrefix, hasErrorCode, isDefaultErrorMessage, } from './error-handler/index.js';
+export { type IErrorOptions, 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,getErrorCode,hasErrorCodePrefix,hasErrorCode,isDefaultErrorMessage}from"./error-handler/index.js";export{Exception}from"./exception/index.js";
+export{DEFAULT_CODE,DEFAULT_MESSAGE}from"./shared/constants.js";export{extractMessage,extractRedactedMessage,encodeError,decodeError,isEncodedError,getErrorCode,hasErrorCodePrefix,hasErrorCode,isDefaultErrorMessage}from"./error-handler/index.js";export{Exception}from"./exception/index.js";

package/package.json

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