Merge pull request #615 from konker/add-or-tee

Add orTee method to tee the error track

Author: supermacro

.changeset/tender-impalas-refuse.md

@@ -0,0 +1,5 @@
+---
+'neverthrow': minor
+---
+
+Add orTee, which is the equivalent of andTee but for the error track.

README.md

@@ -36,6 +36,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`Result.match` (method)](#resultmatch-method)
     - [`Result.asyncMap` (method)](#resultasyncmap-method)
     - [`Result.andTee` (method)](#resultandtee-method)
+    - [`Result.orTee` (method)](#resultortee-method)
     - [`Result.andThrough` (method)](#resultandthrough-method)
     - [`Result.asyncAndThrough` (method)](#resultasyncandthrough-method)
     - [`Result.fromThrowable` (static class method)](#resultfromthrowable-static-class-method)
@@ -55,6 +56,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`ResultAsync.orElse` (method)](#resultasyncorelse-method)
     - [`ResultAsync.match` (method)](#resultasyncmatch-method)
     - [`ResultAsync.andTee` (method)](#resultasyncandtee-method)
+    - [`ResultAsync.orTee` (method)](#resultasyncortee-method)
     - [`ResultAsync.andThrough` (method)](#resultasyncandthrough-method)
     - [`ResultAsync.combine` (static class method)](#resultasynccombine-static-class-method)
     - [`ResultAsync.combineWithAllErrors` (static class method)](#resultasynccombinewithallerrors-static-class-method)
@@ -593,6 +595,53 @@ resAsync.then((res: Result<void, ParseError | InsertError>) => {e
 
 ---
 
+#### `Result.orTee` (method)
+
+Like `andTee` for the error track. Takes a `Result<T, E>` and lets the `Err` value pass through regardless the result of the passed-in function.
+This is a handy way to handle side effects whose failure or success should not affect your main logics such as logging.
+
+**Signature:**
+
+```typescript
+class Result<T, E> {
+  orTee(
+    callback: (value: E) => unknown
+  ): Result<T, E> { ... }
+}
+```
+
+**Example:**
+
+```typescript
+import { parseUserInput } from 'imaginary-parser'
+import { logParseError } from 'imaginary-logger'
+import { insertUser } from 'imaginary-database'
+
+// ^ assume parseUserInput, logParseError and insertUser have the following signatures:
+// parseUserInput(input: RequestData): Result<User, ParseError>
+// logParseError(parseError: ParseError): Result<void, LogError> 
+// insertUser(user: User): ResultAsync<void, InsertError>
+// Note logParseError returns void upon success but insertUser takes User type.
+
+const resAsync = parseUserInput(userInput)
+               .orTee(logParseError)
+               .asyncAndThen(insertUser)
+
+// Note no LogError shows up in the Result type
+resAsync.then((res: Result<void, ParseError | InsertError>) => {e
+  if(res.isErr()){
+    console.log("Oops, at least one step failed", res.error)
+  }
+  else{
+    console.log("User input has been parsed and inserted successfully.")
+  }
+}))
+```
+
+[⬆️  Back to top](#toc)
+
+---
+
 #### `Result.andThrough` (method)
 
 Similar to `andTee` except for:
@@ -1277,6 +1326,53 @@ resAsync.then((res: Result<void, InsertError | NotificationError>) => {e
 
 [⬆️  Back to top](#toc)
 
+---
+#### `ResultAsync.orTee` (method)
+
+Like `andTee` for the error track. Takes a `ResultAsync<T, E>` and lets the original `Err` value pass through regardless 
+the result of the passed-in function.
+This is a handy way to handle side effects whose failure or success should not affect your main logics such as logging. 
+
+**Signature:**
+
+```typescript
+class ResultAsync<T, E> {
+  orTee(
+    callback: (value: E) => unknown
+  ): ResultAsync<T, E>  => { ... }
+}
+```
+
+**Example:**
+
+```typescript
+import { insertUser } from 'imaginary-database'
+import { logInsertError } from 'imaginary-logger'
+import { sendNotification } from 'imaginary-service'
+
+// ^ assume insertUser, logInsertError and sendNotification have the following signatures:
+// insertUser(user: User): ResultAsync<User, InsertError>
+// logInsertError(insertError: InsertError): Result<void, LogError>
+// sendNotification(user: User): ResultAsync<void, NotificationError>
+// Note logInsertError returns void on success but sendNotification takes User type. 
+
+const resAsync = insertUser(user)
+                .orTee(logUser)
+                .andThen(sendNotification)
+
+// Note there is no LogError in the types below 
+resAsync.then((res: Result<void, InsertError | NotificationError>) => {e
+  if(res.isErr()){
+    console.log("Oops, at least one step failed", res.error)
+  }
+  else{
+    console.log("User has been inserted and notified successfully.")
+  }
+}))
+```
+
+[⬆️  Back to top](#toc)
+
 ---
 #### `ResultAsync.andThrough` (method)
 

src/result-async.ts

@@ -130,6 +130,22 @@ export class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
     )
   }
 
+  orTee(f: (t: E) => unknown): ResultAsync<T, E> {
+    return new ResultAsync(
+      this._promise.then(async (res: Result<T, E>) => {
+        if (res.isOk()) {
+          return new Ok<T, E>(res.value)
+        }
+        try {
+          await f(res.error)
+        } catch (e) {
+          // Tee does not care about the error
+        }
+        return new Err<T, E>(res.error)
+      }),
+    )
+  }
+
   mapErr<U>(f: (e: E) => U | Promise<U>): ResultAsync<T, U> {
     return new ResultAsync(
       this._promise.then(async (res: Result<T, E>) => {

src/result.ts

@@ -194,6 +194,18 @@ interface IResult<T, E> {
    */
   andTee(f: (t: T) => unknown): Result<T, E>
 
+  /**
+   * This "tee"s the current `Err` value to an passed-in computation such as side
+   * effect functions but still returns the same `Err` value as the result.
+   *
+   * This is useful when you want to pass the current `Err` value to your side-track
+   * work such as logging but want to continue error-track work after that.
+   * This method does not care about the result of the passed in computation.
+   *
+   * @param f The function to apply to the current `Err` value
+   */
+  orTee(f: (t: E) => unknown): Result<T, E>
+
   /**
    * Similar to `andTee` except error result of the computation will be passed
    * to the downstream in case of an error.
@@ -342,6 +354,10 @@ export class Ok<T, E> implements IResult<T, E> {
     return ok<T, E>(this.value)
   }
 
+  orTee(_f: (t: E) => unknown): Result<T, E> {
+    return ok<T, E>(this.value)
+  }
+
   orElse<R extends Result<unknown, unknown>>(
     _f: (e: E) => R,
   ): Result<InferOkTypes<R> | T, InferErrTypes<R>>
@@ -428,6 +444,15 @@ export class Err<T, E> implements IResult<T, E> {
     return err(this.error)
   }
 
+  orTee(f: (t: E) => unknown): Result<T, E> {
+    try {
+      f(this.error)
+    } catch (e) {
+      // Tee doesn't care about the error
+    }
+    return err<T, E>(this.error)
+  }
+
   andThen<R extends Result<unknown, unknown>>(
     _f: (t: T) => R,
   ): Result<InferOkTypes<R>, InferErrTypes<R> | E>

tests/index.test.ts

@@ -159,6 +159,31 @@ describe('Result.Ok', () => {
     })
   })
 
+  describe('orTee', () => {
+    it('Calls the passed function but returns an original err', () => {
+      const errVal = err(12)
+      const passedFn = vitest.fn((_number) => {})
+
+      const teed = errVal.orTee(passedFn)
+
+      expect(teed.isErr()).toBe(true)
+      expect(passedFn).toHaveBeenCalledTimes(1)
+      expect(teed._unsafeUnwrapErr()).toStrictEqual(12)
+    })
+    it('returns an original err even when the passed function fails', () => {
+      const errVal = err(12)
+      const passedFn = vitest.fn((_number) => {
+        throw new Error('OMG!')
+      })
+
+      const teed = errVal.orTee(passedFn)
+
+      expect(teed.isErr()).toBe(true)
+      expect(passedFn).toHaveBeenCalledTimes(1)
+      expect(teed._unsafeUnwrapErr()).toStrictEqual(12)
+    })
+  })
+
   describe('asyncAndThrough', () => {
     it('Calls the passed function but returns an original ok as Async', async () => {
       const okVal = ok(12)
@@ -1064,6 +1089,31 @@ describe('ResultAsync', () => {
     })
   })
 
+  describe('orTee', () => {
+    it('Calls the passed function but returns an original err', async () => {
+      const errVal = errAsync(12)
+      const passedFn = vitest.fn((_number) => {})
+
+      const teed = await errVal.orTee(passedFn)
+
+      expect(teed.isErr()).toBe(true)
+      expect(passedFn).toHaveBeenCalledTimes(1)
+      expect(teed._unsafeUnwrapErr()).toStrictEqual(12)
+    })
+    it('returns an original err even when the passed function fails', async () => {
+      const errVal = errAsync(12)
+      const passedFn = vitest.fn((_number) => {
+        throw new Error('OMG!')
+      })
+
+      const teed = await errVal.orTee(passedFn)
+
+      expect(teed.isErr()).toBe(true)
+      expect(passedFn).toHaveBeenCalledTimes(1)
+      expect(teed._unsafeUnwrapErr()).toStrictEqual(12)
+    })
+  })
+
   describe('orElse', () => {
     it('Skips orElse on an Ok value', async () => {
       const okVal = okAsync(12)