effect 3.8.4 → 3.9.0

package/dist/dts/Either.d.ts

@@ -125,7 +125,33 @@ export declare const left: <L>(left: L) => Either<never, L>;
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -139,7 +165,27 @@ export declare const fromNullable: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 declare const try_: {
@@ -245,10 +291,18 @@ export declare const getEquivalence: <R, L>({ left, right }: {
  * @since 2.0.0
  */
 export declare const mapBoth: {
+    /**
+     * @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;
@@ -264,7 +318,25 @@ export declare const mapBoth: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -277,7 +349,25 @@ export declare const mapLeft: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -301,10 +391,50 @@ export declare const map: {
  * @since 2.0.0
  */
 export declare const match: {
+    /**
+     * 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;
@@ -340,9 +470,125 @@ export declare const match: {
  * @since 3.4.0
  */
 export declare 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>;
+    /**
+     * 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>>, orLeftWith: (a: NoInfer<A>) => E): Either<A, E>;
 };
 /**
@@ -373,9 +619,117 @@ export declare const liftPredicate: {
  * @category filtering & conditionals
  */
 export declare 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>;
 };
 /**
@@ -396,7 +750,31 @@ export declare const merge: <R, L>(self: Either<R, L>) => L | R;
  * @since 2.0.0
  */
 export declare 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;
 };
 /**
@@ -442,7 +820,47 @@ export declare const getOrUndefined: <R, L>(self: Either<R, L>) => R | undefined
  * @since 2.0.0
  */
 export declare 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;
 };
 /**
@@ -473,7 +891,25 @@ export declare const getOrThrow: <R, L>(self: Either<R, L>) => R;
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -481,7 +917,15 @@ export declare const orElse: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -491,13 +935,61 @@ export declare const flatMap: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -505,7 +997,15 @@ export declare const andThen: {
  * @since 2.0.0
  */
 export declare const zipWith: {
+    /**
+     * @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>;
 };
 /**
@@ -513,7 +1013,15 @@ export declare const zipWith: {
  * @since 2.0.0
  */
 export declare 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>;
 };
 /**
@@ -611,9 +1119,65 @@ export declare const Do: Either<{}>;
  * @since 2.0.0
  */
 export declare 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>, f: (a: A) => Either<B, L2>): Either<{
         [K in N | keyof A]: K extends keyof A ? A[K] : B;
     }, L1 | L2>;
@@ -647,9 +1211,65 @@ export declare const bind: {
  * @since 2.0.0
  */
 export declare 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>;