update docs

gcanti · Apr 20, 2023 · b129121 · b129121
1 parent b52d3d2
commit b129121
Show file tree

Hide file tree

Showing 30 changed files with 440 additions and 173 deletions.
diff --git a/docs/modules/Array.ts.md b/docs/modules/Array.ts.md
@@ -112,6 +112,7 @@ Added in v2.0.0
   - [chainRecBreadthFirst](#chainrecbreadthfirst)
   - [chainRecDepthFirst](#chainrecdepthfirst)
   - [chainWithIndex](#chainwithindex)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
   - [traverseWithIndex](#traversewithindex)
 - [traversing](#traversing)
@@ -1701,33 +1702,14 @@ Added in v2.0.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to
-determine the next computation.
-
-In other words it takes a function `f` that produces an array from a single element of
-the base type `A` and returns a new function which applies `f` to each element of the
-input array (like [`map`](#map)) and, instead of returning an array of arrays, concatenates the
-results into a single array (like [`flatten`](#flatten)).
-
-This is the `chain` component of the array `Monad`.
+Alias of `flatMap`.
 
 **Signature**
 
 ```ts
 export declare const chain: <A, B>(f: (a: A) => B[]) => (ma: A[]) => B[]
 ```
 
-**Example**
-
-```ts
-import { chain, map, replicate } from 'fp-ts/Array'
-import { pipe } from 'fp-ts/function'
-
-const f = (n: number) => replicate(n, `${n}`)
-assert.deepStrictEqual(pipe([1, 2, 3], map(f)), [['1'], ['2', '2'], ['3', '3', '3']])
-assert.deepStrictEqual(pipe([1, 2, 3], chain(f)), ['1', '2', '2', '3', '3', '3'])
-```
-
 Added in v2.0.0
 
 ## chainFirst
@@ -1807,6 +1789,35 @@ assert.deepStrictEqual(pipe(['a', 'b', 'c'], chainWithIndex(f)), ['a0', 'a0', 'b
 
 Added in v2.7.0
 
+## flatMap
+
+Composes computations in sequence, using the return value of one computation to
+determine the next computation.
+
+In other words it takes a function `f` that produces an array from a single element of
+the base type `A` and returns a new function which applies `f` to each element of the
+input array (like [`map`](#map)) and, instead of returning an array of arrays, concatenates the
+results into a single array (like [`flatten`](#flatten)).
+
+**Signature**
+
+```ts
+export declare const flatMap: { <A, B>(f: (a: A) => B[]): (ma: A[]) => B[]; <A, B>(ma: A[], f: (a: A) => B[]): B[] }
+```
+
+**Example**
+
+```ts
+import { flatMap, map, replicate } from 'fp-ts/Array'
+import { pipe } from 'fp-ts/function'
+
+const f = (n: number) => replicate(n, `${n}`)
+assert.deepStrictEqual(pipe([1, 2, 3], map(f)), [['1'], ['2', '2'], ['3', '3', '3']])
+assert.deepStrictEqual(pipe([1, 2, 3], flatMap(f)), ['1', '2', '2', '3', '3', '3'])
+```
+
+Added in v2.14.0
+
 ## flatten
 
 Takes an array of arrays of `A` and flattens them into an array of `A`

diff --git a/docs/modules/Either.ts.md b/docs/modules/Either.ts.md
@@ -158,6 +158,7 @@ Added in v2.0.0
   - [chainOptionK](#chainoptionk)
   - [chainOptionKW](#chainoptionkw)
   - [chainW](#chainw)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
   - [flattenW](#flattenw)
 - [traversing](#traversing)
@@ -1327,7 +1328,7 @@ Added in v2.0.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to determine the next computation.
+Alias of `flatMap`.
 
 **Signature**
 
@@ -1408,40 +1409,28 @@ Added in v2.13.2
 
 ## chainW
 
-Less strict version of [`chain`](#chain).
-
-The `W` suffix (short for **W**idening) means that the error types will be merged.
+Alias of `flatMap`.
 
 **Signature**
 
 ```ts
 export declare const chainW: <E2, A, B>(f: (a: A) => Either<E2, B>) => <E1>(ma: Either<E1, A>) => Either<E2 | E1, B>
 ```
 
-**Example**
-
-```ts
-import * as E from 'fp-ts/Either'
-import { pipe } from 'fp-ts/function'
+Added in v2.6.0
 
-const e1: E.Either<string, number> = E.right(1)
-const e2: E.Either<number, number> = E.right(2)
+## flatMap
 
-export const result1 = pipe(
-  // @ts-expect-error
-  e1,
-  E.chain(() => e2)
-)
+**Signature**
 
-// merged error types -----v-------------v
-// const result2: E.Either<string | number, number>
-export const result2 = pipe(
-  e1, // no error
-  E.chainW(() => e2)
-)
+```ts
+export declare const flatMap: {
+  <A, E2, B>(f: (a: A) => Either<E2, B>): <E1>(ma: Either<E1, A>) => Either<E2 | E1, B>
+  <E1, A, E2, B>(ma: Either<E1, A>, f: (a: A) => Either<E2, B>): Either<E1 | E2, B>
+}
 ```
 
-Added in v2.6.0
+Added in v2.14.0
 
 ## flatten
 

diff --git a/docs/modules/IO.ts.md b/docs/modules/IO.ts.md
@@ -50,6 +50,7 @@ Added in v2.0.0
 - [sequencing](#sequencing)
   - [chain](#chain)
   - [chainFirst](#chainfirst)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
 - [traversing](#traversing)
   - [sequenceArray](#sequencearray)
@@ -281,7 +282,7 @@ Added in v2.0.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to determine the next computation.
+Alias of `flatMap`.
 
 **Signature**
 
@@ -304,6 +305,19 @@ export declare const chainFirst: <A, B>(f: (a: A) => IO<B>) => (first: IO<A>) =>
 
 Added in v2.0.0
 
+## flatMap
+
+**Signature**
+
+```ts
+export declare const flatMap: {
+  <A, B>(f: (a: A) => IO<B>): (ma: IO<A>) => IO<B>
+  <A, B>(ma: IO<A>, f: (a: A) => IO<B>): IO<B>
+}
+```
+
+Added in v2.14.0
+
 ## flatten
 
 **Signature**

diff --git a/docs/modules/IOEither.ts.md b/docs/modules/IOEither.ts.md
@@ -104,6 +104,7 @@ Added in v2.0.0
   - [chainOptionK](#chainoptionk)
   - [chainOptionKW](#chainoptionkw)
   - [chainW](#chainw)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
   - [flattenW](#flattenw)
 - [traversing](#traversing)
@@ -917,7 +918,7 @@ Added in v2.10.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to determine the next computation.
+Alias of `flatMap`.
 
 **Signature**
 
@@ -1056,9 +1057,7 @@ Added in v2.13.2
 
 ## chainW
 
-Less strict version of [`chain`](#chain).
-
-The `W` suffix (short for **W**idening) means that the error types will be merged.
+Alias of `flatMap`.
 
 **Signature**
 
@@ -1070,6 +1069,19 @@ export declare const chainW: <E2, A, B>(
 
 Added in v2.6.0
 
+## flatMap
+
+**Signature**
+
+```ts
+export declare const flatMap: {
+  <A, E2, B>(f: (a: A) => IOEither<E2, B>): <E1>(ma: IOEither<E1, A>) => IOEither<E2 | E1, B>
+  <E1, A, E2, B>(ma: IOEither<E1, A>, f: (a: A) => IOEither<E2, B>): IOEither<E1 | E2, B>
+}
+```
+
+Added in v2.14.0
+
 ## flatten
 
 **Signature**

diff --git a/docs/modules/IOOption.ts.md b/docs/modules/IOOption.ts.md
@@ -89,6 +89,7 @@ Added in v2.12.0
   - [chainIOK](#chainiok)
   - [chainNullableK](#chainnullablek)
   - [chainOptionK](#chainoptionk)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
 - [traversing](#traversing)
   - [traverseReadonlyArrayWithIndex](#traversereadonlyarraywithindex)
@@ -714,6 +715,8 @@ Added in v2.12.0
 
 ## chain
 
+Alias of `flatMap`.
+
 **Signature**
 
 ```ts
@@ -797,6 +800,19 @@ export declare const chainOptionK: <A, B>(f: (a: A) => O.Option<B>) => (ma: IOOp
 
 Added in v2.12.0
 
+## flatMap
+
+**Signature**
+
+```ts
+export declare const flatMap: {
+  <A, B>(f: (a: A) => IOOption<B>): (ma: IOOption<A>) => IOOption<B>
+  <A, B>(ma: IOOption<A>, f: (a: A) => IOOption<B>): IOOption<B>
+}
+```
+
+Added in v2.14.0
+
 ## flatten
 
 **Signature**

diff --git a/docs/modules/Identity.ts.md b/docs/modules/Identity.ts.md
@@ -51,6 +51,7 @@ Added in v2.0.0
 - [sequencing](#sequencing)
   - [chain](#chain)
   - [chainFirst](#chainfirst)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
 - [traversing](#traversing)
   - [sequence](#sequence)
@@ -388,7 +389,7 @@ Added in v2.0.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to determine the next computation.
+Alias of `flatMap`.
 
 **Signature**
 
@@ -411,6 +412,16 @@ export declare const chainFirst: <A, B>(f: (a: A) => B) => (first: A) => A
 
 Added in v2.0.0
 
+## flatMap
+
+**Signature**
+
+```ts
+export declare const flatMap: { <A, B>(f: (a: A) => B): (ma: A) => B; <A, B>(ma: A, f: (a: A) => B): B }
+```
+
+Added in v2.14.0
+
 ## flatten
 
 **Signature**

diff --git a/docs/modules/NonEmptyArray.ts.md b/docs/modules/NonEmptyArray.ts.md
@@ -77,6 +77,7 @@ Added in v2.0.0
   - [chain](#chain)
   - [chainFirst](#chainfirst)
   - [chainWithIndex](#chainwithindex)
+  - [flatMap](#flatmap)
   - [flatten](#flatten)
   - [traverseWithIndex](#traversewithindex)
 - [traversing](#traversing)
@@ -686,29 +687,14 @@ Added in v2.11.0
 
 ## chain
 
-Composes computations in sequence, using the return value of one computation to determine the next computation.
+Alias of `flatMap`.
 
 **Signature**
 
 ```ts
 export declare const chain: <A, B>(f: (a: A) => NonEmptyArray<B>) => (ma: NonEmptyArray<A>) => NonEmptyArray<B>
 ```
 
-**Example**
-
-```ts
-import * as NEA from 'fp-ts/NonEmptyArray'
-import { pipe } from 'fp-ts/function'
-
-assert.deepStrictEqual(
-  pipe(
-    [1, 2, 3],
-    NEA.chain((n) => [`a${n}`, `b${n}`])
-  ),
-  ['a1', 'b1', 'a2', 'b2', 'a3', 'b3']
-)
-```
-
 Added in v2.0.0
 
 ## chainFirst
@@ -736,6 +722,34 @@ export declare const chainWithIndex: <A, B>(
 
 Added in v2.10.0
 
+## flatMap
+
+**Signature**
+
+```ts
+export declare const flatMap: {
+  <A, B>(f: (a: A) => NonEmptyArray<B>): (ma: NonEmptyArray<A>) => NonEmptyArray<B>
+  <A, B>(ma: NonEmptyArray<A>, f: (a: A) => NonEmptyArray<B>): NonEmptyArray<B>
+}
+```
+
+**Example**
+
+```ts
+import * as NEA from 'fp-ts/NonEmptyArray'
+import { pipe } from 'fp-ts/function'
+
+assert.deepStrictEqual(
+  pipe(
+    [1, 2, 3],
+    NEA.flatMap((n) => [`a${n}`, `b${n}`])
+  ),
+  ['a1', 'b1', 'a2', 'b2', 'a3', 'b3']
+)
+```
+
+Added in v2.14.0
+
 ## flatten
 
 **Signature**