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

package/src/UndefinedOr.ts

@@ -1,29 +1,59 @@
 /**
- * This module provides small, allocation-free utilities for working with values of type
- * `A | undefined`, where `undefined` means "no value".
- *
- * Why not `Option<A>`?
- * In TypeScript, `Option<A>` is often unnecessary. If `undefined` already models absence
- * in your domain, using `A | undefined` keeps types simple, avoids extra wrappers, and
- * reduces overhead. The key is that `A` itself must not include `undefined`; in this
- * module `undefined` is reserved to mean "no value".
- *
- * When to use `A | undefined`:
- * - Absence can be represented by `undefined` in your domain model.
- * - You do not need to distinguish between "no value" and "value is undefined".
- * - You want straightforward ergonomics and zero extra allocations.
- *
- * When to prefer `Option<A>`:
- * - You must distinguish `None` from `Some(undefined)` (that is, `undefined` is a valid
- *   payload and carries meaning on its own).
- * - You need a tagged representation for serialization or pattern matching across
- *   boundaries where `undefined` would be ambiguous.
- * - You want the richer `Option` API and are comfortable with the extra wrapper.
- *
- * Lawfulness note:
- * All helpers treat `undefined` as absence. Do not use these utilities with payloads
- * where `A` can itself be `undefined`, or you will lose information. If you need to
- * carry `undefined` as a valid payload, use `Option<A>` instead.
+ * The `UndefinedOr` module works with plain TypeScript values of type
+ * `A | undefined` where `undefined` is the only absence marker. It is a small
+ * alternative to wrapping values in `Option` when your domain already uses
+ * `undefined` to mean "no value".
+ *
+ * **Mental model**
+ *
+ * - A defined value is the present branch.
+ * - `undefined` is reserved for absence; the payload type `A` should not itself
+ *   include `undefined`.
+ * - Helpers such as {@link map} and {@link match} keep values unwrapped and use
+ *   `undefined` directly instead of allocating tagged values.
+ * - The fail-fast combiner and reducer helpers propagate `undefined` when a
+ *   required value is missing.
+ *
+ * **Common tasks**
+ *
+ * - Transform a present value: {@link map}
+ * - Branch on present versus absent: {@link match}
+ * - Unwrap at a boundary: {@link getOrThrow}, {@link getOrThrowWith}
+ * - Adapt throwing code to an optional result: {@link liftThrowable}
+ * - Lift combination and reduction logic: {@link makeReducer},
+ *   {@link makeCombinerFailFast}, {@link makeReducerFailFast}
+ *
+ * **Gotchas**
+ *
+ * - `A | undefined` cannot distinguish "missing" from "present and
+ *   undefined". Use `Option` when that distinction matters.
+ * - {@link liftThrowable} discards the thrown value and also returns
+ *   `undefined` when the wrapped function throws.
+ *
+ * **Example** (Parsing optional input)
+ *
+ * ```ts
+ * import { UndefinedOr } from "effect"
+ *
+ * const parseInteger = UndefinedOr.liftThrowable((input: string) => {
+ *   const value = Number.parseInt(input, 10)
+ *   if (Number.isNaN(value)) {
+ *     throw new Error("not an integer")
+ *   }
+ *   return value
+ * })
+ *
+ * console.log(UndefinedOr.map(parseInteger("42"), (n) => n + 1))
+ * // 43
+ *
+ * console.log(
+ *   UndefinedOr.match(parseInteger("abc"), {
+ *     onUndefined: () => "missing",
+ *     onDefined: (n) => `parsed ${n}`
+ *   })
+ * )
+ * // "missing"
+ * ```
  *
  * @since 4.0.0
  */
@@ -35,6 +65,13 @@ import * as Reducer from "./Reducer.ts"
 /**
  * Maps a defined value with `f`, or returns `undefined` unchanged.
  *
+ * **When to use**
+ *
+ * Use to apply a pure transformation to an `A | undefined` value while
+ * preserving `undefined` as absence.
+ *
+ * @see {@link match} when you need to handle the `undefined` case explicitly
+ *
  * @category mapping
  * @since 4.0.0
  */
@@ -42,6 +79,13 @@ export const map: {
   /**
    * Maps a defined value with `f`, or returns `undefined` unchanged.
    *
+   * **When to use**
+   *
+   * Use to apply a pure transformation to an `A | undefined` value while
+   * preserving `undefined` as absence.
+   *
+   * @see {@link match} when you need to handle the `undefined` case explicitly
+   *
    * @category mapping
    * @since 4.0.0
    */
@@ -49,6 +93,13 @@ export const map: {
   /**
    * Maps a defined value with `f`, or returns `undefined` unchanged.
    *
+   * **When to use**
+   *
+   * Use to apply a pure transformation to an `A | undefined` value while
+   * preserving `undefined` as absence.
+   *
+   * @see {@link match} when you need to handle the `undefined` case explicitly
+   *
    * @category mapping
    * @since 4.0.0
    */
@@ -59,6 +110,14 @@ export const map: {
  * Pattern matches on an `A | undefined` value, running `onDefined` when the
  * value is present or evaluating `onUndefined` when the value is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when you need to turn an `A | undefined` into a non-optional result by
+ * handling both the defined and undefined branches in one expression.
+ *
+ * @see {@link map} for transforming defined values while preserving `undefined`
+ * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+ *
  * @category pattern matching
  * @since 4.0.0
  */
@@ -67,6 +126,14 @@ export const match: {
    * Pattern matches on an `A | undefined` value, running `onDefined` when the
    * value is present or evaluating `onUndefined` when the value is `undefined`.
    *
+   * **When to use**
+   *
+   * Use when you need to turn an `A | undefined` into a non-optional result by
+   * handling both the defined and undefined branches in one expression.
+   *
+   * @see {@link map} for transforming defined values while preserving `undefined`
+   * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+   *
    * @category pattern matching
    * @since 4.0.0
    */
@@ -80,6 +147,14 @@ export const match: {
    * Pattern matches on an `A | undefined` value, running `onDefined` when the
    * value is present or evaluating `onUndefined` when the value is `undefined`.
    *
+   * **When to use**
+   *
+   * Use when you need to turn an `A | undefined` into a non-optional result by
+   * handling both the defined and undefined branches in one expression.
+   *
+   * @see {@link map} for transforming defined values while preserving `undefined`
+   * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+   *
    * @category pattern matching
    * @since 4.0.0
    */
@@ -102,6 +177,19 @@ export const match: {
  * Returns the defined value, or throws the value produced by `onUndefined`
  * when the input is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+ * callers need to provide the thrown error for the undefined case.
+ *
+ * **Details**
+ *
+ * Defined values are returned unchanged. When the input is `undefined`,
+ * `onUndefined` is called and its result is thrown.
+ *
+ * @see {@link getOrThrow} for the default-error sibling
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -110,6 +198,19 @@ export const getOrThrowWith: {
    * Returns the defined value, or throws the value produced by `onUndefined`
    * when the input is `undefined`.
    *
+   * **When to use**
+   *
+   * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+   * callers need to provide the thrown error for the undefined case.
+   *
+   * **Details**
+   *
+   * Defined values are returned unchanged. When the input is `undefined`,
+   * `onUndefined` is called and its result is thrown.
+   *
+   * @see {@link getOrThrow} for the default-error sibling
+   * @see {@link match} for handling defined and undefined cases without throwing
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -118,6 +219,19 @@ export const getOrThrowWith: {
    * Returns the defined value, or throws the value produced by `onUndefined`
    * when the input is `undefined`.
    *
+   * **When to use**
+   *
+   * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+   * callers need to provide the thrown error for the undefined case.
+   *
+   * **Details**
+   *
+   * Defined values are returned unchanged. When the input is `undefined`,
+   * `onUndefined` is called and its result is thrown.
+   *
+   * @see {@link getOrThrow} for the default-error sibling
+   * @see {@link match} for handling defined and undefined cases without throwing
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -133,6 +247,19 @@ export const getOrThrowWith: {
  * Returns the defined value, or throws a default `Error` when the input is
  * `undefined`.
  *
+ * **When to use**
+ *
+ * Use when a value should already be defined at this point and throwing a
+ * generic missing-value `Error` is acceptable.
+ *
+ * **Details**
+ *
+ * Defined inputs are returned unchanged. `undefined` throws
+ * `new Error("getOrThrow called on a undefined")`.
+ *
+ * @see {@link getOrThrowWith} for the sibling that lets callers choose the thrown value
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -144,6 +271,16 @@ export const getOrThrow: <A>(self: A | undefined) => A = getOrThrowWith(() =>
  * Converts a throwing function into one that returns successful results
  * unchanged and returns `undefined` when the function throws.
  *
+ * **When to use**
+ *
+ * Use to adapt exception-throwing functions when `undefined` is the absence
+ * value you want to return for failures.
+ *
+ * **Gotchas**
+ *
+ * Thrown values are discarded. If the wrapped function can successfully return
+ * `undefined`, that success is indistinguishable from a thrown failure.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -164,9 +301,8 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  *
  * **When to use**
  *
- * - Take the first available value (like a fallback chain)
- * - Combine values when both are present
- * - Maintain a `undefined` state only when all values are `undefined`
+ * Use to take the first available value like a fallback chain, combining values
+ * only when both operands are present.
  *
  * **Details**
  *
@@ -191,6 +327,11 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
  * Creates a `Combiner` for `A | undefined` that combines values only when both
  * operands are defined.
  *
+ * **When to use**
+ *
+ * Use to lift a `Combiner` so any `undefined` operand makes the combined result
+ * `undefined`.
+ *
  * **Details**
  *
  * - `undefined` combined with any value returns `undefined`
@@ -216,8 +357,8 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
  *
  * **When to use**
  *
- * - Wrapping an existing `Reducer` to work with `A | undefined` values
- * - Reductions where any `undefined` value should abort the entire result
+ * Use to wrap an existing `Reducer` so any `undefined` value aborts the entire
+ * reduction result.
  *
  * **Details**
  *

package/src/Unify.ts

@@ -1,16 +1,33 @@
 /**
- * The `Unify` module contains the type-level protocol Effect uses to normalize
- * unions of data types that opt in to unification. It is primarily a library
- * authoring tool: data types expose hidden symbol properties describing how
- * their variants should be widened, and {@link Unify} turns those protocol
- * entries into the user-facing union type that TypeScript should infer.
- *
- * Most application code does not need to interact with these symbols directly.
- * The main runtime helper, {@link unify}, is an identity function that preserves
- * values and functions at runtime while applying {@link Unify} to the relevant
- * static type. This is useful when authoring APIs that return branded or
- * protocol-enabled values and need inference to collapse to the public Effect
- * data type rather than exposing implementation details.
+ * The `Unify` module defines the type-level protocol Effect uses to collapse
+ * unions of protocol-enabled values into their public data types. It is mostly
+ * for maintainers of Effect data types and advanced library authors; ordinary
+ * application code usually benefits from unification through APIs such as
+ * `Effect`, `Option`, `Result`, `Stream`, `Layer`, and `Match`.
+ *
+ * **Mental model**
+ *
+ * A type opts in by carrying phantom entries keyed by {@link typeSymbol} and
+ * {@link unifySymbol}. {@link Unify} reads those entries, ignores any protocol
+ * members listed through {@link ignoreSymbol}, and widens matching union
+ * members to the public type each entry returns. The runtime helper
+ * {@link unify} is an identity function; it changes only the static type that
+ * TypeScript sees.
+ *
+ * **Common tasks**
+ *
+ * - Add unification support to a new Effect data type so mixed unions infer as
+ *   the public container type instead of an implementation shape.
+ * - Normalize the return type of branching APIs, matchers, or builders that can
+ *   produce several protocol-enabled values.
+ * - Apply unification to a value or curried function result with {@link unify}
+ *   while preserving the original runtime behavior.
+ *
+ * **Gotchas**
+ *
+ * - Unification is a compile-time protocol, not a runtime conversion hook.
+ * - Protocol entries should be specific to the data type they widen; overly
+ *   broad entries can make inferred unions less precise.
  *
  * @since 2.0.0
  */
@@ -20,11 +37,19 @@ import { identity } from "./Function.ts"
 /**
  * A unique symbol used to identify unification behavior in Effect types.
  *
+ * **When to use**
+ *
+ * Use to implement the unification protocol on library data types that should
+ * widen to a public union type.
+ *
  * **Details**
  *
  * This symbol is used internally by the Effect type system to enable automatic
  * unification of Effect types in unions and complex type operations.
  *
+ * @see {@link typeSymbol} for storing the source type information used during unification
+ * @see {@link ignoreSymbol} for excluding protocol entries from unification
+ *
  * @category symbols
  * @since 2.0.0
  */
@@ -33,6 +58,11 @@ export declare const unifySymbol: unique symbol
 /**
  * The type of the unifySymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the `unifySymbol` property key in type-level protocol
+ * definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for identifying unification
@@ -47,11 +77,18 @@ export type unifySymbol = typeof unifySymbol
 /**
  * A unique symbol used to identify the type information for unification.
  *
+ * **When to use**
+ *
+ * Use to implement the unification protocol on types that need to expose their
+ * original type information.
+ *
  * **Details**
  *
  * This symbol is used internally by the Effect type system to store type
  * information that can be used during type unification operations.
  *
+ * @see {@link unifySymbol} for defining how protocol entries widen
+ *
  * @category symbols
  * @since 2.0.0
  */
@@ -60,6 +97,11 @@ export declare const typeSymbol: unique symbol
 /**
  * The type of the typeSymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the `typeSymbol` property key in type-level protocol
+ * definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for storing type information
@@ -74,12 +116,18 @@ export type typeSymbol = typeof typeSymbol
 /**
  * A unique symbol used to specify types that should be ignored during unification.
  *
+ * **When to use**
+ *
+ * Use to exclude specific protocol properties from type unification.
+ *
  * **Details**
  *
  * This symbol is used internally by the Effect type system to mark types
  * that should be excluded from the unification process, allowing for more
  * precise type handling in complex scenarios.
  *
+ * @see {@link unifySymbol} for defining the protocol entries being filtered
+ *
  * @category symbols
  * @since 2.0.0
  */
@@ -88,6 +136,11 @@ export declare const ignoreSymbol: unique symbol
 /**
  * The type of the ignoreSymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the `ignoreSymbol` property key in type-level protocol
+ * definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for marking types that should
@@ -133,6 +186,10 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
 /**
  * Unifies types that implement the unification protocol.
  *
+ * **When to use**
+ *
+ * Use to normalize unions of types that expose Effect's unification protocol.
+ *
  * **Details**
  *
  * This type performs automatic type unification for types that contain
@@ -163,6 +220,8 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
  * // Results in a properly unified type
  * ```
  *
+ * @see {@link unify} for applying this normalization to a value or function
+ *
  * @category models
  * @since 2.0.0
  */
@@ -192,6 +251,11 @@ export type Unify<A> = Values<
 /**
  * Applies `Unify` to a value or function return type at compile time.
  *
+ * **When to use**
+ *
+ * Use to keep a value or function unchanged at runtime while normalizing its
+ * inferred type with Effect's unification protocol.
+ *
  * **Details**
  *
  * This is an identity function at runtime. For functions, the returned function
@@ -223,6 +287,8 @@ export type Unify<A> = Values<
  * // Type: (a: string) => (b: number) => Unify<{ result: string }>
  * ```
  *
+ * @see {@link Unify} for the type-level normalization applied by this helper
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -230,6 +296,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -261,6 +332,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -277,6 +350,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -308,6 +386,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -323,6 +403,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -354,6 +439,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -366,6 +453,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -397,6 +489,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -408,6 +502,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -439,6 +538,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -449,6 +550,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -480,6 +586,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */

package/src/Utils.ts

@@ -65,10 +65,9 @@ import type * as Types from "./Types.ts"
  *
  * **When to use**
  *
- * Implement `[Symbol.iterator]()` on Effect-like types so they can be
+ * Use to implement `[Symbol.iterator]()` on Effect-like types so they can be
  * `yield*`-ed inside generator functions, such as `Effect.gen` and
- * `Option.gen`. You almost never construct this directly — it is created
- * internally by yieldable types.
+ * `Option.gen`.
  *
  * **Details**
  *
@@ -94,7 +93,7 @@ import type * as Types from "./Types.ts"
  * // { value: 42, done: true }
  * ```
  *
- * @see {@link Gen} — the type-level signature that relies on `SingleShotGen`
+ * @see {@link Gen} for the type-level signature that relies on `SingleShotGen`
  * @category constructors
  * @since 2.0.0
  */
@@ -109,6 +108,11 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   /**
    * Yields the stored value once, then completes with the value sent back in.
    *
+   * **When to use**
+   *
+   * Use to advance a `SingleShotGen` through its single yield and completion
+   * step.
+   *
    * @since 2.0.0
    */
   next(a: A): IteratorResult<T, A> {
@@ -127,6 +131,11 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   /**
    * Creates a fresh single-shot iterator over the stored value.
    *
+   * **When to use**
+   *
+   * Use to iterate the wrapped value again without reusing the consumed
+   * iterator state.
+   *
    * @since 2.0.0
    */
   [Symbol.iterator](): IterableIterator<T, A> {
@@ -140,9 +149,8 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  *
  * **When to use**
  *
- * Define variance constraints for a higher-kinded type so that {@link Gen}
- * can correctly infer `R`, `O`, and `E` from yielded values. You typically
- * don't construct values of this type — it exists purely for type inference.
+ * Use to define variance constraints for a higher-kinded type so that
+ * {@link Gen} can correctly infer `R`, `O`, and `E` from yielded values.
  *
  * **Details**
  *
@@ -164,7 +172,7 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  * >
  * ```
  *
- * @see {@link Gen} — uses `Variance` for type parameter inference
+ * @see {@link Gen} for the type-level signature that uses `Variance`
  * @category models
  * @since 2.0.0
  */
@@ -181,10 +189,8 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  *
  * **When to use**
  *
- * Type the `gen` function of a module that supports generator syntax, such as
- * `Option.gen`, `Result.gen`, and `Effect.gen`. It accepts either `(body)` or
- * `(self, body)` where `body` is a generator function. The `self` overload
- * binds `this` inside the generator.
+ * Use to type the `gen` function of a module that supports generator syntax,
+ * such as `Option.gen`, `Result.gen`, and `Effect.gen`.
  *
  * **Details**
  *
@@ -200,8 +206,8 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  * declare const gen: Utils.Gen<Option.OptionTypeLambda>
  * ```
  *
- * @see {@link Variance} — encodes the variance used for inference
- * @see {@link SingleShotGen} — the iterator protocol that makes yielding work
+ * @see {@link Variance} for encoding the variance used for inference
+ * @see {@link SingleShotGen} for the iterator protocol that makes yielding work
  * @category models
  * @since 2.0.0
  */