effect 3.8.4 → 3.8.5

package/src/Either.ts

@@ -139,7 +139,33 @@ export const left: <L>(left: L) => Either<never, L> = either.left
  * @since 2.0.0
  */
 export const fromNullable: {
+  /**
+   * Takes a lazy default and a nullable value, if the value is not nully (`null` or `undefined`), turn it into a `Right`, if the value is nully use
+   * the provided default as a `Left`.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(Either.fromNullable(1, () => 'fallback'), Either.right(1))
+   * assert.deepStrictEqual(Either.fromNullable(null, () => 'fallback'), Either.left('fallback'))
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <R, L>(onNullable: (right: R) => L): (self: R) => Either<NonNullable<R>, L>
+  /**
+   * Takes a lazy default and a nullable value, if the value is not nully (`null` or `undefined`), turn it into a `Right`, if the value is nully use
+   * the provided default as a `Left`.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(Either.fromNullable(1, () => 'fallback'), Either.right(1))
+   * assert.deepStrictEqual(Either.fromNullable(null, () => 'fallback'), Either.left('fallback'))
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <R, L>(self: R, onNullable: (right: R) => L): Either<NonNullable<R>, L>
 } = dual(
   2,
@@ -158,7 +184,27 @@ export const fromNullable: {
  * @since 2.0.0
  */
 export const fromOption: {
+  /**
+   * @example
+   * import { Either, Option } from "effect"
+   *
+   * assert.deepStrictEqual(Either.fromOption(Option.some(1), () => 'error'), Either.right(1))
+   * assert.deepStrictEqual(Either.fromOption(Option.none(), () => 'error'), Either.left('error'))
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <L>(onNone: () => L): <R>(self: Option<R>) => Either<R, L>
+  /**
+   * @example
+   * import { Either, Option } from "effect"
+   *
+   * assert.deepStrictEqual(Either.fromOption(Option.some(1), () => 'error'), Either.right(1))
+   * assert.deepStrictEqual(Either.fromOption(Option.none(), () => 'error'), Either.left('error'))
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <R, L>(self: Option<R>, onNone: () => L): Either<R, L>
 } = either.fromOption
 
@@ -300,14 +346,27 @@ export const getEquivalence = <R, L>({ left, right }: {
  * @since 2.0.0
  */
 export const mapBoth: {
-  <L, L2, R, R2>(options: {
-    readonly onLeft: (left: L) => L2
-    readonly onRight: (right: R) => R2
-  }): (self: Either<R, L>) => Either<R2, L2>
-  <L, R, L2, R2>(self: Either<R, L>, options: {
-    readonly onLeft: (left: L) => L2
-    readonly onRight: (right: R) => R2
-  }): Either<R2, L2>
+  /**
+   * @category mapping
+   * @since 2.0.0
+   */
+  <L, L2, R, R2>(
+    options: {
+      readonly onLeft: (left: L) => L2
+      readonly onRight: (right: R) => R2
+    }
+  ): (self: Either<R, L>) => Either<R2, L2>
+  /**
+   * @category mapping
+   * @since 2.0.0
+   */
+  <L, R, L2, R2>(
+    self: Either<R, L>,
+    options: {
+      readonly onLeft: (left: L) => L2
+      readonly onRight: (right: R) => R2
+    }
+  ): Either<R2, L2>
 } = dual(
   2,
   <L, R, L2, R2>(self: Either<R, L>, { onLeft, onRight }: {
@@ -326,7 +385,25 @@ export const mapBoth: {
  * @since 2.0.0
  */
 export const mapLeft: {
+  /**
+   * Maps the `Left` side of an `Either` value to a new `Either` value.
+   *
+   * @param self - The input `Either` value to map.
+   * @param f - A transformation function to apply to the `Left` value of the input `Either`.
+   *
+   * @category mapping
+   * @since 2.0.0
+   */
   <L, L2>(f: (left: L) => L2): <R>(self: Either<R, L>) => Either<R, L2>
+  /**
+   * Maps the `Left` side of an `Either` value to a new `Either` value.
+   *
+   * @param self - The input `Either` value to map.
+   * @param f - A transformation function to apply to the `Left` value of the input `Either`.
+   *
+   * @category mapping
+   * @since 2.0.0
+   */
   <R, L, L2>(self: Either<R, L>, f: (left: L) => L2): Either<R, L2>
 } = dual(
   2,
@@ -344,7 +421,25 @@ export const mapLeft: {
  * @since 2.0.0
  */
 export const map: {
+  /**
+   * Maps the `Right` side of an `Either` value to a new `Either` value.
+   *
+   * @param self - An `Either` to map
+   * @param f - The function to map over the value of the `Either`
+   *
+   * @category mapping
+   * @since 2.0.0
+   */
   <R, R2>(f: (right: R) => R2): <L>(self: Either<R, L>) => Either<R2, L>
+  /**
+   * Maps the `Right` side of an `Either` value to a new `Either` value.
+   *
+   * @param self - An `Either` to map
+   * @param f - The function to map over the value of the `Either`
+   *
+   * @category mapping
+   * @since 2.0.0
+   */
   <R, L, R2>(self: Either<R, L>, f: (right: R) => R2): Either<R2, L>
 } = dual(
   2,
@@ -373,14 +468,59 @@ export const map: {
  * @since 2.0.0
  */
 export const match: {
-  <L, B, R, C = B>(options: {
-    readonly onLeft: (left: L) => B
-    readonly onRight: (right: R) => C
-  }): (self: Either<R, L>) => B | C
-  <R, L, B, C = B>(self: Either<R, L>, options: {
-    readonly onLeft: (left: L) => B
-    readonly onRight: (right: R) => C
-  }): B | C
+  /**
+   * Takes two functions and an `Either` value, if the value is a `Left` the inner value is applied to the `onLeft function,
+   * if the value is a `Right` the inner value is applied to the `onRight` function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const onLeft  = (strings: ReadonlyArray<string>): string => `strings: ${strings.join(', ')}`
+   *
+   * const onRight = (value: number): string => `Ok: ${value}`
+   *
+   * assert.deepStrictEqual(pipe(Either.right(1), Either.match({ onLeft, onRight })), 'Ok: 1')
+   * assert.deepStrictEqual(
+   *   pipe(Either.left(['string 1', 'string 2']), Either.match({ onLeft, onRight })),
+   *   'strings: string 1, string 2'
+   * )
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <L, B, R, C = B>(
+    options: {
+      readonly onLeft: (left: L) => B
+      readonly onRight: (right: R) => C
+    }
+  ): (self: Either<R, L>) => B | C
+  /**
+   * Takes two functions and an `Either` value, if the value is a `Left` the inner value is applied to the `onLeft function,
+   * if the value is a `Right` the inner value is applied to the `onRight` function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const onLeft  = (strings: ReadonlyArray<string>): string => `strings: ${strings.join(', ')}`
+   *
+   * const onRight = (value: number): string => `Ok: ${value}`
+   *
+   * assert.deepStrictEqual(pipe(Either.right(1), Either.match({ onLeft, onRight })), 'Ok: 1')
+   * assert.deepStrictEqual(
+   *   pipe(Either.left(['string 1', 'string 2']), Either.match({ onLeft, onRight })),
+   *   'strings: string 1, string 2'
+   * )
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <R, L, B, C = B>(
+    self: Either<R, L>,
+    options: {
+      readonly onLeft: (left: L) => B
+      readonly onRight: (right: R) => C
+    }
+  ): B | C
 } = dual(
   2,
   <R, L, B, C = B>(self: Either<R, L>, { onLeft, onRight }: {
@@ -419,16 +559,125 @@ export const match: {
  * @since 3.4.0
  */
 export const liftPredicate: {
+  /**
+   * Transforms a `Predicate` function into a `Right` of the input value if the predicate returns `true`
+   * or `Left` of the result of the provided function if the predicate returns false
+   *
+   * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     1,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     0,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @category lifting
+   * @since 3.4.0
+   */
   <A, B extends A, E>(refinement: Refinement<NoInfer<A>, B>, orLeftWith: (a: NoInfer<A>) => E): (a: A) => Either<B, E>
-  <A, E>(
-    predicate: Predicate<NoInfer<A>>,
-    orLeftWith: (a: NoInfer<A>) => E
-  ): (a: A) => Either<A, E>
-  <A, E, B extends A>(
-    self: A,
-    refinement: Refinement<A, B>,
-    orLeftWith: (a: A) => E
-  ): Either<B, E>
+  /**
+   * Transforms a `Predicate` function into a `Right` of the input value if the predicate returns `true`
+   * or `Left` of the result of the provided function if the predicate returns false
+   *
+   * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     1,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     0,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @category lifting
+   * @since 3.4.0
+   */
+  <A, E>(predicate: Predicate<NoInfer<A>>, orLeftWith: (a: NoInfer<A>) => E): (a: A) => Either<A, E>
+  /**
+   * Transforms a `Predicate` function into a `Right` of the input value if the predicate returns `true`
+   * or `Left` of the result of the provided function if the predicate returns false
+   *
+   * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     1,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     0,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @category lifting
+   * @since 3.4.0
+   */
+  <A, E, B extends A>(self: A, refinement: Refinement<A, B>, orLeftWith: (a: A) => E): Either<B, E>
+  /**
+   * Transforms a `Predicate` function into a `Right` of the input value if the predicate returns `true`
+   * or `Left` of the result of the provided function if the predicate returns false
+   *
+   * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     1,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     0,
+   *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @category lifting
+   * @since 3.4.0
+   */
   <A, E>(
     self: A,
     predicate: Predicate<NoInfer<A>>,
@@ -468,19 +717,127 @@ export const liftPredicate: {
  * @category filtering & conditionals
  */
 export const filterOrLeft: {
+  /**
+   * Filter the right value with the provided function.
+   * If the predicate fails, set the left value with the result of the provided function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(1),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(0),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering & conditionals
+   */
   <R, B extends R, L2>(
     refinement: Refinement<NoInfer<R>, B>,
     orLeftWith: (right: NoInfer<R>) => L2
   ): <L>(self: Either<R, L>) => Either<B, L2 | L>
+  /**
+   * Filter the right value with the provided function.
+   * If the predicate fails, set the left value with the result of the provided function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(1),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(0),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering & conditionals
+   */
   <R, L2>(
     predicate: Predicate<NoInfer<R>>,
     orLeftWith: (right: NoInfer<R>) => L2
   ): <L>(self: Either<R, L>) => Either<R, L2 | L>
+  /**
+   * Filter the right value with the provided function.
+   * If the predicate fails, set the left value with the result of the provided function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(1),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(0),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering & conditionals
+   */
   <R, L, B extends R, L2>(
     self: Either<R, L>,
     refinement: Refinement<R, B>,
     orLeftWith: (right: R) => L2
   ): Either<B, L | L2>
+  /**
+   * Filter the right value with the provided function.
+   * If the predicate fails, set the left value with the result of the provided function.
+   *
+   * @example
+   * import { pipe, Either } from "effect"
+   *
+   * const isPositive = (n: number): boolean => n > 0
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(1),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.right(1)
+   * )
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     Either.right(0),
+   *     Either.filterOrLeft(isPositive, n => `${n} is not positive`)
+   *   ),
+   *   Either.left("0 is not positive")
+   * )
+   *
+   * @since 2.0.0
+   * @category filtering & conditionals
+   */
   <R, L, E2>(self: Either<R, L>, predicate: Predicate<R>, orLeftWith: (right: R) => E2): Either<R, L | E2>
 } = dual(3, <R, L, E2>(
   self: Either<R, L>,
@@ -510,7 +867,31 @@ export const merge: <R, L>(self: Either<R, L>) => L | R = match({
  * @since 2.0.0
  */
 export const getOrElse: {
+  /**
+   * Returns the wrapped value if it's a `Right` or a default value if is a `Left`.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(Either.getOrElse(Either.right(1), (error) => error + "!"), 1)
+   * assert.deepStrictEqual(Either.getOrElse(Either.left("not a number"), (error) => error + "!"), "not a number!")
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <L, R2>(onLeft: (left: L) => R2): <R>(self: Either<R, L>) => R2 | R
+  /**
+   * Returns the wrapped value if it's a `Right` or a default value if is a `Left`.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(Either.getOrElse(Either.right(1), (error) => error + "!"), 1)
+   * assert.deepStrictEqual(Either.getOrElse(Either.left("not a number"), (error) => error + "!"), "not a number!")
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <R, L, R2>(self: Either<R, L>, onLeft: (left: L) => R2): R | R2
 } = dual(
   2,
@@ -562,7 +943,47 @@ export const getOrUndefined: <R, L>(self: Either<R, L>) => R | undefined = getOr
  * @since 2.0.0
  */
 export const getOrThrowWith: {
+  /**
+   * Extracts the value of an `Either` or throws if the `Either` is `Left`.
+   *
+   * If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+   *
+   * @param self - The `Either` to extract the value from.
+   * @param onLeft - A function that will be called if the `Either` is `Left`. It returns the error to be thrown.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(
+   *   Either.getOrThrowWith(Either.right(1), () => new Error('Unexpected Left')),
+   *   1
+   * )
+   * assert.throws(() => Either.getOrThrowWith(Either.left("error"), () => new Error('Unexpected Left')))
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <L>(onLeft: (left: L) => unknown): <A>(self: Either<A, L>) => A
+  /**
+   * Extracts the value of an `Either` or throws if the `Either` is `Left`.
+   *
+   * If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+   *
+   * @param self - The `Either` to extract the value from.
+   * @param onLeft - A function that will be called if the `Either` is `Left`. It returns the error to be thrown.
+   *
+   * @example
+   * import { Either } from "effect"
+   *
+   * assert.deepStrictEqual(
+   *   Either.getOrThrowWith(Either.right(1), () => new Error('Unexpected Left')),
+   *   1
+   * )
+   * assert.throws(() => Either.getOrThrowWith(Either.left("error"), () => new Error('Unexpected Left')))
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <R, L>(self: Either<R, L>, onLeft: (left: L) => unknown): R
 } = dual(2, <R, L>(self: Either<R, L>, onLeft: (left: L) => unknown): R => {
   if (isRight(self)) {
@@ -602,7 +1023,25 @@ export const getOrThrow: <R, L>(self: Either<R, L>) => R = getOrThrowWith(() =>
  * @since 2.0.0
  */
 export const orElse: {
+  /**
+   * Returns `self` if it is a `Right` or `that` otherwise.
+   *
+   * @param self - The input `Either` value to check and potentially return.
+   * @param that - A function that takes the error value from `self` (if it's a `Left`) and returns a new `Either` value.
+   *
+   * @category error handling
+   * @since 2.0.0
+   */
   <L, R2, L2>(that: (left: L) => Either<R2, L2>): <R>(self: Either<R, L>) => Either<R | R2, L2>
+  /**
+   * Returns `self` if it is a `Right` or `that` otherwise.
+   *
+   * @param self - The input `Either` value to check and potentially return.
+   * @param that - A function that takes the error value from `self` (if it's a `Left`) and returns a new `Either` value.
+   *
+   * @category error handling
+   * @since 2.0.0
+   */
   <R, L, R2, L2>(self: Either<R, L>, that: (left: L) => Either<R2, L2>): Either<R | R2, L2>
 } = dual(
   2,
@@ -615,7 +1054,15 @@ export const orElse: {
  * @since 2.0.0
  */
 export const flatMap: {
+  /**
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, R2, L2>(f: (right: R) => Either<R2, L2>): <L>(self: Either<R, L>) => Either<R2, L | L2>
+  /**
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, L, R2, L2>(self: Either<R, L>, f: (right: R) => Either<R2, L2>): Either<R2, L | L2>
 } = dual(
   2,
@@ -630,13 +1077,61 @@ export const flatMap: {
  * @since 2.0.0
  */
 export const andThen: {
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, R2, L2>(f: (right: R) => Either<R2, L2>): <L>(self: Either<R, L>) => Either<R2, L | L2>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R2, L2>(f: Either<R2, L2>): <L, R1>(self: Either<R1, L>) => Either<R2, L | L2>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, R2>(f: (right: R) => R2): <L>(self: Either<R, L>) => Either<R2, L>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R2>(right: NotFunction<R2>): <R1, L>(self: Either<R1, L>) => Either<R2, L>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, L, R2, L2>(self: Either<R, L>, f: (right: R) => Either<R2, L2>): Either<R2, L | L2>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, L, R2, L2>(self: Either<R, L>, f: Either<R2, L2>): Either<R2, L | L2>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, L, R2>(self: Either<R, L>, f: (right: R) => R2): Either<R2, L>
+  /**
+   * Executes a sequence of two `Either`s. The second `Either` can be dependent on the result of the first `Either`.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <R, L, R2>(self: Either<R, L>, f: NotFunction<R2>): Either<R2, L>
 } = dual(
   2,
@@ -652,15 +1147,16 @@ export const andThen: {
  * @since 2.0.0
  */
 export const zipWith: {
-  <R2, L2, R, B>(
-    that: Either<R2, L2>,
-    f: (right: R, right2: R2) => B
-  ): <L>(self: Either<R, L>) => Either<B, L2 | L>
-  <R, L, R2, L2, B>(
-    self: Either<R, L>,
-    that: Either<R2, L2>,
-    f: (right: R, right2: R2) => B
-  ): Either<B, L | L2>
+  /**
+   * @category zipping
+   * @since 2.0.0
+   */
+  <R2, L2, R, B>(that: Either<R2, L2>, f: (right: R, right2: R2) => B): <L>(self: Either<R, L>) => Either<B, L2 | L>
+  /**
+   * @category zipping
+   * @since 2.0.0
+   */
+  <R, L, R2, L2, B>(self: Either<R, L>, that: Either<R2, L2>, f: (right: R, right2: R2) => B): Either<B, L | L2>
 } = dual(
   3,
   <R, L, R2, L2, B>(self: Either<R, L>, that: Either<R2, L2>, f: (right: R, right2: R2) => B): Either<B, L | L2> =>
@@ -672,7 +1168,15 @@ export const zipWith: {
  * @since 2.0.0
  */
 export const ap: {
+  /**
+   * @category combining
+   * @since 2.0.0
+   */
   <R, L2>(that: Either<R, L2>): <R2, L>(self: Either<(right: R) => R2, L>) => Either<R2, L | L2>
+  /**
+   * @category combining
+   * @since 2.0.0
+   */
   <R, R2, L, L2>(self: Either<(right: R) => R2, L>, that: Either<R, L2>): Either<R2, L | L2>
 } = dual(
   2,
@@ -849,10 +1353,66 @@ export const Do: Either<{}> = right({})
  * @since 2.0.0
  */
 export const bind: {
+  /**
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Either` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   *
+   * @see {@link Do}
+   * @see {@link bindTo}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Either, pipe } from "effect"
+   *
+   * const result = pipe(
+   *   Either.Do,
+   *   Either.bind("x", () => Either.right(2)),
+   *   Either.bind("y", () => Either.right(3)),
+   *   Either.let("sum", ({ x, y }) => x + y)
+   * )
+   * assert.deepStrictEqual(result, Either.right({ x: 2, y: 3, sum: 5 }))
+   *
+   * @category do notation
+   * @since 2.0.0
+   */
   <N extends string, A extends object, B, L2>(
     name: Exclude<N, keyof A>,
     f: (a: A) => Either<B, L2>
   ): <L1>(self: Either<A, L1>) => Either<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, L1 | L2>
+  /**
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Either` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   *
+   * @see {@link Do}
+   * @see {@link bindTo}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Either, pipe } from "effect"
+   *
+   * const result = pipe(
+   *   Either.Do,
+   *   Either.bind("x", () => Either.right(2)),
+   *   Either.bind("y", () => Either.right(3)),
+   *   Either.let("sum", ({ x, y }) => x + y)
+   * )
+   * assert.deepStrictEqual(result, Either.right({ x: 2, y: 3, sum: 5 }))
+   *
+   * @category do notation
+   * @since 2.0.0
+   */
   <A extends object, L1, N extends string, B, L2>(
     self: Either<A, L1>,
     name: Exclude<N, keyof A>,
@@ -889,7 +1449,63 @@ export const bind: {
  * @since 2.0.0
  */
 export const bindTo: {
+  /**
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Either` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Either, pipe } from "effect"
+   *
+   * const result = pipe(
+   *   Either.Do,
+   *   Either.bind("x", () => Either.right(2)),
+   *   Either.bind("y", () => Either.right(3)),
+   *   Either.let("sum", ({ x, y }) => x + y)
+   * )
+   * assert.deepStrictEqual(result, Either.right({ x: 2, y: 3, sum: 5 }))
+   *
+   * @category do notation
+   * @since 2.0.0
+   */
   <N extends string>(name: N): <R, L>(self: Either<R, L>) => Either<{ [K in N]: R }, L>
+  /**
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Either` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Either, pipe } from "effect"
+   *
+   * const result = pipe(
+   *   Either.Do,
+   *   Either.bind("x", () => Either.right(2)),
+   *   Either.bind("y", () => Either.right(3)),
+   *   Either.let("sum", ({ x, y }) => x + y)
+   * )
+   * assert.deepStrictEqual(result, Either.right({ x: 2, y: 3, sum: 5 }))
+   *
+   * @category do notation
+   * @since 2.0.0
+   */
   <R, L, N extends string>(self: Either<R, L>, name: N): Either<{ [K in N]: R }, L>
 } = doNotation.bindTo<EitherTypeLambda>(map)