feat(tap): added 'tap' function

Author: dggluz

README.md

@@ -104,6 +104,31 @@ const rejectedTask = Task.resolve(new Error());
 const rejectedPromise = toPromise(rejectedTask);
 ```
 
+### `tap`
+
+The `tap` _function_ can be found in other libreries. It just takes a `callback` _function_ and return a function that calls the `callback` and _returns_ the _argument_. It's useful when you need to perform some side effect. Suppose you need to log the _resolved value_ at certain point of a `Task` _method chaining_. Without the `tap` _function_ you would probably do something like:
+
+```typescript
+Task
+    .resolve(0)
+    // <Some code here...>
+    .map(resolvedValue => {
+        console.log(resolvedValue);
+        return resolvedValue;
+    })
+    // <And more code here...>
+```
+
+You can't use an _inline function_ nor a _point-free_ style because you don't want the _log_ to change the `Task`'s _resolved value_, so you need to _return_ it. It's way more fancier and handy to just use the `tap` _function_:
+
+```typescript
+Task
+    .resolve(0)
+    // <Some code here...>
+    .map(tap(console.log))
+    // <And more code here...>
+```
+
 ### `share`
 
 `task.pipe(share())`

src/tap.test.ts

@@ -0,0 +1,34 @@
+import { Task } from '@ts-task/task';
+import { jestAssertNever, assertFork } from './testing-utils';
+import { tap } from './tap';
+
+describe('tap', () => {
+	it('`tap` calls the function and returns the argument', cb => {
+		// GIVEN:
+		// A callback,
+		const callback = jest.fn();
+		// ...a value
+		const value = 3;
+
+		// ...and a Task that is resolved with that value
+		const task = Task
+			.resolve(value)
+		
+		// WHEN:
+		// The task is mapped with `tap` and the callback
+			.map(tap(callback))
+		;
+
+		// THEN:
+		task.fork(
+			jestAssertNever(cb),
+			assertFork(cb, resolvedValue => {
+				// The callback is called with the value
+				expect(callback).toBeCalledWith(value);
+
+				// ...and the value is resolved itself.
+				expect(resolvedValue).toEqual(value);
+			})
+		);
+	});
+});

src/tap.ts

@@ -0,0 +1,11 @@
+/**
+ * Calls `fn` performing its side effects but discarding its return value and returning the input parameter instead.
+ * @param fn Unary function that performs side effects and whose return value will be discarded
+ * @returns "tapped" `fn`
+ */
+export const tap = <T> (fn: (x: T) => any) =>
+	(x: T) => {
+		fn(x);
+		return x;
+	}
+;

src/ts-task-utils.ts

@@ -2,3 +2,4 @@ export * from './case-error';
 export * from './to-promise';
 export * from './operators/share';
 export * from './is-instance-of';
+export * from './tap';

test/types/tap.ts

@@ -0,0 +1,18 @@
+import { tap } from '../../src/tap';
+
+// We will test that the function returned by `tap` mantains its parameter's type
+// and also uses it as return type.
+
+// Given a function from number to another type
+const stringifyNumber = (x: number) => x.toString(); // $ExpectType (x: number) => string
+
+// ...the tapped version goes from number to number
+tap(stringifyNumber); // $ExpectType (x: number) => number
+
+///////////////////////////////////
+
+// Given a function from boolean to another type
+const yesOrNo = (x: boolean) => x ? 'Yes' : 'No'; // $ExpectType (x: boolean) => "Yes" | "No"
+
+// ...the tapped versions goes from boolean to boolean
+tap(yesOrNo); // $ExpectType (x: boolean) => boolean