effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Types.ts

@@ -231,8 +231,8 @@ export type ExtractTag<E, K extends string> = E extends { readonly _tag: infer T
  *
  * @see {@link IsUnion}
  *
- * @since 2.0.0
  * @category types
+ * @since 2.0.0
  */
 export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R
   : never
@@ -257,8 +257,8 @@ export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) ext
  * @see {@link MergeLeft}
  * @see {@link MergeRight}
  *
- * @since 2.0.0
  * @category types
+ * @since 2.0.0
  */
 export type Simplify<A> = {
   [K in keyof A]: A[K]
@@ -286,8 +286,8 @@ export type Simplify<A> = {
  *
  * @see {@link EqualsWith}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
   T
@@ -311,8 +311,8 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
  *
  * @see {@link Equals}
  *
- * @since 3.15.0
  * @category models
+ * @since 3.15.0
  */
 export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? Y : N
 
@@ -332,8 +332,8 @@ export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>
  * type No = Types.Has<{ a: number }, "b" | "c"> // false
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof A ? true : never : never) extends never
   ? false
@@ -362,8 +362,8 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
  * @see {@link MergeRecord}
  * @see {@link Simplify}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type MergeLeft<Source, Target> = MergeRight<Target, Source>
 
@@ -389,8 +389,8 @@ export type MergeLeft<Source, Target> = MergeRight<Target, Source>
  * @see {@link MergeLeft}
  * @see {@link Simplify}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type MergeRight<Target, Source> = Simplify<
   & Source
@@ -421,8 +421,8 @@ export type MergeRight<Target, Source> = Simplify<
  * @see {@link MergeLeft}
  * @see {@link MergeRight}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
 
@@ -445,8 +445,8 @@ export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
  * const inherit: Types.Concurrency = "inherit"
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Concurrency = number | "unbounded" | "inherit"
 
@@ -478,8 +478,8 @@ export type Concurrency = number | "unbounded" | "inherit"
  *
  * @see {@link DeepMutable}
  *
- * @since 2.0.0
  * @category types
+ * @since 2.0.0
  */
 export type Mutable<T> = {
   -readonly [P in keyof T]: T[P]
@@ -507,8 +507,8 @@ export type Mutable<T> = {
  *
  * @see {@link Mutable}
  *
- * @since 3.1.0
  * @category types
+ * @since 3.1.0
  */
 export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>>
   : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>>
@@ -534,8 +534,8 @@ export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepM
  * const result = withDefault<"a" | "b">("a", "b")
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type NoInfer<A> = [A][A extends any ? 0 : never]
 
@@ -563,16 +563,16 @@ export type NoInfer<A> = [A][A extends any ? 0 : never]
  * @see {@link Covariant}
  * @see {@link Contravariant}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Invariant<A> = (_: A) => A
 
 /**
  * Namespace for {@link Invariant}-related utilities.
  *
- * @since 3.9.0
  * @category models
+ * @since 3.9.0
  */
 export declare namespace Invariant {
   /**
@@ -589,8 +589,8 @@ export declare namespace Invariant {
    *
    * @see {@link Invariant}
    *
-   * @since 3.9.0
    * @category models
+   * @since 3.9.0
    */
   export type Type<A> = A extends Invariant<infer U> ? U : never
 }
@@ -619,16 +619,16 @@ export declare namespace Invariant {
  * @see {@link Contravariant}
  * @see {@link Invariant}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Covariant<A> = (_: never) => A
 
 /**
  * Namespace for {@link Covariant}-related utilities.
  *
- * @since 3.9.0
  * @category models
+ * @since 3.9.0
  */
 export declare namespace Covariant {
   /**
@@ -645,8 +645,8 @@ export declare namespace Covariant {
    *
    * @see {@link Covariant}
    *
-   * @since 3.9.0
    * @category models
+   * @since 3.9.0
    */
   export type Type<A> = A extends Covariant<infer U> ? U : never
 }
@@ -675,16 +675,16 @@ export declare namespace Covariant {
  * @see {@link Covariant}
  * @see {@link Invariant}
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Contravariant<A> = (_: A) => void
 
 /**
  * Namespace for {@link Contravariant}-related utilities.
  *
- * @since 3.9.0
  * @category models
+ * @since 3.9.0
  */
 export declare namespace Contravariant {
   /**
@@ -701,8 +701,8 @@ export declare namespace Contravariant {
    *
    * @see {@link Contravariant}
    *
-   * @since 3.9.0
    * @category models
+   * @since 3.9.0
    */
   export type Type<A> = A extends Contravariant<infer U> ? U : never
 }
@@ -711,8 +711,8 @@ export declare namespace Contravariant {
  * Conditional type that returns `void` if `S` is an empty object type,
  * otherwise returns `S`.
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type VoidIfEmpty<S> = keyof S extends never ? void : S
 
@@ -731,8 +731,8 @@ export type VoidIfEmpty<S> = keyof S extends never ? void : S
  * // string | number
  * ```
  *
- * @since 2.0.0
  * @category types
+ * @since 2.0.0
  */
 export type NotFunction<T> = T extends Function ? never : T
 
@@ -755,8 +755,8 @@ export type NotFunction<T> = T extends Function ? never : T
  * // { a: number; b: string; readonly c: never }
  * ```
  *
- * @since 3.9.0
  * @category types
+ * @since 3.9.0
  */
 export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyof T>, never>>
 
@@ -768,8 +768,8 @@ export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyo
  *
  * @see {@link unhandled}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export interface unassigned {
   readonly _: unique symbol
@@ -783,8 +783,8 @@ export interface unassigned {
  *
  * @see {@link unassigned}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export interface unhandled {
   readonly _: unique symbol
@@ -811,8 +811,8 @@ export interface unhandled {
  *
  * @see {@link UnionToIntersection}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
 
@@ -840,8 +840,8 @@ export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
  * @see {@link ExtractReason}
  * @see {@link ExcludeReason}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
 
@@ -867,8 +867,8 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
  * @see {@link ReasonOf}
  * @see {@link ExtractReason}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string } } ? E["reason"]["_tag"]
   : never
@@ -897,8 +897,8 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type ExtractReason<E, K extends string> = E extends { readonly reason: infer R }
   ? R extends { readonly _tag: infer T } ? K extends T ? R : never
@@ -929,8 +929,8 @@ export type ExtractReason<E, K extends string> = E extends { readonly reason: in
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type NarrowReason<E, K extends string> = E extends { readonly reason: infer R }
   ? R extends { readonly _tag: infer T } ? K extends T ? E & { readonly reason: R } : never
@@ -963,8 +963,8 @@ export type NarrowReason<E, K extends string> = E extends { readonly reason: inf
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type OmitReason<E, K extends string> = E extends { readonly reason: infer R }
   ? R extends { readonly _tag: infer T } ? K extends T ? never : E & { readonly reason: R }
@@ -995,8 +995,8 @@ export type OmitReason<E, K extends string> = E extends { readonly reason: infer
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type ExcludeReason<E, K extends string> = E extends { readonly reason: infer R }
   ? Exclude<R, { readonly _tag: K }>
@@ -1005,7 +1005,7 @@ export type ExcludeReason<E, K extends string> = E extends { readonly reason: in
 /**
  * Extracts the required keys from a type.
  *
- * @since 4.0.0
  * @category types
+ * @since 4.0.0
  */
 export type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T]

package/src/UndefinedOr.ts

@@ -33,24 +33,40 @@ import { dual } from "./Function.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
+ * Maps a defined value with `f`, or returns `undefined` unchanged.
+ *
  * @since 4.0.0
  */
 export const map: {
   /**
+   * Maps a defined value with `f`, or returns `undefined` unchanged.
+   *
    * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: A | undefined) => B | undefined
   /**
+   * Maps a defined value with `f`, or returns `undefined` unchanged.
+   *
    * @since 4.0.0
    */
   <A, B>(self: A | undefined, f: (a: A) => B): B | undefined
 } = dual(2, (self, f) => (self === undefined ? undefined : f(self)))
 
 /**
+ * Pattern matches on an `A | undefined` value.
+ *
+ * Runs `onDefined` with the value when it is present, or evaluates
+ * `onUndefined` when the value is `undefined`.
+ *
  * @since 4.0.0
  */
 export const match: {
   /**
+   * Pattern matches on an `A | undefined` value.
+   *
+   * Runs `onDefined` with the value when it is present, or evaluates
+   * `onUndefined` when the value is `undefined`.
+   *
    * @since 4.0.0
    */
   <B, A, C = B>(
@@ -60,6 +76,11 @@ export const match: {
     }
   ): (self: A | undefined) => B | C
   /**
+   * Pattern matches on an `A | undefined` value.
+   *
+   * Runs `onDefined` with the value when it is present, or evaluates
+   * `onUndefined` when the value is `undefined`.
+   *
    * @since 4.0.0
    */
   <A, B, C = B>(
@@ -78,14 +99,23 @@ export const match: {
 )
 
 /**
+ * Returns the defined value, or throws the value produced by `onUndefined`
+ * when the input is `undefined`.
+ *
  * @since 4.0.0
  */
 export const getOrThrowWith: {
   /**
+   * Returns the defined value, or throws the value produced by `onUndefined`
+   * when the input is `undefined`.
+   *
    * @since 4.0.0
    */
   (onUndefined: () => unknown): <A>(self: A | undefined) => A
   /**
+   * Returns the defined value, or throws the value produced by `onUndefined`
+   * when the input is `undefined`.
+   *
    * @since 4.0.0
    */
   <A>(self: A | undefined, onUndefined: () => unknown): A
@@ -97,6 +127,9 @@ export const getOrThrowWith: {
 })
 
 /**
+ * Returns the defined value, or throws a default `Error` when the input is
+ * `undefined`.
+ *
  * @since 4.0.0
  */
 export const getOrThrow: <A>(self: A | undefined) => A = getOrThrowWith(() =>
@@ -104,6 +137,12 @@ export const getOrThrow: <A>(self: A | undefined) => A = getOrThrowWith(() =>
 )
 
 /**
+ * Converts a throwing function into one that returns `undefined` when it
+ * throws.
+ *
+ * The returned function passes through successful results and discards thrown
+ * errors by representing them as `undefined`.
+ *
  * @since 4.0.0
  */
 export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
@@ -145,20 +184,11 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
 }
 
 /**
- * Creates a `Combiner` for `UndefinedOr<A>` that only combines values when both
- * operands are not `undefined`, failing fast if either is `undefined`.
+ * Creates a `Combiner` for `A | undefined` that combines values only when both
+ * operands are defined.
  *
- * This `Combiner` is useful for scenarios where you need both values to be
- * present to perform an operation, such as:
- * - Mathematical operations that require two operands
- * - Data validation that needs both fields
- * - Operations that can't proceed with partial data
- *
- * **Behavior:**
- * - `undefined` + `undefined` = `undefined`
- * - `a` + `undefined` = `undefined` (fails fast)
- * - `undefined` + `b` = `undefined` (fails fast)
- * - `a` + `b` = `a + b` (values combined)
+ * If either operand is `undefined`, the combined result is `undefined`. When
+ * both operands are defined, the wrapped combiner combines the two values.
  *
  * @see {@link makeReducerFailFast} if you have a `Reducer` and want to lift it
  * to `UndefinedOr` values.
@@ -173,19 +203,12 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
 }
 
 /**
- * Creates a `Reducer` for `UndefinedOr<A>` by wrapping an existing `Reducer` with
- * fail-fast semantics for `UndefinedOr` values.
+ * Creates a `Reducer` for `A | undefined` by wrapping an existing reducer with
+ * fail-fast semantics.
  *
- * This function lifts a regular `Reducer` into the `UndefinedOr` context, allowing
- * you to use existing `Reducer`s with `UndefinedOr` values while maintaining the
- * fail-fast behavior where any `undefined` value causes the entire reduction to fail.
- *
- * The initial value is `some(reducer.initialValue)`, ensuring the `Reducer`
- * starts with a valid `UndefinedOr` value.
- *
- * **Behavior:**
- * - Fails fast (returns `undefined`) if any operand is `undefined`
- * - Uses the underlying reducer's combine logic when both values are present
+ * The initial value is the wrapped reducer's `initialValue`. Combining two
+ * defined values delegates to the wrapped reducer; if the accumulator or next
+ * value is `undefined`, the reduction returns `undefined`.
  *
  * @see {@link makeCombinerFailFast} if you only have a `Combiner` and want to
  * lift it to `UndefinedOr` values.