effect 3.8.4 → 3.9.0

package/src/Function.ts

@@ -69,10 +69,92 @@ export const isFunction = (input: unknown): input is Function => typeof input ==
  * @since 2.0.0
  */
 export const dual: {
+  /**
+   * Creates a function that can be used in a data-last (aka `pipe`able) or
+   * data-first style.
+   *
+   * The first parameter to `dual` is either the arity of the uncurried function
+   * or a predicate that determines if the function is being used in a data-first
+   * or data-last style.
+   *
+   * Using the arity is the most common use case, but there are some cases where
+   * you may want to use a predicate. For example, if you have a function that
+   * takes an optional argument, you can use a predicate to determine if the
+   * function is being used in a data-first or data-last style.
+   *
+   * @param arity - Either the arity of the uncurried function or a predicate
+   *                which determines if the function is being used in a data-first
+   *                or data-last style.
+   * @param body - The definition of the uncurried function.
+   *
+   * @example
+   * import { dual, pipe } from "effect/Function"
+   *
+   * // Exampe using arity to determine data-first or data-last style
+   * const sum: {
+   *   (that: number): (self: number) => number
+   *   (self: number, that: number): number
+   * } = dual(2, (self: number, that: number): number => self + that)
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(pipe(2, sum(3)), 5)
+   *
+   * // Example using a predicate to determine data-first or data-last style
+   * const sum2: {
+   *   (that: number): (self: number) => number
+   *   (self: number, that: number): number
+   * } = dual((args) => args.length === 1, (self: number, that: number): number => self + that)
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(pipe(2, sum(3)), 5)
+   *
+   * @since 2.0.0
+   */
   <DataLast extends (...args: Array<any>) => any, DataFirst extends (...args: Array<any>) => any>(
     arity: Parameters<DataFirst>["length"],
     body: DataFirst
   ): DataLast & DataFirst
+  /**
+   * Creates a function that can be used in a data-last (aka `pipe`able) or
+   * data-first style.
+   *
+   * The first parameter to `dual` is either the arity of the uncurried function
+   * or a predicate that determines if the function is being used in a data-first
+   * or data-last style.
+   *
+   * Using the arity is the most common use case, but there are some cases where
+   * you may want to use a predicate. For example, if you have a function that
+   * takes an optional argument, you can use a predicate to determine if the
+   * function is being used in a data-first or data-last style.
+   *
+   * @param arity - Either the arity of the uncurried function or a predicate
+   *                which determines if the function is being used in a data-first
+   *                or data-last style.
+   * @param body - The definition of the uncurried function.
+   *
+   * @example
+   * import { dual, pipe } from "effect/Function"
+   *
+   * // Exampe using arity to determine data-first or data-last style
+   * const sum: {
+   *   (that: number): (self: number) => number
+   *   (self: number, that: number): number
+   * } = dual(2, (self: number, that: number): number => self + that)
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(pipe(2, sum(3)), 5)
+   *
+   * // Example using a predicate to determine data-first or data-last style
+   * const sum2: {
+   *   (that: number): (self: number) => number
+   *   (self: number, that: number): number
+   * } = dual((args) => args.length === 1, (self: number, that: number): number => self + that)
+   *
+   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(pipe(2, sum(3)), 5)
+   *
+   * @since 2.0.0
+   */
   <DataLast extends (...args: Array<any>) => any, DataFirst extends (...args: Array<any>) => any>(
     isDataFirst: (args: IArguments) => boolean,
     body: DataFirst
@@ -353,7 +435,41 @@ export const flip = <A extends Array<unknown>, B extends Array<unknown>, C>(
  * @since 2.0.0
  */
 export const compose: {
+  /**
+   * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
+   * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
+   *
+   * @param ab - A function that maps from `A` to `B`.
+   * @param bc - A function that maps from `B` to `C`.
+   *
+   * @example
+   * import { compose } from "effect/Function"
+   *
+   * const increment = (n: number) => n + 1;
+   * const square = (n: number) => n * n;
+   *
+   * assert.strictEqual(compose(increment, square)(2), 9);
+   *
+   * @since 2.0.0
+   */
   <B, C>(bc: (b: B) => C): <A>(self: (a: A) => B) => (a: A) => C
+  /**
+   * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
+   * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
+   *
+   * @param ab - A function that maps from `A` to `B`.
+   * @param bc - A function that maps from `B` to `C`.
+   *
+   * @example
+   * import { compose } from "effect/Function"
+   *
+   * const increment = (n: number) => n + 1;
+   * const square = (n: number) => n * n;
+   *
+   * assert.strictEqual(compose(increment, square)(2), 9);
+   *
+   * @since 2.0.0
+   */
   <A, B, C>(self: (a: A) => B, bc: (b: B) => C): (a: A) => C
 } = dual(2, <A, B, C>(ab: (a: A) => B, bc: (b: B) => C): (a: A) => C => (a) => bc(ab(a)))
 
@@ -420,17 +536,26 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * @since 2.0.0
  */
 export function pipe<A>(a: A): A
-export function pipe<A, B>(a: A, ab: (a: A) => B): B
-export function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C
-export function pipe<A, B, C, D>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D
-export function pipe<A, B, C, D, E>(
+export function pipe<A, B = never>(a: A, ab: (a: A) => B): B
+export function pipe<A, B = never, C = never>(
+  a: A,
+  ab: (a: A) => B,
+  bc: (b: B) => C
+): C
+export function pipe<A, B = never, C = never, D = never>(
+  a: A,
+  ab: (a: A) => B,
+  bc: (b: B) => C,
+  cd: (c: C) => D
+): D
+export function pipe<A, B = never, C = never, D = never, E = never>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
   de: (d: D) => E
 ): E
-export function pipe<A, B, C, D, E, F>(
+export function pipe<A, B = never, C = never, D = never, E = never, F = never>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -438,7 +563,15 @@ export function pipe<A, B, C, D, E, F>(
   de: (d: D) => E,
   ef: (e: E) => F
 ): F
-export function pipe<A, B, C, D, E, F, G>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -447,7 +580,16 @@ export function pipe<A, B, C, D, E, F, G>(
   ef: (e: E) => F,
   fg: (f: F) => G
 ): G
-export function pipe<A, B, C, D, E, F, G, H>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -457,7 +599,17 @@ export function pipe<A, B, C, D, E, F, G, H>(
   fg: (f: F) => G,
   gh: (g: G) => H
 ): H
-export function pipe<A, B, C, D, E, F, G, H, I>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -468,7 +620,18 @@ export function pipe<A, B, C, D, E, F, G, H, I>(
   gh: (g: G) => H,
   hi: (h: H) => I
 ): I
-export function pipe<A, B, C, D, E, F, G, H, I, J>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -480,7 +643,19 @@ export function pipe<A, B, C, D, E, F, G, H, I, J>(
   hi: (h: H) => I,
   ij: (i: I) => J
 ): J
-export function pipe<A, B, C, D, E, F, G, H, I, J, K>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -493,7 +668,20 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K>(
   ij: (i: I) => J,
   jk: (j: J) => K
 ): K
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -507,7 +695,21 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L>(
   jk: (j: J) => K,
   kl: (k: K) => L
 ): L
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -522,7 +724,22 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M>(
   kl: (k: K) => L,
   lm: (l: L) => M
 ): M
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -538,7 +755,23 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N>(
   lm: (l: L) => M,
   mn: (m: M) => N
 ): N
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -555,7 +788,24 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O>(
   mn: (m: M) => N,
   no: (n: N) => O
 ): O
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never,
+  P = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -573,7 +823,25 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>(
   no: (n: N) => O,
   op: (o: O) => P
 ): P
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never,
+  P = never,
+  Q = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -592,7 +860,26 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q>(
   op: (o: O) => P,
   pq: (p: P) => Q
 ): Q
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never,
+  P = never,
+  Q = never,
+  R = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -612,7 +899,27 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R>(
   pq: (p: P) => Q,
   qr: (q: Q) => R
 ): R
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never,
+  P = never,
+  Q = never,
+  R = never,
+  S = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -633,7 +940,28 @@ export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S>(
   qr: (q: Q) => R,
   rs: (r: R) => S
 ): S
-export function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T>(
+export function pipe<
+  A,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never,
+  K = never,
+  L = never,
+  M = never,
+  N = never,
+  O = never,
+  P = never,
+  Q = never,
+  R = never,
+  S = never,
+  T = never
+>(
   a: A,
   ab: (a: A) => B,
   bc: (b: B) => C,
@@ -712,27 +1040,54 @@ export function pipe(
  *
  * @since 2.0.0
  */
-export function flow<A extends ReadonlyArray<unknown>, B>(ab: (...a: A) => B): (...a: A) => B
-export function flow<A extends ReadonlyArray<unknown>, B, C>(ab: (...a: A) => B, bc: (b: B) => C): (...a: A) => C
-export function flow<A extends ReadonlyArray<unknown>, B, C, D>(
+export function flow<A extends ReadonlyArray<unknown>, B = never>(
+  ab: (...a: A) => B
+): (...a: A) => B
+export function flow<A extends ReadonlyArray<unknown>, B = never, C = never>(
   ab: (...a: A) => B,
-  bc: (b: B) => C,
-  cd: (c: C) => D
-): (...a: A) => D
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E>(
+  bc: (b: B) => C
+): (...a: A) => C
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never
+>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D): (...a: A) => D
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
   de: (d: D) => E
 ): (...a: A) => E
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F>(
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
   de: (d: D) => E,
   ef: (e: E) => F
 ): (...a: A) => F
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G>(
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
@@ -740,7 +1095,16 @@ export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G>(
   ef: (e: E) => F,
   fg: (f: F) => G
 ): (...a: A) => G
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H>(
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
@@ -749,7 +1113,17 @@ export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H>(
   fg: (f: F) => G,
   gh: (g: G) => H
 ): (...a: A) => H
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I>(
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,
@@ -759,7 +1133,18 @@ export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I>(
   gh: (g: G) => H,
   hi: (h: H) => I
 ): (...a: A) => I
-export function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J>(
+export function flow<
+  A extends ReadonlyArray<unknown>,
+  B = never,
+  C = never,
+  D = never,
+  E = never,
+  F = never,
+  G = never,
+  H = never,
+  I = never,
+  J = never
+>(
   ab: (...a: A) => B,
   bc: (b: B) => C,
   cd: (c: C) => D,

package/src/GroupBy.ts

@@ -59,10 +59,24 @@ export declare namespace GroupBy {
  * @category destructors
  */
 export const evaluate: {
+  /**
+   * Run the function across all groups, collecting the results in an
+   * arbitrary order.
+   *
+   * @since 2.0.0
+   * @category destructors
+   */
   <K, V, E, A, E2, R2>(
     f: (key: K, stream: Stream.Stream<V, E, never>) => Stream.Stream<A, E2, R2>,
     options?: { readonly bufferSize?: number | undefined } | undefined
   ): <R>(self: GroupBy<K, V, E, R>) => Stream.Stream<A, E | E2, R2 | R>
+  /**
+   * Run the function across all groups, collecting the results in an
+   * arbitrary order.
+   *
+   * @since 2.0.0
+   * @category destructors
+   */
   <K, V, E, R, A, E2, R2>(
     self: GroupBy<K, V, E, R>,
     f: (key: K, stream: Stream.Stream<V, E, never>) => Stream.Stream<A, E2, R2>,
@@ -77,7 +91,19 @@ export const evaluate: {
  * @category utils
  */
 export const filter: {
+  /**
+   * Filter the groups to be processed.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <K>(predicate: Predicate<NoInfer<K>>): <V, E, R>(self: GroupBy<K, V, E, R>) => GroupBy<K, V, E, R>
+  /**
+   * Filter the groups to be processed.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <K, V, E, R>(self: GroupBy<K, V, E, R>, predicate: Predicate<K>): GroupBy<K, V, E, R>
 } = internal.filter
 
@@ -88,7 +114,19 @@ export const filter: {
  * @category utils
  */
 export const first: {
+  /**
+   * Only consider the first `n` groups found in the `Stream`.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   (n: number): <K, V, E, R>(self: GroupBy<K, V, E, R>) => GroupBy<K, V, E, R>
+  /**
+   * Only consider the first `n` groups found in the `Stream`.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <K, V, E, R>(self: GroupBy<K, V, E, R>, n: number): GroupBy<K, V, E, R>
 } = internal.first
 

package/src/Hash.ts

@@ -162,7 +162,15 @@ export const array = <A>(arr: ReadonlyArray<A>) => {
  * @category hashing
  */
 export const cached: {
+  /**
+   * @since 2.0.0
+   * @category hashing
+   */
   (self: object): (hash: number) => number
+  /**
+   * @since 2.0.0
+   * @category hashing
+   */
   (self: object, hash: number): number
 } = function() {
   if (arguments.length === 1) {