@hackylabs/deep-redact 2.2.0 → 3.0.0

package/dist/types/index.d.ts

@@ -1,15 +1,10 @@
-import { DeepRedactConfig } from './types';
+import type { DeepRedactConfig, RedactorUtilsConfig, BlacklistKeyConfig, Types, Transformer, ComplexStringTest, BaseDeepRedactConfig } from './types';
 declare class DeepRedact {
     /**
      * The redactorUtils instance to handle the redaction.
      * @private
      */
     private redactorUtils;
-    /**
-     * A WeakSet to store circular references during redaction. Reset to null after redaction is complete.
-     * @private
-     */
-    private circularReference;
     /**
      * The configuration for the redaction.
      * @private
@@ -22,42 +17,12 @@ declare class DeepRedact {
      * @param {DeepRedactConfig} config. The configuration for the redaction.
      */
     constructor(config: DeepRedactConfig);
-    /**
-     * A transformer for unsupported data types. If `serialise` is false, the value will be returned as is,
-     * otherwise it will transform the value into a format that is supported by JSON.stringify.
-     *
-     * Error, RegExp, and Date instances are technically supported by JSON.stringify,
-     * but they returned as empty objects, therefore they are also transformed here.
-     * @protected
-     * @param {unknown} value The value that is not supported by JSON.stringify.
-     * @returns {unknown} The value in a format that is supported by JSON.stringify.
-     */
-    protected unsupportedTransformer: (value: unknown) => unknown;
-    /**
-     * Calls `unsupportedTransformer` on the provided value and rewrites any circular references.
-     *
-     * Circular references will always be removed to avoid infinite recursion.
-     * When a circular reference is found, the value will be replaced with `[[CIRCULAR_REFERENCE: path.to.original.value]]`.
-     * @protected
-     * @param {unknown} value The value to rewrite.
-     * @param {string | undefined} path The path to the value in the object.
-     * @returns {unknown} The rewritten value.
-     */
-    protected rewriteUnsupported: (value: unknown, path?: string) => unknown;
-    /**
-     * Depending on the value of `serialise`, return the value as a JSON string or as the provided value.
-     *
-     * Also resets the `circularReference` property to null after redaction is complete.
-     * This is to ensure that the WeakSet doesn't cause memory leaks.
-     * @private
-     * @param value
-     */
-    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 to JSON and serialise is true.
      */
     redact: (value: unknown) => unknown;
 }
-export { DeepRedact as default, DeepRedact };
+export { DeepRedact, DeepRedact as default, type BaseDeepRedactConfig, type RedactorUtilsConfig, type BlacklistKeyConfig, type ComplexStringTest, type Transformer, type Types, };

package/dist/types/types.d.ts

@@ -1,5 +1,5 @@
 export type Types = 'string' | 'number' | 'bigint' | 'boolean' | 'object' | 'function' | 'symbol' | 'undefined';
-export type Transformer = (value: unknown) => unknown;
+export type Transformer = (value: unknown, key?: string, reference?: WeakMap<object, unknown>) => unknown;
 export interface BlacklistKeyConfig {
     /**
      * Perform a fuzzy match on the key. This will match any key that contains the string, rather than a case-sensitive match.
@@ -28,13 +28,23 @@ export interface BlacklistKeyConfig {
      * @example true // remove the redacted data.
      */
     remove?: boolean;
+    /**
+     * The replacement value for redacted data. Can be a string, or a function that takes the original value and returns any value.
+     * @default '[REDACTED]'
+     * @example '*' // if `replacement` equals `*` then `joe.bloggs@example.com` becomes `**********************`
+     * @example (value) => `REDACTED: ${typeof value}` // redact the value with a prefix of 'REDACTED: ' and the type of the value.
+     * @example (value) => return typeof value === 'string' ? '*'.repeat(value.length) : '[REDACTED]' // redact the value with a string of the same length.
+     * @param value The original value that is being redacted.
+     * @returns The redacted value or undefined to remove the value.
+     */
+    replacement?: string | ((value: unknown) => unknown);
     /**
      * Replace string values with a redacted string of the same length, using the `replacement` option. Ignored if `remove` is true, `replacement` is a function, or the value is not a string.
      * @default false
      * @example true // if `replacement` equals `*` then `joe.bloggs@example.com` becomes `**********************`
      * @example false // if `replacement` equals `*` then `joe.bloggs@example.com` becomes `*`
      */
-    replacement?: string | ((value: unknown) => unknown);
+    replaceStringByLength?: boolean;
     /**
      * The key to redact. Can be a string or a RegExp.
      * @example 'address' // redact any key that is 'address'.
@@ -54,7 +64,6 @@ export interface BaseDeepRedactConfig {
      * @example [{ key: 'address', fuzzyKeyMatch: true, caseSensitiveKeyMatch: false }] // redact any key that contains 'address' regardless of case.
      */
     blacklistedKeys?: Array<string | RegExp | BlacklistKeyConfig>;
-    blacklistedKeysTransformed: Array<Required<BlacklistKeyConfig>>;
     /**
      * Redact a string value that matches a test pattern.
      * @default []
@@ -63,7 +72,6 @@ export interface BaseDeepRedactConfig {
      * ]
      */
     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,25 +130,48 @@ export interface BaseDeepRedactConfig {
      * Alias of `serialise` for International-English users.
      */
     serialize?: boolean;
+    /**
+     * A list of transformers to apply when transforming unsupported values.
+     * Each transformer should conditionally transform the value, or return the value unchanged to be passed to the next transformer.
+     * Transformers will be run in the order they are provided recursively over the entire object.
+     * @default []
+     * @example [
+     *   // redact a key by name.
+     *   standardTransformers.redactByKey,
+     *   // convert a Date to an ISO string.
+     *   (value: unknown) => {
+     *     if (!(value instanceof Date)) return value
+     *     return value.toISOString()
+     *   },
+     *   // convert a BigInt to a string.
+     *   (value: unknown) => {
+     *     if (typeof value !== 'bigint') return value
+     *     return value.toString(10)
+     *   }
+     */
+    transformers?: Array<Transformer>;
 }
-export type DeepRedactConfig = Partial<Omit<BaseDeepRedactConfig, 'blacklistedKeysTransformed' | 'blacklistedKeys' | 'stringTests'>> & ({
-    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
+export type DeepRedactConfig = Partial<Omit<BaseDeepRedactConfig, '_blacklistedKeysTransformed' | 'blacklistedKeys' | 'stringTests'>> & ({
     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'];
 } | {
     stringTests: BaseDeepRedactConfig['stringTests'];
 });
 export type RedactorUtilsConfig = Omit<BaseDeepRedactConfig, 'serialise' | 'serialize'>;
+export type StackReference = WeakMap<object, unknown>;
+export type Stack = Array<{
+    parent: any;
+    key: string;
+    value: unknown;
+    path: Array<string | number>;
+    redactingParent: boolean;
+    keyConfig: BlacklistKeyConfig | undefined;
+}>;
+export type Logs = Array<{
+    path: string;
+    message: string;
+    raw: unknown;
+    transformed: unknown;
+}> | null;

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

@@ -0,0 +1,130 @@
+import type { RedactorUtilsConfig } from '../types';
+declare class RedactorUtils {
+    /**
+     * The configuration for the redaction.
+     * @private
+     */
+    private readonly config;
+    /**
+     * The computed regex pattern generated from sanitised blacklist keys of flat strings
+     * @private
+     */
+    private readonly computedRegex;
+    /**
+     * Regex to sanitise strings for the computed regex
+     * @private
+     */
+    private readonly sanitiseRegex;
+    /**
+     * The transformed blacklist keys of flat regex patterns and complex config objects
+     * @private
+     */
+    private readonly blacklistedKeysTransformed;
+    constructor(customConfig: RedactorUtilsConfig);
+    private createTransformedBlacklistedKey;
+    /**
+     * Applies transformers to a value
+     * @param value - The value to transform
+     * @param key - The key to check
+     * @returns The transformed value
+     * @private
+     */
+    private applyTransformers;
+    /**
+     * Sanitises a string for the computed regex
+     * @param key - The string to sanitise
+     * @returns The sanitised string
+     * @private
+     */
+    private sanitiseStringForRegex;
+    /**
+     * Checks if a key should be redacted
+     * @param key - The key to check
+     * @returns Whether the key should be redacted
+     * @private
+     */
+    private shouldRedactKey;
+    /**
+     * Checks if a value should be redacted
+     * @param value - The value to check
+     * @param key - The key to check
+     * @returns Whether the value should be redacted
+     * @private
+     */
+    private shouldRedactValue;
+    /**
+     * Redacts a value based on the key-specific config
+     * @param value - The value to redact
+     * @param key - The key to check
+     * @param redactingParent - Whether the parent is being redacted
+     * @returns The redacted value
+     * @private
+     */
+    private redactValue;
+    /**
+     * Applies string transformations
+     * @param value - The value to transform
+     * @param key - The key to check
+     * @returns The transformed value
+     * @private
+     */
+    private applyStringTransformations;
+    /**
+     * Handles primitive values
+     * @param value - The value to handle
+     * @param key - The key to check
+     * @param redactingParent - Whether the parent is being redacted
+     * @param keyConfig - The key config
+     * @returns The transformed value
+     * @private
+     */
+    private handlePrimitiveValue;
+    /**
+     * Handles object values
+     * @param value - The value to handle
+     * @param key - The key to check
+     * @param path - The path to the value
+     * @param redactingParent - Whether the parent is being redacted
+     * @param referenceMap - The reference map
+     * @returns The transformed value and stack
+     * @private
+     */
+    private handleObjectValue;
+    /**
+     * Handles object values
+     * @param value - The value to handle
+     * @param path - The path to the value
+     * @param redactingParent - Whether the parent is being redacted
+     * @returns The transformed value and stack
+     * @private
+     */
+    private handleRetainStructure;
+    /**
+     * Finds the matching key config
+     * @param key - The key to find
+     * @returns The matching key config
+     * @private
+     */
+    private findMatchingKeyConfig;
+    /**
+     * Initialises the traversal
+     * @param raw - The raw value to traverse
+     * @returns The output and stack
+     * @private
+     */
+    private initialiseTraversal;
+    /**
+     * Pre-processes the input to replace circular references with transformer objects
+     * @param raw - The raw value to process
+     * @returns The processed value with circular references replaced
+     * @private
+     */
+    private replaceCircularReferences;
+    /**
+     * Traverses the raw value
+     * @param raw - The raw value to traverse
+     * @returns The transformed value
+     */
+    traverse: (raw: unknown) => unknown;
+}
+export default RedactorUtils;

package/dist/types/utils/standardTransformers/bigint.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from '../../types';
+export declare const _bigint: Transformer;

package/dist/types/utils/standardTransformers/date.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _date: Transformer;

package/dist/types/utils/standardTransformers/error.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _error: Transformer;

package/dist/types/utils/standardTransformers/index.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "src/types";
+export declare const standardTransformers: Transformer[];

package/dist/types/utils/standardTransformers/map.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _map: Transformer;

package/dist/types/utils/standardTransformers/regex.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _regex: Transformer;

package/dist/types/utils/standardTransformers/set.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _set: Transformer;

package/dist/types/utils/standardTransformers/url.d.ts

@@ -0,0 +1,2 @@
+import type { Transformer } from "../../types";
+export declare const _url: Transformer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackylabs/deep-redact",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",
@@ -11,14 +11,59 @@
   "module": "./dist/esm/index.mjs",
   "exports": {
     ".": {
-      "import": "./dist/esm/index.mjs",
-      "require": "./dist/cjs/index.js",
+      "import": "./dist/index",
+      "require": "./dist/index",
       "types": "./dist/types/index.d.ts"
     },
-    "./utils/redactorUtils": {
-      "import": "./dist/esm/utils/redactorUtils.mjs",
-      "require": "./dist/cjs/utils/redactorUtils.js",
-      "types": "./dist/types/utils/redactorUtils.d.ts"
+    "./types": {
+      "import": "./dist/types",
+      "require": "./dist/types",
+      "types": "./dist/types/types.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils",
+      "require": "./dist/utils",
+      "types": "./dist/types/utils.d.ts"
+    },
+    "./utils/standardTransformers/bigint": {
+      "import": "./dist/utils/standardTransformers/bigint",
+      "require": "./dist/utils/standardTransformers/bigint",
+      "types": "./dist/types/utils/standardTransformers/bigint.d.ts"
+    },
+    "./utils/standardTransformers/date": {
+      "import": "./dist/utils/standardTransformers/date",
+      "require": "./dist/utils/standardTransformers/date",
+      "types": "./dist/types/utils/standardTransformers/date.d.ts"
+    },
+    "./utils/standardTransformers/error": {
+      "import": "./dist/utils/standardTransformers/error",
+      "require": "./dist/utils/standardTransformers/error",
+      "types": "./dist/types/utils/standardTransformers/error.d.ts"
+    },
+    "./utils/standardTransformers": {
+      "import": "./dist/utils/standardTransformers",
+      "require": "./dist/utils/standardTransformers",
+      "types": "./dist/types/utils/standardTransformers.d.ts"
+    },
+    "./utils/standardTransformers/map": {
+      "import": "./dist/utils/standardTransformers/map",
+      "require": "./dist/utils/standardTransformers/map",
+      "types": "./dist/types/utils/standardTransformers/map.d.ts"
+    },
+    "./utils/standardTransformers/regex": {
+      "import": "./dist/utils/standardTransformers/regex",
+      "require": "./dist/utils/standardTransformers/regex",
+      "types": "./dist/types/utils/standardTransformers/regex.d.ts"
+    },
+    "./utils/standardTransformers/set": {
+      "import": "./dist/utils/standardTransformers/set",
+      "require": "./dist/utils/standardTransformers/set",
+      "types": "./dist/types/utils/standardTransformers/set.d.ts"
+    },
+    "./utils/standardTransformers/url": {
+      "import": "./dist/utils/standardTransformers/url",
+      "require": "./dist/utils/standardTransformers/url",
+      "types": "./dist/types/utils/standardTransformers/url.d.ts"
     }
   },
   "files": [
@@ -51,28 +96,35 @@
   },
   "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 bench && npm run build:esm && npm run build:cjs && npm run update-exports && 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",
+    "load": "npx vitest run test/load/redact.test.ts --reporter=basic --coverage=false",
+    "load:dev": "npx vitest test/load/redact.test.ts --coverage=false --reporter=basic",
+    "unit": "npx vitest run test/unit --reporter=verbose",
+    "unit:dev": "npx vitest test/unit --coverage=false --reporter=verbose",
     "update-readme": "npx ts-node ./scripts/update-readme.ts",
-    "update-license": "npx ts-node ./scripts/update-license.ts"
+    "update-license": "npx ts-node ./scripts/update-license.ts",
+    "update-exports": "npx ts-node ./scripts/update-exports.ts"
   },
   "//": [
-    "fast-redact and obglob are installed only as benchmark comparisons and are not used in the library",
+    "autocannon, fast-redact and obglob are installed only as internal benchmark comparisons and are not used in the library",
     "all dependencies are for development purposes only"
   ],
   "devDependencies": {
     "@hackylabs/obglob": "1.1.2",
     "@memlab/core": "1.1.34",
+    "@types/autocannon": "7.12.6",
     "@types/fast-redact": "3.0.4",
     "@types/node": "20.14.12",
     "@typescript-eslint/eslint-plugin": "7.14.1",
     "@typescript-eslint/parser": "7.14.1",
     "@vitest/coverage-v8": "2.0.4",
+    "autocannon": "8.0.0",
     "eslint": "8.57.0",
     "eslint-config-airbnb-base": "15.0.0",
     "eslint-config-airbnb-typescript": "18.0.0",
@@ -80,9 +132,10 @@
     "eslint-plugin-n": "17.9.0",
     "eslint-plugin-promise": "7.0.0",
     "fast-redact": "3.5.0",
-    "image-charts": "6.1.19",
-    "superjson": "2.2.1",
     "typescript": "5.6.2",
     "vitest": "2.0.4"
-  }
+  },
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": true,
+  "editor.defaultFormatter": "EditorConfig.editorconfig"
 }