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>

Example

(Creating a redacted value)

import { Redacted } from "effect"

const API_KEY = Redacted.make("1234567890")
String(API_KEY) // => "<redacted>"

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

Example

(Retrieving a redacted value)

import { Redacted } from "effect"

const API_KEY = Redacted.make("1234567890")

Redacted.value(API_KEY) // => "1234567890"

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>

Example

(Checking for redacted values)

import { Redacted } from "effect"

const secret = Redacted.make("my-secret")
const plainString = "not-secret"

Redacted.isRedacted(secret) // => true
Redacted.isRedacted(plainString) // => false

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>>

Example

(Comparing redacted values)

import { Equivalence, Redacted } from "effect"

const API_KEY1 = Redacted.make("1234567890")
const API_KEY2 = Redacted.make("1-34567890")
const API_KEY3 = Redacted.make("1234567890")

const equivalence = Redacted.makeEquivalence(Equivalence.strictEqual<string>())

equivalence(API_KEY1, API_KEY2) // => false
equivalence(API_KEY1, API_KEY3) // => true

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;
}

Example

(Creating redacted values)

import { Redacted } from "effect"

// Create a redacted value to protect sensitive information
const apiKey = Redacted.make("secret-key")
const userPassword = Redacted.make("user-password")

// TypeScript will infer the types as Redacted<string>
Array.of(String(apiKey), String(userPassword)) // => ["<redacted>", "<redacted>"]

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.

Example

(Using namespace utilities)

import { Redacted } from "effect"

// Use the Redacted namespace for type-level operations
const secret = Redacted.make("my-secret")

// The namespace contains utilities for working with Redacted values
Redacted.isRedacted(secret) // => true

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

Example

(Wiping a redacted value)

import { Redacted, Result } from "effect"

const API_KEY = Redacted.make("1234567890")

Redacted.value(API_KEY) // => "1234567890"

Redacted.wipeUnsafe(API_KEY)

const failure = Result.try({
  try: () => Redacted.value(API_KEY),
  catch: (error) => (error as Error).message
})
failure // => Result.fail("Unable to get redacted value")