feat: tapEither

gcanti · May 15, 2023 · 93ac4e6 · 93ac4e6
1 parent 8674480
commit 93ac4e6
Show file tree

Hide file tree

Showing 26 changed files with 1,013 additions and 332 deletions.
diff --git a/docs/modules/FromEither.ts.md b/docs/modules/FromEither.ts.md
@@ -16,6 +16,8 @@ Added in v2.10.0
 
 - [constructors](#constructors)
   - [fromOption](#fromoption)
+- [legacy](#legacy)
+  - [chainFirstEitherK](#chainfirsteitherk)
 - [lifting](#lifting)
   - [fromPredicate](#frompredicate)
 - [model](#model)
@@ -28,11 +30,11 @@ Added in v2.10.0
   - [FromEither4 (interface)](#fromeither4-interface)
 - [utils](#utils)
   - [chainEitherK](#chaineitherk)
-  - [chainFirstEitherK](#chainfirsteitherk)
   - [chainOptionK](#chainoptionk)
   - [filterOrElse](#filterorelse)
   - [fromEitherK](#fromeitherk)
   - [fromOptionK](#fromoptionk)
+  - [tapEither](#tapeither)
 
 ---
 
@@ -63,6 +65,47 @@ export declare function fromOption<F>(F: FromEither<F>): <E>(onNone: LazyArg<E>)
 
 Added in v2.10.0
 
+# legacy
+
+## chainFirstEitherK
+
+Alias of `tapEither`.
+
+**Signature**
+
+```ts
+export declare function chainFirstEitherK<M extends URIS4>(
+  F: FromEither4<M>,
+  M: Chain4<M>
+): <A, E, B>(f: (a: A) => Either<E, B>) => <S, R>(ma: Kind4<M, S, R, E, A>) => Kind4<M, S, R, E, A>
+export declare function chainFirstEitherK<M extends URIS3>(
+  F: FromEither3<M>,
+  M: Chain3<M>
+): <A, E, B>(f: (a: A) => Either<E, B>) => <R>(ma: Kind3<M, R, E, A>) => Kind3<M, R, E, A>
+export declare function chainFirstEitherK<M extends URIS3, E>(
+  F: FromEither3C<M, E>,
+  M: Chain3C<M, E>
+): <A, B>(f: (a: A) => Either<E, B>) => <R>(ma: Kind3<M, R, E, A>) => Kind3<M, R, E, A>
+export declare function chainFirstEitherK<M extends URIS2>(
+  F: FromEither2<M>,
+  M: Chain2<M>
+): <A, E, B>(f: (a: A) => Either<E, B>) => (ma: Kind2<M, E, A>) => Kind2<M, E, A>
+export declare function chainFirstEitherK<M extends URIS2, E>(
+  F: FromEither2C<M, E>,
+  M: Chain2C<M, E>
+): <A, B>(f: (a: A) => Either<E, B>) => (ma: Kind2<M, E, A>) => Kind2<M, E, A>
+export declare function chainFirstEitherK<M extends URIS>(
+  F: FromEither1<M>,
+  M: Chain1<M>
+): <E, A, B>(f: (a: A) => Either<E, B>) => (ma: Kind<M, A>) => Kind<M, A>
+export declare function chainFirstEitherK<M>(
+  F: FromEither<M>,
+  M: Chain<M>
+): <A, E, B>(f: (a: A) => Either<E, B>) => (ma: HKT2<M, E, A>) => HKT2<M, E, A>
+```
+
+Added in v2.12.0
+
 # lifting
 
 ## fromPredicate
@@ -248,43 +291,6 @@ export declare function chainEitherK<M>(
 
 Added in v2.10.0
 
-## chainFirstEitherK
-
-**Signature**
-
-```ts
-export declare function chainFirstEitherK<M extends URIS4>(
-  F: FromEither4<M>,
-  M: Chain4<M>
-): <A, E, B>(f: (a: A) => Either<E, B>) => <S, R>(ma: Kind4<M, S, R, E, A>) => Kind4<M, S, R, E, A>
-export declare function chainFirstEitherK<M extends URIS3>(
-  F: FromEither3<M>,
-  M: Chain3<M>
-): <A, E, B>(f: (a: A) => Either<E, B>) => <R>(ma: Kind3<M, R, E, A>) => Kind3<M, R, E, A>
-export declare function chainFirstEitherK<M extends URIS3, E>(
-  F: FromEither3C<M, E>,
-  M: Chain3C<M, E>
-): <A, B>(f: (a: A) => Either<E, B>) => <R>(ma: Kind3<M, R, E, A>) => Kind3<M, R, E, A>
-export declare function chainFirstEitherK<M extends URIS2>(
-  F: FromEither2<M>,
-  M: Chain2<M>
-): <A, E, B>(f: (a: A) => Either<E, B>) => (ma: Kind2<M, E, A>) => Kind2<M, E, A>
-export declare function chainFirstEitherK<M extends URIS2, E>(
-  F: FromEither2C<M, E>,
-  M: Chain2C<M, E>
-): <A, B>(f: (a: A) => Either<E, B>) => (ma: Kind2<M, E, A>) => Kind2<M, E, A>
-export declare function chainFirstEitherK<M extends URIS>(
-  F: FromEither1<M>,
-  M: Chain1<M>
-): <E, A, B>(f: (a: A) => Either<E, B>) => (ma: Kind<M, A>) => Kind<M, A>
-export declare function chainFirstEitherK<M>(
-  F: FromEither<M>,
-  M: Chain<M>
-): <A, E, B>(f: (a: A) => Either<E, B>) => (ma: HKT2<M, E, A>) => HKT2<M, E, A>
-```
-
-Added in v2.12.0
-
 ## chainOptionK
 
 **Signature**
@@ -449,3 +455,40 @@ export declare function fromOptionK<F>(
 ```
 
 Added in v2.10.0
+
+## tapEither
+
+**Signature**
+
+```ts
+export declare function tapEither<M extends URIS4>(
+  F: FromEither4<M>,
+  M: Chain4<M>
+): <A, E, B, S, R>(self: Kind4<M, S, R, E, A>, f: (a: A) => Either<E, B>) => Kind4<M, S, R, E, A>
+export declare function tapEither<M extends URIS3>(
+  F: FromEither3<M>,
+  M: Chain3<M>
+): <A, E, B, R>(self: Kind3<M, R, E, A>, f: (a: A) => Either<E, B>) => Kind3<M, R, E, A>
+export declare function tapEither<M extends URIS3, E>(
+  F: FromEither3C<M, E>,
+  M: Chain3C<M, E>
+): <A, B, R>(self: Kind3<M, R, E, A>, f: (a: A) => Either<E, B>) => Kind3<M, R, E, A>
+export declare function tapEither<M extends URIS2>(
+  F: FromEither2<M>,
+  M: Chain2<M>
+): <A, E, B>(self: Kind2<M, E, A>, f: (a: A) => Either<E, B>) => Kind2<M, E, A>
+export declare function tapEither<M extends URIS2, E>(
+  F: FromEither2C<M, E>,
+  M: Chain2C<M, E>
+): <A, B>(self: Kind2<M, E, A>, f: (a: A) => Either<E, B>) => Kind2<M, E, A>
+export declare function tapEither<M extends URIS>(
+  F: FromEither1<M>,
+  M: Chain1<M>
+): <E, A, B>(self: Kind<M, A>, f: (a: A) => Either<E, B>) => Kind<M, A>
+export declare function tapEither<M>(
+  F: FromEither<M>,
+  M: Chain<M>
+): <A, E, B>(self: HKT2<M, E, A>, f: (a: A) => Either<E, B>) => HKT2<M, E, A>
+```
+
+Added in v2.16.0
diff --git a/docs/modules/IOEither.ts.md b/docs/modules/IOEither.ts.md
@@ -20,6 +20,7 @@ Added in v2.0.0
 
 - [combinators](#combinators)
   - [tap](#tap)
+  - [tapEither](#tapeither)
 - [constructors](#constructors)
   - [left](#left)
   - [leftIO](#leftio)
@@ -79,6 +80,8 @@ Added in v2.0.0
   - [chainEitherK](#chaineitherk)
   - [chainEitherKW](#chaineitherkw)
   - [chainFirst](#chainfirst)
+  - [chainFirstEitherK](#chainfirsteitherk)
+  - [chainFirstEitherKW](#chainfirsteitherkw)
   - [chainFirstW](#chainfirstw)
   - [chainOptionK](#chainoptionk)
   - [chainOptionKW](#chainoptionkw)
@@ -106,8 +109,6 @@ Added in v2.0.0
   - [matchEW](#matchew)
   - [matchW](#matchw)
 - [sequencing](#sequencing)
-  - [chainFirstEitherK](#chainfirsteitherk)
-  - [chainFirstEitherKW](#chainfirsteitherkw)
   - [chainFirstIOK](#chainfirstiok)
   - [chainIOK](#chainiok)
   - [flatMap](#flatmap)
@@ -170,6 +171,39 @@ export declare const tap: {
 
 Added in v2.15.0
 
+## tapEither
+
+Composes computations in sequence, using the return value of one computation to determine the next computation and
+keeping only the result of the first.
+
+**Signature**
+
+```ts
+export declare const tapEither: {
+  <E1, A, E2, _>(self: IOEither<E1, A>, f: (a: A) => E.Either<E2, _>): IOEither<E1 | E2, A>
+  <A, E2, _>(f: (a: A) => E.Either<E2, _>): <E1>(self: IOEither<E1, A>) => IOEither<E2 | E1, A>
+}
+```
+
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as IOE from 'fp-ts/IOEither'
+import * as E from 'fp-ts/Either'
+
+const compute = (value: string) =>
+  pipe(
+    IOE.of(value),
+    IOE.tapEither(() => (value.length > 0 ? E.right('ok') : E.left('error')))
+  )
+
+assert.deepStrictEqual(compute('')(), E.left('error'))
+assert.deepStrictEqual(compute('fp-ts')(), E.right('fp-ts'))
+```
+
+Added in v2.16.0
+
 # constructors
 
 ## left
@@ -794,6 +828,34 @@ export declare const chainFirst: <E, A, B>(f: (a: A) => IOEither<E, B>) => (ma:
 
 Added in v2.0.0
 
+## chainFirstEitherK
+
+Alias of `tapEither`.
+
+**Signature**
+
+```ts
+export declare const chainFirstEitherK: <A, E, B>(f: (a: A) => E.Either<E, B>) => (ma: IOEither<E, A>) => IOEither<E, A>
+```
+
+Added in v2.12.0
+
+## chainFirstEitherKW
+
+Alias of `tapEither`.
+
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
+**Signature**
+
+```ts
+export declare const chainFirstEitherKW: <A, E2, B>(
+  f: (a: A) => E.Either<E2, B>
+) => <E1>(ma: IOEither<E1, A>) => IOEither<E2 | E1, A>
+```
+
+Added in v2.12.0
+
 ## chainFirstW
 
 Alias of `tap`.
@@ -1098,30 +1160,6 @@ Added in v2.10.0
 
 # sequencing
 
-## chainFirstEitherK
-
-**Signature**
-
-```ts
-export declare const chainFirstEitherK: <A, E, B>(f: (a: A) => E.Either<E, B>) => (ma: IOEither<E, A>) => IOEither<E, A>
-```
-
-Added in v2.12.0
-
-## chainFirstEitherKW
-
-The `W` suffix (short for **W**idening) means that the error types will be merged.
-
-**Signature**
-
-```ts
-export declare const chainFirstEitherKW: <A, E2, B>(
-  f: (a: A) => E.Either<E2, B>
-) => <E1>(ma: IOEither<E1, A>) => IOEither<E2 | E1, A>
-```
-
-Added in v2.12.0
-
 ## chainFirstIOK
 
 **Signature**

diff --git a/docs/modules/IOOption.ts.md b/docs/modules/IOOption.ts.md
@@ -19,6 +19,7 @@ Added in v2.12.0
 
 - [combinators](#combinators)
   - [tap](#tap)
+  - [tapEither](#tapeither)
 - [constructors](#constructors)
   - [none](#none)
   - [of](#of)
@@ -68,6 +69,7 @@ Added in v2.12.0
 - [legacy](#legacy)
   - [chain](#chain)
   - [chainFirst](#chainfirst)
+  - [chainFirstEitherK](#chainfirsteitherk)
 - [lifting](#lifting)
   - [fromEitherK](#fromeitherk)
   - [fromIOK](#fromiok)
@@ -87,7 +89,6 @@ Added in v2.12.0
   - [matchW](#matchw)
 - [sequencing](#sequencing)
   - [chainEitherK](#chaineitherk)
-  - [chainFirstEitherK](#chainfirsteitherk)
   - [chainFirstIOK](#chainfirstiok)
   - [chainIOK](#chainiok)
   - [chainNullableK](#chainnullablek)
@@ -127,6 +128,40 @@ export declare const tap: {
 
 Added in v2.15.0
 
+## tapEither
+
+Composes computations in sequence, using the return value of one computation to determine the next computation and
+keeping only the result of the first.
+
+**Signature**
+
+```ts
+export declare const tapEither: {
+  <A, E, _>(self: IOOption<A>, f: (a: A) => Either<E, _>): IOOption<A>
+  <A, E, _>(f: (a: A) => Either<E, _>): (self: IOOption<A>) => IOOption<A>
+}
+```
+
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as IOO from 'fp-ts/IOOption'
+import * as O from 'fp-ts/Option'
+import * as E from 'fp-ts/Either'
+
+const compute = (value: number) =>
+  pipe(
+    IOO.of(value),
+    IOO.tapEither((value) => (value > 0 ? E.right('ok') : E.left('error')))
+  )
+
+assert.deepStrictEqual(compute(1)(), O.of(1))
+assert.deepStrictEqual(compute(-1)(), O.none)
+```
+
+Added in v2.16.0
+
 # constructors
 
 ## none
@@ -592,6 +627,18 @@ export declare const chainFirst: <A, B>(f: (a: A) => IOOption<B>) => (first: IOO
 
 Added in v2.12.0
 
+## chainFirstEitherK
+
+Alias of `tapEither`.
+
+**Signature**
+
+```ts
+export declare const chainFirstEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma: IOOption<A>) => IOOption<A>
+```
+
+Added in v2.12.0
+
 # lifting
 
 ## fromEitherK
@@ -770,16 +817,6 @@ export declare const chainEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma:
 
 Added in v2.12.0
 
-## chainFirstEitherK
-
-**Signature**
-
-```ts
-export declare const chainFirstEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma: IOOption<A>) => IOOption<A>
-```
-
-Added in v2.12.0
-
 ## chainFirstIOK
 
 **Signature**