error-message-utils 1.2.11 → 1.2.13

package/README.md

@@ -133,6 +133,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.
@@ -157,6 +180,19 @@ hasErrorCode(exception, 'ACCESS_DENIED'); // true
 hasErrorCode(exception, 'PAYMENT_FAILED'); // false
 ```
 
+Use `hasErrorCodePrefix` when related string codes share a prefix. Empty prefixes and numeric codes
+do not match.
+
+```typescript
+import { Exception, hasErrorCodePrefix } from 'error-message-utils';
+
+const exception = new Exception('User not found', 'USER_NOT_FOUND');
+
+hasErrorCodePrefix(exception, 'USER_'); // true
+hasErrorCodePrefix('USER_NOT_FOUND', 'USER_'); // true
+hasErrorCodePrefix(exception, 'PAYMENT_'); // false
+```
+
 ### Encode and Decode Plain Strings
 
 `encodeError` and `decodeError` are lower-level helpers for systems that can only pass string
@@ -219,8 +255,10 @@ import {
   decodeError,
   encodeError,
   extractMessage,
+  extractRedactedMessage,
   getErrorCode,
   hasErrorCode,
+  hasErrorCodePrefix,
   isDefaultErrorMessage,
   isEncodedError,
   type IDecodedError,
@@ -241,11 +279,13 @@ import {
 | 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. |
 | `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. |
+| `hasErrorCodePrefix` | `(error: unknown, prefix: string) => boolean` | Checks whether an error resolves to a string code that starts with the provided non-empty prefix. Raw string codes are supported; numeric codes do not match. |
 | `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
@@ -274,7 +314,7 @@ type IExceptionRecord = {
 | --- | --- |
 | `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`. |
+| `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()`. |
 
 ### 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
  */
@@ -38,6 +45,13 @@ export declare const isEncodedError: (error: any) => boolean;
  * @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 has a string code that starts with the specified prefix.
+ * @param error The error to be checked, can be of any type.
+ * @param prefix The non-empty prefix to check against.
+ * @returns A boolean indicating whether the error code starts with the specified prefix.
+ */
+export declare const hasErrorCodePrefix: (error: unknown, prefix: string) => boolean;
 /**
  * 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,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);
+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/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, hasErrorCode, isDefaultErrorMessage, } from './error-handler/index.js';
+export { extractMessage, extractRedactedMessage, encodeError, decodeError, isEncodedError, getErrorCode, hasErrorCodePrefix, 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,getErrorCode,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.11",
+  "version": "1.2.13",
   "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",