add more flatMap* dual functions

CHANGELOG.md

@@ -38,6 +38,39 @@ high state of flux, you're at risk of it changing without notice.
   - `Task`
   - `TaskEither`
   - `TaskOption`
+- add `flatMapNullable` (dual) to
+  - `Either`
+  - `IOEither`
+  - `ReaderEither`
+  - `ReaderTaskEither`
+  - `StateReaderTaskEither`
+  - `TaskEither`
+- add `flatMapOption` (dual) to
+  - `Either`
+  - `IOEither`
+  - `ReaderEither`
+  - `ReaderTaskEither`
+  - `StateReaderTaskEither`
+  - `TaskEither`
+- add `liftNullable` to
+  - `Either`
+  - `IOEither`
+  - `ReaderEither`
+  - `ReaderTaskEither`
+  - `StateReaderTaskEither`
+  - `TaskEither`
+- add `liftOption` to
+  - `Either`
+  - `IOEither`
+  - `ReaderEither`
+  - `ReaderTaskEither`
+  - `StateReaderTaskEither`
+  - `TaskEither`
+- add `flatMapEither` (dual) to
+  - `IOEither`
+  - `ReaderEither`
+  - `ReaderTaskEither`
+  - `TaskEither`
 - `Array`
   - add index to `flatMap`
 - `NonEmptyArray`

Do.md

@@ -2,11 +2,11 @@
 
 **Cheatsheet**
 
-| Haskell       | TypeScript                      |
-| ------------- | ------------------------------- |
-| `a <- action` | `bind('a', (scope) => action)`  |
-| `_ <- action` | `chainFirst((scope) => action)` |
-| `return ...`  | `map((scope) => ...)`           |
+| Haskell       | TypeScript                     |
+| ------------- | ------------------------------ |
+| `a <- action` | `bind('a', (scope) => action)` |
+| `_ <- action` | `tap((scope) => action)`       |
+| `return ...`  | `map((scope) => ...)`          |
 
 **Example**
 
@@ -33,9 +33,9 @@ declare const getLine: T.Task<string>
 
 const nameDo: T.Task<void> = pipe(
   T.Do,
-  T.chainFirst(() => putStrLn('What is your first name? ')),
+  T.tap(() => putStrLn('What is your first name? ')),
   T.bind('first', () => getLine),
-  T.chainFirst(() => putStrLn('And your last name? ')),
+  T.tap(() => putStrLn('And your last name? ')),
   T.bind('last', () => getLine),
   T.bind('full', ({ first, last }) => T.of(first + ' ' + last)),
   T.flatMap(({ full }) => putStrLn('Pleased to meet you, ' + full + '!'))

docs/guides/do-notation.md

@@ -27,14 +27,14 @@ declare const readLine: T.Task<string>
 const main: T.Task<{ x: string; y: string }> = pipe(
   readLine,
   T.map((x) => ({ x })),
-  T.chain(({ x }) =>
+  T.flatMap(({ x }) =>
     pipe(
       readLine,
       T.map((y) => ({ x, y }))
     )
   ),
-  T.chainFirst(({ x }) => print(x)),
-  T.chainFirst(({ y }) => print(y))
+  T.tap(({ x }) => print(x)),
+  T.tap(({ y }) => print(y))
 )
 ```
 
@@ -48,8 +48,8 @@ const mainDo: T.Task<{ x: string; y: string }> = pipe(
   T.Do,
   T.bind('x', () => readLine),
   T.bind('y', () => readLine),
-  T.chainFirst(({ x }) => print(x)),
-  T.chainFirst(({ y }) => print(y))
+  T.tap(({ x }) => print(x)),
+  T.tap(({ y }) => print(y))
 )
 ```
 
@@ -85,8 +85,8 @@ const mainDo: IO.IO<{ x: string; y: string }> = pipe(
   IO.Do,
   IO.bind('x', () => readLine),
   IO.bind('y', () => readLine),
-  IO.chainFirst(({ x }) => print(x)),
-  IO.chainFirst(({ y }) => print(y))
+  IO.tap(({ x }) => print(x)),
+  IO.tap(({ y }) => print(y))
 )
 ```
 
@@ -105,8 +105,8 @@ pipe(
   readLine,
   T.bindTo('x'),
   T.bind('y', () => readLine),
-  T.chainFirst(({ x }) => print(x)),
-  T.chainFirst(({ y }) => print(y))
+  T.tap(({ x }) => print(x)),
+  T.tap(({ y }) => print(y))
 )
 ```
 

docs/guides/purescript.md

@@ -33,10 +33,10 @@ declare const readLine: T.Task<string>
 
 pipe(
   T.Do,
-  T.chainFirst(() => print('foo')),
-  T.chainFirst(() => print('bar')),
+  T.tap(() => print('foo')),
+  T.tap(() => print('bar')),
   T.bind('x', () => readLine),
-  T.chain(({ x }) => print(x))
+  T.flatMap(({ x }) => print(x))
 )
 ```
 
@@ -123,14 +123,16 @@ TypeScript
 
 ```ts
 // here TypeScript also provides exhaustiveness check
-const maybe = <A, B>(onNone: () => B, onSome: (a: A) => B) => (fa: Option<A>): B => {
-  switch (fa._tag) {
-    case 'None':
-      return onNone()
-    case 'Some':
-      return onSome(fa.value)
+const maybe =
+  <A, B>(onNone: () => B, onSome: (a: A) => B) =>
+  (fa: Option<A>): B => {
+    switch (fa._tag) {
+      case 'None':
+        return onNone()
+      case 'Some':
+        return onSome(fa.value)
+    }
   }
-}
 ```
 
 ## Type classes

docs/modules/Either.ts.md

@@ -136,11 +136,16 @@ Added in v2.0.0
   - [chain](#chain)
   - [chainFirst](#chainfirst)
   - [chainFirstW](#chainfirstw)
+  - [chainNullableK](#chainnullablek)
+  - [chainOptionK](#chainoptionk)
+  - [chainOptionKW](#chainoptionkw)
   - [chainW](#chainw)
-- [lifting](#lifting)
   - [fromNullableK](#fromnullablek)
   - [fromOptionK](#fromoptionk)
+- [lifting](#lifting)
   - [fromPredicate](#frompredicate)
+  - [liftNullable](#liftnullable)
+  - [liftOption](#liftoption)
 - [mapping](#mapping)
   - [bimap](#bimap)
   - [flap](#flap)
@@ -158,10 +163,9 @@ Added in v2.0.0
   - [isLeft](#isleft)
   - [isRight](#isright)
 - [sequencing](#sequencing)
-  - [chainNullableK](#chainnullablek)
-  - [chainOptionK](#chainoptionk)
-  - [chainOptionKW](#chainoptionkw)
   - [flatMap](#flatmap)
+  - [flatMapNullable](#flatmapnullable)
+  - [flatMapOption](#flatmapoption)
   - [flatten](#flatten)
   - [flattenW](#flattenw)
 - [traversing](#traversing)
@@ -684,9 +688,9 @@ Added in v2.10.0
 
 ```ts
 export declare const filterOrElse: {
-  <A, B, E>(refinement: Refinement<A, B>, onFalse: (a: A) => E): (ma: Either<E, A>) => Either<E, B>
-  <A, E>(predicate: Predicate<A>, onFalse: (a: A) => E): <B>(mb: Either<E, B>) => Either<E, B>
-  <A, E>(predicate: Predicate<A>, onFalse: (a: A) => E): (ma: Either<E, A>) => Either<E, A>
+  <A, B extends A, E>(refinement: Refinement<A, B>, onFalse: (a: A) => E): (self: Either<E, A>) => Either<E, B>
+  <A, E>(predicate: Predicate<A>, onFalse: (a: A) => E): <B extends A>(self: Either<E, B>) => Either<E, B>
+  <A, E>(predicate: Predicate<A>, onFalse: (a: A) => E): (self: Either<E, A>) => Either<E, A>
 }
 ```
 
@@ -1148,6 +1152,48 @@ export declare const chainFirstW: <E2, A, B>(
 
 Added in v2.8.0
 
+## chainNullableK
+
+Use `flatMapNullable`.
+
+**Signature**
+
+```ts
+export declare const chainNullableK: <E>(
+  e: E
+) => <A, B>(f: (a: A) => B | null | undefined) => (ma: Either<E, A>) => Either<E, NonNullable<B>>
+```
+
+Added in v2.9.0
+
+## chainOptionK
+
+Use `flatMapOption`.
+
+**Signature**
+
+```ts
+export declare const chainOptionK: <E>(
+  onNone: LazyArg<E>
+) => <A, B>(f: (a: A) => Option<B>) => (ma: Either<E, A>) => Either<E, B>
+```
+
+Added in v2.11.0
+
+## chainOptionKW
+
+Use `flatMapOption`.
+
+**Signature**
+
+```ts
+export declare const chainOptionKW: <E2>(
+  onNone: LazyArg<E2>
+) => <A, B>(f: (a: A) => Option<B>) => <E1>(ma: Either<E1, A>) => Either<E2 | E1, B>
+```
+
+Added in v2.13.2
+
 ## chainW
 
 Alias of `flatMap`.
@@ -1160,10 +1206,10 @@ export declare const chainW: <E2, A, B>(f: (a: A) => Either<E2, B>) => <E1>(ma:
 
 Added in v2.6.0
 
-# lifting
-
 ## fromNullableK
 
+Use `liftNullable`.
+
 **Signature**
 
 ```ts
@@ -1176,6 +1222,8 @@ Added in v2.9.0
 
 ## fromOptionK
 
+Use `liftOption`.
+
 **Signature**
 
 ```ts
@@ -1186,6 +1234,8 @@ export declare const fromOptionK: <E>(
 
 Added in v2.10.0
 
+# lifting
+
 ## fromPredicate
 
 **Signature**
@@ -1228,6 +1278,32 @@ assert.deepStrictEqual(
 
 Added in v2.0.0
 
+## liftNullable
+
+**Signature**
+
+```ts
+export declare const liftNullable: <A extends readonly unknown[], B, E>(
+  f: (...a: A) => B | null | undefined,
+  onNullable: (...a: A) => E
+) => (...a: A) => Either<E, NonNullable<B>>
+```
+
+Added in v2.15.0
+
+## liftOption
+
+**Signature**
+
+```ts
+export declare const liftOption: <A extends readonly unknown[], B, E>(
+  f: (...a: A) => Option<B>,
+  onNone: (...a: A) => E
+) => (...a: A) => Either<E, B>
+```
+
+Added in v2.15.0
+
 # mapping
 
 ## bimap
@@ -1399,58 +1475,49 @@ Added in v2.0.0
 
 # sequencing
 
-## chainNullableK
-
-**Signature**
-
-```ts
-export declare const chainNullableK: <E>(
-  e: E
-) => <A, B>(f: (a: A) => B | null | undefined) => (ma: Either<E, A>) => Either<E, NonNullable<B>>
-```
-
-Added in v2.9.0
-
-## chainOptionK
+## flatMap
 
 **Signature**
 
 ```ts
-export declare const chainOptionK: <E>(
-  onNone: LazyArg<E>
-) => <A, B>(f: (a: A) => Option<B>) => (ma: Either<E, A>) => Either<E, B>
+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.11.0
-
-## chainOptionKW
+Added in v2.14.0
 
-Less strict version of [`chainOptionK`](#chainoptionk).
-
-The `W` suffix (short for **W**idening) means that the error types will be merged.
+## flatMapNullable
 
 **Signature**
 
 ```ts
-export declare const chainOptionKW: <E2>(
-  onNone: LazyArg<E2>
-) => <A, B>(f: (a: A) => Option<B>) => <E1>(ma: Either<E1, A>) => Either<E2 | E1, B>
+export declare const flatMapNullable: {
+  <A, B, E2>(f: (a: A) => B | null | undefined, onNullable: (a: A) => E2): <E1>(
+    self: Either<E1, A>
+  ) => Either<E2 | E1, NonNullable<B>>
+  <E1, A, B, E2>(self: Either<E1, A>, f: (a: A) => B | null | undefined, onNullable: (a: A) => E2): Either<
+    E1 | E2,
+    NonNullable<B>
+  >
+}
 ```
 
-Added in v2.13.2
+Added in v2.15.0
 
-## flatMap
+## flatMapOption
 
 **Signature**
 
 ```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>
+export declare const flatMapOption: {
+  <A, B, E2>(f: (a: A) => Option<B>, onNone: (a: A) => E2): <E1>(self: Either<E1, A>) => Either<E2 | E1, B>
+  <E1, A, B, E2>(self: Either<E1, A>, f: (a: A) => Option<B>, onNone: (a: A) => E2): Either<E1 | E2, B>
 }
 ```
 
-Added in v2.14.0
+Added in v2.15.0
 
 ## flatten