@hackylabs/deep-redact 2.2.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

@@ -73,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
@@ -134,23 +158,23 @@ Redact and Obglob are slower and rely on dependencies.
 
 | 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 |
+| 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,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.1",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",