API Reference

API Reference

This page provides detailed information about Purgo's API.

Main Module

purgo(options?)

Initializes Purgo with custom options.

interface PurgoOptions {
  targets?: Array<'console' | 'fetch' | 'xhr'>;
  patterns?: Array<RegExp | string>;
  censor?: (match: string) => string;
  hashMode?: boolean;
}

Parameters

• targets: Array of targets to patch (default: ['console', 'fetch', 'xhr'])
• patterns: Array of built-in pattern names or custom RegExp objects (default: ['email', 'phone', 'ssn', 'mrn', 'icd10'])
• censor: Function to transform matched content (default: () => '***')
• hashMode: Enable SHA-256 hashing of censored tokens for correlation (default: false)

Example

import { purgo } from 'purgo';

purgo({
  targets: ['console', 'fetch'],
  patterns: ['email', 'ssn', /\bMRN-\d{8}\b/g],
  censor: (match) => '[REDACTED]' + match.slice(-2)
});

Note: When using ES modules, we recommend using the auto-patching import (import 'purgo') or the combined approach with import 'purgo/node' and import { initRedactionEngine } from 'purgo/core' rather than the named import (import { purgo } from 'purgo'), which may cause issues in some environments.

redact(value)

Redacts PHI from any value while preserving structure.

function redact<T>(value: T): T;

Parameters

• value: Any value to redact (string, object, array, etc.)

Returns

A copy of the input value with sensitive information redacted.

Example

import { redact } from 'purgo';

const patientData = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  ssn: '123-45-6789',
  records: [
    { id: 1, diagnosis: 'E11.9' }
  ]
};

const safeData = redact(patientData);
// Result: 
// { 
//   name: 'John Doe', 
//   email: '***', 
//   ssn: '***',
//   records: [
//     { id: 1, diagnosis: '***' }
//   ]
// }

Core Module

The core module provides just the redaction functionality without any automatic patching of global objects.

initRedactionEngine(options?)

Initializes the redaction engine with custom options.

interface RedactionEngineOptions {
  patterns?: Array<RegExp | string>;
  censor?: (match: string) => string;
  hashMode?: boolean;
}

Parameters

• patterns: Array of built-in pattern names or custom RegExp objects (default: ['email', 'phone', 'ssn', 'mrn', 'icd10'])
• censor: Function to transform matched content (default: () => '***')
• hashMode: Enable SHA-256 hashing of censored tokens for correlation (default: false)

Example

import { initRedactionEngine } from 'purgo/core';

initRedactionEngine({
  patterns: ['email', 'ssn', /\bMRN-\d{8}\b/g],
  censor: (match) => '[REDACTED]' + match.slice(-2)
});

redact(value) (Core Module)

Same as the main module's redact function, but without automatic patching of global objects.

Node.js Module

pinoRedactor(options)

Creates a redactor for use with Pino logger.

interface PinoRedactorOptions {
  paths: string[];
  additionalPatterns?: Array<RegExp | string>;
  censor?: (match: string) => string;
}

Parameters

• paths: Array of paths to redact in the log object (e.g., ['req.body.ssn', 'patient.email'])
• additionalPatterns: Additional patterns to use for redaction (default: [])
• censor: Function to transform matched content (default: () => '***')

Example

import { pinoRedactor } from 'purgo/node';
import pino from 'pino';

const logger = pino({
  redact: pinoRedactor({
    paths: ['req.body.ssn', 'req.body.email', 'patient.mrn'],
    additionalPatterns: [/\bMRN-\d{8}\b/g],
    censor: (match) => '[REDACTED]' + match.slice(-2)
  })
});

Built-in Patterns

Purgo includes several built-in patterns for common types of PHI:

• email: Email addresses
• phone: Phone numbers in various formats
• ssn: Social Security Numbers
• mrn: Medical Record Numbers
• icd10: ICD-10 diagnosis codes

You can reference these by name in the patterns array:

purgo({
  patterns: ['email', 'phone', 'ssn', 'mrn', 'icd10']
});

Custom Patterns

You can define custom patterns using regular expressions:

purgo({
  patterns: [
    'email',                        // Built-in pattern
    /\bMRN-\d{8}\b/g,               // Custom pattern for Medical Record Numbers
    /\b[A-Z]{2}-\d{6}-[A-Z]\b/g,    // Custom pattern for patient IDs
  ]
});

TypeScript Support

As of v0.1.2, all modules include full TypeScript declarations for improved developer experience.