feat: tapEither

gcanti · May 16, 2023 · fea57c0 · fea57c0
1 parent 8674480
commit fea57c0
Show file tree

Hide file tree

Showing 25 changed files with 927 additions and 294 deletions.
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**

diff --git a/docs/modules/Option.ts.md b/docs/modules/Option.ts.md
@@ -73,6 +73,7 @@ Added in v2.0.0
 
 - [combinators](#combinators)
   - [tap](#tap)
+  - [tapEither](#tapeither)
 - [constructors](#constructors)
   - [getLeft](#getleft)
   - [getRight](#getright)
@@ -137,6 +138,7 @@ Added in v2.0.0
 - [legacy](#legacy)
   - [chain](#chain)
   - [chainFirst](#chainfirst)
+  - [chainFirstEitherK](#chainfirsteitherk)
 - [lifting](#lifting)
   - [fromEitherK](#fromeitherk)
   - [fromNullableK](#fromnullablek)
@@ -158,7 +160,6 @@ Added in v2.0.0
   - [isSome](#issome)
 - [sequencing](#sequencing)
   - [chainEitherK](#chaineitherk)
-  - [chainFirstEitherK](#chainfirsteitherk)
   - [chainNullableK](#chainnullablek)
   - [flatMap](#flatmap)
   - [flatten](#flatten)
@@ -213,6 +214,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: {
+  <A, E, _>(self: Option<A>, f: (a: A) => Either<E, _>): Option<A>
+  <A, E, _>(f: (a: A) => Either<E, _>): (self: Option<A>) => Option<A>
+}
+```
+
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as O from 'fp-ts/Option'
+import * as E from 'fp-ts/Either'
+
+const compute = (value: number) =>
+  pipe(
+    O.of(value),
+    O.tapEither((value) => (value > 0 ? E.right('ok') : E.left('error')))
+  )
+
+assert.deepStrictEqual(compute(1), O.of(1))
+assert.deepStrictEqual(compute(-42), O.none)
+```
+
+Added in v2.16.0
+
 # constructors
 
 ## getLeft
@@ -1034,6 +1068,18 @@ export declare const chainFirst: <A, B>(f: (a: A) => Option<B>) => (first: Optio
 
 Added in v2.0.0
 
+## chainFirstEitherK
+
+Alias of `tapEither`.
+
+**Signature**
+
+```ts
+export declare const chainFirstEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma: Option<A>) => Option<A>
+```
+
+Added in v2.12.0
+
 # lifting
 
 ## fromEitherK
@@ -1300,16 +1346,6 @@ export declare const chainEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma:
 
 Added in v2.11.0
 
-## chainFirstEitherK
-
-**Signature**
-
-```ts
-export declare const chainFirstEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma: Option<A>) => Option<A>
-```
-
-Added in v2.12.0
-
 ## chainNullableK
 
 This is `chain` + `fromNullable`, useful when working with optional values.