API Reference ​

createRedactor ​

Creates an immutable redactor instance. The redactor is frozen and cannot be modified after creation.

ts
function createRedactor(
  config: RedactorConfig & { restore: true },
): RedactorWithRestore;
function createRedactor(config: RedactorConfig): RedactorWithoutRestore;

TypeScript overloads ensure that when restore: true is set, redact() returns RedactResult ({ text, map }); otherwise it returns a plain string.

Parameters ​

Returns ​

A frozen redactor object with redact(), inspect(), stream(), restore(), and policy properties.

Example ​

ts
import { createRedactor } from "sensored";

const redactor = createRedactor({ presets: ["pii"], rules: {} });

Redactor methods ​

redact ​

Redacts sensitive data from the input text.

ts
// Without restore
redact(text: string): string

// With restore
redact(text: string): RedactResult

Throws INPUT_LIMIT if the text exceeds maxInputLength.

redactAsync ​

Async variant of redact() that runs semantic confirmation on detected PII candidates before redacting. Requires semantic config. See AI Confirmation for details.

ts
redactAsync(text: string): Promise<AsyncRedactResult>

Throws INPUT_LIMIT if the text exceeds maxInputLength.

inspect ​

Inspects the input text and returns detections without transforming it.

ts
inspect(text: string): Inspection

Returns the original text plus an array of InspectionGroup objects with match details including values, offsets, and reasons.

stream ​

Creates an async iterable that redacts a stream of text chunks.

ts
stream(
  chunks: AsyncIterable<string>,
  options?: StreamOptions,
): AsyncIterable<StreamEvent>

Throws STREAM_UNSUPPORTED if any active rule's detector lacks stream metadata.

restore ​

Restores redacted text to its original form using a restoration map.

ts
restore(text: string, map: RestorationMap): string

policy ​

The frozen, resolved policy object mapping rule IDs to their RuleSetting.

ts
readonly policy: Readonly<Record<string, RuleSetting>>

describe ​

Returns descriptions of the detectors active in this redactor's resolved policy. Each description includes an optional contextHint for context-dependent detectors. See LLM Steering.

ts
describe(): readonly DetectorDescription[]

Types ​

RedactorConfig ​

ts
interface RedactorConfig {
  presets?: readonly string[];
  customPresets?: Readonly<
    Record<string, Readonly<Record<string, RuleSetting | "off">>>
  >;
  limits?: { maxInputLength?: number };
  rules: Readonly<Record<string, RuleSetting | "off">>;
  detectors?: readonly DetectorDefinition[];
  restore?: boolean;
  allowlist?: readonly string[];
  readonly semantic?: SemanticConfig;
}

SemanticConfig ​

ts
interface SemanticConfig {
  readonly provider: "jev";
  readonly apiKey: string;
  readonly model?: string;
  readonly thresholds?: Readonly<Record<string, number>>;
  readonly contextWindow?: number;
}

RuleSetting ​

ts
type RuleSetting =
  RedactRule | FormatPreserveRule | TokenReplaceRule | MaskRule | RemoveRule;

RedactRule ​

ts
interface RedactRule {
  readonly action: "redact";
  readonly replacement?: string;
  readonly priority?: number;
}

MaskRule ​

ts
interface MaskRule {
  readonly action: "mask";
  readonly preserve?: { readonly first?: number; readonly last?: number };
}

RemoveRule ​

ts
interface RemoveRule {
  readonly action: "remove";
}

FormatPreserveRule ​

ts
interface FormatPreserveRule {
  readonly action: "format-preserve";
}

TokenReplaceRule ​

ts
interface TokenReplaceRule {
  readonly action: "token-replace";
  readonly tokens?: Readonly<Record<string, string>>;
}

RedactResult ​

ts
interface RedactResult {
  readonly text: string;
  readonly map: RestorationMap;
}

AsyncRedactResult ​

ts
interface AsyncRedactResult {
  readonly text: string;
  readonly map?: RestorationMap;
  readonly detections: readonly SemanticDetection[];
  readonly warnings?: readonly string[];
}

SemanticDetection ​

ts
interface SemanticDetection extends Detection {
  readonly semanticConfirmed: boolean;
  readonly noul?: number;
}

RestorationMap ​

ts
type RestorationMap = Readonly<Record<string, string>>;

DetectorDefinition ​

ts
interface DetectorDefinition {
  readonly id: string;
  readonly entityType: string;
  readonly replacement: string;
  readonly pattern: RegExp;
  readonly context?: { readonly before: number; readonly after: number };
  readonly stream?: {
    readonly maxMatchLength: number;
    readonly leftContext: number;
    readonly rightContext: number;
    readonly boundaryLookaround: number;
  };
  readonly validate?: (candidate: {
    readonly value: string;
    readonly before: string;
    readonly after: string;
  }) => false | readonly string[];
  readonly contextHint?: {
    readonly labels?: readonly string[];
    readonly position?: "preceding" | "following" | "both";
    readonly instructions?: string;
  };
  readonly semanticConfirm?: (candidate: {
    readonly value: string;
    readonly before: string;
    readonly after: string;
  }) => SemanticQuestion;
}

SemanticQuestion ​

ts
interface SemanticQuestion {
  readonly instructions:
    | string
    | {
        readonly task: string;
        readonly candidate: string;
        readonly before?: string;
        readonly after?: string;
      };
  readonly criteria?: {
    readonly true: string;
    readonly false: string;
  };
}

ContextHint ​

Describes the context labels a detector requires. Returned by listDetectors() and redactor.describe().

ts
interface ContextHint {
  readonly required: boolean;
  readonly labels: readonly string[];
  readonly position: "preceding" | "following" | "both";
  readonly window: { readonly before: number; readonly after: number };
  readonly instructions?: string;
}

DetectorDescription ​

A frozen description of a detector, returned by listDetectors() and redactor.describe().

ts
interface DetectorDescription {
  readonly id: string;
  readonly entityType: string;
  readonly replacement: string;
  readonly stream: boolean;
  readonly contextHint?: ContextHint;
}

Inspection ​

ts
interface Inspection {
  readonly text: string;
  readonly groups: readonly InspectionGroup[];
}

InspectionGroup ​

ts
interface InspectionGroup {
  readonly start: number;
  readonly end: number;
  readonly replacement: string;
  readonly matches: readonly InspectedMatch[];
}

InspectedMatch ​

ts
interface InspectedMatch extends Detection {
  readonly value: string;
}

Detection ​

ts
interface Detection {
  readonly start: number;
  readonly end: number;
  readonly ruleId: string;
  readonly entityType: string;
  readonly reasons: readonly string[];
}

StreamOptions ​

ts
interface StreamOptions {
  readonly signal?: AbortSignal;
  readonly report?: boolean;
  readonly restore?: boolean;
}

StreamEvent ​

ts
type StreamEvent =
  | { readonly type: "text"; readonly text: string }
  | { readonly type: "detection"; readonly group: InspectionGroup }
  | { readonly type: "complete"; readonly map?: RestorationMap };

Errors ​

SensoredError ​

ts
class SensoredError extends Error {
  readonly code: ErrorCode;
  readonly path?: string;
  readonly info?: Readonly<Record<string, unknown>>;

  toProblemDetails(
    statusMap?: Partial<Record<ErrorCode, number>>,
  ): ProblemDetails;
}

ErrorCode ​

ts
type ErrorCode =
  | "INVALID_CONFIG"
  | "UNKNOWN_RULE"
  | "EMPTY_POLICY"
  | "INPUT_LIMIT"
  | "DETECTOR_CONTRACT"
  | "POLICY_CONFLICT"
  | "STREAM_UNSUPPORTED"
  | "BUFFER_LIMIT"
  | "SOURCE_FAILURE"
  | "CANCELLED";

ProblemDetails ​

ts
interface ProblemDetails {
  readonly type: string;
  readonly title: string;
  readonly status: number;
  readonly detail: string;
  readonly code: ErrorCode;
  readonly path?: string;
  readonly [key: string]: unknown;
}

See Errors for the full error reference with default HTTP statuses.

Standalone functions ​

listDetectors ​

Returns descriptions of all 129 built-in detectors, including their context hints. See LLM Steering.

ts
import { listDetectors } from "sensored";

function listDetectors(): readonly DetectorDescription[];

restore ​

Restores redacted text using a restoration map. Can be used without a redactor instance.

ts
import { restore } from "sensored";

function restore(text: string, map: RestorationMap): string;

Constants ​

MAX_INPUT_LENGTH ​

The default maximum input length in UTF-16 code units.

ts
const MAX_INPUT_LENGTH: 1_048_576; // 1 MiB

Exports ​

ts
// Factory
export { createRedactor };

// Standalone functions
export { listDetectors };
export { restore };

// Error class and types
export { SensoredError };
export type { ErrorCode, ProblemDetails };

// Detector base class (for advanced custom detectors)
export { Detector };

// Example detector
export { employeeIdExample };

// Type exports
export type {
  AsyncRedactResult,
  ContextHint,
  Detection,
  DetectorDescription,
  DetectorDefinition,
  FormatPreserveRule,
  InspectedMatch,
  Inspection,
  InspectionGroup,
  MaskRule,
  RedactorConfig,
  RedactResult,
  RedactRule,
  RemoveRule,
  RestorationMap,
  RuleSetting,
  SemanticCandidate,
  SemanticConfig,
  SemanticDetection,
  SemanticQuestion,
  SemanticResult,
  StreamEvent,
  StreamOptions,
  TokenReplaceRule,
};

// Constants
export { MAX_INPUT_LENGTH };

Last updated:

Released under the MIT License.

Copyright © 2026 Dennis Thompson