effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Redactable.ts

@@ -76,7 +76,7 @@ import { hasProperty } from "./Predicate.ts"
  *
  * **When to use**
  *
- * Use this symbol as the property key when implementing {@link Redactable}.
+ * Use as the property key when implementing the `Redactable` protocol.
  *
  * **Details**
  *
@@ -99,8 +99,8 @@ import { hasProperty } from "./Predicate.ts"
  * }
  * ```
  *
- * @see {@link Redactable} - the interface this symbol belongs to
- * @see {@link isRedactable} - check whether a value has this symbol
+ * @see {@link Redactable} for the interface this symbol belongs to
+ * @see {@link isRedactable} to check whether a value has this symbol
  * @category symbol
  * @since 3.10.0
  */
@@ -111,8 +111,8 @@ export const symbolRedactable: unique symbol = Symbol.for("~effect/Redactable")
  *
  * **When to use**
  *
- * Implement this interface on any class or object that holds sensitive data and
- * should present a sanitized form when inspected or logged.
+ * Use to define classes or objects that hold sensitive data and should present
+ * a sanitized form when inspected or logged.
  *
  * **Details**
  *
@@ -133,9 +133,9 @@ export const symbolRedactable: unique symbol = Symbol.for("~effect/Redactable")
  * }
  * ```
  *
- * @see {@link symbolRedactable} - the symbol key to implement
- * @see {@link redact} - apply redaction to any value
- * @see {@link isRedactable} - type guard for this interface
+ * @see {@link symbolRedactable} for the symbol key to implement
+ * @see {@link redact} to apply redaction to any value
+ * @see {@link isRedactable} for the type guard for this interface
  * @category models
  * @since 3.10.0
  */
@@ -147,8 +147,12 @@ export interface Redactable {
  * Type guard that checks whether a value implements the {@link Redactable}
  * interface.
  *
- * @see {@link Redactable} - the interface being checked
- * @see {@link redact} - applies redaction if the value is redactable
+ * **When to use**
+ *
+ * Use to narrow an unknown value before calling redaction-specific helpers.
+ *
+ * @see {@link Redactable} for the interface being checked
+ * @see {@link redact} to apply redaction if the value is redactable
  * @category guards
  * @since 3.10.0
  */
@@ -160,7 +164,7 @@ export const isRedactable = (u: unknown): u is Redactable => hasProperty(u, symb
  *
  * **When to use**
  *
- * Use this as the general-purpose entry point for redaction when the input may
+ * Use as the general-purpose entry point for redaction when the input may
  * or may not implement the redaction protocol.
  *
  * **Details**
@@ -173,8 +177,8 @@ export const isRedactable = (u: unknown): u is Redactable => hasProperty(u, symb
  * Redaction is not recursive. Nested redactable values inside the returned
  * object are not automatically redacted.
  *
- * @see {@link isRedactable} - check before redacting
- * @see {@link getRedacted} - lower-level variant for known redactables
+ * @see {@link isRedactable} to check before redacting
+ * @see {@link getRedacted} for the lower-level variant for known redactables
  * @category destructors
  * @since 3.10.0
  */
@@ -189,7 +193,7 @@ export function redact(u: unknown): unknown {
  *
  * **When to use**
  *
- * Use this when you have already verified the value is `Redactable`, for
+ * Use when you have already verified the value is `Redactable`, for
  * example with {@link isRedactable}, and want to avoid a second check.
  *
  * **Details**
@@ -201,8 +205,8 @@ export function redact(u: unknown): unknown {
  *
  * If no fiber is active, an empty `Context` is passed to the redaction method.
  *
- * @see {@link redact} - higher-level variant that handles non-redactable values
- * @see {@link isRedactable} - type guard to verify before calling this
+ * @see {@link redact} for the higher-level variant that handles non-redactable values
+ * @see {@link isRedactable} for the type guard to verify before calling this
  * @category destructors
  * @since 4.0.0
  */

package/src/Redacted.ts

@@ -1,8 +1,45 @@
 /**
- * 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.
+ * The `Redacted` module wraps sensitive values so normal rendering paths show
+ * a placeholder instead of the underlying value. It is designed to reduce
+ * accidental disclosure in logs, error messages, JSON output, and inspection
+ * output while still allowing trusted code to recover the original value.
+ *
+ * **Mental model**
+ *
+ * - A `Redacted<A>` carries an underlying value of type `A` behind a wrapper
+ * - String, JSON, and inspection output render as `<redacted>` or
+ *   `<redacted:label>` when a label is provided
+ * - {@link value} retrieves the underlying value and should be used only at
+ *   trusted boundaries
+ * - Equality and hashing are based on the underlying value, not the redacted
+ *   placeholder
+ *
+ * **Common tasks**
+ *
+ * - Wrap a secret with {@link make}
+ * - Check unknown input with {@link isRedacted}
+ * - Recover the secret at a trusted boundary with {@link value}
+ * - Remove the stored association with {@link wipeUnsafe}
+ * - Compare redacted values with an underlying equivalence via
+ *   {@link makeEquivalence}
+ *
+ * **Gotchas**
+ *
+ * - `Redacted` is not encryption and does not zero memory; it reduces
+ *   accidental display of sensitive values
+ * - Labels are visible in rendered output, so labels must not contain secrets
+ * - After {@link wipeUnsafe}, calling {@link value} on the same wrapper fails
+ *
+ * **Example** (Rendering a redacted value)
+ *
+ * ```ts
+ * import { Redacted } from "effect"
+ *
+ * const token = Redacted.make("secret-token", { label: "api-token" })
+ *
+ * String(token) // "<redacted:api-token>"
+ * Redacted.value(token) // "secret-token"
+ * ```
  *
  * @since 3.3.0
  */
@@ -21,6 +58,11 @@ const TypeId = "~effect/data/Redacted"
  * 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
@@ -50,6 +92,10 @@ export interface Redacted<out A = string> extends Redacted.Variance<A>, Equal.Eq
 /**
  * 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)
  *
  * ```ts
@@ -68,6 +114,11 @@ export declare namespace Redacted {
   /**
    * Type-level variance marker for `Redacted`.
    *
+   * **When to use**
+   *
+   * Use when defining internals that need to preserve the covariant value type
+   * carried by `Redacted`.
+   *
    * **Details**
    *
    * This interface records the covariant value type carried by a `Redacted`
@@ -85,6 +136,10 @@ export declare namespace Redacted {
   /**
    * Extracts the underlying value type from a `Redacted` type.
    *
+   * **When to use**
+   *
+   * Use to infer the sensitive value type from an existing `Redacted` type.
+   *
    * **Example** (Extracting the redacted value type)
    *
    * ```ts
@@ -109,6 +164,10 @@ export declare namespace Redacted {
 /**
  * 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
@@ -134,6 +193,11 @@ export const isRedacted = (u: unknown): u is Redacted<unknown> => hasProperty(u,
 /**
  * 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
@@ -192,6 +256,10 @@ const Proto = {
  * Retrieves the original value from a `Redacted` instance. Use this function
  * with caution, as it exposes the sensitive data.
  *
+ * **When to use**
+ *
+ * Use when the underlying sensitive value is required at a trusted boundary.
+ *
  * **Example** (Retrieving a redacted value)
  *
  * ```ts
@@ -212,6 +280,11 @@ export const value: <T>(self: Redacted<T>) => T = redacted.value
  * 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
@@ -246,6 +319,11 @@ export const wipeUnsafe = <T>(self: Redacted<T>): boolean => redacted.redactedRe
  * equivalence relation for the underlying values `A`. This function is useful
  * for comparing `Redacted` instances without exposing their contents.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` for `Redacted` values based on their
+ * underlying values.
+ *
  * **Example** (Comparing redacted values)
  *
  * ```ts

package/src/Reducer.ts

@@ -75,7 +75,7 @@ import type * as Combiner from "./Combiner.ts"
  *
  * **When to use**
  *
- * - You need to fold/reduce a collection into a single value.
+ * Use when you need to fold/reduce a collection into a single value.
  * - You want a reusable reducing strategy that can be passed to library
  *   functions like `Struct.makeReducer`, `Option.makeReducer`, or
  *   `Record.makeReducerUnion`.
@@ -112,10 +112,22 @@ import type * as Combiner from "./Combiner.ts"
  * @since 4.0.0
  */
 export interface Reducer<A> extends Combiner.Combiner<A> {
-  /** Neutral starting value (combining with this changes nothing). */
+  /**
+   * Neutral starting value (combining with this changes nothing).
+   *
+   * **When to use**
+   *
+   * Use to seed a reduction and represent the result of reducing an empty collection.
+   */
   readonly initialValue: A
 
-  /** Combines all values in the collection, starting from `initialValue`. */
+  /**
+   * Combines all values in the collection, starting from `initialValue`.
+   *
+   * **When to use**
+   *
+   * Use to reduce an iterable with this reducer's initial value and combining operation.
+   */
   readonly combineAll: (collection: Iterable<A>) => A
 }
 
@@ -124,7 +136,7 @@ export interface Reducer<A> extends Combiner.Combiner<A> {
  *
  * **When to use**
  *
- * - You have a custom reducing operation not covered by a pre-built reducer.
+ * Use when you have a custom reducing operation not covered by a pre-built reducer.
  * - You want to provide an optimized `combineAll` (e.g. short-circuiting on
  *   a known absorbing element like `0` for multiplication).
  *
@@ -190,7 +202,7 @@ export function make<A>(
  *
  * **When to use**
  *
- * - You need the "right" value to act as the accumulator side.
+ * Use when you need the "right" value to act as the accumulator side.
  * - You want to reverse the natural direction of a non-commutative reducer
  *   (e.g. string concatenation becomes prepend).
  *