feat: tapIO

gcanti · May 16, 2023 · 26c6c1a · 26c6c1a
1 parent c8a9ae9
commit 26c6c1a
Show file tree

Hide file tree

Showing 28 changed files with 949 additions and 215 deletions.
diff --git a/docs/modules/IOEither.ts.md b/docs/modules/IOEither.ts.md
@@ -21,6 +21,7 @@ Added in v2.0.0
 - [combinators](#combinators)
   - [tap](#tap)
   - [tapEither](#tapeither)
+  - [tapIO](#tapio)
 - [constructors](#constructors)
   - [left](#left)
   - [leftIO](#leftio)
@@ -82,6 +83,7 @@ Added in v2.0.0
   - [chainFirst](#chainfirst)
   - [chainFirstEitherK](#chainfirsteitherk)
   - [chainFirstEitherKW](#chainfirsteitherkw)
+  - [chainFirstIOK](#chainfirstiok)
   - [chainFirstW](#chainfirstw)
   - [chainOptionK](#chainoptionk)
   - [chainOptionKW](#chainoptionkw)
@@ -109,7 +111,6 @@ Added in v2.0.0
   - [matchEW](#matchew)
   - [matchW](#matchw)
 - [sequencing](#sequencing)
-  - [chainFirstIOK](#chainfirstiok)
   - [chainIOK](#chainiok)
   - [flatMap](#flatmap)
   - [flatMapEither](#flatmapeither)
@@ -204,6 +205,39 @@ assert.deepStrictEqual(compute('fp-ts')(), E.right('fp-ts'))
 
 Added in v2.16.0
 
+## tapIO
+
+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 tapIO: {
+  <E, A, _>(self: IOEither<E, A>, f: (a: A) => I.IO<_>): IOEither<E, A>
+  <A, _>(f: (a: A) => I.IO<_>): <E>(self: IOEither<E, A>) => IOEither<E, 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
@@ -856,6 +890,18 @@ export declare const chainFirstEitherKW: <A, E2, B>(
 
 Added in v2.12.0
 
+## chainFirstIOK
+
+Alias of `tapIO`.
+
+**Signature**
+
+```ts
+export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => <E>(first: IOEither<E, A>) => IOEither<E, A>
+```
+
+Added in v2.10.0
+
 ## chainFirstW
 
 Alias of `tap`.
@@ -1160,16 +1206,6 @@ Added in v2.10.0
 
 # sequencing
 
-## chainFirstIOK
-
-**Signature**
-
-```ts
-export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => <E>(first: IOEither<E, A>) => IOEither<E, A>
-```
-
-Added in v2.10.0
-
 ## chainIOK
 
 **Signature**

diff --git a/docs/modules/IOOption.ts.md b/docs/modules/IOOption.ts.md
@@ -20,6 +20,7 @@ Added in v2.12.0
 - [combinators](#combinators)
   - [tap](#tap)
   - [tapEither](#tapeither)
+  - [tapIO](#tapio)
 - [constructors](#constructors)
   - [none](#none)
   - [of](#of)
@@ -70,6 +71,7 @@ Added in v2.12.0
   - [chain](#chain)
   - [chainFirst](#chainfirst)
   - [chainFirstEitherK](#chainfirsteitherk)
+  - [chainFirstIOK](#chainfirstiok)
 - [lifting](#lifting)
   - [fromEitherK](#fromeitherk)
   - [fromIOK](#fromiok)
@@ -89,7 +91,6 @@ Added in v2.12.0
   - [matchW](#matchw)
 - [sequencing](#sequencing)
   - [chainEitherK](#chaineitherk)
-  - [chainFirstIOK](#chainfirstiok)
   - [chainIOK](#chainiok)
   - [chainNullableK](#chainnullablek)
   - [chainOptionK](#chainoptionk)
@@ -162,6 +163,50 @@ assert.deepStrictEqual(compute(-1)(), O.none)
 
 Added in v2.16.0
 
+## tapIO
+
+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 tapIO: {
+  <A, _>(self: IOOption<A>, f: (a: A) => I.IO<_>): IOOption<A>
+  <A, _>(f: (a: A) => I.IO<_>): (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 Console from 'fp-ts/Console'
+
+// Will output `Hello, fp-ts` into the stdout
+const effectA = pipe(
+  IOO.of('fp-ts'),
+  IOO.tapIO((value) => Console.log(`Hello, ${value}`))
+)
+
+// No output
+const effectB = pipe(
+  IOO.none as IOO.IOOption<string>,
+  IOO.tapIO((value) => Console.log(`Hello, ${value}`))
+)
+
+async function test() {
+  assert.deepStrictEqual(effectA(), O.of('fp-ts'))
+  assert.deepStrictEqual(effectB(), O.none)
+}
+
+test()
+```
+
+Added in v2.16.0
+
 # constructors
 
 ## none
@@ -639,6 +684,18 @@ export declare const chainFirstEitherK: <E, A, B>(f: (a: A) => Either<E, B>) =>
 
 Added in v2.12.0
 
+## chainFirstIOK
+
+Alias of `tapIO`.
+
+**Signature**
+
+```ts
+export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => (first: IOOption<A>) => IOOption<A>
+```
+
+Added in v2.12.0
+
 # lifting
 
 ## fromEitherK
@@ -817,16 +874,6 @@ export declare const chainEitherK: <E, A, B>(f: (a: A) => Either<E, B>) => (ma:
 
 Added in v2.12.0
 
-## chainFirstIOK
-
-**Signature**
-
-```ts
-export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => (first: IOOption<A>) => IOOption<A>
-```
-
-Added in v2.12.0
-
 ## chainIOK
 
 **Signature**

diff --git a/docs/modules/ReaderIO.ts.md b/docs/modules/ReaderIO.ts.md
@@ -14,6 +14,7 @@ Added in v2.13.0
 
 - [combinators](#combinators)
   - [tap](#tap)
+  - [tapIO](#tapio)
 - [constructors](#constructors)
   - [ask](#ask)
   - [asks](#asks)
@@ -43,6 +44,7 @@ Added in v2.13.0
 - [legacy](#legacy)
   - [chain](#chain)
   - [chainFirst](#chainfirst)
+  - [chainFirstIOK](#chainfirstiok)
   - [chainFirstW](#chainfirstw)
   - [chainW](#chainw)
 - [lifting](#lifting)
@@ -54,7 +56,6 @@ Added in v2.13.0
 - [model](#model)
   - [ReaderIO (interface)](#readerio-interface)
 - [sequencing](#sequencing)
-  - [chainFirstIOK](#chainfirstiok)
   - [chainFirstReaderK](#chainfirstreaderk)
   - [chainFirstReaderKW](#chainfirstreaderkw)
   - [chainIOK](#chainiok)
@@ -100,6 +101,42 @@ export declare const tap: {
 
 Added in v2.15.0
 
+## tapIO
+
+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 tapIO: {
+  <R, A, _>(self: ReaderIO<R, A>, f: (a: A) => I.IO<_>): ReaderIO<R, A>
+  <A, _>(f: (a: A) => I.IO<_>): <R>(self: ReaderIO<R, A>) => ReaderIO<R, A>
+}
+```
+
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as RIO from 'fp-ts/ReaderIO'
+import * as Console from 'fp-ts/Console'
+
+// Will output `Hello, fp-ts` into the stdout
+const effect = pipe(
+  RIO.ask<string>(),
+  RIO.tapIO((value) => Console.log(`Hello, ${value}`))
+)
+
+async function test() {
+  assert.deepStrictEqual(effect('fp-ts')(), 'fp-ts')
+}
+
+test()
+```
+
+Added in v2.16.0
+
 # constructors
 
 ## ask
@@ -382,6 +419,18 @@ export declare const chainFirst: <A, R, B>(f: (a: A) => ReaderIO<R, B>) => (firs
 
 Added in v2.13.0
 
+## chainFirstIOK
+
+Alias of `tapIO`.
+
+**Signature**
+
+```ts
+export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => <E>(first: ReaderIO<E, A>) => ReaderIO<E, A>
+```
+
+Added in v2.13.0
+
 ## chainFirstW
 
 Alias of `tap`.
@@ -477,16 +526,6 @@ Added in v2.13.0
 
 # sequencing
 
-## chainFirstIOK
-
-**Signature**
-
-```ts
-export declare const chainFirstIOK: <A, B>(f: (a: A) => I.IO<B>) => <E>(first: ReaderIO<E, A>) => ReaderIO<E, A>
-```
-
-Added in v2.13.0
-
 ## chainFirstReaderK
 
 **Signature**