@hackylabs/deep-redact 3.0.5 → 4.0.0

package/dist/types/types.d.ts

@@ -1,224 +0,0 @@
-export type Types = 'string' | 'number' | 'bigint' | 'boolean' | 'object' | 'function' | 'symbol' | 'undefined';
-export type Transformer = (value: unknown, key?: string, reference?: WeakMap<object, unknown>) => unknown;
-/**
- * Configuration for organised transformers by type and constructor
- */
-export interface OrganisedTransformers {
-    /**
-     * Transformers for primitive types (based on typeof result)
-     */
-    byType?: {
-        bigint?: Transformer[];
-        string?: Transformer[];
-        number?: Transformer[];
-        boolean?: Transformer[];
-        symbol?: Transformer[];
-        function?: Transformer[];
-        object?: Transformer[];
-        undefined?: Transformer[];
-    };
-    /**
-     * Transformers for specific constructors (based on instanceof checks)
-     */
-    byConstructor?: {
-        Date?: Transformer[];
-        Error?: Transformer[];
-        Map?: Transformer[];
-        Set?: Transformer[];
-        RegExp?: Transformer[];
-        URL?: Transformer[];
-        [key: string]: Transformer[] | undefined;
-    };
-    /**
-     * Transformers that run on all values (like the current system)
-     */
-    fallback?: Transformer[];
-}
-/**
- * Transformer configuration - supports both old array format and new organised format
- */
-export type TransformerConfig = Transformer[] | OrganisedTransformers;
-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.
-     * @default false
-     * @example true // match any key that contains the string 'address', such as 'homeAddress', 'workAddress', 'addressLine1', etc.
-     * @example false // match only keys that contain 'address' from start to end.
-     */
-    fuzzyKeyMatch?: boolean;
-    /**
-     * Perform a case-sensitive match on the key
-     * @default true
-     * @example false // match any key that contains the string 'address' regardless of upper, lower, snake, camel or any other case.
-     * @example true // match only keys that are exactly 'address' in the same case.
-     */
-    caseSensitiveKeyMatch?: boolean;
-    /**
-     * Retain the structure of the object, but redact the values.
-     * @default false
-     * @example true // retain the structure of the object, but redact the values. { a: '1' } => becomes { a: '[REDACTED]' }
-     * @example false // redact the entire object. { a: '1' } => becomes '[REDACTED]'
-     */
-    retainStructure?: boolean;
-    /**
-     * Remove the redacted data instead of replacing it with the `replacement` value.
-     * @default false // replace the redacted data with the `replacement` value.
-     * @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 `*`
-     */
-    replaceStringByLength?: boolean;
-    /**
-     * The key to redact. Can be a string or a RegExp.
-     * @example 'address' // redact any key that is 'address'.
-     * @example /^address$/ // redact any key that is exactly 'address'.
-     */
-    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.
-     * @default []
-     * @example ['password', 'ssn'] // redact any key that is 'password' or 'ssn'.
-     * @example [{ key: 'address', fuzzyKeyMatch: true, caseSensitiveKeyMatch: false }] // redact any key that contains 'address' regardless of case.
-     */
-    blacklistedKeys?: Array<string | RegExp | BlacklistKeyConfig>;
-    /**
-     * Redact a string value that matches a test pattern.
-     * @default []
-     * @example [
-     *   /^[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}$/,  // redact any string that looks like an IP address.
-     * ]
-     */
-    stringTests?: Array<RegExp | 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
-     * @example true // match any key that contains the string 'address', such as 'homeAddress', 'workAddress', 'addressLine1', etc.
-     * @example false // match only keys that contain 'address' from start to end.
-     */
-    fuzzyKeyMatch?: boolean;
-    /**
-     * Perform a case-sensitive match on the key
-     * @default true
-     * @example false // match any key that contains the string 'address' regardless of upper, lower, snake, camel or any other case.
-     * @example true // match only keys that are exactly 'address' in the same case.
-     */
-    caseSensitiveKeyMatch?: boolean;
-    /**
-     * Retain the structure of the object, but redact the values.
-     * @default false
-     * @example true // retain the structure of the object, but redact the values. { a: '1' } => becomes { a: '[REDACTED]' }
-     * @example false // redact the entire object. { a: '1' } => becomes '[REDACTED]'
-     */
-    retainStructure?: boolean;
-    /**
-     * 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 `*`
-     */
-    replaceStringByLength?: 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 (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 | Transformer;
-    /**
-     * Remove the redacted data instead of replacing it with the `replacement` value.
-     */
-    remove?: boolean;
-    /**
-     * The types of values that should be redacted. If the value is not one of these types, it will not be redacted.
-     * @default ['string']
-     * @example ['string', 'number'] // redact only strings and numbers, leave other types unchanged.
-     */
-    types?: Types[];
-    /**
-     * Serialise the redacted data. If true, the redacted data will be returned as a JSON string. If false, it will be returned as an object.
-     * @default true
-     * @example true // return the redacted data as a JSON string.
-     * @example false // return the redacted data as the same type as the original data.
-     */
-    serialise?: boolean;
-    /**
-     * Alias of `serialise` for International-English users.
-     */
-    serialize?: boolean;
-    /**
-     * Configuration for transformers to apply when transforming unsupported values.
-     * Supports both legacy array format and new organised format for better performance.
-     *
-     * Legacy format: Array of transformers that run on all values in order
-     * New format: Object with transformers organised by type and constructor
-     *
-     * @default []
-     * @example
-     * // Legacy format (still supported)
-     * [
-     *   (value: unknown) => {
-     *     if (typeof value !== 'bigint') return value
-     *     return value.toString(10)
-     *   },
-     *   (value: unknown) => {
-     *     if (!(value instanceof Date)) return value
-     *     return value.toISOString()
-     *   }
-     * ]
-     *
-     * @example
-     * {
-     *   byType: {
-     *     bigint: [(value: unknown) => (value as bigint).toString(10)]
-     *   },
-     *   byConstructor: {
-     *     Date: [(value: unknown) => (value as Date).toISOString()]
-     *   },
-     *   fallback: [
-     *     // transformers that run on all values
-     *   ]
-     * }
-     */
-    transformers?: TransformerConfig;
-}
-export type DeepRedactConfig = Partial<Omit<BaseDeepRedactConfig, '_blacklistedKeysTransformed' | 'blacklistedKeys' | 'stringTests'>> & ({
-    blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
-    stringTests: BaseDeepRedactConfig['stringTests'];
-} | {
-    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;
-}>;

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

@@ -1,52 +0,0 @@
-import type { Transformer } from '../types';
-/**
- * Registry for organizing transformers by type and constructor for efficient lookup
- */
-export declare class TransformerRegistry {
-    private typeTransformers;
-    private constructorTransformers;
-    private fallbackTransformers;
-    /**
-     * Add a transformer for a specific typeof result
-     * @param type - The typeof result (e.g., 'bigint', 'string', etc.)
-     * @param transformer - The transformer function
-     */
-    addTypeTransformer(type: string, transformer: Transformer): void;
-    /**
-     * Add a transformer for a specific constructor
-     * @param constructor - The constructor function (e.g., Date, Error, etc.)
-     * @param transformer - The transformer function
-     */
-    addConstructorTransformer(constructor: Function, transformer: Transformer): void;
-    /**
-     * Add a fallback transformer that runs on all values
-     * @param transformer - The transformer function
-     */
-    addFallbackTransformer(transformer: Transformer): void;
-    /**
-     * Get relevant transformers for a value
-     * @param value - The value to get transformers for
-     * @returns Array of relevant transformers
-     */
-    getTransformersForValue(value: unknown): Transformer[];
-    /**
-     * Apply transformers to a value
-     * @param value - The value to transform
-     * @param key - The key (optional)
-     * @param referenceMap - Reference map for circular references (optional)
-     * @returns The transformed value
-     */
-    applyTransformers(value: unknown, key?: string, referenceMap?: WeakMap<object, string>): unknown;
-    /**
-     * Clear all transformers
-     */
-    clear(): void;
-    /**
-     * Get all registered transformers for debugging
-     */
-    getRegisteredTransformers(): {
-        types: Map<string, Transformer[]>;
-        constructors: Map<Function, Transformer[]>;
-        fallback: Transformer[];
-    };
-}

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

@@ -1,131 +0,0 @@
-import type { RedactorUtilsConfig } from '../types.js';
-declare class RedactorUtils {
-    /**
-     * The configuration for the redaction.
-     * @private
-     */
-    private readonly config;
-    /**
-     * The transformed blacklist keys of flat regex patterns and complex config objects
-     * @private
-     */
-    private readonly blacklistedKeysTransformed;
-    /**
-     * The transformer registry for efficient transformer lookup
-     * @private
-     */
-    private readonly transformerRegistry;
-    constructor(customConfig: RedactorUtilsConfig);
-    /**
-     * Sets up the transformer registry based on the configuration
-     * @param transformers - The transformer configuration
-     * @private
-     */
-    private setupTransformerRegistry;
-    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;
-    /**
-     * 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;
-    /**
-     * Checks if a non-traversable value requires transformers
-     * @param value - The value to check
-     * @returns Whether the value requires transformers
-     * @private
-     */
-    private requiresTransformers;
-    /**
-     * 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

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

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

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

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

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

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

@@ -1,9 +0,0 @@
-import type { Transformer, OrganisedTransformers } from "../../types.js";
-/**
- * Standard transformers in array for legacy support
- */
-export declare const standardTransformers: Transformer[];
-/**
- * Standard transformers organised by type and constructor for performance reasons
- */
-export declare const organisedStandardTransformers: OrganisedTransformers;

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

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

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

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

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

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

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

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

package/dist/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.mjs

@@ -1 +0,0 @@
-export {};

package/dist/utils/TransformerRegistry.js

@@ -1,100 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransformerRegistry = void 0;
-/**
- * Registry for organizing transformers by type and constructor for efficient lookup
- */
-class TransformerRegistry {
-    constructor() {
-        this.typeTransformers = new Map();
-        this.constructorTransformers = new Map();
-        this.fallbackTransformers = [];
-    }
-    /**
-     * Add a transformer for a specific typeof result
-     * @param type - The typeof result (e.g., 'bigint', 'string', etc.)
-     * @param transformer - The transformer function
-     */
-    addTypeTransformer(type, transformer) {
-        if (!this.typeTransformers.has(type)) {
-            this.typeTransformers.set(type, []);
-        }
-        this.typeTransformers.get(type).push(transformer);
-    }
-    /**
-     * Add a transformer for a specific constructor
-     * @param constructor - The constructor function (e.g., Date, Error, etc.)
-     * @param transformer - The transformer function
-     */
-    addConstructorTransformer(constructor, transformer) {
-        if (!this.constructorTransformers.has(constructor)) {
-            this.constructorTransformers.set(constructor, []);
-        }
-        this.constructorTransformers.get(constructor).push(transformer);
-    }
-    /**
-     * Add a fallback transformer that runs on all values
-     * @param transformer - The transformer function
-     */
-    addFallbackTransformer(transformer) {
-        this.fallbackTransformers.push(transformer);
-    }
-    /**
-     * Get relevant transformers for a value
-     * @param value - The value to get transformers for
-     * @returns Array of relevant transformers
-     */
-    getTransformersForValue(value) {
-        const transformers = [];
-        const type = typeof value;
-        if (this.typeTransformers.has(type)) {
-            transformers.push(...this.typeTransformers.get(type));
-        }
-        if (typeof value === 'object' && value !== null) {
-            const constructor = value.constructor;
-            if (this.constructorTransformers.has(constructor)) {
-                transformers.push(...this.constructorTransformers.get(constructor));
-            }
-        }
-        transformers.push(...this.fallbackTransformers);
-        return transformers;
-    }
-    /**
-     * Apply transformers to a value
-     * @param value - The value to transform
-     * @param key - The key (optional)
-     * @param referenceMap - Reference map for circular references (optional)
-     * @returns The transformed value
-     */
-    applyTransformers(value, key, referenceMap) {
-        if (typeof value === 'string')
-            return value;
-        const transformers = this.getTransformersForValue(value);
-        for (const transformer of transformers) {
-            const transformed = transformer(value, key, referenceMap);
-            if (transformed !== value) {
-                return transformed;
-            }
-        }
-        return value;
-    }
-    /**
-     * Clear all transformers
-     */
-    clear() {
-        this.typeTransformers.clear();
-        this.constructorTransformers.clear();
-        this.fallbackTransformers = [];
-    }
-    /**
-     * Get all registered transformers for debugging
-     */
-    getRegisteredTransformers() {
-        return {
-            types: new Map(this.typeTransformers),
-            constructors: new Map(this.constructorTransformers),
-            fallback: [...this.fallbackTransformers]
-        };
-    }
-}
-exports.TransformerRegistry = TransformerRegistry;

package/dist/utils/TransformerRegistry.mjs

@@ -1,94 +0,0 @@
-/**
- * Registry for organizing transformers by type and constructor for efficient lookup
- */
-export class TransformerRegistry {
-    typeTransformers = new Map();
-    constructorTransformers = new Map();
-    fallbackTransformers = [];
-    /**
-     * Add a transformer for a specific typeof result
-     * @param type - The typeof result (e.g., 'bigint', 'string', etc.)
-     * @param transformer - The transformer function
-     */
-    addTypeTransformer(type, transformer) {
-        if (!this.typeTransformers.has(type)) {
-            this.typeTransformers.set(type, []);
-        }
-        this.typeTransformers.get(type).push(transformer);
-    }
-    /**
-     * Add a transformer for a specific constructor
-     * @param constructor - The constructor function (e.g., Date, Error, etc.)
-     * @param transformer - The transformer function
-     */
-    addConstructorTransformer(constructor, transformer) {
-        if (!this.constructorTransformers.has(constructor)) {
-            this.constructorTransformers.set(constructor, []);
-        }
-        this.constructorTransformers.get(constructor).push(transformer);
-    }
-    /**
-     * Add a fallback transformer that runs on all values
-     * @param transformer - The transformer function
-     */
-    addFallbackTransformer(transformer) {
-        this.fallbackTransformers.push(transformer);
-    }
-    /**
-     * Get relevant transformers for a value
-     * @param value - The value to get transformers for
-     * @returns Array of relevant transformers
-     */
-    getTransformersForValue(value) {
-        const transformers = [];
-        const type = typeof value;
-        if (this.typeTransformers.has(type)) {
-            transformers.push(...this.typeTransformers.get(type));
-        }
-        if (typeof value === 'object' && value !== null) {
-            const constructor = value.constructor;
-            if (this.constructorTransformers.has(constructor)) {
-                transformers.push(...this.constructorTransformers.get(constructor));
-            }
-        }
-        transformers.push(...this.fallbackTransformers);
-        return transformers;
-    }
-    /**
-     * Apply transformers to a value
-     * @param value - The value to transform
-     * @param key - The key (optional)
-     * @param referenceMap - Reference map for circular references (optional)
-     * @returns The transformed value
-     */
-    applyTransformers(value, key, referenceMap) {
-        if (typeof value === 'string')
-            return value;
-        const transformers = this.getTransformersForValue(value);
-        for (const transformer of transformers) {
-            const transformed = transformer(value, key, referenceMap);
-            if (transformed !== value) {
-                return transformed;
-            }
-        }
-        return value;
-    }
-    /**
-     * Clear all transformers
-     */
-    clear() {
-        this.typeTransformers.clear();
-        this.constructorTransformers.clear();
-        this.fallbackTransformers = [];
-    }
-    /**
-     * Get all registered transformers for debugging
-     */
-    getRegisteredTransformers() {
-        return {
-            types: new Map(this.typeTransformers),
-            constructors: new Map(this.constructorTransformers),
-            fallback: [...this.fallbackTransformers]
-        };
-    }
-}