@hackylabs/deep-redact 2.1.0 → 2.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Benjamin Green (https://bengreen.dev)
+Copyright (c) 2025 Benjamin Green (https://bengreen.dev)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,7 +6,9 @@
 Faster than Fast Redact <sup>1</sup> as well as being safer and more configurable than many other redaction solutions,
 Deep Redact is a zero-dependency tool that redacts sensitive information from strings and objects. It is designed to be
 used in a production environment where sensitive information needs to be redacted from logs, error messages, files,
-and other outputs.
+and other outputs. Supporting both strings and objects or a mix of both, Deep Redact can be used to redact sensitive
+information from more data structures than any other redaction library. Even partially redacting sensitive information
+from strings is supported, by way of custom regex patterns and replacers.
 
 Circular references and other unsupported values are handled gracefully, and the library is designed to be as fast as
 possible while still being easy to use and configure.
@@ -58,7 +60,7 @@ objRedaction.redact(obj)
 // }
 
 const strRedaction = new DeepRedact({
-  stringTests: [
+  partialStringTests: [
     {
       pattern: /<(email|password)>([^<]+)<\/\1>/gi,
       replacer: (value: string, pattern: RegExp) => value.replace(pattern, '<$1>[REDACTED]</$1>'),
@@ -71,6 +73,30 @@ strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine<
 // '<email>[REDACTED]</email><keepThis>This is fine</keepThis><password>[REDACTED]</password>'
 ```
 
+// Override the `unsupportedTransformer` method to handle unsupported values
+
+```typescript
+class CustomRedaction extends DeepRedact {
+  constructor(options) {
+    super(options)
+    this.rewriteUnsupported = (value) => {
+      if (value instanceof BigInt) return value.toString()
+
+      // Add more conditional statements for unsupported value types here (e.g. Error, Date, Map, Set, etc.)
+
+      // If the value is supported, return it
+      return value
+    }
+  }
+}
+
+const customRedaction = new CustomRedaction({
+  blacklistedKeys: ['sensitive', 'password', /name/i],
+})
+
+customRedaction.redact({ a: BigInt(1) })
+```
+
 ## Configuration
 
 ### Main Options
@@ -78,7 +104,8 @@ strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine<
 | key | description | type | options | default | required |
 | --- | --- | --- | --- | --- | --- |
 | blacklistedKeys | Deeply compare names of these keys against the keys in your object. | array | Array<string￨RegExp￨BlacklistKeyConfig> | [] | N |
-| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. | array | Array<RegExp￨StringTestConfig> | [] | N |
+| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. Will redact whole string values. If you want to redact only part of the string, use `partialStringTests` instead. If a replacer function is provided in the config for the associated test, it will be used to redact the value. | array | Array<RegExp￨StringTestConfig> | [] | N |
+| partialStringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. Will redact only the matched part of the string using the replacer function provided in the config for the associated test. | array | StringTestConfig[] | [] | N |
 | fuzzyKeyMatch | Loosely compare key names by checking if the key name of your unredacted object is included anywhere within the name of your blacklisted key. For example, is "pass" (your key) included in "password" (from config). | boolean |  | false | N |
 | caseSensitiveKeyMatch | Loosely compare key names by normalising the strings. This involves removing non-word characters and transforms the string to lowercase. This means you never have to worry having to list duplicate keys in different formats such as snake_case, camelCase, PascalCase or any other case. | boolean |  | true | N |
 | remove | Determines whether or not to remove the key from the object when it is redacted. | boolean |  | false | N |
@@ -131,22 +158,23 @@ Redact and Obglob are slower and rely on dependencies.
 
 | scenario | ops / sec | op duration (ms) | margin of error | sample count |
 | --- | --- | --- | --- | --- |
-| DeepRedact, XML | 171985.01 | 0.0058144601 | 0.00004 | 85993 |
-| JSON.stringify, large object | 162406.59 | 0.0061573855 | 0.00002 | 81204 |
-| DeepRedact, remove item, single object | 25293.55 | 0.039535775 | 0.00023 | 12647 |
-| Regex replace, large object | 22529.52 | 0.0443862153 | 0.00024 | 11265 |
-| DeepRedact, custom replacer function, single object | 22324.84 | 0.0447931554 | 0.00037 | 11163 |
-| DeepRedact, default config, large object | 21437.04 | 0.046648239 | 0.00028 | 10719 |
-| DeepRedact, replace string by length, single object | 21018.32 | 0.0475775519 | 0.00084 | 10510 |
-| DeepRedact, fuzzy matching, single object | 18000.38 | 0.0555543858 | 0.0003 | 9001 |
-| DeepRedact, retain structure, single object | 17581.5 | 0.056877956 | 0.00037 | 8791 |
-| DeepRedact, config per key, single object | 16914.73 | 0.0591200552 | 0.0004 | 8458 |
-| DeepRedact, default config, 1000 large objects | 7989.05 | 0.1251712531 | 0.0018 | 3995 |
-| fast redact, large object | 5929.58 | 0.1686459096 | 0.00126 | 2965 |
-| ObGlob, large object | 4939.98 | 0.2024300664 | 0.01105 | 2470 |
-| DeepRedact, case insensitive matching, single object | 4721.59 | 0.2117932541 | 0.00378 | 2361 |
-| DeepRedact, fuzzy and case insensitive matching, single object | 4686.29 | 0.2133882948 | 0.0018 | 2344 |
-| JSON.stringify, 1000 large objects | 222.05 | 4.5035912679 | 0.04553 | 112 |
-| ObGlob, 1000 large objects | 164.55 | 6.0771323614 | 0.11829 | 83 |
-| fast redact, 1000 large objects | 120.7 | 8.2848202295 | 0.05702 | 61 |
-| Regex replace, 1000 large objects | 93.5 | 10.6954525319 | 0.39014 | 47 |
+| DeepRedact, partial redaction | 176654.38 | 0.0056607711 | 0.00003 | 88329 |
+| JSON.stringify, large object | 164287.01 | 0.0060869085 | 0.00002 | 82144 |
+| DeepRedact, remove item, single object | 25142.69 | 0.0397729959 | 0.00029 | 12572 |
+| Regex replace, large object | 23061.11 | 0.0433630529 | 0.00022 | 11531 |
+| DeepRedact, default config, large object | 21454.71 | 0.0466098038 | 0.00086 | 10728 |
+| DeepRedact, custom replacer function, single object | 21026.51 | 0.047559016 | 0.00047 | 10514 |
+| DeepRedact, replace string by length, single object | 19629.37 | 0.0509440788 | 0.00032 | 9815 |
+| DeepRedact, retain structure, single object | 18238.97 | 0.0548276723 | 0.00049 | 9120 |
+| DeepRedact, fuzzy matching, single object | 17470.6 | 0.0572390237 | 0.00029 | 8736 |
+| DeepRedact, config per key, single object | 15398.94 | 0.0649395488 | 0.00036 | 7700 |
+| DeepRedact, default config, 1000 large objects | 8401.8 | 0.1190220507 | 0.00103 | 4201 |
+| fast redact, large object | 5898.84 | 0.1695249305 | 0.00133 | 2950 |
+| ObGlob, large object | 4876.54 | 0.2050635404 | 0.01142 | 2439 |
+| DeepRedact, case insensitive matching, single object | 3576.62 | 0.279593299 | 0.00282 | 1789 |
+| DeepRedact, fuzzy and case insensitive matching, single object | 3379.78 | 0.295877197 | 0.00244 | 1690 |
+| JSON.stringify, 1000 large objects | 220.76 | 4.5298012342 | 0.10929 | 111 |
+| ObGlob, 1000 large objects | 166.2 | 6.0168303571 | 0.07621 | 84 |
+| DeepRedact, partial redaction large string | 126.88 | 7.8814680469 | 0.28048 | 64 |
+| fast redact, 1000 large objects | 122.12 | 8.1884899032 | 0.06661 | 62 |
+| Regex replace, 1000 large objects | 93.88 | 10.6515390208 | 0.36668 | 48 |

package/dist/cjs/index.js

@@ -47,13 +47,11 @@ class DeepRedact {
          * @returns {unknown} The value in a format that is supported by JSON.stringify.
          */
         this.unsupportedTransformer = (value) => {
-            if (!this.config.serialise)
-                return value;
             if (typeof value === 'bigint') {
                 return {
                     __unsupported: {
                         type: 'bigint',
-                        value: value.toString(),
+                        value: value.toString(10),
                         radix: 10,
                     },
                 };
@@ -145,15 +143,27 @@ class DeepRedact {
          * This is to ensure that the WeakSet doesn't cause memory leaks.
          * @private
          * @param value
+         * @returns {unknown} The value as a JSON string or as the provided value.
+         * @throws {Error} If the value cannot be serialised.
          */
         this.maybeSerialise = (value) => {
             this.circularReference = null;
-            return this.config.serialise ? JSON.stringify(value) : value;
+            if (!this.config.serialise)
+                return value;
+            if (typeof value === 'string')
+                return value;
+            try {
+                return JSON.stringify(value);
+            }
+            catch (error) {
+                throw new Error('Failed to serialise value. Did you override the `unsupportedTransformer` method and return a value that is not supported by JSON.stringify?');
+            }
         };
         /**
          * Redact the provided value. The value will be stripped of any circular references and other unsupported data types, before being redacted according to the configuration and finally serialised if required.
          * @param {unknown} value The value to redact.
          * @returns {unknown} The redacted value.
+         * @throws {Error} If the value cannot be serialised.
          */
         this.redact = (value) => {
             return this.maybeSerialise(this.redactorUtils.recurse(this.rewriteUnsupported(value)));

package/dist/cjs/utils/redactorUtils.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const defaultConfig = {
     stringTests: [],
     blacklistedKeys: [],
+    partialStringTests: [],
     blacklistedKeysTransformed: [],
     fuzzyKeyMatch: false,
     caseSensitiveKeyMatch: true,
@@ -14,7 +15,7 @@ const defaultConfig = {
 };
 class RedactorUtils {
     constructor(customConfig) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         /**
          * The configuration for the redaction.
          * @private
@@ -82,36 +83,37 @@ class RedactorUtils {
         this.redactString = (value, replacement, remove, shouldRedact) => {
             if (!value || typeof value !== 'string')
                 return value;
+            const maybePartiallyRedacted = this.partialStringRedact(value);
             const { stringTests } = this.config;
             if (!shouldRedact) {
                 const result = stringTests === null || stringTests === void 0 ? void 0 : stringTests.map((test) => {
                     if (test instanceof RegExp) {
-                        if (!test.test(value))
-                            return value;
+                        if (!test.test(maybePartiallyRedacted))
+                            return maybePartiallyRedacted;
                         if (remove)
                             return undefined;
                         if (typeof replacement === 'function')
-                            return replacement(value);
+                            return replacement(maybePartiallyRedacted);
                         if (this.config.replaceStringByLength)
-                            return replacement.repeat(value.length);
+                            return replacement.repeat(maybePartiallyRedacted.length);
                         return replacement;
                     }
-                    if (remove && test.pattern.test(value))
+                    if (remove && test.pattern.test(maybePartiallyRedacted))
                         return undefined;
-                    return test.replacer(value, test.pattern);
+                    return test.replacer(maybePartiallyRedacted, test.pattern);
                 }).filter(Boolean)[0];
                 if (result)
                     return result;
                 if (remove)
                     return undefined;
-                return value;
+                return maybePartiallyRedacted;
             }
             if (remove)
                 return undefined;
             if (typeof replacement === 'function')
-                return replacement(value);
+                return replacement(maybePartiallyRedacted);
             if (this.config.replaceStringByLength)
-                return replacement.repeat(value.length);
+                return replacement.repeat(maybePartiallyRedacted.length);
             return replacement;
         };
         /**
@@ -160,6 +162,16 @@ class RedactorUtils {
                 return [prop, this.recurse(val, key !== null && key !== void 0 ? key : prop, shouldRedact)];
             }).filter(([prop]) => prop !== undefined));
         };
+        this.partialStringRedact = (value) => {
+            const { partialStringTests } = this.config;
+            if (partialStringTests.length === 0)
+                return value;
+            let result = value;
+            partialStringTests.forEach((test) => {
+                result = test.replacer(result, test.pattern);
+            });
+            return result;
+        };
         /**
          * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
          * @private
@@ -185,7 +197,7 @@ class RedactorUtils {
                 return this.redactArray(value);
             return this.redactObject(value, key, parentShouldRedact);
         };
-        this.config = Object.assign(Object.assign(Object.assign({}, defaultConfig), customConfig), { blacklistedKeys: (_a = customConfig.blacklistedKeys) !== null && _a !== void 0 ? _a : [], blacklistedKeysTransformed: (_c = (_b = customConfig.blacklistedKeys) === null || _b === void 0 ? void 0 : _b.map((key) => {
+        this.config = Object.assign(Object.assign(Object.assign({}, defaultConfig), customConfig), { partialStringTests: (_a = customConfig.partialStringTests) !== null && _a !== void 0 ? _a : [], blacklistedKeys: (_b = customConfig.blacklistedKeys) !== null && _b !== void 0 ? _b : [], blacklistedKeysTransformed: (_d = (_c = customConfig.blacklistedKeys) === null || _c === void 0 ? void 0 : _c.map((key) => {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
                 const isObject = !(typeof key === 'string' || key instanceof RegExp);
                 const setKey = isObject ? key.key : key;
@@ -208,7 +220,7 @@ class RedactorUtils {
                     };
                 }
                 return fallback;
-            })) !== null && _c !== void 0 ? _c : [] });
+            })) !== null && _d !== void 0 ? _d : [] });
     }
 }
 /**
@@ -217,7 +229,7 @@ class RedactorUtils {
  * @param str The string to normalise.
  * @returns {string} The normalised string.
  */
-RedactorUtils.normaliseString = (str) => str.toLowerCase().replace(/\W/g, '');
+RedactorUtils.normaliseString = (str) => str.toLowerCase().replaceAll(/\W/g, '');
 /**
  * Determine if a key matches a given blacklistedKeyConfig. This will check the key against the blacklisted keys,
  * using the configuration option for the given key falling back to the default configuration.

package/dist/esm/index.mjs

@@ -42,13 +42,11 @@ class DeepRedact {
      * @returns {unknown} The value in a format that is supported by JSON.stringify.
      */
     unsupportedTransformer = (value) => {
-        if (!this.config.serialise)
-            return value;
         if (typeof value === 'bigint') {
             return {
                 __unsupported: {
                     type: 'bigint',
-                    value: value.toString(),
+                    value: value.toString(10),
                     radix: 10,
                 },
             };
@@ -138,15 +136,27 @@ class DeepRedact {
      * This is to ensure that the WeakSet doesn't cause memory leaks.
      * @private
      * @param value
+     * @returns {unknown} The value as a JSON string or as the provided value.
+     * @throws {Error} If the value cannot be serialised.
      */
     maybeSerialise = (value) => {
         this.circularReference = null;
-        return this.config.serialise ? JSON.stringify(value) : value;
+        if (!this.config.serialise)
+            return value;
+        if (typeof value === 'string')
+            return value;
+        try {
+            return JSON.stringify(value);
+        }
+        catch (error) {
+            throw new Error('Failed to serialise value. Did you override the `unsupportedTransformer` method and return a value that is not supported by JSON.stringify?');
+        }
     };
     /**
      * Redact the provided value. The value will be stripped of any circular references and other unsupported data types, before being redacted according to the configuration and finally serialised if required.
      * @param {unknown} value The value to redact.
      * @returns {unknown} The redacted value.
+     * @throws {Error} If the value cannot be serialised.
      */
     redact = (value) => {
         return this.maybeSerialise(this.redactorUtils.recurse(this.rewriteUnsupported(value)));

package/dist/esm/utils/redactorUtils.mjs

@@ -1,6 +1,7 @@
 const defaultConfig = {
     stringTests: [],
     blacklistedKeys: [],
+    partialStringTests: [],
     blacklistedKeysTransformed: [],
     fuzzyKeyMatch: false,
     caseSensitiveKeyMatch: true,
@@ -20,6 +21,7 @@ class RedactorUtils {
         this.config = {
             ...defaultConfig,
             ...customConfig,
+            partialStringTests: customConfig.partialStringTests ?? [],
             blacklistedKeys: customConfig.blacklistedKeys ?? [],
             blacklistedKeysTransformed: customConfig.blacklistedKeys?.map((key) => {
                 const isObject = !(typeof key === 'string' || key instanceof RegExp);
@@ -52,7 +54,7 @@ class RedactorUtils {
      * @param str The string to normalise.
      * @returns {string} The normalised string.
      */
-    static normaliseString = (str) => str.toLowerCase().replace(/\W/g, '');
+    static normaliseString = (str) => str.toLowerCase().replaceAll(/\W/g, '');
     /**
      * Determine if a key matches a given blacklistedKeyConfig. This will check the key against the blacklisted keys,
      * using the configuration option for the given key falling back to the default configuration.
@@ -133,36 +135,37 @@ class RedactorUtils {
     redactString = (value, replacement, remove, shouldRedact) => {
         if (!value || typeof value !== 'string')
             return value;
+        const maybePartiallyRedacted = this.partialStringRedact(value);
         const { stringTests } = this.config;
         if (!shouldRedact) {
             const result = stringTests?.map((test) => {
                 if (test instanceof RegExp) {
-                    if (!test.test(value))
-                        return value;
+                    if (!test.test(maybePartiallyRedacted))
+                        return maybePartiallyRedacted;
                     if (remove)
                         return undefined;
                     if (typeof replacement === 'function')
-                        return replacement(value);
+                        return replacement(maybePartiallyRedacted);
                     if (this.config.replaceStringByLength)
-                        return replacement.repeat(value.length);
+                        return replacement.repeat(maybePartiallyRedacted.length);
                     return replacement;
                 }
-                if (remove && test.pattern.test(value))
+                if (remove && test.pattern.test(maybePartiallyRedacted))
                     return undefined;
-                return test.replacer(value, test.pattern);
+                return test.replacer(maybePartiallyRedacted, test.pattern);
             }).filter(Boolean)[0];
             if (result)
                 return result;
             if (remove)
                 return undefined;
-            return value;
+            return maybePartiallyRedacted;
         }
         if (remove)
             return undefined;
         if (typeof replacement === 'function')
-            return replacement(value);
+            return replacement(maybePartiallyRedacted);
         if (this.config.replaceStringByLength)
-            return replacement.repeat(value.length);
+            return replacement.repeat(maybePartiallyRedacted.length);
         return replacement;
     };
     /**
@@ -211,6 +214,16 @@ class RedactorUtils {
             return [prop, this.recurse(val, key ?? prop, shouldRedact)];
         }).filter(([prop]) => prop !== undefined));
     };
+    partialStringRedact = (value) => {
+        const { partialStringTests } = this.config;
+        if (partialStringTests.length === 0)
+            return value;
+        let result = value;
+        partialStringTests.forEach((test) => {
+            result = test.replacer(result, test.pattern);
+        });
+        return result;
+    };
     /**
      * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
      * @private

package/dist/types/index.d.ts

@@ -51,12 +51,15 @@ declare class DeepRedact {
      * This is to ensure that the WeakSet doesn't cause memory leaks.
      * @private
      * @param value
+     * @returns {unknown} The value as a JSON string or as the provided value.
+     * @throws {Error} If the value cannot be serialised.
      */
     private maybeSerialise;
     /**
      * Redact the provided value. The value will be stripped of any circular references and other unsupported data types, before being redacted according to the configuration and finally serialised if required.
      * @param {unknown} value The value to redact.
      * @returns {unknown} The redacted value.
+     * @throws {Error} If the value cannot be serialised.
      */
     redact: (value: unknown) => unknown;
 }

package/dist/types/types.d.ts

@@ -42,6 +42,10 @@ export interface BlacklistKeyConfig {
      */
     key: string | RegExp;
 }
+export interface ComplexStringTest {
+    pattern: RegExp;
+    replacer: (value: string, pattern: RegExp) => string;
+}
 export interface BaseDeepRedactConfig {
     /**
      * Keys that should be redacted. Can be a string, or an object with additional configuration options.
@@ -58,10 +62,8 @@ export interface BaseDeepRedactConfig {
      *   /^[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}$/,  // redact any string that looks like an IP address.
      * ]
      */
-    stringTests?: Array<RegExp | {
-        pattern: RegExp;
-        replacer: (value: string, pattern: RegExp) => string;
-    }>;
+    stringTests?: Array<RegExp | ComplexStringTest>;
+    partialStringTests?: Array<ComplexStringTest>;
     /**
      * Perform a fuzzy match on the key. This will match any key that contains the string, rather than a case-sensitive match.
      * @default false
@@ -122,8 +124,20 @@ export interface BaseDeepRedactConfig {
     serialize?: boolean;
 }
 export type DeepRedactConfig = Partial<Omit<BaseDeepRedactConfig, 'blacklistedKeysTransformed' | 'blacklistedKeys' | 'stringTests'>> & ({
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
     blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
     stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
+    blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
+} | {
+    blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
+    stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
+    stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
 } | {
     blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
 } | {

package/dist/types/utils/redactorUtils.d.ts

@@ -77,6 +77,7 @@ declare class RedactorUtils {
      * @param {boolean} parentShouldRedact Whether the item should be redacted based on the key within the parent object.
      */
     private redactObject;
+    partialStringRedact: (value: string) => string;
     /**
      * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
      * @private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackylabs/deep-redact",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",