feat: 🎸 adds a tap function for running side-effects

Provides a tap, as an alternative for a map function that doesn't change
the value.

README.md

@@ -54,6 +54,18 @@ const now: Array<number> = orig.map(x => parseInt(x));
     none().map(v => console.log(v)) // does not print
 ```
 
+### tap
+Like `map`, it calls a function with the current value, if there is one, but ignores any return value and the result is always the original Maybe.  Intended for running side-effects, without changing the value.
+
+```typescript
+some(1)
+    // If this was `.map`, then the result of this call would be None
+    .tap(x => console.log(`Original value is ${x}`))
+    .map(x => x + 1)
+    .tap(x => console.log(`New value is ${x}`))
+```
+
+
 ### flatMap
 FlatMap also accesses the contained value, but it expects that its "mapper" function returns a container of the same type.
 Imagine the conceptually equivalent array container:

src/maybe.ts

@@ -24,6 +24,7 @@ export default abstract class Maybe<T> {
     abstract expect(msg?: string | Error): T;
     abstract caseOf<R>(funcs: MatchType<T, R>): Maybe<R>;
     abstract map<U>(f: (v: T) => Nullable<U>): Maybe<U>;
+    abstract tap(f: (v: T) => void): Maybe<T>;
     abstract flatMap<U>(f: (v: T) => Maybe<U>): Maybe<U>;
     abstract orElse<U>(def: U | (() => U)): T | U;
     abstract or<U>(other: Maybe<U> | (() => Maybe<U>)): Maybe<T | U>;

src/none.ts

@@ -32,6 +32,10 @@ export default class None<T> extends Maybe<T> {
         return this as any;
     }
 
+    tap(): Maybe<T> {
+        return this;
+    }
+
     flatMap<U>(): Maybe<U> {
         return this as any;
     }

src/some.ts

@@ -17,6 +17,12 @@ export default class Some<T> extends Maybe<T> {
         return maybe<U>(f(this.value!));
     }
 
+    tap(f: (v: T) => void): Maybe<T> {
+        f(this.value!);
+        return this;
+    }
+
+
     flatMap<U>(f: (v: T) => Maybe<U>): Maybe<U> {
         return f(this.value!);
     }

tests/maybe.test.ts

@@ -49,6 +49,29 @@ test('map - Gives back a maybe', checkInstance(
     none().map(noop),
 ));
 
+// ---
+// Tap
+// ---
+
+test('Calls map function when contained value is non-nil', () => {
+    expect.assertions(2);
+
+    const value = "i'm not nil";
+    const definitely = some(value);
+
+    definitely
+        .tap(v => expect(v).toBe(value))
+        .tap(v => expect(v).toBe(value));
+});
+
+test('Does not call tap function when contained value is nil', () => {
+    none().tap(raiseError);
+});
+
+test('tap - Gives back a maybe', checkInstance(
+    none().tap(noop),
+));
+
 // --------
 // Flat Map
 // --------