effect 3.8.4 → 3.8.5

package/src/Option.ts

@@ -193,14 +193,67 @@ export const isSome: <A>(self: Option<A>) => self is Some<A> = option.isSome
  * @since 2.0.0
  */
 export const match: {
-  <B, A, C = B>(options: {
-    readonly onNone: LazyArg<B>
-    readonly onSome: (a: A) => C
-  }): (self: Option<A>) => B | C
-  <A, B, C = B>(self: Option<A>, options: {
-    readonly onNone: LazyArg<B>
-    readonly onSome: (a: A) => C
-  }): 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
+   */
+  <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
+    }
+  ): B | C
 } = dual(
   2,
   <A, B, C = B>(self: Option<A>, { onNone, onSome }: {
@@ -295,7 +348,37 @@ export const getLeft: <R, L>(self: Either<R, L>) => Option<L> = either.getLeft
  * @since 2.0.0
  */
 export 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
 } = dual(
   2,
@@ -344,7 +427,89 @@ export const getOrElse: {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -379,7 +544,61 @@ export const orElse: {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -399,7 +618,31 @@ export const orElseSome: {
  * @since 2.0.0
  */
 export 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>>
 } = dual(
   2,
@@ -561,7 +804,47 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  * @since 2.0.0
  */
 export 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
 } = dual(2, <A>(self: Option<A>, onNone: () => unknown): A => {
   if (isSome(self)) {
@@ -599,7 +882,25 @@ export const getOrThrow: <A>(self: Option<A>) => A = getOrThrowWith(() => new Er
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -613,6 +914,12 @@ export const map: {
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <X, B>(self: Option<X>, b: B): Option<B> => map(self, () => b))
 
@@ -641,7 +948,19 @@ export {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -655,13 +974,61 @@ export const flatMap: {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -712,7 +1079,85 @@ export const andThen: {
  * @since 2.0.0
  */
 export 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>>
 } = dual(
   2,
@@ -731,7 +1176,15 @@ export const flatten: <A>(self: Option<Option<A>>) => Option<A> = flatMap(identi
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <X, B>(self: Option<X>, that: Option<B>): Option<B> => flatMap(self, () => that))
 
@@ -740,7 +1193,15 @@ export const zipRight: {
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <A, B, C>(afb: (a: A) => Option<B>, bfc: (b: B) => Option<C>) => (a: A): Option<C> => flatMap(afb(a), bfc))
 
@@ -756,7 +1217,29 @@ export const composeK: {
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <A, X>(self: Option<A>, that: Option<X>): Option<A> => tap(self, () => that))
 
@@ -782,7 +1265,49 @@ export const zipLeft: {
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <A, X>(self: Option<A>, f: (a: A) => Option<X>): Option<A> => flatMap(self, (a) => map(f(a), () => a)))
 
@@ -890,7 +1415,55 @@ export const all: <const I extends Iterable<Option<any>> | Record<string, Option
  * @since 2.0.0
  */
 export 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>
 } = dual(
   3,
@@ -903,7 +1476,15 @@ export const zipWith: {
  * @since 2.0.0
  */
 export 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>
 } = dual(2, <A, B>(self: Option<(a: A) => B>, that: Option<A>): Option<B> => zipWith(self, that, (f, a) => f(a)))
 
@@ -924,7 +1505,39 @@ export const ap: {
  * @since 2.0.0
  */
 export 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
 } = dual(
   3,
@@ -962,7 +1575,15 @@ export const toArray = <A>(self: Option<A>): Array<A> => isNone(self) ? [] : [se
  * @since 2.0.0
  */
 export 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>]
 } = dual(2, <A, B, C>(
   self: Option<A>,
@@ -996,7 +1617,47 @@ export const partitionMap: {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -1032,9 +1693,121 @@ export const filterMap: {
  * @since 2.0.0
  */
 export 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>
 } = dual(
   2,
@@ -1114,15 +1887,60 @@ export const lift2 = <A, B, C>(f: (a: A, b: B) => C): {
  */
 export const liftPredicate: { // Note: I intentionally avoid using the NoInfer pattern here.
   <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>
-  <A, B extends A>(
-    self: A,
-    refinement: Refinement<A, B>
-  ): Option<B>
-  <B extends A, A = B>(
-    self: B,
-    predicate: Predicate<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
+   */
+  <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>
 } = dual(
   2,
   <B extends A, A = B>(b: B, predicate: Predicate<A>): Option<B> => predicate(b) ? some(b) : none()
@@ -1159,7 +1977,19 @@ const _equivalence = Equal.equivalence()
  * @since 2.0.0
  */
 export 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
 } = containsWith(_equivalence)
 
@@ -1181,9 +2011,77 @@ export const contains: {
  * @since 2.0.0
  */
 export 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
 } = dual(
   2,
@@ -1226,7 +2124,75 @@ export const exists: {
  * @since 2.0.0
  */
 export const bindTo: {
+  // -------------------------------------------------------------------------------------
+  // do notation
+  // -------------------------------------------------------------------------------------
+
+  /**
+   * 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 }>
+  // -------------------------------------------------------------------------------------
+  // do notation
+  // -------------------------------------------------------------------------------------
+
+  /**
+   * 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 }>
 } = doNotation.bindTo<OptionTypeLambda>(map)
 
@@ -1307,10 +2273,70 @@ export {
  * @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 `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>,