piiranha

Remove personally identifiable information from text.

This package is published on npm as @doist/piiranha and is maintained as a fork of the original solvvy/redact-pii package.

Prerequisites

This library is primarily written for Node.js, but also works in the browser with compatible tooling/runtime (such as Vite, Webpack, Rollup, Parcel, esbuild). A transpiler/build setup such as TypeScript compiler, Babel, or both, can be used to target older browser support. It is written in TypeScript and currently compiles to ES2016. The project is tested in CI on Node.js 18.x and 20.x.

Simple example (synchronous API)

npm install @doist/piiranha

import { SyncRedactor } from 'piiranha';
const redactor = new SyncRedactor();
const redactedText = redactor.redact('Hi David Johnson, Please give me a call at 555-555-5555');
// Hi NAME, Please give me a call at PHONE_NUMBER
console.log(redactedText);

CommonJS equivalent:

const { SyncRedactor } = require('piiranha');
const redactor = new SyncRedactor();
const redactedText = redactor.redact('Hi David Johnson, Please give me a call at 555-555-5555');
// Hi NAME, Please give me a call at PHONE_NUMBER
console.log(redactedText);

Simple example (asynchronous / promise-based API)

import { AsyncRedactor } from 'piiranha';
const redactor = new AsyncRedactor();
redactor.redactAsync('Hi David Johnson, Please give me a call at 555-555-5555').then((redactedText) => {
  // Hi NAME, Please give me a call at PHONE_NUMBER
  console.log(redactedText);
});

Supported Features

• sync and async API variants
• ability to customize what to use as replacement value for detected patterns
• built in regex based redaction rules for:
  • credentials
  • creditCardNumber
  • emailAddress
  • ipAddress
  • names
  • password
  • phoneNumber
  • streetAddress
  • username
  • usSocialSecurityNumber
  • zipcode
  • url
  • digits
• ability to add custom redaction regex patterns and complete custom redaction functions (both sync and async)

Advanced usage and features

Customize replacement values

import { SyncRedactor } from 'piiranha';

// use a single replacement value for all built-in patterns found.
const redactor = new SyncRedactor({ globalReplaceWith: 'TOP_SECRET' });
redactor.redact('Dear David Johnson, I live at 42 Wallaby Way');
// Dear TOP_SECRET, I live at TOP_SECRET

// use a custom replacement value for a specific built-in pattern
const redactor = new SyncRedactor({
  builtInRedactors: {
    names: {
      replaceWith: 'ANONYMOUS_PERSON',
    },
  },
});

redactor.redact('Dear David Johnson');
// Dear ANONYMOUS_PERSON

Add custom patterns or redaction functions

Note that the order of redaction rules matters, therefore you have to decide whether you want your custom redaction rules to run before or after the built-in ones. Generally it's better to put very specialized patterns or functions before the built-in ones and more broad / general ones after.

import { SyncRedactor } from 'piiranha';

// add a custom regexp pattern
const redactor = new SyncRedactor({
  customRedactors: {
    before: [
      {
        regexpPattern: /\b(cat|dog|cow)s?\b/gi,
        replaceWith: 'ANIMAL',
      },
    ],
  },
});

redactor.redact('I love cats, dogs, and cows');
// I love ANIMAL, ANIMAL, and ANIMAL

// add a synchronous custom redaction function
const redactor = new SyncRedactor({
  customRedactors: {
    before: [
      {
        redact(textToRedact) {
          return textToRedact.includes('TopSecret')
            ? 'THIS_FILE_IS_SO_TOP_SECRET_WE_HAD_TO_REDACT_EVERYTHING'
            : textToRedact;
        },
      },
    ],
  },
});

redactor.redact('This document is classified as TopSecret.');
// THIS_FILE_IS_SO_TOP_SECRET_WE_HAD_TO_REDACT_EVERYTHING

import { AsyncRedactor } from './src/index';

// add an asynchronous custom redaction function
const redactor = new AsyncRedactor({
  customRedactors: {
    before: [
      {
        redactAsync(textToRedact) {
          return myCustomRESTApiServer.redactCustomWords(textToRedact);
        },
      },
    ],
  },
});

Disable specific built-in redaction rules

const redactor = new SyncRedactor({
  builtInRedactors: {
    names: {
      enabled: false,
    },
    emailAddress: {
      enabled: false,
    },
  },
});

Contributing

Enable local git hooks

To block direct local commits to the main branch, run:

npm run setup-hooks

This configures core.hooksPath to use the committed hooks in .githooks/.

Pull Request requirements

Before a PR can be merged to main:

• Code owner review — A maintainer must approve the PR
• Passing tests — All automated checks must pass:
  • TypeScript type checking
  • Jest unit tests (Node.js 18.x and 20.x)
  • Prettier code formatting
• Stale reviews dismissed — If you push new commits after approval, the review is dismissed and must be re-approved

These checks ensure code quality and prevent regressions.

Branch naming convention

For non-main branches, commits are allowed only when branch names match:

<owner>/<type>/<description>

Allowed type values:

• feat
• fix
• chore
• docs
• refactor
• test
• ci
• build
• perf
• style

Examples:

• odsamuels/chore/setup-hooks
• alice/feat/redaction-pipeline

Automation branches are also allowed:

• dependabot/*
• renovate/*

Run tests

You can run the tests via npm run test.