effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Data.ts

@@ -81,16 +81,17 @@ import type { Unify } from "./Unify.ts"
 /**
  * Base class for immutable data types.
  *
+ * **When to use**
+ *
+ * Use `Class` when you need a lightweight immutable value type with `.pipe()` support. If you also need a `_tag` discriminator, use {@link TaggedClass}; if you need a yieldable error, use {@link Error} or {@link TaggedError}.
+ *
+ * **Details**
+ *
  * Extend `Class` with a type parameter to declare fields. The constructor
  * accepts those fields as a single object argument. When there are no fields
- * the argument is optional.
- *
- * - Use when you need a lightweight immutable value type with `.pipe()` support.
- * - Instances are `Readonly` and `Pipeable`.
- * - If you also need a `_tag` discriminator, use {@link TaggedClass} instead.
- * - If you need a yieldable error, use {@link Error} or {@link TaggedError}.
+ * the argument is optional. Instances are `Readonly` and `Pipeable`.
  *
- * **Example** (defining a value class)
+ * **Example** (Defining a value class)
  *
  * ```ts
  * import { Data, Equal } from "effect"
@@ -124,15 +125,17 @@ export const Class: new<A extends Record<string, any> = {}>(
 /**
  * Base class for immutable data types with a `_tag` discriminator.
  *
+ * **When to use**
+ *
+ * Use `TaggedClass` when you need a single-variant tagged type or an ad-hoc discriminator. For multi-variant unions, prefer {@link TaggedEnum} with {@link taggedEnum}; for yieldable errors, use {@link TaggedError}.
+ *
+ * **Details**
+ *
  * Like {@link Class}, but the resulting instances also carry a
  * `readonly _tag: Tag` property. The `_tag` is excluded from the constructor
  * argument.
  *
- * - Use when you need a single-variant tagged type or an ad-hoc discriminator.
- * - For multi-variant unions, prefer {@link TaggedEnum} + {@link taggedEnum}.
- * - For yieldable errors, use {@link TaggedError}.
- *
- * **Example** (defining a tagged class)
+ * **Example** (Defining a tagged class)
  *
  * ```ts
  * import { Data } from "effect"
@@ -165,17 +168,21 @@ export const TaggedClass = <Tag extends string>(
 /**
  * Transforms a record of variant definitions into a discriminated union type.
  *
+ * **When to use**
+ *
+ * Use `TaggedEnum` when you have two or more variants that share a common `_tag` discriminator. For generic tagged enums, see {@link TaggedEnum.WithGenerics}.
+ *
+ * **Details**
+ *
  * Each key in the record becomes a variant with `readonly _tag` set to that
  * key. Use with {@link taggedEnum} to get runtime constructors, type guards,
  * and pattern matching.
  *
- * - Use when you have two or more variants that share a common `_tag`
- *   discriminator.
- * - Variant records must **not** include a `_tag` property — it is added
- *   automatically.
- * - For generic tagged enums, see {@link TaggedEnum.WithGenerics}.
+ * **Gotchas**
  *
- * **Example** (defining a tagged enum)
+ * Variant records must **not** include a `_tag` property; it is added automatically.
+ *
+ * **Example** (Defining a tagged enum)
  *
  * ```ts
  * import { Data } from "effect"
@@ -223,6 +230,8 @@ type UntaggedChildren<A> = true extends ChildrenAreTagged<A>
 /**
  * Namespace for `TaggedEnum` utility types.
  *
+ * **Details**
+ *
  * Provides helper types for:
  * - Generic tagged enums ({@link TaggedEnum.WithGenerics}, {@link TaggedEnum.Kind})
  * - Extracting constructor arguments ({@link TaggedEnum.Args}) and variant
@@ -235,15 +244,17 @@ export declare namespace TaggedEnum {
   /**
    * Defines a tagged enum shape that accepts generic type parameters.
    *
+   * **When to use**
+   *
+   * Use `WithGenerics` when variant payloads need to be parameterized, such as `Result<E, A>`. Pass the interface, not the type alias, to {@link taggedEnum} to get generic-aware constructors.
+   *
+   * **Details**
+   *
    * Extend this interface and set `taggedEnum` to your union type, using
    * `this["A"]`, `this["B"]`, etc. as placeholders for the generics. The
    * `Count` parameter declares how many generics are used (up to 4).
    *
-   * - Use when variant payloads need to be parameterized (e.g., `Result<E, A>`).
-   * - Pass the interface (not the type alias) to {@link taggedEnum} to get
-   *   generic-aware constructors.
-   *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -283,10 +294,11 @@ export declare namespace TaggedEnum {
    * Applies concrete type arguments to a `WithGenerics` definition, producing
    * the resulting tagged union type.
    *
-   * - Use to refer to a specific instantiation of a generic tagged enum in
-   *   type signatures.
+   * **When to use**
+   *
+   * Use `Kind` to refer to a specific instantiation of a generic tagged enum in type signatures.
    *
-   * **Example** (applying generics)
+   * **Example** (Applying generics)
    *
    * ```ts
    * import type { Data } from "effect"
@@ -326,9 +338,11 @@ export declare namespace TaggedEnum {
    * Extracts the constructor argument type for a specific variant of a tagged
    * union.
    *
+   * **Details**
+   *
    * Returns `void` if the variant has no fields beyond `_tag`.
    *
-   * **Example** (extracting variant args)
+   * **Example** (Extracting variant args)
    *
    * ```ts
    * import type { Data } from "effect"
@@ -387,12 +401,14 @@ export declare namespace TaggedEnum {
   /**
    * The full constructor-object type returned by {@link taggedEnum}.
    *
+   * **Details**
+   *
    * Includes:
    * - A constructor function for each variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard for the given variant
    * - `$match` — exhaustive pattern matching (data-last or data-first)
    *
-   * **Example** (using the constructor object)
+   * **Example** (Using the constructor object)
    *
    * ```ts
    * import { Data } from "effect"
@@ -460,6 +476,8 @@ export declare namespace TaggedEnum {
    * Function type that constructs a tagged-union variant from its fields,
    * excluding the keys listed in `Tag`.
    *
+   * **Details**
+   *
    * The constructor returns the full variant type `A`. If no fields remain
    * after excluding `Tag` keys, the constructor argument type becomes `void`.
    *
@@ -473,6 +491,8 @@ export declare namespace TaggedEnum {
   /**
    * Type-guard and pattern-matching interface for generic tagged enums.
    *
+   * **Details**
+   *
    * This is the `$is` / `$match` portion of the object returned by
    * {@link taggedEnum} when used with a {@link WithGenerics} definition.
    *
@@ -534,16 +554,22 @@ export declare namespace TaggedEnum {
  * Creates runtime constructors, type guards, and pattern matching for a
  * {@link TaggedEnum} type.
  *
+ * **When to use**
+ *
+ * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+ *
+ * **Details**
+ *
  * Returns an object with:
  * - One constructor per variant (keyed by tag name)
  * - `$is(tag)` — returns a type-guard function
  * - `$match` — exhaustive pattern matching (data-first or data-last)
  *
- * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
- * - Constructors produce **plain objects** (not class instances).
- * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+ * **Gotchas**
+ *
+ * Constructors produce **plain objects**, not class instances.
  *
- * **Example** (basic usage)
+ * **Example** (Basic usage)
  *
  * ```ts
  * import { Data } from "effect"
@@ -568,7 +594,7 @@ export declare namespace TaggedEnum {
  * console.log(msg) // "/missing not found"
  * ```
  *
- * **Example** (generic tagged enum)
+ * **Example** (Generic tagged enum)
  *
  * ```ts
  * import { Data } from "effect"
@@ -598,16 +624,22 @@ export const taggedEnum: {
    * Creates runtime constructors, type guards, and pattern matching for a
    * {@link TaggedEnum} type.
    *
+   * **When to use**
+   *
+   * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   *
+   * **Details**
+   *
    * Returns an object with:
    * - One constructor per variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard function
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
-   * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
-   * - Constructors produce **plain objects** (not class instances).
-   * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * **Gotchas**
    *
-   * **Example** (basic usage)
+   * Constructors produce **plain objects**, not class instances.
+   *
+   * **Example** (Basic usage)
    *
    * ```ts
    * import { Data } from "effect"
@@ -632,7 +664,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -673,16 +705,22 @@ export const taggedEnum: {
    * Creates runtime constructors, type guards, and pattern matching for a
    * {@link TaggedEnum} type.
    *
+   * **When to use**
+   *
+   * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   *
+   * **Details**
+   *
    * Returns an object with:
    * - One constructor per variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard function
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
-   * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
-   * - Constructors produce **plain objects** (not class instances).
-   * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * **Gotchas**
+   *
+   * Constructors produce **plain objects**, not class instances.
    *
-   * **Example** (basic usage)
+   * **Example** (Basic usage)
    *
    * ```ts
    * import { Data } from "effect"
@@ -707,7 +745,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -748,16 +786,22 @@ export const taggedEnum: {
    * Creates runtime constructors, type guards, and pattern matching for a
    * {@link TaggedEnum} type.
    *
+   * **When to use**
+   *
+   * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   *
+   * **Details**
+   *
    * Returns an object with:
    * - One constructor per variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard function
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
-   * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
-   * - Constructors produce **plain objects** (not class instances).
-   * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * **Gotchas**
+   *
+   * Constructors produce **plain objects**, not class instances.
    *
-   * **Example** (basic usage)
+   * **Example** (Basic usage)
    *
    * ```ts
    * import { Data } from "effect"
@@ -782,7 +826,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -823,16 +867,22 @@ export const taggedEnum: {
    * Creates runtime constructors, type guards, and pattern matching for a
    * {@link TaggedEnum} type.
    *
+   * **When to use**
+   *
+   * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   *
+   * **Details**
+   *
    * Returns an object with:
    * - One constructor per variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard function
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
-   * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
-   * - Constructors produce **plain objects** (not class instances).
-   * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * **Gotchas**
    *
-   * **Example** (basic usage)
+   * Constructors produce **plain objects**, not class instances.
+   *
+   * **Example** (Basic usage)
    *
    * ```ts
    * import { Data } from "effect"
@@ -857,7 +907,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -898,16 +948,22 @@ export const taggedEnum: {
    * Creates runtime constructors, type guards, and pattern matching for a
    * {@link TaggedEnum} type.
    *
+   * **When to use**
+   *
+   * Use `taggedEnum` when you have a `TaggedEnum` type and need to construct or inspect values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   *
+   * **Details**
+   *
    * Returns an object with:
    * - One constructor per variant (keyed by tag name)
    * - `$is(tag)` — returns a type-guard function
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
-   * - Use when you have a `TaggedEnum` type and need to construct/inspect values.
-   * - Constructors produce **plain objects** (not class instances).
-   * - For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * **Gotchas**
    *
-   * **Example** (basic usage)
+   * Constructors produce **plain objects**, not class instances.
+   *
+   * **Example** (Basic usage)
    *
    * ```ts
    * import { Data } from "effect"
@@ -932,7 +988,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (generic tagged enum)
+   * **Example** (Generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -1005,15 +1061,18 @@ function taggedMatch<
 /**
  * Base class for yieldable errors.
  *
+ * **When to use**
+ *
+ * Use `Error` for errors that do **not** need tag-based discrimination. If you need `Effect.catchTag` support, use {@link TaggedError}.
+ *
+ * **Details**
+ *
  * Extends `Cause.YieldableError`, so instances can be yielded inside
  * `Effect.gen` to fail the enclosing effect. Fields are passed as a single
- * object; when there are no fields the argument is optional.
- *
- * - Use for errors that do **not** need tag-based discrimination.
- * - If you need `Effect.catchTag` support, use {@link TaggedError} instead.
- * - If a `message` field is provided, it becomes the error's `.message`.
+ * object; when there are no fields the argument is optional. If a `message`
+ * field is provided, it becomes the error's `.message`.
  *
- * **Example** (defining a yieldable error)
+ * **Example** (Defining a yieldable error)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -1044,15 +1103,18 @@ export const Error: new<A extends Record<string, any> = {}>(
 /**
  * Creates a tagged error class with a `_tag` discriminator.
  *
+ * **When to use**
+ *
+ * Use `TaggedError` for domain errors in Effect applications where you want discriminated-union error handling.
+ *
+ * **Details**
+ *
  * Like {@link Error}, but instances also carry a `readonly _tag` property,
  * enabling `Effect.catchTag` and `Effect.catchTags` for tag-based recovery.
- * The `_tag` is excluded from the constructor argument.
- *
- * - Use for domain errors in Effect applications where you want
- *   discriminated-union error handling.
- * - Yielding an instance inside `Effect.gen` fails the effect with this error.
+ * The `_tag` is excluded from the constructor argument. Yielding an instance
+ * inside `Effect.gen` fails the effect with this error.
  *
- * **Example** (tag-based error recovery)
+ * **Example** (Tag-based error recovery)
  *
  * ```ts
  * import { Data, Effect } from "effect"