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

package/src/Inspectable.ts

@@ -1,22 +1,48 @@
 /**
- * This module provides utilities for making values inspectable and debuggable in TypeScript.
+ * Inspection protocol for stable string, JSON, and Node.js representations.
  *
- * The Inspectable interface provides a standard way to implement custom string representations
- * for objects, making them easier to debug and inspect. It includes support for JSON
- * serialization, Node.js inspection, and safe circular reference handling.
+ * This module is the small bridge used by Effect data types to explain
+ * themselves in logs, REPLs, test failures, and JSON-like diagnostics. Implement
+ * `Inspectable` or extend {@link Class} when a value should expose one
+ * representation to `toString`, `toJSON`, and Node's `util.inspect`; use
+ * {@link toJson} and {@link toStringUnknown} when formatting values supplied by
+ * user code.
  *
- * The module also includes redaction capabilities for sensitive data, allowing objects
- * to provide different representations based on the current execution context.
+ * ## Mental model
+ *
+ * Inspectable values choose their own JSON representation. {@link BaseProto}
+ * and {@link Class} derive `toString()` from that representation with the
+ * formatter and expose the same value through {@link NodeInspectSymbol}.
+ * {@link toJson} is defensive: it calls zero-argument `toJSON` methods,
+ * recurses through arrays, returns `"[toJSON threw]"` if a custom serializer
+ * fails, and applies redaction to other values.
+ *
+ * ## Common tasks
+ *
+ * - Extend {@link Class} for classes that only need to define `toJSON`.
+ * - Reuse {@link BaseProto} for object prototypes that should share standard
+ *   inspection behavior.
+ * - Format unknown diagnostic values with {@link toStringUnknown}.
+ * - Implement {@link NodeInspectSymbol} when integrating directly with
+ *   Node.js inspection.
+ *
+ * ## Gotchas
+ *
+ * `toJson` is meant for inspection, not canonical persistence. It catches
+ * `toJSON` failures, does not deeply traverse arbitrary objects, and may
+ * replace redactable values according to current redaction behavior. Keep
+ * custom `toJSON` implementations side-effect free so logging and debugging do
+ * not change program state.
  *
  * **Example** (Creating inspectable values)
  *
  * ```ts
- * import { Formatter, Inspectable } from "effect"
+ * import { Inspectable } from "effect"
  *
  * class User extends Inspectable.Class {
  *   constructor(
- *     public readonly name: string,
- *     public readonly email: string
+ *     readonly id: number,
+ *     readonly name: string
  *   ) {
  *     super()
  *   }
@@ -24,15 +50,15 @@
  *   toJSON() {
  *     return {
  *       _tag: "User",
+ *       id: this.id,
  *       name: this.name,
- *       email: this.email
  *     }
  *   }
  * }
  *
- * const user = new User("Alice", "alice@example.com")
- * console.log(user.toString()) // Pretty printed JSON
- * console.log(Formatter.format(user)) // Same as toString()
+ * const user = new User(1, "Alice")
+ * console.log(user.toString())
+ * console.log(user[Inspectable.NodeInspectSymbol]())
  * ```
  *
  * @since 2.0.0
@@ -44,6 +70,10 @@ import { redact } from "./Redactable.ts"
 /**
  * Symbol used by Node.js for custom object inspection.
  *
+ * **When to use**
+ *
+ * Use to implement Node.js custom inspection for a value.
+ *
  * **Details**
  *
  * This symbol is recognized by Node.js's `util.inspect()` function and the REPL
@@ -77,6 +107,10 @@ export const NodeInspectSymbol = Symbol.for("nodejs.util.inspect.custom")
  * This symbol type is used to implement custom inspection behavior in Node.js
  * environments.
  *
+ * **When to use**
+ *
+ * Use to type methods keyed by the Node.js custom inspection symbol.
+ *
  * **Example** (Typing custom Node inspection)
  *
  * ```ts
@@ -102,6 +136,10 @@ export type NodeInspectSymbol = typeof NodeInspectSymbol
 /**
  * Interface for objects that can be inspected and provide custom string representations.
  *
+ * **When to use**
+ *
+ * Use to define values with custom string, JSON, and Node.js inspection output.
+ *
  * **Details**
  *
  * Objects implementing this interface can control how they appear in debugging contexts,
@@ -148,6 +186,11 @@ export interface Inspectable {
 /**
  * Safely converts a value to a JSON-serializable representation.
  *
+ * **When to use**
+ *
+ * Use when you need a safe, JSON-serializable representation of a value
+ * without risking unhandled errors.
+ *
  * **Details**
  *
  * This function attempts to extract JSON data from objects that implement the
@@ -155,6 +198,8 @@ export interface Inspectable {
  * For objects that don't have a `toJSON` method, it applies redaction to
  * protect sensitive information.
  *
+ * @see {@link toStringUnknown} for converting unknown values to strings
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -178,6 +223,10 @@ export const toJson = (input: unknown): unknown => {
 /**
  * Converts an unknown value to a string for diagnostics.
  *
+ * **When to use**
+ *
+ * Use to produce a diagnostic string from a value whose runtime type is unknown.
+ *
  * **Details**
  *
  * Strings are returned unchanged. Objects are formatted as JSON using the
@@ -201,6 +250,10 @@ export const toStringUnknown = (u: unknown, whitespace: number | string | undefi
 /**
  * A base prototype object that implements the {@link Inspectable} interface.
  *
+ * **When to use**
+ *
+ * Use as a prototype for plain objects that should share standard inspectable behavior.
+ *
  * **Details**
  *
  * This object provides default implementations for the {@link Inspectable} methods.
@@ -245,6 +298,10 @@ export const BaseProto: Inspectable = {
 /**
  * Abstract base class that implements the Inspectable interface.
  *
+ * **When to use**
+ *
+ * Use as a base class for inspectable objects that define their own JSON representation.
+ *
  * **Details**
  *
  * This class provides a convenient way to create inspectable objects by extending it.
@@ -287,6 +344,10 @@ export abstract class Class {
   /**
    * Returns a JSON representation of this object.
    *
+   * **When to use**
+   *
+   * Use to provide the JSON representation consumed by inherited inspection methods.
+   *
    * **Details**
    *
    * Subclasses must implement this method to define how the object
@@ -298,6 +359,10 @@ export abstract class Class {
   /**
    * Node.js custom inspection method.
    *
+   * **When to use**
+   *
+   * Use to expose the class JSON representation to Node.js inspection.
+   *
    * @since 2.0.0
    */
   [NodeInspectSymbol]() {
@@ -306,6 +371,10 @@ export abstract class Class {
   /**
    * Returns a formatted string representation of this object.
    *
+   * **When to use**
+   *
+   * Use to format the class JSON representation as a string.
+   *
    * @since 2.0.0
    */
   toString() {

package/src/Iterable.ts

@@ -1,31 +1,54 @@
 /**
- * This module provides utility functions for working with Iterables in TypeScript.
+ * The `Iterable` module works with any JavaScript value that implements
+ * `[Symbol.iterator]`, including arrays, strings, generators, sets, and custom
+ * lazy sequences. It provides constructors, transformations, searches, grouping,
+ * and folding helpers that can be used without converting to an array first.
+ *
+ * **Mental model**
+ *
+ * - An `Iterable<A>` creates an `Iterator<A>` when it is consumed.
+ * - Transformations such as {@link map}, {@link filter}, {@link flatMap},
+ *   {@link take}, and {@link drop} return new iterables and usually do no work
+ *   until the result is iterated.
+ * - Consumers such as {@link reduce}, {@link size}, {@link head},
+ *   {@link findFirst}, and `Array.from` pull values from an iterator.
+ * - Constructors such as {@link range}, {@link makeBy}, {@link repeat},
+ *   {@link forever}, and {@link unfold} can represent unbounded sequences.
+ *
+ * **Common tasks**
+ *
+ * - Create sequences: {@link empty}, {@link of}, {@link range}, {@link makeBy},
+ *   {@link replicate}, {@link unfold}
+ * - Transform values: {@link map}, {@link flatMap}, {@link flatten},
+ *   {@link filter}, {@link filterMap}
+ * - Slice and search: {@link take}, {@link drop}, {@link takeWhile},
+ *   {@link findFirst}, {@link findLast}, {@link contains}
+ * - Combine and group: {@link appendAll}, {@link zipWith}, {@link chunksOf},
+ *   {@link groupBy}, {@link cartesian}
+ * - Fold or collect: {@link reduce}, {@link scan}, {@link countBy},
+ *   `Array.from`
  *
- * Iterables are objects that implement the iterator protocol, allowing them to be
- * consumed with `for...of` loops, spread syntax, and other iteration constructs.
- * This module provides a comprehensive set of functions for creating, transforming,
- * and working with iterables in a functional programming style.
+ * **Gotchas**
  *
- * Unlike arrays, iterables can be lazy and potentially infinite, making them suitable
- * for stream processing and memory-efficient data manipulation. All functions in this
- * module preserve the lazy nature of iterables where possible.
+ * - Laziness depends on the operation. Functions such as {@link size} and
+ *   {@link reduce} consume the iterable immediately.
+ * - Some JavaScript iterables are single-use iterators. Reusing the same value
+ *   after it has been consumed may produce no elements.
+ * - Unbounded iterables must be limited before full collection, for example
+ *   with {@link take}.
  *
- * **Example** (Working with iterables)
+ * **Example** (Building a lazy pipeline)
  *
  * ```ts
- * import { Iterable, Option } from "effect"
- *
- * // Create iterables
- * const numbers = Iterable.range(1, 5)
- * const doubled = Iterable.map(numbers, (x) => x * 2)
- * const filtered = Iterable.filter(doubled, (x) => x > 5)
+ * import { Iterable } from "effect"
  *
- * console.log(Array.from(filtered)) // [6, 8, 10]
+ * const naturals = Iterable.range(1)
+ * const squares = Iterable.map(naturals, (n) => n * n)
+ * const evenSquares = Iterable.filter(squares, (n) => n % 2 === 0)
+ * const firstFive = Iterable.take(evenSquares, 5)
  *
- * // Infinite iterables
- * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => Option.some([a, [b, a + b]]))
- * const first10 = Iterable.take(fibonacci, 10)
- * console.log(Array.from(first10)) // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+ * console.log(Array.from(firstFive))
+ * // [4, 16, 36, 64, 100]
  * ```
  *
  * @since 2.0.0
@@ -189,10 +212,16 @@ export const replicate: {
  * Repeats an iterable `n` times, yielding the full contents of `self` for each
  * repetition.
  *
+ * **When to use**
+ *
+ * Use to repeat an iterable's contents a specific number of times.
+ *
  * **Details**
  *
  * The result is lazy. Each repetition obtains a new iterator from `self`.
  *
+ * @see {@link forever} for repeating without an upper bound
+ * @see {@link replicate} for repeating a single value
  * @category constructors
  * @since 4.0.0
  */
@@ -201,10 +230,16 @@ export const repeat: {
    * Repeats an iterable `n` times, yielding the full contents of `self` for each
    * repetition.
    *
+   * **When to use**
+   *
+   * Use to repeat an iterable's contents a specific number of times.
+   *
    * **Details**
    *
    * The result is lazy. Each repetition obtains a new iterator from `self`.
    *
+   * @see {@link forever} for repeating without an upper bound
+   * @see {@link replicate} for repeating a single value
    * @category constructors
    * @since 4.0.0
    */
@@ -213,10 +248,16 @@ export const repeat: {
    * Repeats an iterable `n` times, yielding the full contents of `self` for each
    * repetition.
    *
+   * **When to use**
+   *
+   * Use to repeat an iterable's contents a specific number of times.
+   *
    * **Details**
    *
    * The result is lazy. Each repetition obtains a new iterator from `self`.
    *
+   * @see {@link forever} for repeating without an upper bound
+   * @see {@link replicate} for repeating a single value
    * @category constructors
    * @since 4.0.0
    */
@@ -226,11 +267,19 @@ export const repeat: {
 /**
  * Repeats an iterable without an upper bound.
  *
+ * **When to use**
+ *
+ * Use to cycle a reusable iterable without an upper bound when a downstream
+ * consumer controls how many values are taken.
+ *
  * **Gotchas**
  *
  * The returned iterable is lazy and should usually be bounded with `take` or
  * another terminating consumer before materializing it.
  *
+ * @see {@link repeat} for repeating an iterable a specific number of times
+ * @see {@link take} for bounding the unbounded result before materializing it
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -398,6 +447,21 @@ export const prependAll: {
 /**
  * Append an element to the end of an `Iterable`, creating a new `Iterable`.
  *
+ * **When to use**
+ *
+ * Use to add one element after all elements of an iterable while keeping the
+ * result as a lazy `Iterable`.
+ *
+ * **Details**
+ *
+ * The result yields every element from `self` first, then yields `last` after
+ * `self` is exhausted.
+ *
+ * **Gotchas**
+ *
+ * If `self` is infinite or never completes, the appended element is never
+ * reached.
+ *
  * **Example** (Appending an element)
  *
  * ```ts
@@ -415,6 +479,9 @@ export const prependAll: {
  * console.log(Array.from(result)) // [1, 2, 3, 4]
  * ```
  *
+ * @see {@link prepend} for adding one element before the existing elements
+ * @see {@link appendAll} for appending all elements from another iterable
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -422,6 +489,21 @@ export const append: {
   /**
    * Append an element to the end of an `Iterable`, creating a new `Iterable`.
    *
+   * **When to use**
+   *
+   * Use to add one element after all elements of an iterable while keeping the
+   * result as a lazy `Iterable`.
+   *
+   * **Details**
+   *
+   * The result yields every element from `self` first, then yields `last` after
+   * `self` is exhausted.
+   *
+   * **Gotchas**
+   *
+   * If `self` is infinite or never completes, the appended element is never
+   * reached.
+   *
    * **Example** (Appending an element)
    *
    * ```ts
@@ -439,6 +521,9 @@ export const append: {
    * console.log(Array.from(result)) // [1, 2, 3, 4]
    * ```
    *
+   * @see {@link prepend} for adding one element before the existing elements
+   * @see {@link appendAll} for appending all elements from another iterable
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -446,6 +531,21 @@ export const append: {
   /**
    * Append an element to the end of an `Iterable`, creating a new `Iterable`.
    *
+   * **When to use**
+   *
+   * Use to add one element after all elements of an iterable while keeping the
+   * result as a lazy `Iterable`.
+   *
+   * **Details**
+   *
+   * The result yields every element from `self` first, then yields `last` after
+   * `self` is exhausted.
+   *
+   * **Gotchas**
+   *
+   * If `self` is infinite or never completes, the appended element is never
+   * reached.
+   *
    * **Example** (Appending an element)
    *
    * ```ts
@@ -463,6 +563,9 @@ export const append: {
    * console.log(Array.from(result)) // [1, 2, 3, 4]
    * ```
    *
+   * @see {@link prepend} for adding one element before the existing elements
+   * @see {@link appendAll} for appending all elements from another iterable
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -472,6 +575,20 @@ export const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
+ * **When to use**
+ *
+ * Use to lazily concatenate two iterables while preserving order, yielding all
+ * elements from `self` before `that`.
+ *
+ * **Details**
+ *
+ * The result is lazy. The iterator for `that` is not created or read until
+ * `self` is exhausted.
+ *
+ * **Gotchas**
+ *
+ * If `self` is infinite or never completes, `that` is never reached.
+ *
  * **Example** (Concatenating iterables)
  *
  * ```ts
@@ -495,6 +612,9 @@ export const append: {
  * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
  * ```
  *
+ * @see {@link append} for appending one value instead of another iterable
+ * @see {@link prependAll} for yielding another iterable before `self`
+ *
  * @category concatenating
  * @since 2.0.0
  */
@@ -502,6 +622,20 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
+   * **When to use**
+   *
+   * Use to lazily concatenate two iterables while preserving order, yielding all
+   * elements from `self` before `that`.
+   *
+   * **Details**
+   *
+   * The result is lazy. The iterator for `that` is not created or read until
+   * `self` is exhausted.
+   *
+   * **Gotchas**
+   *
+   * If `self` is infinite or never completes, `that` is never reached.
+   *
    * **Example** (Concatenating iterables)
    *
    * ```ts
@@ -525,6 +659,9 @@ export const appendAll: {
    * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
    * ```
    *
+   * @see {@link append} for appending one value instead of another iterable
+   * @see {@link prependAll} for yielding another iterable before `self`
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -532,6 +669,20 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
+   * **When to use**
+   *
+   * Use to lazily concatenate two iterables while preserving order, yielding all
+   * elements from `self` before `that`.
+   *
+   * **Details**
+   *
+   * The result is lazy. The iterator for `that` is not created or read until
+   * `self` is exhausted.
+   *
+   * **Gotchas**
+   *
+   * If `self` is infinite or never completes, `that` is never reached.
+   *
    * **Example** (Concatenating iterables)
    *
    * ```ts
@@ -555,6 +706,9 @@ export const appendAll: {
    * console.log(Array.from(result)) // [0, -1, -2, 1, 2]
    * ```
    *
+   * @see {@link append} for appending one value instead of another iterable
+   * @see {@link prependAll} for yielding another iterable before `self`
+   *
    * @category concatenating
    * @since 2.0.0
    */
@@ -2901,7 +3055,7 @@ const constEmptyIterator: Iterator<never> = {
  *
  * **When to use**
  *
- * Use this reusable empty iterable as a base case for operations or when you
+ * Use as a base case for operations or when you
  * need to represent "no data" in a type-safe way.
  *
  * **Example** (Creating an empty iterable)
@@ -2930,7 +3084,7 @@ export const empty = <A = never>(): Iterable<A> => constEmpty
  *
  * **When to use**
  *
- * Use this to wrap a single value in an iterable context so it can be combined
+ * Use to wrap a single value in an iterable context so it can be combined
  * with other iterable operations.
  *
  * **Example** (Wrapping a single value)
@@ -3939,7 +4093,7 @@ export const filter: {
  *
  * **When to use**
  *
- * Use this when working with APIs or functions that return nullable values,
+ * Use when working with APIs or functions that return nullable values,
  * providing a clean way to filter out null or undefined while transforming.
  *
  * **Example** (FlatMapping nullable results)
@@ -3985,7 +4139,7 @@ export const flatMapNullishOr: {
    *
    * **When to use**
    *
-   * Use this when working with APIs or functions that return nullable values,
+   * Use when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null or undefined while transforming.
    *
    * **Example** (FlatMapping nullable results)
@@ -4031,7 +4185,7 @@ export const flatMapNullishOr: {
    *
    * **When to use**
    *
-   * Use this when working with APIs or functions that return nullable values,
+   * Use when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null or undefined while transforming.
    *
    * **Example** (FlatMapping nullable results)