@hackylabs/deep-redact 2.2.0 → 2.2.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Benjamin Green (https://bengreen.dev)
+Copyright (c) 2026 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

@@ -3,12 +3,11 @@
 [![npm version](https://badge.fury.io/js/@hackylabs%2Fdeep-redact.svg)](https://badge.fury.io/js/@hackylabs%2Fdeep-redact)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hackylabs/deep-redact/blob/main/LICENSE)
 
-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. 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.
+Deep Redact is a safe, configurable, 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. Supporting both strings and objects or a mix of both, Deep Redact can be used to
+redact sensitive information from a wide range of data structures. 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.
@@ -73,6 +72,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
@@ -110,47 +133,16 @@ strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine<
 | replacer | A function that will be called with the value of the string that matched the pattern and the pattern itself. This function should return the new (redacted) value to replace the original value. | function | Y |
 
 ### Benchmark
-Comparisons are made against JSON.stringify, Regex.replace, Fast Redact &
-(one of my other creations, [@hackylabs/obglob](https://npmjs.com/package/@hackylabs/obglob)) as well as different
-configurations of Deep Redact, using [this test object](./test/setup/dummyUser.ts). Fast Redact was configured to redact
-the same keys on the same object as Deep Redact without using wildcards.
-
-The benchmark is run on a 2021 iMac with an M1 chip with 16GB memory running macOS Sequoia 15.0.0.
-
-JSON.stringify is included as a benchmark because it is the fastest way to deeply iterate over an object, although it
-doesn't redact any sensitive information.
-
-Regex.replace is included as a benchmark because it is the fastest way to redact sensitive information from a string.
-However, a regex pattern for all keys to be redacted is much harder to configure than a dedicated redaction library,
-especially when dealing with multiple types of values. It also doesn't handle circular references or other unsupported
-values as gracefully as deep-redact unless a third-party library is used to stringify the object beforehand.
-
-Fast-redact is included as a benchmark because it's the next fastest library available specifically for redaction.
-
-Neither JSON.stringify, Regex.replace nor Fast Redact offer the same level of configurability as deep-redact. Both Fast
-Redact and Obglob are slower and rely on dependencies.
-
-![Benchmark](./benchmark.png)
-
-| scenario | ops / sec | op duration (ms) | margin of error | sample count |
-| --- | --- | --- | --- | --- |
-| DeepRedact, partial redaction | 178183.03 | 0.0056122067 | 0.00003 | 89092 |
-| JSON.stringify, large object | 161672.63 | 0.0061853388 | 0.00004 | 80837 |
-| DeepRedact, remove item, single object | 25085.95 | 0.039862959 | 0.00033 | 12543 |
-| DeepRedact, default config, large object | 23164.57 | 0.0431693713 | 0.00023 | 11583 |
-| Regex replace, large object | 22828.32 | 0.043805244 | 0.00031 | 11415 |
-| DeepRedact, custom replacer function, single object | 22520.52 | 0.0444039553 | 0.00039 | 11261 |
-| DeepRedact, replace string by length, single object | 22470.94 | 0.0445019191 | 0.00025 | 11236 |
-| DeepRedact, retain structure, single object | 18315.67 | 0.0545980591 | 0.00026 | 9158 |
-| DeepRedact, fuzzy matching, single object | 18077.45 | 0.0553175285 | 0.00035 | 9039 |
-| DeepRedact, config per key, single object | 16055.96 | 0.0622821745 | 0.00031 | 8028 |
-| DeepRedact, default config, 1000 large objects | 8077.4 | 0.1238022 | 0.00187 | 4039 |
-| fast redact, large object | 5918.61 | 0.1689584628 | 0.00151 | 2960 |
-| ObGlob, large object | 5193.29 | 0.1925563273 | 0.00972 | 2597 |
-| DeepRedact, case insensitive matching, single object | 3477.6 | 0.2875549482 | 0.00324 | 1739 |
-| DeepRedact, fuzzy and case insensitive matching, single object | 3437.73 | 0.2908896131 | 0.00239 | 1719 |
-| ObGlob, 1000 large objects | 237.69 | 4.2072005126 | 0.05005 | 119 |
-| JSON.stringify, 1000 large objects | 230.33 | 4.3416907672 | 0.04373 | 116 |
-| DeepRedact, partial redaction large string | 127.18 | 7.8628400156 | 0.4176 | 64 |
-| fast redact, 1000 large objects | 119.33 | 8.3803393 | 0.31943 | 60 |
-| Regex replace, 1000 large objects | 97.12 | 10.2963537755 | 0.29341 | 49 |
+
+A benchmark comparing Deep Redact against other libraries appeared in earlier versions of this README. It has been
+withdrawn because of a subtle flaw in how the test data was constructed.
+
+The multi-object scenarios built their input with `Array(1000).fill(user)`, which produces an array of 1000 references
+to a *single* shared object rather than 1000 distinct objects. Deep Redact's circular-reference protection correctly
+detects the repeated reference and replaces every occurrence after the first with a circular-reference marker, so it
+effectively redacted one object while the other libraries redacted all 1000. That short-circuiting is correct behaviour
+in its own right, which is part of why the benchmarking mistake was easy to overlook, but it meant the libraries were
+doing very different amounts of work and overstated Deep Redact's throughput by roughly 50-70x in those cases. The
+single-object scenarios were also not strictly like-for-like.
+
+Because the figures were not representative, this release makes no performance comparison against other libraries.

package/dist/cjs/index.js

@@ -47,8 +47,6 @@ 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: {
@@ -145,18 +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;
-            const result = this.redactorUtils.partialStringRedact(value);
             if (!this.config.serialise)
-                return result;
-            return typeof result === 'string' ? result : JSON.stringify(result);
+                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

@@ -83,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;
         };
         /**
@@ -165,23 +166,11 @@ class RedactorUtils {
             const { partialStringTests } = this.config;
             if (partialStringTests.length === 0)
                 return value;
-            let result;
-            if (typeof value === 'string') {
-                result = value;
-            }
-            else {
-                try {
-                    result = JSON.stringify(value);
-                }
-                catch (error) {
-                    // It should never reach this point, but if it does, it will throw an error that must not contain sensitive data.
-                    throw new Error('Failed to stringify value for partialStringRedact. Did you replace the rewriteUnsupported method with something that returns non-serialisable data?');
-                }
-            }
+            let result = value;
             partialStringTests.forEach((test) => {
                 result = test.replacer(result, test.pattern);
             });
-            return typeof value === 'string' ? result : JSON.parse(result);
+            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.

package/dist/esm/index.mjs

@@ -42,8 +42,6 @@ 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: {
@@ -138,18 +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;
-        const result = this.redactorUtils.partialStringRedact(value);
         if (!this.config.serialise)
-            return result;
-        return typeof result === 'string' ? result : JSON.stringify(result);
+            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

@@ -135,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;
     };
     /**
@@ -217,23 +218,11 @@ class RedactorUtils {
         const { partialStringTests } = this.config;
         if (partialStringTests.length === 0)
             return value;
-        let result;
-        if (typeof value === 'string') {
-            result = value;
-        }
-        else {
-            try {
-                result = JSON.stringify(value);
-            }
-            catch (error) {
-                // It should never reach this point, but if it does, it will throw an error that must not contain sensitive data.
-                throw new Error('Failed to stringify value for partialStringRedact. Did you replace the rewriteUnsupported method with something that returns non-serialisable data?');
-            }
-        }
+        let result = value;
         partialStringTests.forEach((test) => {
             result = test.replacer(result, test.pattern);
         });
-        return typeof value === 'string' ? result : JSON.parse(result);
+        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.

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/utils/redactorUtils.d.ts

@@ -77,7 +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: unknown) => unknown;
+    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.2.0",
+  "version": "2.2.2",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",
@@ -51,11 +51,9 @@
   },
   "scripts": {
     "lint": "eslint",
-    "build": "npm run lint && npm run test && npm run bench && npm run build:esm && npm run build:cjs && npm run update-readme && npm run update-license",
+    "build": "npm run lint && npm run test && npm run build:esm && npm run build:cjs && npm run update-readme && npm run update-license",
     "build:esm": "tsc --project tsconfig.esm.json && ./scripts/js-to-mjs.sh",
     "build:cjs": "tsc --project tsconfig.cjs.json",
-    "bench": "npx vitest bench --watch=false",
-    "bench:dev": "npx vitest bench",
     "test:dev": "npx vitest",
     "test": "npx vitest run",
     "update-readme": "npx ts-node ./scripts/update-readme.ts",