Skip to content

Redacted

Wraps sensitive values so normal output does not reveal them.

A Redacted<A> shows a redacted placeholder in string, JSON, and inspection output, while still storing the original value for trusted code that needs to recover it. This helps reduce accidental leaks in logs and diagnostics. This module includes constructors, runtime checks, value recovery, wiping of stored values, and comparison helpers that avoid exposing the wrapped value at the call site.

7 exports Added in v3.3.0 Source

Constructors

make

Added in v3.3.0 Source

Creates a Redacted wrapper for a sensitive value.

When to use

Use to wrap a sensitive value so normal string, JSON, and inspection output is redacted.

Details

The wrapper redacts string, JSON, and inspection output to reduce accidental disclosure. The original value remains retrievable with Redacted.value until the wrapper is wiped or becomes unreachable.

Signature

declare function make<T>(
  value: T,
  options?: {
    readonly label?: string;
  },
): Redacted<T>;

Getters

value

Added in v3.3.0 Source

Retrieves the original value from a Redacted instance. Use this function with caution, as it exposes the sensitive data.

When to use

Use when you need the underlying sensitive value at a trusted boundary.

Signature

declare const value: <T>(self: Redacted<T>) => T;

Guards

isRedacted

Added in v3.3.0 Source

Returns true if a value is a Redacted wrapper.

When to use

Use to validate unknown input and narrow it to Redacted.

Details

When this function returns true, TypeScript narrows the value to Redacted<unknown>.

Signature

declare function isRedacted(u: unknown): u is Redacted<unknown>;

Instances

makeEquivalence

Added in v4.0.0 Source

Generates an equivalence relation for Redacted<A> values based on an equivalence relation for the underlying values A. This function is useful for comparing Redacted instances without exposing their contents.

When to use

Use when you need to compare wrapped secrets through an approved equality rule without exposing the underlying values at each comparison site.

Signature

declare function makeEquivalence<A>(isEquivalent: Equivalence<A>): Equivalence<Redacted<A>>;

Models

Redacted interface

Added in v3.3.0 Source

A wrapper for sensitive values whose string, JSON, and inspection output is redacted.

When to use

Use to carry sensitive values while reducing accidental exposure in string, JSON, and inspection output.

Gotchas

The underlying value is still stored in memory and can be recovered with Redacted.value until the wrapper is wiped or becomes unreachable. Use Redacted to reduce accidental disclosure in logs and diagnostics, not as a cryptographic protection mechanism.

Signature

interface Redacted<out A = string> extends Variance<A>, Equal, Pipeable {
  readonly label: string | undefined;
}

Other

Redacted

Added in v3.3.0 Source

Namespace containing type-level members associated with Redacted values.

When to use

Use to access type-level helpers associated with Redacted.

Unsafe

wipeUnsafe

Added in v4.0.0 Source

Deletes the stored value for a Redacted wrapper, making future Redacted.value calls on that wrapper fail.

When to use

Use when a Redacted wrapper should no longer be able to reveal its stored value.

Gotchas

This unsafe operation does not zero memory and does not affect other references to the original value. It only removes the value from the internal redacted registry.

Signature

declare function wipeUnsafe<T>(self: Redacted<T>): boolean;