effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Data.ts

@@ -39,6 +39,10 @@
  * - `taggedEnum()` creates **plain objects**, not class instances. If you need
  *   class-based variants, use `TaggedClass` or `TaggedError` instead.
  * - `TaggedEnum.WithGenerics` supports up to 4 generic type parameters.
+ * - `$is(tag)` only checks the `_tag` field, not the full structure. It is safe
+ *   when the tag value is globally unique across your application and the value
+ *   was produced by your constructors. For untrusted input, validate with
+ *   the `Schema` module before using `$is`.
  *
  * ## Quickstart
  *
@@ -79,11 +83,11 @@ import type * as Types from "./Types.ts"
 import type { Unify } from "./Unify.ts"
 
 /**
- * Base class for immutable data types.
+ * Provides a 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}.
+ * Use 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**
  *
@@ -123,11 +127,11 @@ export const Class: new<A extends Record<string, any> = {}>(
 } as any
 
 /**
- * Base class for immutable data types with a `_tag` discriminator.
+ * Provides a 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}.
+ * Use 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**
  *
@@ -170,13 +174,12 @@ export const TaggedClass = <Tag extends string>(
  *
  * **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}.
+ * Use 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.
+ * key. Use with {@link taggedEnum} to get constructors and matchers.
  *
  * **Gotchas**
  *
@@ -203,7 +206,7 @@ export const TaggedClass = <Tag extends string>(
  * // "BadRequest"
  * ```
  *
- * @see {@link taggedEnum} — runtime constructors for a `TaggedEnum`
+ * @see {@link taggedEnum} — constructors and matchers for a `TaggedEnum`
  * @see {@link TaggedEnum.WithGenerics} — generic tagged enums
  * @see {@link TaggedEnum.Constructor} — the constructor object type
  *
@@ -230,6 +233,11 @@ type UntaggedChildren<A> = true extends ChildrenAreTagged<A>
 /**
  * Namespace for `TaggedEnum` utility types.
  *
+ * **When to use**
+ *
+ * Use to reference utility types for constructing, extracting, and matching
+ * `TaggedEnum` variants.
+ *
  * **Details**
  *
  * Provides helper types for:
@@ -246,7 +254,7 @@ export declare namespace TaggedEnum {
    *
    * **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.
+   * Use 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 and matchers.
    *
    * **Details**
    *
@@ -275,7 +283,7 @@ export declare namespace TaggedEnum {
    * ```
    *
    * @see {@link Kind} — apply concrete types to a `WithGenerics` definition
-   * @see {@link taggedEnum} — runtime constructors
+   * @see {@link taggedEnum} — constructors and matchers
    *
    * @category models
    * @since 2.0.0
@@ -296,7 +304,7 @@ export declare namespace TaggedEnum {
    *
    * **When to use**
    *
-   * Use `Kind` to refer to a specific instantiation of a generic tagged enum in type signatures.
+   * Use to refer to a specific instantiation of a generic tagged enum in type signatures.
    *
    * **Example** (Applying generics)
    *
@@ -338,6 +346,11 @@ export declare namespace TaggedEnum {
    * Extracts the constructor argument type for a specific variant of a tagged
    * union.
    *
+   * **When to use**
+   *
+   * Use to derive the argument object expected by a constructor for one tagged
+   * union variant.
+   *
    * **Details**
    *
    * Returns `void` if the variant has no fields beyond `_tag`.
@@ -375,6 +388,10 @@ export declare namespace TaggedEnum {
   /**
    * Extracts the full variant type (including `_tag`) for a specific tag.
    *
+   * **When to use**
+   *
+   * Use to select one full tagged-union variant by its `_tag` value.
+   *
    * **Example** (extracting a variant type)
    *
    * ```ts
@@ -399,13 +416,19 @@ export declare namespace TaggedEnum {
   > = Extract<A, { readonly _tag: K }>
 
   /**
-   * The full constructor-object type returned by {@link taggedEnum}.
+   * The full constructors-and-matchers object type returned by {@link taggedEnum}.
+   *
+   * **When to use**
+   *
+   * Use to type the constructors-and-matchers object returned by `taggedEnum`.
    *
    * **Details**
    *
    * Includes:
    * - A constructor function for each variant (keyed by tag name)
-   * - `$is(tag)` — returns a type-guard for the given variant
+   * - `$is(tag)` — returns a type-guard that checks only the `_tag` field;
+   *   safe when the tag is globally unique and the value was produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    * - `$match` — exhaustive pattern matching (data-last or data-first)
    *
    * **Example** (Using the constructor object)
@@ -433,7 +456,7 @@ export declare namespace TaggedEnum {
    * })
    * ```
    *
-   * @see {@link taggedEnum} — creates a `Constructor`
+   * @see {@link taggedEnum} — creates constructors and matchers
    *
    * @category types
    * @since 3.1.0
@@ -476,6 +499,10 @@ export declare namespace TaggedEnum {
    * Function type that constructs a tagged-union variant from its fields,
    * excluding the keys listed in `Tag`.
    *
+   * **When to use**
+   *
+   * Use to type an individual constructor for one tagged-union variant.
+   *
    * **Details**
    *
    * The constructor returns the full variant type `A`. If no fields remain
@@ -491,6 +518,10 @@ export declare namespace TaggedEnum {
   /**
    * Type-guard and pattern-matching interface for generic tagged enums.
    *
+   * **When to use**
+   *
+   * Use to type the `$is` and `$match` helpers for generic tagged enums.
+   *
    * **Details**
    *
    * This is the `$is` / `$match` portion of the object returned by
@@ -551,23 +582,25 @@ export declare namespace TaggedEnum {
 }
 
 /**
- * Creates runtime constructors, type guards, and pattern matching for a
- * {@link TaggedEnum} type.
+ * Creates constructors and matchers for a `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.
+ * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+ * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
  * - `$match` — exhaustive pattern matching (data-first or data-last)
  *
  * **Gotchas**
  *
- * Constructors produce **plain objects**, not class instances.
+ * - Constructors produce **plain objects**, not class instances.
+ * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+ *   on the tag being globally unique and the value being produced by your
+ *   constructors. For untrusted input, validate with the `Schema` module first.
  *
  * **Example** (Basic usage)
  *
@@ -621,23 +654,25 @@ export declare namespace TaggedEnum {
  */
 export const taggedEnum: {
   /**
-   * Creates runtime constructors, type guards, and pattern matching for a
-   * {@link TaggedEnum} type.
+   * Creates constructors and matchers for a `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.
+   * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
    * **Gotchas**
    *
-   * Constructors produce **plain objects**, not class instances.
+   * - Constructors produce **plain objects**, not class instances.
+   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+   *   on the tag being globally unique and the value being produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    *
    * **Example** (Basic usage)
    *
@@ -702,23 +737,25 @@ export const taggedEnum: {
   >
 
   /**
-   * Creates runtime constructors, type guards, and pattern matching for a
-   * {@link TaggedEnum} type.
+   * Creates constructors and matchers for a `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.
+   * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
    * **Gotchas**
    *
-   * Constructors produce **plain objects**, not class instances.
+   * - Constructors produce **plain objects**, not class instances.
+   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+   *   on the tag being globally unique and the value being produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    *
    * **Example** (Basic usage)
    *
@@ -783,23 +820,25 @@ export const taggedEnum: {
   >
 
   /**
-   * Creates runtime constructors, type guards, and pattern matching for a
-   * {@link TaggedEnum} type.
+   * Creates constructors and matchers for a `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.
+   * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
    * **Gotchas**
    *
-   * Constructors produce **plain objects**, not class instances.
+   * - Constructors produce **plain objects**, not class instances.
+   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+   *   on the tag being globally unique and the value being produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    *
    * **Example** (Basic usage)
    *
@@ -864,23 +903,25 @@ export const taggedEnum: {
   >
 
   /**
-   * Creates runtime constructors, type guards, and pattern matching for a
-   * {@link TaggedEnum} type.
+   * Creates constructors and matchers for a `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.
+   * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
    * **Gotchas**
    *
-   * Constructors produce **plain objects**, not class instances.
+   * - Constructors produce **plain objects**, not class instances.
+   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+   *   on the tag being globally unique and the value being produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    *
    * **Example** (Basic usage)
    *
@@ -945,23 +986,25 @@ export const taggedEnum: {
   >
 
   /**
-   * Creates runtime constructors, type guards, and pattern matching for a
-   * {@link TaggedEnum} type.
+   * Creates constructors and matchers for a `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.
+   * Use when you have a `TaggedEnum` type and need constructors and matchers for its 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
+   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
    * - `$match` — exhaustive pattern matching (data-first or data-last)
    *
    * **Gotchas**
    *
-   * Constructors produce **plain objects**, not class instances.
+   * - Constructors produce **plain objects**, not class instances.
+   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
+   *   on the tag being globally unique and the value being produced by your
+   *   constructors. For untrusted input, validate with the `Schema` module first.
    *
    * **Example** (Basic usage)
    *
@@ -1059,11 +1102,12 @@ function taggedMatch<
 }
 
 /**
- * Base class for yieldable errors.
+ * Provides a 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}.
+ * Use when defining yieldable errors that do **not** need tag-based
+ * discrimination. If you need tag-based recovery, use {@link TaggedError}.
  *
  * **Details**
  *
@@ -1105,7 +1149,8 @@ export const Error: new<A extends Record<string, any> = {}>(
  *
  * **When to use**
  *
- * Use `TaggedError` for domain errors in Effect applications where you want discriminated-union error handling.
+ * Use when modeling domain errors in Effect applications where you want
+ * discriminated-union error handling.
  *
  * **Details**
  *