diff --git a/packages/effect/src/Redacted.ts b/packages/effect/src/Redacted.ts index 76be45bfc3..3c8a2b4261 100644 --- a/packages/effect/src/Redacted.ts +++ b/packages/effect/src/Redacted.ts @@ -1,4 +1,9 @@ /** + * The Redacted module provides functionality for handling sensitive information + * securely within your application. By using the `Redacted` data type, you can + * ensure that sensitive values are not accidentally exposed in logs or error + * messages. + * * @since 3.3.0 */ import type * as Equal from "./Equal.js" @@ -54,24 +59,73 @@ export declare namespace Redacted { export const isRedacted: (u: unknown) => u is Redacted = redacted_.isRedacted /** + * This function creates a `Redacted` instance from a given value `A`, + * securely hiding its content. + * + * @example + * import { Redacted } from "effect" + * + * const API_KEY = Redacted.make("1234567890") + * * @since 3.3.0 * @category constructors */ export const make: (value: A) => Redacted = redacted_.make /** + * Retrieves the original value from a `Redacted` instance. Use this function + * with caution, as it exposes the sensitive data. + * + * @example + * import { Redacted } from "effect" + * + * const API_KEY = Redacted.make("1234567890") + * + * assert.equal(Redacted.value(API_KEY), "1234567890") + * * @since 3.3.0 * @category getters */ export const value: (self: Redacted) => A = redacted_.value /** + * Erases the underlying value of a `Redacted` instance, rendering it unusable. + * This function is intended to ensure that sensitive data does not remain in + * memory longer than necessary. + * + * @example + * import { Redacted } from "effect" + * + * const API_KEY = Redacted.make("1234567890") + * + * assert.equal(Redacted.value(API_KEY), "1234567890") + * + * Redacted.unsafeWipe(API_KEY) + * + * assert.throws(() => Redacted.value(API_KEY), new Error("Unable to get redacted value")) + * * @since 3.3.0 * @category unsafe */ export const unsafeWipe: (self: Redacted) => boolean = redacted_.unsafeWipe /** + * Generates an equivalence relation for `Redacted` values based on an + * equivalence relation for the underlying values `A`. This function is useful + * for comparing `Redacted` instances without exposing their contents. + * + * @example + * import { Redacted, Equivalence } from "effect" + * + * const API_KEY1 = Redacted.make("1234567890") + * const API_KEY2 = Redacted.make("1-34567890") + * const API_KEY3 = Redacted.make("1234567890") + * + * const equivalence = Redacted.getEquivalence(Equivalence.string) + * + * assert.equal(equivalence(API_KEY1, API_KEY2), false) + * assert.equal(equivalence(API_KEY1, API_KEY3), true) + * * @category equivalence * @since 3.3.0 */ diff --git a/packages/effect/src/index.ts b/packages/effect/src/index.ts index 1c2eb003d5..addc39bbee 100644 --- a/packages/effect/src/index.ts +++ b/packages/effect/src/index.ts @@ -615,6 +615,11 @@ export * as Record from "./Record.js" export * as RedBlackTree from "./RedBlackTree.js" /** + * The Redacted module provides functionality for handling sensitive information + * securely within your application. By using the `Redacted` data type, you can + * ensure that sensitive values are not accidentally exposed in logs or error + * messages. + * * @since 3.3.0 */ export * as Redacted from "./Redacted.js"