pii-redact 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neenakrishnan1501-bit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# PII Redact
+
+A lightweight and extensible TypeScript library for identifying and redacting Personally Identifiable Information (PII) from both unstructured text and structured objects.
+
+## Installation
+
+```bash
+npm install pii-redact
+```
+
+## Features
+
+- **Built-in Matchers**: Email, Phone Number, Credit Card, SSN, IP Address, Physical Address, Zipcode, Location Coordinates, Passport, and Driver's License.
+- **Built-in Strategies**: Replace, Mask, and Hash.
+- **Structured Object Redaction**: Recursively redacts PII throughout deeply nested objects and arrays.
+- **Extensible**: Easily provide your own custom regex matchers or complex redaction strategies.
+- **TypeScript First**: Strict typings for a robust developer experience.
+
+## Basic Usage
+
+### Understanding DefaultMatchers
+
+`DefaultMatchers` is a convenience array exported by the library that contains all the standard, built-in matchers. If you only want to redact specific types of PII (e.g., only emails and phone numbers), you can pass an array of just the matchers you want:
+
+```typescript
+import { Redactor, EmailMatcher, PhoneMatcher } from 'pii-redact';
+
+// This redactor will ONLY look for emails and phone numbers
+const redactor = new Redactor({ matchers: [EmailMatcher, PhoneMatcher] });
+```
+
+### Unstructured Text Redaction
+
+```typescript
+import { Redactor, DefaultMatchers } from 'pii-redact';
+
+// Create a Redactor using the default built-in matchers
+const redactor = new Redactor({ matchers: DefaultMatchers });
+
+const originalText = "Hello, my email is admin@example.com and phone is (555) 123-4567.";
+const safeText = redactor.redact(originalText);
+
+console.log(safeText);
+// Output: "Hello, my email is [EMAIL] and phone is [PHONE]."
+```
+
+### Structured Object Redaction
+
+```typescript
+import { Redactor, DefaultMatchers } from 'pii-redact';
+
+const redactor = new Redactor({ matchers: DefaultMatchers });
+
+const payload = {
+  user: {
+    id: 12345,
+    name: "John Doe",
+    contactDetails: "Contact me at (555) 123-4567",
+    emails: ["primary@domain.com", "secondary@domain.com"]
+  }
+};
+
+const safePayload = redactor.redactObject(payload);
+
+console.log(safePayload.user.contactDetails); // "Contact me at [PHONE]"
+console.log(safePayload.user.emails[0]);      // "[EMAIL]"
+```
+
+### HTML Redaction
+
+If you have raw HTML and want to redact the visible text *without* breaking tags or attributes, use `.redactHtml()`:
+
+```typescript
+import { Redactor, DefaultMatchers } from 'pii-redact';
+
+const redactor = new Redactor({ matchers: DefaultMatchers });
+
+const html = `
+  <div id="contact-info" data-email="admin@example.com">
+    <p>Please contact me at admin@example.com or call (555) 123-4567.</p>
+    <a href="mailto:admin@example.com">Email Admin</a>
+  </div>
+`;
+
+const safeHtml = redactor.redactHtml(html);
+
+console.log(safeHtml);
+/* Output:
+  <div id="contact-info" data-email="admin@example.com">
+    <p>Please contact me at [EMAIL] or call [PHONE].</p>
+    <a href="mailto:admin@example.com">Email Admin</a>
+  </div>
+*/
+```
+
+## Changing the Redaction Strategy
+
+By default, the `Redactor` uses the `ReplaceStrategy` (which replaces matches with e.g. `[EMAIL]`). You can configure this globally:
+
+### Masking
+
+Replaces the characters with asterisks, optionally leaving parts of the string visible for context.
+
+```typescript
+import { Redactor, EmailMatcher, MaskStrategy } from 'pii-redact';
+
+const redactor = new Redactor({
+  matchers: [EmailMatcher],
+  // Leaves 2 chars at the start, and 4 at the end visible:
+  defaultStrategy: new MaskStrategy({ maskChar: '*', unmaskedStart: 2, unmaskedEnd: 4 })
+});
+
+console.log(redactor.redact('john.doe@example.com'));
+// Output: "jo**************.com"
+```
+
+### Hashing
+
+Replaces the characters with a cryptographic hash (useful for maintaining uniqueness in analytics databases without retaining the actual PII).
+
+```typescript
+import { Redactor, SSNMatcher, HashStrategy } from 'pii-redact';
+
+const redactor = new Redactor({
+  matchers: [SSNMatcher],
+  defaultStrategy: new HashStrategy('sha256')
+});
+
+console.log(redactor.redact('My SSN is 123-45-6789'));
+// Output: "My SSN is a3b8d... [sha256 hash]"
+```
+
+### Advanced: NLP Named Entity Recognition
+
+By default, the library uses extremely fast RegEx matchers. However, RegEx is purely structural and cannot reliably detect things like People's names or specific Geographic locations without context.
+
+To solve this, `pii-redact` ships with an optional Natural Language Processing (NLP) integration via `compromise`. It intelligently reads the context of a sentence to detect **People, Organizations, and Locations**.
+
+Because NLP adds a slight performance overhead and dependency weight, it is *not* included in `DefaultMatchers`. You must explicitly import it if you want context-aware redaction.
+
+```typescript
+import { Redactor, NlpMatcher, DefaultMatchers } from 'pii-redact';
+
+// Combine the NLP Matcher with standard RegEx Matchers
+const redactor = new Redactor({ 
+  matchers: [
+    new NlpMatcher(), // Detects People, Orgs, Locations
+    ...DefaultMatchers // Detects Phones, Emails, SSNs, etc.
+  ]
+});
+
+const text = "John Smith flew to Chicago to visit Microsoft on his (555) 123-4567 phone.";
+
+console.log(redactor.redact(text));
+// Output: "[PERSON] flew to [LOCATION] to visit [ORG] on his [PHONE] phone."
+```
+
+You can optionally configure what the `NlpMatcher` specifically looks for:
+
+```typescript
+new NlpMatcher({
+  detectPeople: true,
+  detectOrganizations: false,
+  detectLocations: false
+})
+```
+
+## Custom Matchers & Strategies
+
+You can easily extend the library by implementing the `Matcher` or `RedactionStrategy` interfaces.
+
+```typescript
+import { Matcher, MatchResult, Redactor } from 'pii-redact';
+
+class CustomSecretMatcher implements Matcher {
+  name = 'secret_code';
+  
+  match(text: string): MatchResult[] {
+    const results: MatchResult[] = [];
+    const regex = /SECRET-[A-Z0-9]{5}/g;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      results.push({ value: match[0], start: match.index, end: match.index + match[0].length });
+    }
+    return results;
+  }
+}
+
+const redactor = new Redactor({ matchers: [new CustomSecretMatcher()] });
+```
+
+## Running the Demo
+
+A simple static HTML demo is included in the `demo/` folder to test the library purely in your browser.
+
+1. Navigate to the `demo` directory: `cd demo`
+2. Open `index.html` in any web browser (e.g. `open index.html` on Mac).
+3. Type any text and test the different redaction strategies!
+
+## License
+
+MIT License.

package/dist/index.d.mts

@@ -0,0 +1,139 @@
+interface Matcher {
+    /** Uniquely identifies the type of PII (e.g., 'email', 'phone') */
+    name: string;
+    /**
+     * Finds all instances of the PII in the given text.
+     * Returns an array of objects containing the matched string and its start/end indices.
+     */
+    match(text: string): MatchResult[];
+}
+interface MatchResult {
+    value: string;
+    start: number;
+    end: number;
+    /** Optional override for the strategy replacement name */
+    name?: string;
+}
+interface RedactionStrategy {
+    /** Uniquely identifies the strategy (e.g., 'replace', 'mask', 'hash') */
+    name: string;
+    /**
+     * Applies the strategy to a matched PII string.
+     * @param matchedValue The actual PII string found
+     * @param matcherName The type of PII (e.g., 'email')
+     */
+    apply(matchedValue: string, matcherName?: string): string;
+}
+interface RedactorConfig {
+    /** The built-in or custom matchers to enable */
+    matchers?: Matcher[];
+    /** The default fallback strategy if a specific matcher doesn't override it */
+    defaultStrategy?: RedactionStrategy;
+}
+
+interface NlpMatcherConfig {
+    detectPeople?: boolean;
+    detectOrganizations?: boolean;
+    detectLocations?: boolean;
+}
+/**
+ * A matcher that uses Natural Language Processing (via compromise)
+ * to detect named entities through sentence context rather than regex.
+ */
+declare class NlpMatcher implements Matcher {
+    name: string;
+    private config;
+    constructor(config?: NlpMatcherConfig);
+    match(text: string): MatchResult[];
+}
+
+/**
+ * A base class for Regex-based matchers to avoid boilerplate.
+ */
+declare class RegexMatcher implements Matcher {
+    name: string;
+    private regex;
+    constructor(name: string, regex: RegExp);
+    match(text: string): MatchResult[];
+}
+declare const EmailMatcher: RegexMatcher;
+declare const PhoneMatcher: RegexMatcher;
+declare const CreditCardMatcher: RegexMatcher;
+declare const SSNMatcher: RegexMatcher;
+declare const IPv4Matcher: RegexMatcher;
+declare const ZipcodeMatcher: RegexMatcher;
+declare const AddressMatcher: RegexMatcher;
+declare const LocationCoordinatesMatcher: RegexMatcher;
+declare const PassportMatcher: RegexMatcher;
+declare const MentionMatcher: RegexMatcher;
+declare const DriverLicenseMatcher: RegexMatcher;
+declare const DateOfBirthMatcher: RegexMatcher;
+
+declare class Redactor {
+    private matchers;
+    private defaultStrategy;
+    constructor(config?: RedactorConfig);
+    /**
+     * Redacts PII from an unstructured text string.
+     */
+    redact(text: string): string;
+    /**
+     * Recursively traverses an object or array and redacts any string values found.
+     */
+    redactObject<T>(obj: T): T;
+    /**
+     * Safely redacts PII from an HTML string without corrupting tags or attributes.
+     */
+    redactHtml(htmlString: string): string;
+}
+
+/**
+ * Replaces the matched PII with a static string.
+ */
+declare class ReplaceStrategy implements RedactionStrategy {
+    name: string;
+    private replacement;
+    /**
+     * @param replacement The string to replace the PII with. If not provided, it defaults to using the matcher name (e.g., [EMAIL]).
+     */
+    constructor(replacement?: string);
+    apply(_matchedValue: string, matcherName?: string): string;
+}
+/**
+ * Masks the matched PII by replacing most characters with a masking character,
+ * while leaving a few visible to provide context.
+ */
+declare class MaskStrategy implements RedactionStrategy {
+    name: string;
+    private maskChar;
+    private unmaskedStart;
+    private unmaskedEnd;
+    /**
+     * @param options.maskChar The character to use for masking (default: '*')
+     * @param options.unmaskedStart Number of characters to leave unmasked at the start (default: 1)
+     * @param options.unmaskedEnd Number of characters to leave unmasked at the end (default: 1)
+     */
+    constructor(options?: {
+        maskChar?: string;
+        unmaskedStart?: number;
+        unmaskedEnd?: number;
+    });
+    apply(matchedValue: string): string;
+}
+/**
+ * Replaces the matched PII with a cryptographic hash.
+ * Useful for preserving uniqueness without revealing the actual value.
+ */
+declare class HashStrategy implements RedactionStrategy {
+    name: string;
+    private algorithm;
+    /**
+     * @param algorithm The cryptographic hash algorithm to use (default: 'sha256')
+     */
+    constructor(algorithm?: string);
+    apply(matchedValue: string): string;
+}
+
+declare const DefaultMatchers: RegexMatcher[];
+
+export { AddressMatcher, CreditCardMatcher, DateOfBirthMatcher, DefaultMatchers, DriverLicenseMatcher, EmailMatcher, HashStrategy, IPv4Matcher, LocationCoordinatesMatcher, MaskStrategy, type MatchResult, type Matcher, MentionMatcher, NlpMatcher, type NlpMatcherConfig, PassportMatcher, PhoneMatcher, type RedactionStrategy, Redactor, type RedactorConfig, RegexMatcher, ReplaceStrategy, SSNMatcher, ZipcodeMatcher };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+interface Matcher {
+    /** Uniquely identifies the type of PII (e.g., 'email', 'phone') */
+    name: string;
+    /**
+     * Finds all instances of the PII in the given text.
+     * Returns an array of objects containing the matched string and its start/end indices.
+     */
+    match(text: string): MatchResult[];
+}
+interface MatchResult {
+    value: string;
+    start: number;
+    end: number;
+    /** Optional override for the strategy replacement name */
+    name?: string;
+}
+interface RedactionStrategy {
+    /** Uniquely identifies the strategy (e.g., 'replace', 'mask', 'hash') */
+    name: string;
+    /**
+     * Applies the strategy to a matched PII string.
+     * @param matchedValue The actual PII string found
+     * @param matcherName The type of PII (e.g., 'email')
+     */
+    apply(matchedValue: string, matcherName?: string): string;
+}
+interface RedactorConfig {
+    /** The built-in or custom matchers to enable */
+    matchers?: Matcher[];
+    /** The default fallback strategy if a specific matcher doesn't override it */
+    defaultStrategy?: RedactionStrategy;
+}
+
+interface NlpMatcherConfig {
+    detectPeople?: boolean;
+    detectOrganizations?: boolean;
+    detectLocations?: boolean;
+}
+/**
+ * A matcher that uses Natural Language Processing (via compromise)
+ * to detect named entities through sentence context rather than regex.
+ */
+declare class NlpMatcher implements Matcher {
+    name: string;
+    private config;
+    constructor(config?: NlpMatcherConfig);
+    match(text: string): MatchResult[];
+}
+
+/**
+ * A base class for Regex-based matchers to avoid boilerplate.
+ */
+declare class RegexMatcher implements Matcher {
+    name: string;
+    private regex;
+    constructor(name: string, regex: RegExp);
+    match(text: string): MatchResult[];
+}
+declare const EmailMatcher: RegexMatcher;
+declare const PhoneMatcher: RegexMatcher;
+declare const CreditCardMatcher: RegexMatcher;
+declare const SSNMatcher: RegexMatcher;
+declare const IPv4Matcher: RegexMatcher;
+declare const ZipcodeMatcher: RegexMatcher;
+declare const AddressMatcher: RegexMatcher;
+declare const LocationCoordinatesMatcher: RegexMatcher;
+declare const PassportMatcher: RegexMatcher;
+declare const MentionMatcher: RegexMatcher;
+declare const DriverLicenseMatcher: RegexMatcher;
+declare const DateOfBirthMatcher: RegexMatcher;
+
+declare class Redactor {
+    private matchers;
+    private defaultStrategy;
+    constructor(config?: RedactorConfig);
+    /**
+     * Redacts PII from an unstructured text string.
+     */
+    redact(text: string): string;
+    /**
+     * Recursively traverses an object or array and redacts any string values found.
+     */
+    redactObject<T>(obj: T): T;
+    /**
+     * Safely redacts PII from an HTML string without corrupting tags or attributes.
+     */
+    redactHtml(htmlString: string): string;
+}
+
+/**
+ * Replaces the matched PII with a static string.
+ */
+declare class ReplaceStrategy implements RedactionStrategy {
+    name: string;
+    private replacement;
+    /**
+     * @param replacement The string to replace the PII with. If not provided, it defaults to using the matcher name (e.g., [EMAIL]).
+     */
+    constructor(replacement?: string);
+    apply(_matchedValue: string, matcherName?: string): string;
+}
+/**
+ * Masks the matched PII by replacing most characters with a masking character,
+ * while leaving a few visible to provide context.
+ */
+declare class MaskStrategy implements RedactionStrategy {
+    name: string;
+    private maskChar;
+    private unmaskedStart;
+    private unmaskedEnd;
+    /**
+     * @param options.maskChar The character to use for masking (default: '*')
+     * @param options.unmaskedStart Number of characters to leave unmasked at the start (default: 1)
+     * @param options.unmaskedEnd Number of characters to leave unmasked at the end (default: 1)
+     */
+    constructor(options?: {
+        maskChar?: string;
+        unmaskedStart?: number;
+        unmaskedEnd?: number;
+    });
+    apply(matchedValue: string): string;
+}
+/**
+ * Replaces the matched PII with a cryptographic hash.
+ * Useful for preserving uniqueness without revealing the actual value.
+ */
+declare class HashStrategy implements RedactionStrategy {
+    name: string;
+    private algorithm;
+    /**
+     * @param algorithm The cryptographic hash algorithm to use (default: 'sha256')
+     */
+    constructor(algorithm?: string);
+    apply(matchedValue: string): string;
+}
+
+declare const DefaultMatchers: RegexMatcher[];
+
+export { AddressMatcher, CreditCardMatcher, DateOfBirthMatcher, DefaultMatchers, DriverLicenseMatcher, EmailMatcher, HashStrategy, IPv4Matcher, LocationCoordinatesMatcher, MaskStrategy, type MatchResult, type Matcher, MentionMatcher, NlpMatcher, type NlpMatcherConfig, PassportMatcher, PhoneMatcher, type RedactionStrategy, Redactor, type RedactorConfig, RegexMatcher, ReplaceStrategy, SSNMatcher, ZipcodeMatcher };

package/dist/index.js

@@ -0,0 +1,374 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AddressMatcher: () => AddressMatcher,
+  CreditCardMatcher: () => CreditCardMatcher,
+  DateOfBirthMatcher: () => DateOfBirthMatcher,
+  DefaultMatchers: () => DefaultMatchers,
+  DriverLicenseMatcher: () => DriverLicenseMatcher,
+  EmailMatcher: () => EmailMatcher,
+  HashStrategy: () => HashStrategy,
+  IPv4Matcher: () => IPv4Matcher,
+  LocationCoordinatesMatcher: () => LocationCoordinatesMatcher,
+  MaskStrategy: () => MaskStrategy,
+  MentionMatcher: () => MentionMatcher,
+  NlpMatcher: () => NlpMatcher,
+  PassportMatcher: () => PassportMatcher,
+  PhoneMatcher: () => PhoneMatcher,
+  Redactor: () => Redactor,
+  RegexMatcher: () => RegexMatcher,
+  ReplaceStrategy: () => ReplaceStrategy,
+  SSNMatcher: () => SSNMatcher,
+  ZipcodeMatcher: () => ZipcodeMatcher
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/strategies/index.ts
+var import_crypto = __toESM(require("crypto"));
+var ReplaceStrategy = class {
+  name = "replace";
+  replacement;
+  /**
+   * @param replacement The string to replace the PII with. If not provided, it defaults to using the matcher name (e.g., [EMAIL]).
+   */
+  constructor(replacement) {
+    this.replacement = replacement || "";
+  }
+  apply(_matchedValue, matcherName) {
+    if (this.replacement) {
+      return this.replacement;
+    }
+    return `[${(matcherName || "REDACTED").toUpperCase()}]`;
+  }
+};
+var MaskStrategy = class {
+  name = "mask";
+  maskChar;
+  unmaskedStart;
+  unmaskedEnd;
+  /**
+   * @param options.maskChar The character to use for masking (default: '*')
+   * @param options.unmaskedStart Number of characters to leave unmasked at the start (default: 1)
+   * @param options.unmaskedEnd Number of characters to leave unmasked at the end (default: 1)
+   */
+  constructor(options) {
+    this.maskChar = options?.maskChar || "*";
+    this.unmaskedStart = options?.unmaskedStart ?? 1;
+    this.unmaskedEnd = options?.unmaskedEnd ?? 1;
+  }
+  apply(matchedValue) {
+    const length = matchedValue.length;
+    if (length <= this.unmaskedStart + this.unmaskedEnd) {
+      return this.maskChar.repeat(length);
+    }
+    const start = matchedValue.slice(0, this.unmaskedStart);
+    const end = matchedValue.slice(length - this.unmaskedEnd);
+    const middle = this.maskChar.repeat(length - this.unmaskedStart - this.unmaskedEnd);
+    return `${start}${middle}${end}`;
+  }
+};
+var HashStrategy = class {
+  name = "hash";
+  algorithm;
+  /**
+   * @param algorithm The cryptographic hash algorithm to use (default: 'sha256')
+   */
+  constructor(algorithm = "sha256") {
+    this.algorithm = algorithm;
+  }
+  apply(matchedValue) {
+    return import_crypto.default.createHash(this.algorithm).update(matchedValue).digest("hex");
+  }
+};
+
+// src/redactor.ts
+var import_node_html_parser = require("node-html-parser");
+var Redactor = class {
+  matchers;
+  defaultStrategy;
+  constructor(config) {
+    this.matchers = config?.matchers || [];
+    this.defaultStrategy = config?.defaultStrategy || new ReplaceStrategy();
+  }
+  /**
+   * Redacts PII from an unstructured text string.
+   */
+  redact(text) {
+    if (!text || typeof text !== "string") return text;
+    const allMatches = [];
+    for (const matcher of this.matchers) {
+      const results = matcher.match(text);
+      for (const result of results) {
+        const replacement = this.defaultStrategy.apply(result.value, result.name || matcher.name);
+        allMatches.push({ start: result.start, end: result.end, replacement });
+      }
+    }
+    if (allMatches.length === 0) return text;
+    allMatches.sort((a, b) => a.start - b.start);
+    let resultText = text;
+    const validMatches = [];
+    let lastEnd = -1;
+    for (const match of allMatches) {
+      if (match.start >= lastEnd) {
+        validMatches.push(match);
+        lastEnd = match.end;
+      }
+    }
+    for (let i = validMatches.length - 1; i >= 0; i--) {
+      const { start, end, replacement } = validMatches[i];
+      resultText = resultText.substring(0, start) + replacement + resultText.substring(end);
+    }
+    return resultText;
+  }
+  /**
+   * Recursively traverses an object or array and redacts any string values found.
+   */
+  redactObject(obj) {
+    if (obj === null || obj === void 0) return obj;
+    if (typeof obj === "string") {
+      return this.redact(obj);
+    }
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.redactObject(item));
+    }
+    if (typeof obj === "object") {
+      const result = {};
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = this.redactObject(value);
+      }
+      return result;
+    }
+    return obj;
+  }
+  /**
+   * Safely redacts PII from an HTML string without corrupting tags or attributes.
+   */
+  redactHtml(htmlString) {
+    if (!htmlString || typeof htmlString !== "string") return htmlString;
+    const root = (0, import_node_html_parser.parse)(htmlString);
+    const traverse = (node) => {
+      if (node.nodeType === 3) {
+        const textNode = node;
+        if (textNode.rawText && textNode.rawText.trim()) {
+          textNode.rawText = this.redact(textNode.rawText);
+        }
+      } else if (node.nodeType === 1) {
+        const element = node;
+        if (element.tagName && ["SCRIPT", "STYLE"].includes(element.tagName.toUpperCase())) {
+          return;
+        }
+        for (const child of element.childNodes) {
+          traverse(child);
+        }
+      }
+    };
+    traverse(root);
+    return root.toString();
+  }
+};
+
+// src/matchers/nlp.ts
+var import_compromise = __toESM(require("compromise"));
+var NlpMatcher = class {
+  name;
+  config;
+  constructor(config) {
+    this.name = "nlp";
+    this.config = {
+      detectPeople: true,
+      detectOrganizations: true,
+      detectLocations: true,
+      ...config
+    };
+  }
+  match(text) {
+    const results = [];
+    const doc = (0, import_compromise.default)(text);
+    if (this.config.detectPeople) {
+      const people = doc.people().out("offset");
+      people.forEach((p) => {
+        results.push({
+          value: p.text,
+          // e.g. "John Smith"
+          name: "person",
+          // Override name for specific replacement (e.g. [PERSON])
+          start: p.offset.start,
+          end: p.offset.start + p.offset.length
+        });
+      });
+    }
+    if (this.config.detectOrganizations) {
+      const orgs = doc.organizations().out("offset");
+      orgs.forEach((o) => {
+        results.push({
+          value: o.text,
+          // e.g. "Google"
+          name: "org",
+          // Override name for specific replacement (e.g. [ORG])
+          start: o.offset.start,
+          end: o.offset.start + o.offset.length
+        });
+      });
+    }
+    if (this.config.detectLocations) {
+      const places = doc.places().out("offset");
+      places.forEach((p) => {
+        results.push({
+          value: p.text,
+          // e.g. "New York"
+          name: "location",
+          // Override name for specific replacement (e.g. [LOCATION])
+          start: p.offset.start,
+          end: p.offset.start + p.offset.length
+        });
+      });
+    }
+    return results;
+  }
+};
+
+// src/matchers/index.ts
+var RegexMatcher = class {
+  name;
+  regex;
+  constructor(name, regex) {
+    this.name = name;
+    if (!regex.flags.includes("g")) {
+      this.regex = new RegExp(regex.source, regex.flags + "g");
+    } else {
+      this.regex = regex;
+    }
+  }
+  match(text) {
+    const results = [];
+    let match;
+    this.regex.lastIndex = 0;
+    while ((match = this.regex.exec(text)) !== null) {
+      results.push({
+        value: match[0],
+        start: match.index,
+        end: match.index + match[0].length
+      });
+    }
+    return results;
+  }
+};
+var EmailMatcher = new RegexMatcher(
+  "email",
+  /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
+);
+var PhoneMatcher = new RegexMatcher(
+  "phone",
+  /(?<!\d)(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}(?!\d)/g
+);
+var CreditCardMatcher = new RegexMatcher(
+  "credit_card",
+  /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b/g
+);
+var SSNMatcher = new RegexMatcher(
+  "ssn",
+  /\b(?!(000|666|9))\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g
+);
+var IPv4Matcher = new RegexMatcher(
+  "ipv4",
+  /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g
+);
+var ZipcodeMatcher = new RegexMatcher(
+  "zipcode",
+  /\b\d{5}(?:[-\s]\d{4})?\b/g
+);
+var AddressMatcher = new RegexMatcher(
+  "address",
+  /\b\d{1,5}\s(?:[a-zA-Z0-9\s.,-]{1,50})\s(?:St|Street|Rd|Road|Ave|Avenue|Blvd|Boulevard|Ln|Lane|Dr|Drive|Ct|Court)\b/gi
+);
+var LocationCoordinatesMatcher = new RegexMatcher(
+  "location",
+  /[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)/g
+);
+var PassportMatcher = new RegexMatcher(
+  "passport",
+  /\b(?:[A-Z]{1,2}\d{6,8}|\d{9})\b/g
+);
+var MentionMatcher = new RegexMatcher(
+  "mention",
+  /(?<=^|\s)@[a-zA-Z0-9_\-]+/g
+);
+var DriverLicenseMatcher = new RegexMatcher(
+  "driver_license",
+  // Varies heavily by state. Covers alphanumeric formats of 7-14 chars commonly seen in the US.
+  // Using positive lookahead (?=.*[0-9]) to ensure it has at least one number, preventing normal 7-14 letter words from matching.
+  /\b(?=.*[0-9])[A-Za-z0-9]{7,14}\b/g
+);
+var DateOfBirthMatcher = new RegexMatcher(
+  "date_of_birth",
+  // Matches common DOB formats: MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD, MM-DD-YYYY, etc.
+  /\b(?:(?:0?[1-9]|1[0-2])[-/](?:0?[1-9]|[12][0-9]|3[01])[-/](?:19|20)\d{2}|(?:19|20)\d{2}[-/](?:0?[1-9]|1[0-2])[-/](?:0?[1-9]|[12][0-9]|3[01]))\b/g
+);
+
+// src/index.ts
+var DefaultMatchers = [
+  EmailMatcher,
+  PhoneMatcher,
+  CreditCardMatcher,
+  SSNMatcher,
+  IPv4Matcher,
+  ZipcodeMatcher,
+  LocationCoordinatesMatcher,
+  PassportMatcher,
+  DriverLicenseMatcher,
+  MentionMatcher,
+  DateOfBirthMatcher,
+  // Address matcher is typically noisy without NLP, so it's included but should be used with caution
+  AddressMatcher
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AddressMatcher,
+  CreditCardMatcher,
+  DateOfBirthMatcher,
+  DefaultMatchers,
+  DriverLicenseMatcher,
+  EmailMatcher,
+  HashStrategy,
+  IPv4Matcher,
+  LocationCoordinatesMatcher,
+  MaskStrategy,
+  MentionMatcher,
+  NlpMatcher,
+  PassportMatcher,
+  PhoneMatcher,
+  Redactor,
+  RegexMatcher,
+  ReplaceStrategy,
+  SSNMatcher,
+  ZipcodeMatcher
+});

package/dist/index.mjs

@@ -0,0 +1,319 @@
+// src/strategies/index.ts
+import crypto from "crypto";
+var ReplaceStrategy = class {
+  name = "replace";
+  replacement;
+  /**
+   * @param replacement The string to replace the PII with. If not provided, it defaults to using the matcher name (e.g., [EMAIL]).
+   */
+  constructor(replacement) {
+    this.replacement = replacement || "";
+  }
+  apply(_matchedValue, matcherName) {
+    if (this.replacement) {
+      return this.replacement;
+    }
+    return `[${(matcherName || "REDACTED").toUpperCase()}]`;
+  }
+};
+var MaskStrategy = class {
+  name = "mask";
+  maskChar;
+  unmaskedStart;
+  unmaskedEnd;
+  /**
+   * @param options.maskChar The character to use for masking (default: '*')
+   * @param options.unmaskedStart Number of characters to leave unmasked at the start (default: 1)
+   * @param options.unmaskedEnd Number of characters to leave unmasked at the end (default: 1)
+   */
+  constructor(options) {
+    this.maskChar = options?.maskChar || "*";
+    this.unmaskedStart = options?.unmaskedStart ?? 1;
+    this.unmaskedEnd = options?.unmaskedEnd ?? 1;
+  }
+  apply(matchedValue) {
+    const length = matchedValue.length;
+    if (length <= this.unmaskedStart + this.unmaskedEnd) {
+      return this.maskChar.repeat(length);
+    }
+    const start = matchedValue.slice(0, this.unmaskedStart);
+    const end = matchedValue.slice(length - this.unmaskedEnd);
+    const middle = this.maskChar.repeat(length - this.unmaskedStart - this.unmaskedEnd);
+    return `${start}${middle}${end}`;
+  }
+};
+var HashStrategy = class {
+  name = "hash";
+  algorithm;
+  /**
+   * @param algorithm The cryptographic hash algorithm to use (default: 'sha256')
+   */
+  constructor(algorithm = "sha256") {
+    this.algorithm = algorithm;
+  }
+  apply(matchedValue) {
+    return crypto.createHash(this.algorithm).update(matchedValue).digest("hex");
+  }
+};
+
+// src/redactor.ts
+import { parse } from "node-html-parser";
+var Redactor = class {
+  matchers;
+  defaultStrategy;
+  constructor(config) {
+    this.matchers = config?.matchers || [];
+    this.defaultStrategy = config?.defaultStrategy || new ReplaceStrategy();
+  }
+  /**
+   * Redacts PII from an unstructured text string.
+   */
+  redact(text) {
+    if (!text || typeof text !== "string") return text;
+    const allMatches = [];
+    for (const matcher of this.matchers) {
+      const results = matcher.match(text);
+      for (const result of results) {
+        const replacement = this.defaultStrategy.apply(result.value, result.name || matcher.name);
+        allMatches.push({ start: result.start, end: result.end, replacement });
+      }
+    }
+    if (allMatches.length === 0) return text;
+    allMatches.sort((a, b) => a.start - b.start);
+    let resultText = text;
+    const validMatches = [];
+    let lastEnd = -1;
+    for (const match of allMatches) {
+      if (match.start >= lastEnd) {
+        validMatches.push(match);
+        lastEnd = match.end;
+      }
+    }
+    for (let i = validMatches.length - 1; i >= 0; i--) {
+      const { start, end, replacement } = validMatches[i];
+      resultText = resultText.substring(0, start) + replacement + resultText.substring(end);
+    }
+    return resultText;
+  }
+  /**
+   * Recursively traverses an object or array and redacts any string values found.
+   */
+  redactObject(obj) {
+    if (obj === null || obj === void 0) return obj;
+    if (typeof obj === "string") {
+      return this.redact(obj);
+    }
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.redactObject(item));
+    }
+    if (typeof obj === "object") {
+      const result = {};
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = this.redactObject(value);
+      }
+      return result;
+    }
+    return obj;
+  }
+  /**
+   * Safely redacts PII from an HTML string without corrupting tags or attributes.
+   */
+  redactHtml(htmlString) {
+    if (!htmlString || typeof htmlString !== "string") return htmlString;
+    const root = parse(htmlString);
+    const traverse = (node) => {
+      if (node.nodeType === 3) {
+        const textNode = node;
+        if (textNode.rawText && textNode.rawText.trim()) {
+          textNode.rawText = this.redact(textNode.rawText);
+        }
+      } else if (node.nodeType === 1) {
+        const element = node;
+        if (element.tagName && ["SCRIPT", "STYLE"].includes(element.tagName.toUpperCase())) {
+          return;
+        }
+        for (const child of element.childNodes) {
+          traverse(child);
+        }
+      }
+    };
+    traverse(root);
+    return root.toString();
+  }
+};
+
+// src/matchers/nlp.ts
+import nlp from "compromise";
+var NlpMatcher = class {
+  name;
+  config;
+  constructor(config) {
+    this.name = "nlp";
+    this.config = {
+      detectPeople: true,
+      detectOrganizations: true,
+      detectLocations: true,
+      ...config
+    };
+  }
+  match(text) {
+    const results = [];
+    const doc = nlp(text);
+    if (this.config.detectPeople) {
+      const people = doc.people().out("offset");
+      people.forEach((p) => {
+        results.push({
+          value: p.text,
+          // e.g. "John Smith"
+          name: "person",
+          // Override name for specific replacement (e.g. [PERSON])
+          start: p.offset.start,
+          end: p.offset.start + p.offset.length
+        });
+      });
+    }
+    if (this.config.detectOrganizations) {
+      const orgs = doc.organizations().out("offset");
+      orgs.forEach((o) => {
+        results.push({
+          value: o.text,
+          // e.g. "Google"
+          name: "org",
+          // Override name for specific replacement (e.g. [ORG])
+          start: o.offset.start,
+          end: o.offset.start + o.offset.length
+        });
+      });
+    }
+    if (this.config.detectLocations) {
+      const places = doc.places().out("offset");
+      places.forEach((p) => {
+        results.push({
+          value: p.text,
+          // e.g. "New York"
+          name: "location",
+          // Override name for specific replacement (e.g. [LOCATION])
+          start: p.offset.start,
+          end: p.offset.start + p.offset.length
+        });
+      });
+    }
+    return results;
+  }
+};
+
+// src/matchers/index.ts
+var RegexMatcher = class {
+  name;
+  regex;
+  constructor(name, regex) {
+    this.name = name;
+    if (!regex.flags.includes("g")) {
+      this.regex = new RegExp(regex.source, regex.flags + "g");
+    } else {
+      this.regex = regex;
+    }
+  }
+  match(text) {
+    const results = [];
+    let match;
+    this.regex.lastIndex = 0;
+    while ((match = this.regex.exec(text)) !== null) {
+      results.push({
+        value: match[0],
+        start: match.index,
+        end: match.index + match[0].length
+      });
+    }
+    return results;
+  }
+};
+var EmailMatcher = new RegexMatcher(
+  "email",
+  /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
+);
+var PhoneMatcher = new RegexMatcher(
+  "phone",
+  /(?<!\d)(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}(?!\d)/g
+);
+var CreditCardMatcher = new RegexMatcher(
+  "credit_card",
+  /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b/g
+);
+var SSNMatcher = new RegexMatcher(
+  "ssn",
+  /\b(?!(000|666|9))\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g
+);
+var IPv4Matcher = new RegexMatcher(
+  "ipv4",
+  /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g
+);
+var ZipcodeMatcher = new RegexMatcher(
+  "zipcode",
+  /\b\d{5}(?:[-\s]\d{4})?\b/g
+);
+var AddressMatcher = new RegexMatcher(
+  "address",
+  /\b\d{1,5}\s(?:[a-zA-Z0-9\s.,-]{1,50})\s(?:St|Street|Rd|Road|Ave|Avenue|Blvd|Boulevard|Ln|Lane|Dr|Drive|Ct|Court)\b/gi
+);
+var LocationCoordinatesMatcher = new RegexMatcher(
+  "location",
+  /[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)/g
+);
+var PassportMatcher = new RegexMatcher(
+  "passport",
+  /\b(?:[A-Z]{1,2}\d{6,8}|\d{9})\b/g
+);
+var MentionMatcher = new RegexMatcher(
+  "mention",
+  /(?<=^|\s)@[a-zA-Z0-9_\-]+/g
+);
+var DriverLicenseMatcher = new RegexMatcher(
+  "driver_license",
+  // Varies heavily by state. Covers alphanumeric formats of 7-14 chars commonly seen in the US.
+  // Using positive lookahead (?=.*[0-9]) to ensure it has at least one number, preventing normal 7-14 letter words from matching.
+  /\b(?=.*[0-9])[A-Za-z0-9]{7,14}\b/g
+);
+var DateOfBirthMatcher = new RegexMatcher(
+  "date_of_birth",
+  // Matches common DOB formats: MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD, MM-DD-YYYY, etc.
+  /\b(?:(?:0?[1-9]|1[0-2])[-/](?:0?[1-9]|[12][0-9]|3[01])[-/](?:19|20)\d{2}|(?:19|20)\d{2}[-/](?:0?[1-9]|1[0-2])[-/](?:0?[1-9]|[12][0-9]|3[01]))\b/g
+);
+
+// src/index.ts
+var DefaultMatchers = [
+  EmailMatcher,
+  PhoneMatcher,
+  CreditCardMatcher,
+  SSNMatcher,
+  IPv4Matcher,
+  ZipcodeMatcher,
+  LocationCoordinatesMatcher,
+  PassportMatcher,
+  DriverLicenseMatcher,
+  MentionMatcher,
+  DateOfBirthMatcher,
+  // Address matcher is typically noisy without NLP, so it's included but should be used with caution
+  AddressMatcher
+];
+export {
+  AddressMatcher,
+  CreditCardMatcher,
+  DateOfBirthMatcher,
+  DefaultMatchers,
+  DriverLicenseMatcher,
+  EmailMatcher,
+  HashStrategy,
+  IPv4Matcher,
+  LocationCoordinatesMatcher,
+  MaskStrategy,
+  MentionMatcher,
+  NlpMatcher,
+  PassportMatcher,
+  PhoneMatcher,
+  Redactor,
+  RegexMatcher,
+  ReplaceStrategy,
+  SSNMatcher,
+  ZipcodeMatcher
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pii-redact",
+  "version": "1.0.0",
+  "description": "A lightweight and extensible library for identifying and redacting Personally Identifiable Information (PII) from structured and unstructured text.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/ --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neenakrishnan1501-bit/pii-redact.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/neenakrishnan1501-bit/pii-redact/issues"
+  },
+  "homepage": "https://github.com/neenakrishnan1501-bit/pii-redact#readme",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.3.5",
+    "jest": "^30.2.0",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "compromise": "^14.15.0",
+    "node-html-parser": "^7.1.0"
+  }
+}