effect 3.8.4 → 3.9.0

package/dist/dts/Option.d.ts

@@ -175,10 +175,58 @@ export declare const isSome: <A>(self: Option<A>) => self is Some<A>;
  * @since 2.0.0
  */
 export declare const match: {
+    /**
+     * Matches the given `Option` and returns either the provided `onNone` value or the result of the provided `onSome`
+     * function when passed the `Option`'s value.
+     *
+     * @param self - The `Option` to match
+     * @param onNone - The value to be returned if the `Option` is `None`
+     * @param onSome - The function to be called if the `Option` is `Some`, it will be passed the `Option`'s value and its result will be returned
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(Option.some(1), Option.match({ onNone: () => 'a none', onSome: (a) => `a some containing ${a}` })),
+     *   'a some containing 1'
+     * )
+     *
+     * assert.deepStrictEqual(
+     *   pipe(Option.none(), Option.match({ onNone: () => 'a none', onSome: (a) => `a some containing ${a}` })),
+     *   'a none'
+     * )
+     *
+     * @category pattern matching
+     * @since 2.0.0
+     */
     <B, A, C = B>(options: {
         readonly onNone: LazyArg<B>;
         readonly onSome: (a: A) => C;
     }): (self: Option<A>) => B | C;
+    /**
+     * Matches the given `Option` and returns either the provided `onNone` value or the result of the provided `onSome`
+     * function when passed the `Option`'s value.
+     *
+     * @param self - The `Option` to match
+     * @param onNone - The value to be returned if the `Option` is `None`
+     * @param onSome - The function to be called if the `Option` is `Some`, it will be passed the `Option`'s value and its result will be returned
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(Option.some(1), Option.match({ onNone: () => 'a none', onSome: (a) => `a some containing ${a}` })),
+     *   'a some containing 1'
+     * )
+     *
+     * assert.deepStrictEqual(
+     *   pipe(Option.none(), Option.match({ onNone: () => 'a none', onSome: (a) => `a some containing ${a}` })),
+     *   'a none'
+     * )
+     *
+     * @category pattern matching
+     * @since 2.0.0
+     */
     <A, B, C = B>(self: Option<A>, options: {
         readonly onNone: LazyArg<B>;
         readonly onSome: (a: A) => C;
@@ -261,7 +309,37 @@ export declare const getLeft: <R, L>(self: Either<R, L>) => Option<L>;
  * @since 2.0.0
  */
 export declare const getOrElse: {
+    /**
+     * Returns the value of the `Option` if it is `Some`, otherwise returns `onNone`
+     *
+     * @param self - The `Option` to get the value of.
+     * @param onNone - Function that returns the default value to return if the `Option` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.getOrElse(() => 0)), 1)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.getOrElse(() => 0)), 0)
+     *
+     * @category getters
+     * @since 2.0.0
+     */
     <B>(onNone: LazyArg<B>): <A>(self: Option<A>) => B | A;
+    /**
+     * Returns the value of the `Option` if it is `Some`, otherwise returns `onNone`
+     *
+     * @param self - The `Option` to get the value of.
+     * @param onNone - Function that returns the default value to return if the `Option` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.getOrElse(() => 0)), 1)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.getOrElse(() => 0)), 0)
+     *
+     * @category getters
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, onNone: LazyArg<B>): A | B;
 };
 /**
@@ -306,7 +384,89 @@ export declare const getOrElse: {
  * @since 2.0.0
  */
 export declare const orElse: {
+    /**
+     * Returns the provided `Option` `that` if `self` is `None`, otherwise returns `self`.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param that - The `Option` to return if `self` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElse(() => Option.none())
+     *   ),
+     *   Option.none()
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElse(() => Option.none())
+     *   ),
+     *   Option.some('a')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElse(() => Option.some('b'))
+     *   ),
+     *   Option.some('b')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElse(() => Option.some('b'))
+     *   ),
+     *   Option.some('a')
+     * )
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<B | A>;
+    /**
+     * Returns the provided `Option` `that` if `self` is `None`, otherwise returns `self`.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param that - The `Option` to return if `self` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElse(() => Option.none())
+     *   ),
+     *   Option.none()
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElse(() => Option.none())
+     *   ),
+     *   Option.some('a')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElse(() => Option.some('b'))
+     *   ),
+     *   Option.some('b')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElse(() => Option.some('b'))
+     *   ),
+     *   Option.some('a')
+     * )
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<A | B>;
 };
 /**
@@ -337,7 +497,61 @@ export declare const orElse: {
  * @since 2.0.0
  */
 export declare const orElseSome: {
+    /**
+     * Returns the provided default value as `Some` if `self` is `None`, otherwise returns `self`.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param onNone - Function that returns the default value to return if the `Option` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElseSome(() => 'b')
+     *   ),
+     *   Option.some('b')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElseSome(() => 'b')
+     *   ),
+     *   Option.some('a')
+     * )
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <B>(onNone: LazyArg<B>): <A>(self: Option<A>) => Option<B | A>;
+    /**
+     * Returns the provided default value as `Some` if `self` is `None`, otherwise returns `self`.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param onNone - Function that returns the default value to return if the `Option` is `None`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.none(),
+     *     Option.orElseSome(() => 'b')
+     *   ),
+     *   Option.some('b')
+     * )
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some('a'),
+     *     Option.orElseSome(() => 'b')
+     *   ),
+     *   Option.some('a')
+     * )
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, onNone: LazyArg<B>): Option<A | B>;
 };
 /**
@@ -353,7 +567,31 @@ export declare const orElseSome: {
  * @since 2.0.0
  */
 export declare const orElseEither: {
+    /**
+     * Similar to `orElse`, but instead of returning a simple union, it returns an `Either` object,
+     * which contains information about which of the two `Option`s has been chosen.
+     *
+     * This is useful when it's important to know whether the value was retrieved from the first `Option` or the second option.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param that - The second `Option` to be considered if the first `Option` is `None`.
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<Either<B, A>>;
+    /**
+     * Similar to `orElse`, but instead of returning a simple union, it returns an `Either` object,
+     * which contains information about which of the two `Option`s has been chosen.
+     *
+     * This is useful when it's important to know whether the value was retrieved from the first `Option` or the second option.
+     *
+     * @param self - The first `Option` to be checked.
+     * @param that - The second `Option` to be considered if the first `Option` is `None`.
+     *
+     * @category error handling
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, that: LazyArg<Option<B>>): Option<Either<B, A>>;
 };
 /**
@@ -478,7 +716,47 @@ export declare const liftThrowable: <A extends ReadonlyArray<unknown>, B>(f: (..
  * @since 2.0.0
  */
 export declare const getOrThrowWith: {
+    /**
+     * Extracts the value of an `Option` or throws if the `Option` is `None`.
+     *
+     * 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 `Option` to extract the value from.
+     * @param onNone - A function that will be called if the `Option` is `None`. It returns the error to be thrown.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   Option.getOrThrowWith(Option.some(1), () => new Error('Unexpected None')),
+     *   1
+     * )
+     * assert.throws(() => Option.getOrThrowWith(Option.none(), () => new Error('Unexpected None')))
+     *
+     * @category conversions
+     * @since 2.0.0
+     */
     (onNone: () => unknown): <A>(self: Option<A>) => A;
+    /**
+     * Extracts the value of an `Option` or throws if the `Option` is `None`.
+     *
+     * 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 `Option` to extract the value from.
+     * @param onNone - A function that will be called if the `Option` is `None`. It returns the error to be thrown.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * assert.deepStrictEqual(
+     *   Option.getOrThrowWith(Option.some(1), () => new Error('Unexpected None')),
+     *   1
+     * )
+     * assert.throws(() => Option.getOrThrowWith(Option.none(), () => new Error('Unexpected None')))
+     *
+     * @category conversions
+     * @since 2.0.0
+     */
     <A>(self: Option<A>, onNone: () => unknown): A;
 };
 /**
@@ -509,7 +787,25 @@ export declare const getOrThrow: <A>(self: Option<A>) => A;
  * @since 2.0.0
  */
 export declare const map: {
+    /**
+     * Maps the `Some` side of an `Option` value to a new `Option` value.
+     *
+     * @param self - An `Option` to map
+     * @param f - The function to map over the value of the `Option`
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => B): (self: Option<A>) => Option<B>;
+    /**
+     * Maps the `Some` side of an `Option` value to a new `Option` value.
+     *
+     * @param self - An `Option` to map
+     * @param f - The function to map over the value of the `Option`
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => B): Option<B>;
 };
 /**
@@ -519,6 +815,12 @@ export declare const map: {
  * @since 2.0.0
  */
 export declare const as: {
+    /**
+     * Maps the `Some` value of this `Option` to the specified constant value.
+     *
+     * @category mapping
+     * @since 2.0.0
+     */
     <B>(b: B): <X>(self: Option<X>) => Option<B>;
 };
 /**
@@ -543,7 +845,19 @@ void_ as void };
  * @since 2.0.0
  */
 export declare const flatMap: {
+    /**
+     * Applies a function to the value of an `Option` and flattens the result, if the input is `Some`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => Option<B>): (self: Option<A>) => Option<B>;
+    /**
+     * Applies a function to the value of an `Option` and flattens the result, if the input is `Some`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => Option<B>): Option<B>;
 };
 /**
@@ -553,13 +867,61 @@ export declare const flatMap: {
  * @since 2.0.0
  */
 export declare const andThen: {
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => Option<B>): (self: Option<A>) => Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <B>(f: Option<B>): <A>(self: Option<A>) => Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => B): (self: Option<A>) => Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <B>(f: NotFunction<B>): <A>(self: Option<A>) => Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => Option<B>): Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: Option<B>): Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => B): Option<B>;
+    /**
+     * Executes a sequence of two `Option`s. The second `Option` can be dependent on the result of the first `Option`.
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: NotFunction<B>): Option<B>;
 };
 /**
@@ -602,7 +964,85 @@ export declare const andThen: {
  * @since 2.0.0
  */
 export declare const flatMapNullable: {
+    /**
+     * This is `flatMap` + `fromNullable`, useful when working with optional values.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * interface Employee {
+     *   company?: {
+     *     address?: {
+     *       street?: {
+     *         name?: string
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * const employee1: Employee = { company: { address: { street: { name: 'high street' } } } }
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some(employee1),
+     *     Option.flatMapNullable(employee => employee.company?.address?.street?.name),
+     *   ),
+     *   Option.some('high street')
+     * )
+     *
+     * const employee2: Employee = { company: { address: { street: {} } } }
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some(employee2),
+     *     Option.flatMapNullable(employee => employee.company?.address?.street?.name),
+     *   ),
+     *   Option.none()
+     * )
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => B | null | undefined): (self: Option<A>) => Option<NonNullable<B>>;
+    /**
+     * This is `flatMap` + `fromNullable`, useful when working with optional values.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * interface Employee {
+     *   company?: {
+     *     address?: {
+     *       street?: {
+     *         name?: string
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * const employee1: Employee = { company: { address: { street: { name: 'high street' } } } }
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some(employee1),
+     *     Option.flatMapNullable(employee => employee.company?.address?.street?.name),
+     *   ),
+     *   Option.some('high street')
+     * )
+     *
+     * const employee2: Employee = { company: { address: { street: {} } } }
+     *
+     * assert.deepStrictEqual(
+     *   pipe(
+     *     Option.some(employee2),
+     *     Option.flatMapNullable(employee => employee.company?.address?.street?.name),
+     *   ),
+     *   Option.none()
+     * )
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => B | null | undefined): Option<NonNullable<B>>;
 };
 /**
@@ -615,7 +1055,15 @@ export declare const flatten: <A>(self: Option<Option<A>>) => Option<A>;
  * @since 2.0.0
  */
 export declare const zipRight: {
+    /**
+     * @category zipping
+     * @since 2.0.0
+     */
     <B>(that: Option<B>): <_>(self: Option<_>) => Option<B>;
+    /**
+     * @category zipping
+     * @since 2.0.0
+     */
     <X, B>(self: Option<X>, that: Option<B>): Option<B>;
 };
 /**
@@ -623,7 +1071,15 @@ export declare const zipRight: {
  * @since 2.0.0
  */
 export declare const composeK: {
+    /**
+     * @category sequencing
+     * @since 2.0.0
+     */
     <B, C>(bfc: (b: B) => Option<C>): <A>(afb: (a: A) => Option<B>) => (a: A) => Option<C>;
+    /**
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, B, C>(afb: (a: A) => Option<B>, bfc: (b: B) => Option<C>): (a: A) => Option<C>;
 };
 /**
@@ -638,7 +1094,29 @@ export declare const composeK: {
  * @since 2.0.0
  */
 export declare const zipLeft: {
+    /**
+     * Sequences the specified `that` `Option` but ignores its value.
+     *
+     * It is useful when we want to chain multiple operations, but only care about the result of `self`.
+     *
+     * @param that - The `Option` that will be ignored in the chain and discarded
+     * @param self - The `Option` we care about
+     *
+     * @category zipping
+     * @since 2.0.0
+     */
     <_>(that: Option<_>): <A>(self: Option<A>) => Option<A>;
+    /**
+     * Sequences the specified `that` `Option` but ignores its value.
+     *
+     * It is useful when we want to chain multiple operations, but only care about the result of `self`.
+     *
+     * @param that - The `Option` that will be ignored in the chain and discarded
+     * @param self - The `Option` we care about
+     *
+     * @category zipping
+     * @since 2.0.0
+     */
     <A, X>(self: Option<A>, that: Option<X>): Option<A>;
 };
 /**
@@ -663,7 +1141,49 @@ export declare const zipLeft: {
  * @since 2.0.0
  */
 export declare const tap: {
+    /**
+     * Applies the provided function `f` to the value of the `Option` if it is `Some` and returns the original `Option`
+     * unless `f` returns `None`, in which case it returns `None`.
+     *
+     * This function is useful for performing additional computations on the value of the input `Option` without affecting its value.
+     *
+     * @param f - Function to apply to the value of the `Option` if it is `Some`
+     * @param self - The `Option` to apply the function to
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const getInteger = (n: number) => Number.isInteger(n) ? Option.some(n) : Option.none()
+     *
+     * assert.deepStrictEqual(Option.tap(Option.none(), getInteger), Option.none())
+     * assert.deepStrictEqual(Option.tap(Option.some(1), getInteger), Option.some(1))
+     * assert.deepStrictEqual(Option.tap(Option.some(1.14), getInteger), Option.none())
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, X>(f: (a: A) => Option<X>): (self: Option<A>) => Option<A>;
+    /**
+     * Applies the provided function `f` to the value of the `Option` if it is `Some` and returns the original `Option`
+     * unless `f` returns `None`, in which case it returns `None`.
+     *
+     * This function is useful for performing additional computations on the value of the input `Option` without affecting its value.
+     *
+     * @param f - Function to apply to the value of the `Option` if it is `Some`
+     * @param self - The `Option` to apply the function to
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const getInteger = (n: number) => Number.isInteger(n) ? Option.some(n) : Option.none()
+     *
+     * assert.deepStrictEqual(Option.tap(Option.none(), getInteger), Option.none())
+     * assert.deepStrictEqual(Option.tap(Option.some(1), getInteger), Option.some(1))
+     * assert.deepStrictEqual(Option.tap(Option.some(1.14), getInteger), Option.none())
+     *
+     * @category sequencing
+     * @since 2.0.0
+     */
     <A, X>(self: Option<A>, f: (a: A) => Option<X>): Option<A>;
 };
 /**
@@ -725,7 +1245,55 @@ export declare const all: <const I extends Iterable<Option<any>> | Record<string
  * @since 2.0.0
  */
 export declare const zipWith: {
+    /**
+     * Zips two `Option` values together using a provided function, returning a new `Option` of the result.
+     *
+     * @param self - The left-hand side of the zip operation
+     * @param that - The right-hand side of the zip operation
+     * @param f - The function used to combine the values of the two `Option`s
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * type Complex = [real: number, imaginary: number]
+     *
+     * const complex = (real: number, imaginary: number): Complex => [real, imaginary]
+     *
+     * assert.deepStrictEqual(Option.zipWith(Option.none(), Option.none(), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.none(), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.none(), Option.some(1), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.some(2), complex), Option.some([1, 2]))
+     *
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), complex)(Option.some(2)), Option.some([2, 1]))
+     *
+     * @category zipping
+     * @since 2.0.0
+     */
     <B, A, C>(that: Option<B>, f: (a: A, b: B) => C): (self: Option<A>) => Option<C>;
+    /**
+     * Zips two `Option` values together using a provided function, returning a new `Option` of the result.
+     *
+     * @param self - The left-hand side of the zip operation
+     * @param that - The right-hand side of the zip operation
+     * @param f - The function used to combine the values of the two `Option`s
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * type Complex = [real: number, imaginary: number]
+     *
+     * const complex = (real: number, imaginary: number): Complex => [real, imaginary]
+     *
+     * assert.deepStrictEqual(Option.zipWith(Option.none(), Option.none(), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.none(), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.none(), Option.some(1), complex), Option.none())
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), Option.some(2), complex), Option.some([1, 2]))
+     *
+     * assert.deepStrictEqual(Option.zipWith(Option.some(1), complex)(Option.some(2)), Option.some([2, 1]))
+     *
+     * @category zipping
+     * @since 2.0.0
+     */
     <A, B, C>(self: Option<A>, that: Option<B>, f: (a: A, b: B) => C): Option<C>;
 };
 /**
@@ -733,7 +1301,15 @@ export declare const zipWith: {
  * @since 2.0.0
  */
 export declare const ap: {
+    /**
+     * @category combining
+     * @since 2.0.0
+     */
     <A>(that: Option<A>): <B>(self: Option<(a: A) => B>) => Option<B>;
+    /**
+     * @category combining
+     * @since 2.0.0
+     */
     <A, B>(self: Option<(a: A) => B>, that: Option<A>): Option<B>;
 };
 /**
@@ -753,7 +1329,39 @@ export declare const ap: {
  * @since 2.0.0
  */
 export declare const reduceCompact: {
+    /**
+     * Reduces an `Iterable` of `Option<A>` to a single value of type `B`, elements that are `None` are ignored.
+     *
+     * @param self - The Iterable of `Option<A>` to be reduced.
+     * @param b - The initial value of the accumulator.
+     * @param f - The reducing function that takes the current accumulator value and the unwrapped value of an `Option<A>`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const iterable = [Option.some(1), Option.none(), Option.some(2), Option.none()]
+     * assert.deepStrictEqual(pipe(iterable, Option.reduceCompact(0, (b, a) => b + a)), 3)
+     *
+     * @category folding
+     * @since 2.0.0
+     */
     <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<Option<A>>) => B;
+    /**
+     * Reduces an `Iterable` of `Option<A>` to a single value of type `B`, elements that are `None` are ignored.
+     *
+     * @param self - The Iterable of `Option<A>` to be reduced.
+     * @param b - The initial value of the accumulator.
+     * @param f - The reducing function that takes the current accumulator value and the unwrapped value of an `Option<A>`.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const iterable = [Option.some(1), Option.none(), Option.some(2), Option.none()]
+     * assert.deepStrictEqual(pipe(iterable, Option.reduceCompact(0, (b, a) => b + a)), 3)
+     *
+     * @category folding
+     * @since 2.0.0
+     */
     <A, B>(self: Iterable<Option<A>>, b: B, f: (b: B, a: A) => B): B;
 };
 /**
@@ -778,7 +1386,15 @@ export declare const toArray: <A>(self: Option<A>) => Array<A>;
  * @since 2.0.0
  */
 export declare const partitionMap: {
+    /**
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B, C>(f: (a: A) => Either<C, B>): (self: Option<A>) => [left: Option<B>, right: Option<C>];
+    /**
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B, C>(self: Option<A>, f: (a: A) => Either<C, B>): [left: Option<B>, right: Option<C>];
 };
 /**
@@ -802,7 +1418,47 @@ export declare const partitionMap: {
  * @since 2.0.0
  */
 export declare const filterMap: {
+    /**
+     * Maps over the value of an `Option` and filters out `None`s.
+     *
+     * Useful when in addition to filtering you also want to change the type of the `Option`.
+     *
+     * @param self - The `Option` to map over.
+     * @param f - A function to apply to the value of the `Option`.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const evenNumber = (n: number) => n % 2 === 0 ? Option.some(n) : Option.none()
+     *
+     * assert.deepStrictEqual(Option.filterMap(Option.none(), evenNumber), Option.none())
+     * assert.deepStrictEqual(Option.filterMap(Option.some(3), evenNumber), Option.none())
+     * assert.deepStrictEqual(Option.filterMap(Option.some(2), evenNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B>(f: (a: A) => Option<B>): (self: Option<A>) => Option<B>;
+    /**
+     * Maps over the value of an `Option` and filters out `None`s.
+     *
+     * Useful when in addition to filtering you also want to change the type of the `Option`.
+     *
+     * @param self - The `Option` to map over.
+     * @param f - A function to apply to the value of the `Option`.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const evenNumber = (n: number) => n % 2 === 0 ? Option.some(n) : Option.none()
+     *
+     * assert.deepStrictEqual(Option.filterMap(Option.none(), evenNumber), Option.none())
+     * assert.deepStrictEqual(Option.filterMap(Option.some(3), evenNumber), Option.none())
+     * assert.deepStrictEqual(Option.filterMap(Option.some(2), evenNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B>(self: Option<A>, f: (a: A) => Option<B>): Option<B>;
 };
 /**
@@ -834,9 +1490,121 @@ export declare const filterMap: {
  * @since 2.0.0
  */
 export declare const filter: {
+    /**
+     * Filters an `Option` using a predicate. If the predicate is not satisfied or the `Option` is `None` returns `None`.
+     *
+     * If you need to change the type of the `Option` in addition to filtering, see `filterMap`.
+     *
+     * @param predicate - A predicate function to apply to the `Option` value.
+     * @param fb - The `Option` to filter.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * // predicate
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(3), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isEven), Option.some(2))
+     *
+     * // refinement
+     * const isNumber = (v: unknown): v is number => typeof v === "number"
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some('hello'), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => Option<B>;
+    /**
+     * Filters an `Option` using a predicate. If the predicate is not satisfied or the `Option` is `None` returns `None`.
+     *
+     * If you need to change the type of the `Option` in addition to filtering, see `filterMap`.
+     *
+     * @param predicate - A predicate function to apply to the `Option` value.
+     * @param fb - The `Option` to filter.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * // predicate
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(3), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isEven), Option.some(2))
+     *
+     * // refinement
+     * const isNumber = (v: unknown): v is number => typeof v === "number"
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some('hello'), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => Option<A>;
+    /**
+     * Filters an `Option` using a predicate. If the predicate is not satisfied or the `Option` is `None` returns `None`.
+     *
+     * If you need to change the type of the `Option` in addition to filtering, see `filterMap`.
+     *
+     * @param predicate - A predicate function to apply to the `Option` value.
+     * @param fb - The `Option` to filter.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * // predicate
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(3), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isEven), Option.some(2))
+     *
+     * // refinement
+     * const isNumber = (v: unknown): v is number => typeof v === "number"
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some('hello'), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): Option<B>;
+    /**
+     * Filters an `Option` using a predicate. If the predicate is not satisfied or the `Option` is `None` returns `None`.
+     *
+     * If you need to change the type of the `Option` in addition to filtering, see `filterMap`.
+     *
+     * @param predicate - A predicate function to apply to the `Option` value.
+     * @param fb - The `Option` to filter.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * // predicate
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(3), isEven), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isEven), Option.some(2))
+     *
+     * // refinement
+     * const isNumber = (v: unknown): v is number => typeof v === "number"
+     *
+     * assert.deepStrictEqual(Option.filter(Option.none(), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some('hello'), isNumber), Option.none())
+     * assert.deepStrictEqual(Option.filter(Option.some(2), isNumber), Option.some(2))
+     *
+     * @category filtering
+     * @since 2.0.0
+     */
     <A>(self: Option<A>, predicate: Predicate<A>): Option<A>;
 };
 /**
@@ -906,8 +1674,59 @@ export declare const lift2: <A, B, C>(f: (a: A, b: B) => C) => {
  */
 export declare const liftPredicate: {
     <A, B extends A>(refinement: Refinement<A, B>): (a: A) => Option<B>;
+    /**
+     * Transforms a `Predicate` function into a `Some` of the input value if the predicate returns `true` or `None`
+     * if the predicate returns `false`.
+     *
+     * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const getOption = Option.liftPredicate((n: number) => n >= 0)
+     *
+     * assert.deepStrictEqual(getOption(-1), Option.none())
+     * assert.deepStrictEqual(getOption(1), Option.some(1))
+     *
+     * @category lifting
+     * @since 2.0.0
+     */
     <B extends A, A = B>(predicate: Predicate<A>): (b: B) => Option<B>;
+    /**
+     * Transforms a `Predicate` function into a `Some` of the input value if the predicate returns `true` or `None`
+     * if the predicate returns `false`.
+     *
+     * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const getOption = Option.liftPredicate((n: number) => n >= 0)
+     *
+     * assert.deepStrictEqual(getOption(-1), Option.none())
+     * assert.deepStrictEqual(getOption(1), Option.some(1))
+     *
+     * @category lifting
+     * @since 2.0.0
+     */
     <A, B extends A>(self: A, refinement: Refinement<A, B>): Option<B>;
+    /**
+     * Transforms a `Predicate` function into a `Some` of the input value if the predicate returns `true` or `None`
+     * if the predicate returns `false`.
+     *
+     * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+     *
+     * @example
+     * import { Option } from "effect"
+     *
+     * const getOption = Option.liftPredicate((n: number) => n >= 0)
+     *
+     * assert.deepStrictEqual(getOption(-1), Option.none())
+     * assert.deepStrictEqual(getOption(1), Option.some(1))
+     *
+     * @category lifting
+     * @since 2.0.0
+     */
     <B extends A, A = B>(self: B, predicate: Predicate<A>): Option<B>;
 };
 /**
@@ -938,7 +1757,19 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  * @since 2.0.0
  */
 export declare const contains: {
+    /**
+     * Returns a function that checks if an `Option` contains a given value using the default `Equivalence`.
+     *
+     * @category elements
+     * @since 2.0.0
+     */
     <A>(a: A): (self: Option<A>) => boolean;
+    /**
+     * Returns a function that checks if an `Option` contains a given value using the default `Equivalence`.
+     *
+     * @category elements
+     * @since 2.0.0
+     */
     <A>(self: Option<A>, a: A): boolean;
 };
 /**
@@ -959,9 +1790,77 @@ export declare const contains: {
  * @since 2.0.0
  */
 export declare const exists: {
+    /**
+     * Check if a value in an `Option` type meets a certain predicate.
+     *
+     * @param self - The `Option` to check.
+     * @param predicate - The condition to check.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(pipe(Option.some(2), Option.exists(isEven)), true)
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.exists(isEven)), false)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.exists(isEven)), false)
+     *
+     * @since 2.0.0
+     */
     <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => self is Option<B>;
+    /**
+     * Check if a value in an `Option` type meets a certain predicate.
+     *
+     * @param self - The `Option` to check.
+     * @param predicate - The condition to check.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(pipe(Option.some(2), Option.exists(isEven)), true)
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.exists(isEven)), false)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.exists(isEven)), false)
+     *
+     * @since 2.0.0
+     */
     <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => boolean;
+    /**
+     * Check if a value in an `Option` type meets a certain predicate.
+     *
+     * @param self - The `Option` to check.
+     * @param predicate - The condition to check.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(pipe(Option.some(2), Option.exists(isEven)), true)
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.exists(isEven)), false)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.exists(isEven)), false)
+     *
+     * @since 2.0.0
+     */
     <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): self is Option<B>;
+    /**
+     * Check if a value in an `Option` type meets a certain predicate.
+     *
+     * @param self - The `Option` to check.
+     * @param predicate - The condition to check.
+     *
+     * @example
+     * import { pipe, Option } from "effect"
+     *
+     * const isEven = (n: number) => n % 2 === 0
+     *
+     * assert.deepStrictEqual(pipe(Option.some(2), Option.exists(isEven)), true)
+     * assert.deepStrictEqual(pipe(Option.some(1), Option.exists(isEven)), false)
+     * assert.deepStrictEqual(pipe(Option.none(), Option.exists(isEven)), false)
+     *
+     * @since 2.0.0
+     */
     <A>(self: Option<A>, predicate: Predicate<A>): boolean;
 };
 /**
@@ -995,9 +1894,69 @@ export declare const exists: {
  * @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 `Option` 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
+     * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+     *
+     * @see {@link Do}
+     * @see {@link bind}
+     * @see {@link let_ let}
+     *
+     * @example
+     * import { Option, pipe } from "effect"
+     *
+     * const result = pipe(
+     *   Option.Do,
+     *   Option.bind("x", () => Option.some(2)),
+     *   Option.bind("y", () => Option.some(3)),
+     *   Option.let("sum", ({ x, y }) => x + y),
+     *   Option.filter(({ x, y }) => x * y > 5)
+     * )
+     * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
+     *
+     * @category do notation
+     * @since 2.0.0
+     */
     <N extends string>(name: N): <A>(self: Option<A>) => Option<{
         [K in N]: A;
     }>;
+    /**
+     * 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 `Option` 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
+     * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+     *
+     * @see {@link Do}
+     * @see {@link bind}
+     * @see {@link let_ let}
+     *
+     * @example
+     * import { Option, pipe } from "effect"
+     *
+     * const result = pipe(
+     *   Option.Do,
+     *   Option.bind("x", () => Option.some(2)),
+     *   Option.bind("y", () => Option.some(3)),
+     *   Option.let("sum", ({ x, y }) => x + y),
+     *   Option.filter(({ x, y }) => x * y > 5)
+     * )
+     * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
+     *
+     * @category do notation
+     * @since 2.0.0
+     */
     <A, N extends string>(self: Option<A>, name: N): Option<{
         [K in N]: A;
     }>;
@@ -1073,9 +2032,69 @@ let_ as let };
  * @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 `Option` 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
+     * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+     *
+     * @see {@link Do}
+     * @see {@link bindTo}
+     * @see {@link let_ let}
+     *
+     * @example
+     * import { Option, pipe } from "effect"
+     *
+     * const result = pipe(
+     *   Option.Do,
+     *   Option.bind("x", () => Option.some(2)),
+     *   Option.bind("y", () => Option.some(3)),
+     *   Option.let("sum", ({ x, y }) => x + y),
+     *   Option.filter(({ x, y }) => x * y > 5)
+     * )
+     * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
+     *
+     * @category do notation
+     * @since 2.0.0
+     */
     <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: A) => Option<B>): (self: Option<A>) => Option<{
         [K in N | keyof A]: K extends keyof A ? A[K] : B;
     }>;
+    /**
+     * 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 `Option` 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
+     * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+     *
+     * @see {@link Do}
+     * @see {@link bindTo}
+     * @see {@link let_ let}
+     *
+     * @example
+     * import { Option, pipe } from "effect"
+     *
+     * const result = pipe(
+     *   Option.Do,
+     *   Option.bind("x", () => Option.some(2)),
+     *   Option.bind("y", () => Option.some(3)),
+     *   Option.let("sum", ({ x, y }) => x + y),
+     *   Option.filter(({ x, y }) => x * y > 5)
+     * )
+     * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
+     *
+     * @category do notation
+     * @since 2.0.0
+     */
     <A extends object, N extends string, B>(self: Option<A>, name: Exclude<N, keyof A>, f: (a: A) => Option<B>): Option<{
         [K in N | keyof A]: K extends keyof A ? A[K] : B;
     }>;