effect 3.8.4 → 3.8.5

package/src/Boolean.ts

@@ -44,14 +44,51 @@ export const isBoolean: (input: unknown) => input is boolean = predicate.isBoole
  * @since 2.0.0
  */
 export const match: {
-  <A, B = A>(options: {
-    readonly onFalse: LazyArg<A>
-    readonly onTrue: LazyArg<B>
-  }): (value: boolean) => A | B
-  <A, B>(value: boolean, options: {
-    readonly onFalse: LazyArg<A>
-    readonly onTrue: LazyArg<B>
-  }): A | B
+  /**
+   * This function returns the result of either of the given functions depending on the value of the boolean parameter.
+   * It is useful when you have to run one of two functions depending on the boolean value.
+   *
+   * @param value - the boolean value that decides which function will be executed.
+   * @param onFalse - a lazy evaluation function that will be executed when the `value` is `false`.
+   * @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
+   *
+   * @example
+   * import { Boolean } from "effect"
+   *
+   * assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <A, B = A>(
+    options: {
+      readonly onFalse: LazyArg<A>
+      readonly onTrue: LazyArg<B>
+    }
+  ): (value: boolean) => A | B
+  /**
+   * This function returns the result of either of the given functions depending on the value of the boolean parameter.
+   * It is useful when you have to run one of two functions depending on the boolean value.
+   *
+   * @param value - the boolean value that decides which function will be executed.
+   * @param onFalse - a lazy evaluation function that will be executed when the `value` is `false`.
+   * @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
+   *
+   * @example
+   * import { Boolean } from "effect"
+   *
+   * assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <A, B>(
+    value: boolean,
+    options: {
+      readonly onFalse: LazyArg<A>
+      readonly onTrue: LazyArg<B>
+    }
+  ): A | B
 } = dual(2, <A, B>(value: boolean, options: {
   readonly onFalse: LazyArg<A>
   readonly onTrue: LazyArg<B>
@@ -98,7 +135,35 @@ export const not = (self: boolean): boolean => !self
  * @since 2.0.0
  */
 export const and: {
+  /**
+   * Combines two boolean using AND: `self && that`.
+   *
+   * @example
+   * import { and } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(and(true, true), true)
+   * assert.deepStrictEqual(and(true, false), false)
+   * assert.deepStrictEqual(and(false, true), false)
+   * assert.deepStrictEqual(and(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two boolean using AND: `self && that`.
+   *
+   * @example
+   * import { and } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(and(true, true), true)
+   * assert.deepStrictEqual(and(true, false), false)
+   * assert.deepStrictEqual(and(false, true), false)
+   * assert.deepStrictEqual(and(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => self && that)
 
@@ -117,7 +182,35 @@ export const and: {
  * @since 2.0.0
  */
 export const nand: {
+  /**
+   * Combines two boolean using NAND: `!(self && that)`.
+   *
+   * @example
+   * import { nand } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(nand(true, true), false)
+   * assert.deepStrictEqual(nand(true, false), true)
+   * assert.deepStrictEqual(nand(false, true), true)
+   * assert.deepStrictEqual(nand(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two boolean using NAND: `!(self && that)`.
+   *
+   * @example
+   * import { nand } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(nand(true, true), false)
+   * assert.deepStrictEqual(nand(true, false), true)
+   * assert.deepStrictEqual(nand(false, true), true)
+   * assert.deepStrictEqual(nand(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => !(self && that))
 
@@ -136,7 +229,35 @@ export const nand: {
  * @since 2.0.0
  */
 export const or: {
+  /**
+   * Combines two boolean using OR: `self || that`.
+   *
+   * @example
+   * import { or } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(or(true, true), true)
+   * assert.deepStrictEqual(or(true, false), true)
+   * assert.deepStrictEqual(or(false, true), true)
+   * assert.deepStrictEqual(or(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two boolean using OR: `self || that`.
+   *
+   * @example
+   * import { or } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(or(true, true), true)
+   * assert.deepStrictEqual(or(true, false), true)
+   * assert.deepStrictEqual(or(false, true), true)
+   * assert.deepStrictEqual(or(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => self || that)
 
@@ -155,7 +276,35 @@ export const or: {
  * @since 2.0.0
  */
 export const nor: {
+  /**
+   * Combines two booleans using NOR: `!(self || that)`.
+   *
+   * @example
+   * import { nor } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(nor(true, true), false)
+   * assert.deepStrictEqual(nor(true, false), false)
+   * assert.deepStrictEqual(nor(false, true), false)
+   * assert.deepStrictEqual(nor(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two booleans using NOR: `!(self || that)`.
+   *
+   * @example
+   * import { nor } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(nor(true, true), false)
+   * assert.deepStrictEqual(nor(true, false), false)
+   * assert.deepStrictEqual(nor(false, true), false)
+   * assert.deepStrictEqual(nor(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => !(self || that))
 
@@ -174,7 +323,35 @@ export const nor: {
  * @since 2.0.0
  */
 export const xor: {
+  /**
+   * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
+   *
+   * @example
+   * import { xor } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(xor(true, true), false)
+   * assert.deepStrictEqual(xor(true, false), true)
+   * assert.deepStrictEqual(xor(false, true), true)
+   * assert.deepStrictEqual(xor(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
+   *
+   * @example
+   * import { xor } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(xor(true, true), false)
+   * assert.deepStrictEqual(xor(true, false), true)
+   * assert.deepStrictEqual(xor(false, true), true)
+   * assert.deepStrictEqual(xor(false, false), false)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => (!self && that) || (self && !that))
 
@@ -193,7 +370,35 @@ export const xor: {
  * @since 2.0.0
  */
 export const eqv: {
+  /**
+   * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
+   *
+   * @example
+   * import { eqv } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(eqv(true, true), true)
+   * assert.deepStrictEqual(eqv(true, false), false)
+   * assert.deepStrictEqual(eqv(false, true), false)
+   * assert.deepStrictEqual(eqv(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
+   *
+   * @example
+   * import { eqv } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(eqv(true, true), true)
+   * assert.deepStrictEqual(eqv(true, false), false)
+   * assert.deepStrictEqual(eqv(false, true), false)
+   * assert.deepStrictEqual(eqv(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self: boolean, that: boolean): boolean => !xor(self, that))
 
@@ -212,7 +417,35 @@ export const eqv: {
  * @since 2.0.0
  */
 export const implies: {
+  /**
+   * Combines two booleans using an implication: `(!self || that)`.
+   *
+   * @example
+   * import { implies } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(implies(true, true), true)
+   * assert.deepStrictEqual(implies(true, false), false)
+   * assert.deepStrictEqual(implies(false, true), true)
+   * assert.deepStrictEqual(implies(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (that: boolean): (self: boolean) => boolean
+  /**
+   * Combines two booleans using an implication: `(!self || that)`.
+   *
+   * @example
+   * import { implies } from "effect/Boolean"
+   *
+   * assert.deepStrictEqual(implies(true, true), true)
+   * assert.deepStrictEqual(implies(true, false), false)
+   * assert.deepStrictEqual(implies(false, true), true)
+   * assert.deepStrictEqual(implies(false, false), true)
+   *
+   * @category combinators
+   * @since 2.0.0
+   */
   (self: boolean, that: boolean): boolean
 } = dual(2, (self, that) => self ? that : true)
 

package/src/Cause.ts

@@ -668,7 +668,23 @@ export const stripFailures: <E>(self: Cause<E>) => Cause<never> = internal.strip
  * @category getters
  */
 export const stripSomeDefects: {
+  /**
+   * Remove all `Die` causes that the specified partial function is defined at,
+   * returning `Some` with the remaining causes or `None` if there are no
+   * remaining causes.
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   (pf: (defect: unknown) => Option.Option<unknown>): <E>(self: Cause<E>) => Option.Option<Cause<E>>
+  /**
+   * Remove all `Die` causes that the specified partial function is defined at,
+   * returning `Some` with the remaining causes or `None` if there are no
+   * remaining causes.
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <E>(self: Cause<E>, pf: (defect: unknown) => Option.Option<unknown>): Option.Option<Cause<E>>
 } = internal.stripSomeDefects
 
@@ -677,7 +693,15 @@ export const stripSomeDefects: {
  * @category mapping
  */
 export const as: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <E2>(error: E2): <E>(self: Cause<E>) => Cause<E2>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <E, E2>(self: Cause<E>, error: E2): Cause<E2>
 } = internal.as
 
@@ -686,7 +710,15 @@ export const as: {
  * @category mapping
  */
 export const map: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <E, E2>(f: (e: E) => E2): (self: Cause<E>) => Cause<E2>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <E, E2>(self: Cause<E>, f: (e: E) => E2): Cause<E2>
 } = internal.map
 
@@ -695,7 +727,15 @@ export const map: {
  * @category sequencing
  */
 export const flatMap: {
+  /**
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E, E2>(f: (e: E) => Cause<E2>): (self: Cause<E>) => Cause<E2>
+  /**
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E, E2>(self: Cause<E>, f: (e: E) => Cause<E2>): Cause<E2>
 } = internal.flatMap
 
@@ -706,9 +746,33 @@ export const flatMap: {
  * @category sequencing
  */
 export const andThen: {
+  /**
+   * Executes a sequence of two `Cause`s. The second `Cause` can be dependent on the result of the first `Cause`.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E, E2>(f: (e: E) => Cause<E2>): (self: Cause<E>) => Cause<E2>
+  /**
+   * Executes a sequence of two `Cause`s. The second `Cause` can be dependent on the result of the first `Cause`.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E2>(f: Cause<E2>): <E>(self: Cause<E>) => Cause<E2>
+  /**
+   * Executes a sequence of two `Cause`s. The second `Cause` can be dependent on the result of the first `Cause`.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E, E2>(self: Cause<E>, f: (e: E) => Cause<E2>): Cause<E2>
+  /**
+   * Executes a sequence of two `Cause`s. The second `Cause` can be dependent on the result of the first `Cause`.
+   *
+   * @since 2.0.0
+   * @category sequencing
+   */
   <E, E2>(self: Cause<E>, f: Cause<E2>): Cause<E2>
 } = internal.andThen
 
@@ -726,7 +790,21 @@ export const flatten: <E>(self: Cause<Cause<E>>) => Cause<E> = internal.flatten
  * @category elements
  */
 export const contains: {
+  /**
+   * Returns `true` if the `self` cause contains or is equal to `that` cause,
+   * `false` otherwise.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <E2>(that: Cause<E2>): <E>(self: Cause<E>) => boolean
+  /**
+   * Returns `true` if the `self` cause contains or is equal to `that` cause,
+   * `false` otherwise.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <E, E2>(self: Cause<E>, that: Cause<E2>): boolean
 } = internal.contains
 
@@ -748,7 +826,23 @@ export const squash: <E>(self: Cause<E>) => unknown = core.causeSquash
  * @category destructors
  */
 export const squashWith: {
+  /**
+   * Squashes a `Cause` down to a single defect, chosen to be the "most important"
+   * defect. If a recoverable error is found, the provided function will be used
+   * to map the error a defect, and the resulting value will be returned.
+   *
+   * @since 2.0.0
+   * @category destructors
+   */
   <E>(f: (error: E) => unknown): (self: Cause<E>) => unknown
+  /**
+   * Squashes a `Cause` down to a single defect, chosen to be the "most important"
+   * defect. If a recoverable error is found, the provided function will be used
+   * to map the error a defect, and the resulting value will be returned.
+   *
+   * @since 2.0.0
+   * @category destructors
+   */
   <E>(self: Cause<E>, f: (error: E) => unknown): unknown
 } = core.causeSquashWith
 
@@ -760,7 +854,21 @@ export const squashWith: {
  * @category elements
  */
 export const find: {
+  /**
+   * Uses the provided partial function to search the specified cause and attempt
+   * to extract information from it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <E, Z>(pf: (cause: Cause<E>) => Option.Option<Z>): (self: Cause<E>) => Option.Option<Z>
+  /**
+   * Uses the provided partial function to search the specified cause and attempt
+   * to extract information from it.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <E, Z>(self: Cause<E>, pf: (cause: Cause<E>) => Option.Option<Z>): Option.Option<Z>
 } = internal.find
 
@@ -771,9 +879,33 @@ export const find: {
  * @category filtering
  */
 export const filter: {
+  /**
+   * Filters causes which match the provided predicate out of the specified cause.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <E, EB extends E>(refinement: Refinement<Cause<NoInfer<E>>, Cause<EB>>): (self: Cause<E>) => Cause<EB>
+  /**
+   * Filters causes which match the provided predicate out of the specified cause.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <E>(predicate: Predicate<Cause<NoInfer<E>>>): (self: Cause<E>) => Cause<E>
+  /**
+   * Filters causes which match the provided predicate out of the specified cause.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <E, EB extends E>(self: Cause<E>, refinement: Refinement<Cause<E>, Cause<EB>>): Cause<EB>
+  /**
+   * Filters causes which match the provided predicate out of the specified cause.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <E>(self: Cause<E>, predicate: Predicate<Cause<E>>): Cause<E>
 } = internal.filter
 
@@ -784,6 +916,12 @@ export const filter: {
  * @category folding
  */
 export const match: {
+  /**
+   * Folds the specified cause into a value of type `Z`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, E>(
     options: {
       readonly onEmpty: Z
@@ -794,6 +932,12 @@ export const match: {
       readonly onParallel: (left: Z, right: Z) => Z
     }
   ): (self: Cause<E>) => Z
+  /**
+   * Folds the specified cause into a value of type `Z`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, E>(
     self: Cause<E>,
     options: {
@@ -815,8 +959,26 @@ export const match: {
  * @category folding
  */
 export const reduce: {
+  /**
+   * Reduces the specified cause into a value of type `Z`, beginning with the
+   * provided `zero` value.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <Z, E>(zero: Z, pf: (accumulator: Z, cause: Cause<E>) => Option.Option<Z>): (self: Cause<E>) => Z
-  <Z, E>(self: Cause<E>, zero: Z, pf: (accumulator: Z, cause: Cause<E>) => Option.Option<Z>): Z
+  /**
+   * Reduces the specified cause into a value of type `Z`, beginning with the
+   * provided `zero` value.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <Z, E>(
+    self: Cause<E>,
+    zero: Z,
+    pf: (accumulator: Z, cause: Cause<E>) => Option.Option<Z>
+  ): Z
 } = internal.reduce
 
 /**
@@ -827,7 +989,21 @@ export const reduce: {
  * @category folding
  */
 export const reduceWithContext: {
+  /**
+   * Reduces the specified cause into a value of type `Z` using a `Cause.Reducer`.
+   * Also allows for accessing the provided context during reduction.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <C, E, Z>(context: C, reducer: CauseReducer<C, E, Z>): (self: Cause<E>) => Z
+  /**
+   * Reduces the specified cause into a value of type `Z` using a `Cause.Reducer`.
+   * Also allows for accessing the provided context during reduction.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   <C, E, Z>(self: Cause<E>, context: C, reducer: CauseReducer<C, E, Z>): Z
 } = internal.reduceWithContext