Library Documentation

Installation

Install OpenRedaction via npm:

npm install openredaction

Basic Usage

Import and use the redact function to detect and redact PII from text.

Example:
import { redact } from 'openredaction';

const text = "My name is John Doe and my email is john@example.com";
const result = await redact(text);

console.log(result.redacted_text);
// "My name is [REDACTED] and my email is [REDACTED]"

console.log(result.detections);
// [
//   {
//     type: "PERSON",
//     text: "John Doe",
//     start: 11,
//     end: 19
//   },
//   {
//     type: "EMAIL",
//     text: "john@example.com",
//     start: 38,
//     end: 55
//   }
// ]

Regex Patterns vs AI Layer

OpenRedaction uses regex patterns by default for fast, deterministic detection. An optional AI/NER layer is available for messy, unstructured text.

When to Use Regex (Default)

  • Structured data (forms, databases, JSON)
  • When you need fast processing (milliseconds)
  • When you need deterministic results
  • When cost and transparency matter

Regex patterns are fast, transparent, and easy to audit. They work great for most use cases.

When to Use AI Layer (Optional)

  • Messy chat logs and transcripts
  • Unstructured text with typos
  • Context-dependent entity detection

⚠ Note: AI layer increases latency (seconds vs milliseconds) and cost. Use only when necessary.

Enable AI Layer:
import { redact } from 'openredaction';

const result = await redact(text, {
  useAI: true  // Optional: enable AI layer for messy text
});

By default, useAI is false. Set it to true to enable the optional AI/NER layer for improved detection on messy text. Note: AI layer increases latency and cost. Use only when necessary.

Self-Hosting

OpenRedaction is designed to be self-hosted. Deploy on your own infrastructure for complete privacy and control.

Deployment Options

  • Node.js Server: Run directly in your Node.js application
  • Docker: Containerize and deploy on any infrastructure
  • On-Premise: Deploy on your own servers for maximum control

When self-hosted, you maintain complete control over your data. No data leaves your environment.

Error Handling

Invalid Input
try {
  const result = await redact(null);
} catch (error) {
  console.error('Error:', error.message);
  // "Invalid input: text must be a non-empty string"
}

Advanced Usage

Custom Options

import { redact } from 'openredaction';

const result = await redact(text, {
  useAI: false,           // Enable optional AI layer
  patterns: ['email', 'phone'],  // Custom pattern selection
  redactionChar: '[REDACTED]'    // Custom redaction string
});

Batch Processing

import { redact } from 'openredaction';

const texts = [
  "Contact John at john@example.com",
  "Call 555-123-4567 for support"
];

const results = await Promise.all(
  texts.map(text => redact(text))
);

results.forEach((result, index) => {
  console.log(`Text ${index + 1}:`, result.redacted_text);
});

Resources