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

package/src/Types.ts

@@ -298,7 +298,7 @@ export type Simplify<A> = {
  *
  * **When to use**
  *
- * Use in conditional types or type-level tests to assert type equality.
+ * Use to assert type equality in conditional types or type-level tests.
  *
  * **Details**
  *
@@ -354,7 +354,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
 export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? Y : N
 
 /**
- * Checks if an object type contains any of the specified keys.
+ * Checks whether an object type contains any of the specified keys.
  *
  * **When to use**
  *
@@ -382,8 +382,8 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
   : true
 
 /**
- * Merges two object types where keys from `Source` take precedence over
- * `Target` on conflict.
+ * Left-biased merge of two object types where keys from `Source` take
+ * precedence over `Target` on conflict.
  *
  * **When to use**
  *
@@ -415,8 +415,8 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
 export type MergeLeft<Source, Target> = MergeRight<Target, Source>
 
 /**
- * Merges two object types where keys from `Source` take precedence over
- * `Target` on conflict.
+ * Right-biased merge of two object types where keys from `Source` take
+ * precedence over `Target` on conflict.
  *
  * **When to use**
  *
@@ -457,7 +457,7 @@ export type MergeRight<Target, Source> = Simplify<
  *
  * **When to use**
  *
- * Prefer {@link MergeLeft} or {@link MergeRight} for clarity about which
+ * Use when prefer {@link MergeLeft} or {@link MergeRight} for clarity about which
  * side wins.
  *
  * **Example** (Merging records)
@@ -484,6 +484,10 @@ export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
  * Describes the concurrency level for Effect operations that run multiple
  * effects.
  *
+ * **When to use**
+ *
+ * Use to type options that control how many effects may run at the same time.
+ *
  * **Details**
  *
  * - `number` — run at most N effects concurrently.
@@ -587,8 +591,8 @@ export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepM
  *
  * **When to use**
  *
- * Use on a function parameter when you want inference to come from other
- * parameters, not this one.
+ * Use when a function parameter must match an inferred type without becoming
+ * an inference source.
  *
  * **Details**
  *
@@ -647,12 +651,20 @@ export type Invariant<A> = (_: A) => A
 /**
  * Namespace for {@link Invariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Invariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Invariant {
   /**
    * Extracts the type parameter `A` from an `Invariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from an invariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -707,12 +719,20 @@ export type Covariant<A> = (_: never) => A
 /**
  * Namespace for {@link Covariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Covariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Covariant {
   /**
    * Extracts the type parameter `A` from a `Covariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from a covariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -767,12 +787,20 @@ export type Contravariant<A> = (_: A) => void
 /**
  * Namespace for {@link Contravariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Contravariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Contravariant {
   /**
    * Extracts the type parameter `A` from a `Contravariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from a contravariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -794,6 +822,10 @@ export declare namespace Contravariant {
  * Conditional type that returns `void` if `S` is an empty object type,
  * otherwise returns `S`.
  *
+ * **When to use**
+ *
+ * Use to erase an empty object type from an API result or parameter position.
+ *
  * @category types
  * @since 3.19.20
  */
@@ -829,8 +861,7 @@ export type NotFunction<T> = T extends Function ? never : T
  *
  * **When to use**
  *
- * Use in generic functions to catch accidental extra properties at compile
- * time.
+ * Use to catch accidental extra properties in generic functions at compile time.
  *
  * **Details**
  *
@@ -856,6 +887,11 @@ export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyo
 /**
  * Branded marker interface representing an unassigned type parameter.
  *
+ * **When to use**
+ *
+ * Use when Effect's type-level machinery needs to represent a type parameter
+ * that has not been assigned yet.
+ *
  * **Details**
  *
  * Used internally by the Effect type system to indicate that a type parameter
@@ -873,6 +909,11 @@ export interface unassigned {
 /**
  * Branded marker interface representing an unhandled error type.
  *
+ * **When to use**
+ *
+ * Use when Effect's type-level machinery needs to represent an error type that
+ * has not been handled yet.
+ *
  * **Details**
  *
  * Used internally by the Effect type system to indicate that an error type
@@ -890,6 +931,10 @@ export interface unhandled {
 /**
  * Checks whether a type `T` is a union type.
  *
+ * **When to use**
+ *
+ * Use to branch type-level logic depending on whether a type is a union.
+ *
  * **Details**
  *
  * - Compares `[T]` against `[UnionToIntersection<T>]`. If they differ, `T`
@@ -950,6 +995,11 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
 /**
  * Extracts the `_tag` values from the `reason` type of an error.
  *
+ * **When to use**
+ *
+ * Use to get the discriminant values available inside a nested `reason`
+ * error union.
+ *
  * **Details**
  *
  * This is shorthand for `Tags<ReasonOf<E>>`. It returns `never` if `E` has no
@@ -983,7 +1033,7 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  *
  * **When to use**
  *
- * Use to narrow down to a single reason variant from a nested error type.
+ * Use to extract only the matching reason variant from a nested error type.
  *
  * **Details**
  *
@@ -1020,7 +1070,8 @@ export type ExtractReason<E, K extends string> = E extends { readonly reason: in
  *
  * **When to use**
  *
- * Use to narrow down to a single reason variant from a nested error type.
+ * Use to preserve the original error shape while narrowing its nested reason
+ * field to the matching variant.
  *
  * **Details**
  *
@@ -1129,6 +1180,10 @@ export type ExcludeReason<E, K extends string> = E extends { readonly reason: in
 /**
  * Extracts the required keys from a type.
  *
+ * **When to use**
+ *
+ * Use to derive the keys whose properties must be present on an object type.
+ *
  * @category types
  * @since 4.0.0
  */

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**
  *