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

package/src/Cron.ts

@@ -66,6 +66,11 @@ const TypeId = "~effect/time/Cron"
 /**
  * Represents a cron schedule with time constraints and timezone information.
  *
+ * **When to use**
+ *
+ * Use to represent a recurring calendar schedule that can be matched against
+ * dates or used to compute scheduled occurrences.
+ *
  * **Details**
  *
  * A `Cron` instance defines when a scheduled task should run, supporting
@@ -123,6 +128,11 @@ const TypeId = "~effect/time/Cron"
  * console.log(matches) // true if it's 9 AM on a weekday
  * ```
  *
+ * @see {@link make} for creating a schedule from explicit field constraints
+ * @see {@link parse} for creating a schedule from a cron expression string
+ * @see {@link match} for testing a date against a schedule
+ * @see {@link next} for finding the next scheduled occurrence
+ *
  * @category models
  * @since 2.0.0
  */
@@ -231,6 +241,10 @@ const CronProto = {
 /**
  * Checks if a given value is a Cron instance.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `Cron` schedule.
+ *
  * **Details**
  *
  * This function is a type guard that determines whether the provided
@@ -255,6 +269,9 @@ const CronProto = {
  * console.log(Cron.isCron("not a cron")) // false
  * ```
  *
+ * @see {@link make} for constructing a `Cron` value directly
+ * @see {@link parse} for constructing a `Cron` value from a string
+ *
  * @category guards
  * @since 2.0.0
  */
@@ -263,6 +280,10 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
 /**
  * Creates a Cron instance from time constraints.
  *
+ * **When to use**
+ *
+ * Use to build a cron schedule from explicit sets of allowed time-field values.
+ *
  * **Details**
  *
  * Constructs a cron schedule by specifying which seconds, minutes, hours,
@@ -357,6 +378,8 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
  * })
  * ```
  *
+ * @see {@link parse} for building a schedule from a cron expression string
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -462,6 +485,10 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError"
 /**
  * Represents an error that occurs when parsing a cron expression fails.
  *
+ * **When to use**
+ *
+ * Use to handle invalid cron expression failures returned by `parse`.
+ *
  * **Details**
  *
  * This error provides information about what went wrong during parsing,
@@ -480,6 +507,9 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError"
  * }
  * ```
  *
+ * @see {@link parse} for the parser that returns this error in `Result.fail`
+ * @see {@link isCronParseError} for narrowing unknown values to this error type
+ *
  * @category models
  * @since 4.0.0
  */
@@ -493,6 +523,10 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
 /**
  * Checks if a given value is a CronParseError instance.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown failure before handling it as a cron parse error.
+ *
  * **Details**
  *
  * This function is a type guard that determines whether the provided
@@ -514,6 +548,9 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
  * console.log(Cron.isCronParseError("not an error")) // false
  * ```
  *
+ * @see {@link CronParseError} for the parse error type
+ * @see {@link parse} for producing `CronParseError` values on invalid input
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -523,6 +560,11 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * Parses a cron expression into a `Cron` instance, returning a `Result` instead
  * of throwing.
  *
+ * **When to use**
+ *
+ * Use to parse cron expressions from configuration or user input while handling
+ * invalid input as a `Result`.
+ *
  * **Details**
  *
  * The expression may contain five fields, where seconds default to `0`, or six
@@ -550,6 +592,9 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * )
  * ```
  *
+ * @see {@link parseUnsafe} for throwing on invalid cron expressions
+ * @see {@link make} for constructing a schedule from explicit field constraints
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -587,7 +632,7 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  *
  * **When to use**
  *
- * Use this when the input is expected to be valid and you want to avoid
+ * Use when the input is expected to be valid and you want to avoid
  * handling the `Result` type.
  *
  * **Example** (Parsing cron expressions unsafely)
@@ -613,6 +658,10 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
 /**
  * Returns `true` when a date/time matches a `Cron` schedule.
  *
+ * **When to use**
+ *
+ * Use to test whether a specific date/time satisfies a cron schedule.
+ *
  * **Details**
  *
  * Seconds, minutes, hours, months, and the optional timezone are checked
@@ -638,6 +687,9 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
  * console.log(matches3) // false - wrong day
  * ```
  *
+ * @see {@link next} for finding the next matching date/time
+ * @see {@link prev} for finding the previous matching date/time
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -683,6 +735,11 @@ const daysInMonth = (date: Date): number =>
 /**
  * Returns the next scheduled date/time for the given Cron instance.
  *
+ * **When to use**
+ *
+ * Use to find the next occurrence of a cron schedule after a specific date/time
+ * or after the current time.
+ *
  * **Details**
  *
  * Searches for the next date and time when the cron schedule should trigger,
@@ -706,6 +763,9 @@ const daysInMonth = (date: Date): number =>
  * console.log(nextFromNow) // Next occurrence from now
  * ```
  *
+ * @see {@link prev} for finding the previous scheduled occurrence
+ * @see {@link sequence} for iterating future scheduled occurrences
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -716,6 +776,22 @@ export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
 /**
  * Returns the previous scheduled date/time for the given Cron instance.
  *
+ * **When to use**
+ *
+ * Use to find the most recent occurrence of a cron schedule before a specific
+ * date/time or before the current time.
+ *
+ * **Details**
+ *
+ * When no date/time is provided, the search starts from the current time.
+ *
+ * **Gotchas**
+ *
+ * The search is strict: if the supplied date/time already matches the schedule,
+ * the result is the earlier occurrence.
+ *
+ * @see {@link next} for finding the next scheduled occurrence
+ *
  * @category utils
  * @since 3.20.0
  */
@@ -880,6 +956,10 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
 /**
  * Returns an infinite iterator that yields dates matching the Cron schedule.
  *
+ * **When to use**
+ *
+ * Use to lazily iterate future occurrences of a cron schedule.
+ *
  * **Details**
  *
  * The iterator generates an infinite sequence of dates when the cron schedule
@@ -901,6 +981,8 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
  * // [Mon Jan 02 2023 09:00:00, Tue Jan 03 2023 09:00:00, ...]
  * ```
  *
+ * @see {@link next} for computing one next occurrence
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -914,6 +996,10 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  * An `Equivalence` instance for comparing the field restrictions of two `Cron`
  * schedules.
  *
+ * **When to use**
+ *
+ * Use to compare cron schedules through APIs that accept an `Equivalence`.
+ *
  * **Details**
  *
  * This comparison checks seconds, minutes, hours, days, months, and weekdays.
@@ -943,6 +1029,8 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  * console.log(Cron.Equivalence(cron1, cron2)) // true
  * ```
  *
+ * @see {@link equals} for directly comparing two `Cron` values
+ *
  * @category instances
  * @since 2.0.0
  */
@@ -962,6 +1050,11 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
 /**
  * Checks whether two `Cron` instances have the same field restrictions.
  *
+ * **When to use**
+ *
+ * Use to directly compare whether two cron schedules have the same field
+ * restrictions.
+ *
  * **Details**
  *
  * The comparison checks seconds, minutes, hours, days, months, and weekdays.
@@ -992,6 +1085,8 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
  * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
  * ```
  *
+ * @see {@link Equivalence} for the reusable equivalence instance
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -999,6 +1094,11 @@ export const equals: {
   /**
    * Checks whether two `Cron` instances have the same field restrictions.
    *
+   * **When to use**
+   *
+   * Use to directly compare whether two cron schedules have the same field
+   * restrictions.
+   *
    * **Details**
    *
    * The comparison checks seconds, minutes, hours, days, months, and weekdays.
@@ -1029,6 +1129,8 @@ export const equals: {
    * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
    * ```
    *
+   * @see {@link Equivalence} for the reusable equivalence instance
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1036,6 +1138,11 @@ export const equals: {
   /**
    * Checks whether two `Cron` instances have the same field restrictions.
    *
+   * **When to use**
+   *
+   * Use to directly compare whether two cron schedules have the same field
+   * restrictions.
+   *
    * **Details**
    *
    * The comparison checks seconds, minutes, hours, days, months, and weekdays.
@@ -1066,6 +1173,8 @@ export const equals: {
    * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
    * ```
    *
+   * @see {@link Equivalence} for the reusable equivalence instance
+   *
    * @category predicates
    * @since 2.0.0
    */

package/src/Crypto.ts

@@ -200,6 +200,18 @@ export interface Crypto {
 /**
  * The service identifier for the platform `Crypto` service.
  *
+ * **When to use**
+ *
+ * Use when you need to provide or retrieve the full platform Crypto service
+ * from an effect's context.
+ *
+ * **Details**
+ *
+ * Providing this service supplies the cryptographic operations described by the
+ * `Crypto` interface.
+ *
+ * @see {@link make} for constructing a Crypto service from primitive operations
+ *
  * @category services
  * @since 4.0.0
  */
@@ -209,6 +221,23 @@ export const Crypto: Context.Service<Crypto, Crypto> = Context.Service("effect/C
  * Creates a `Crypto` service from the primitive implementation, deriving the
  * random generator helpers and UUID generation from those primitives.
  *
+ * **When to use**
+ *
+ * Use to build a Crypto service for a platform integration, test layer, or
+ * custom runtime from primitive random-byte and digest operations.
+ *
+ * **Details**
+ *
+ * The constructor derives random numbers, booleans, integer ranges, shuffling,
+ * and UUID generation from `impl.randomBytes`. Digest operations delegate to
+ * `impl.digest`.
+ *
+ * **Gotchas**
+ *
+ * `impl.randomBytes` must return cryptographically secure bytes of the
+ * requested length. UUID formatting mutates the byte array returned for UUID
+ * generation, so the implementation should return a fresh array for each call.
+ *
  * **Example** (Creating a Crypto service)
  *
  * ```ts

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
  *
@@ -83,7 +87,7 @@ import type { Unify } from "./Unify.ts"
  *
  * **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**
  *
@@ -127,7 +131,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  *
  * **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,7 +174,7 @@ 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**
  *
@@ -230,6 +234,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 +255,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.
    *
    * **Details**
    *
@@ -296,7 +305,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 +347,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 +389,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
@@ -401,11 +419,18 @@ export declare namespace TaggedEnum {
   /**
    * The full constructor-object type returned by {@link taggedEnum}.
    *
+   * **When to use**
+   *
+   * Use to type the full constructor and matcher 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)
@@ -476,6 +501,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 +520,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
@@ -556,18 +589,21 @@ export declare namespace TaggedEnum {
  *
  * **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 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
+ * - `$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)
  *
@@ -626,18 +662,21 @@ export const taggedEnum: {
    *
    * **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 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
+   * - `$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)
    *
@@ -707,18 +746,21 @@ export const taggedEnum: {
    *
    * **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 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
+   * - `$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)
    *
@@ -788,18 +830,21 @@ export const taggedEnum: {
    *
    * **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 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
+   * - `$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)
    *
@@ -869,18 +914,21 @@ export const taggedEnum: {
    *
    * **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 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
+   * - `$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)
    *
@@ -950,18 +998,21 @@ export const taggedEnum: {
    *
    * **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 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
+   * - `$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)
    *
@@ -1063,7 +1114,7 @@ function taggedMatch<
  *
  * **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 you use `Error` for errors that do **not** need tag-based discrimination. If you need `Effect.catchTag` support, use {@link TaggedError}.
  *
  * **Details**
  *
@@ -1105,7 +1156,7 @@ 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 you use `TaggedError` for domain errors in Effect applications where you want discriminated-union error handling.
  *
  * **Details**
  *