feat: Add unwrapOrElse

.changeset/unwrapOrElse.md

@@ -0,0 +1,5 @@
+---
+'neverthrow': minor
+---
+
+Add unwrapOrElse

README.md

@@ -30,6 +30,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`Result.map` (method)](#resultmap-method)
     - [`Result.mapErr` (method)](#resultmaperr-method)
     - [`Result.unwrapOr` (method)](#resultunwrapor-method)
+    - [`Result.unwrapOrElse` (method)](#resultunwraporelse-method)
     - [`Result.andThen` (method)](#resultandthen-method)
     - [`Result.asyncAndThen` (method)](#resultasyncandthen-method)
     - [`Result.orElse` (method)](#resultorelse-method)
@@ -51,6 +52,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`ResultAsync.map` (method)](#resultasyncmap-method)
     - [`ResultAsync.mapErr` (method)](#resultasyncmaperr-method)
     - [`ResultAsync.unwrapOr` (method)](#resultasyncunwrapor-method)
+    - [`ResultAsync.unwrapOrElse` (method)](#resultasyncunwraporelse-method)
     - [`ResultAsync.andThen` (method)](#resultasyncandthen-method)
     - [`ResultAsync.orElse` (method)](#resultasyncorelse-method)
     - [`ResultAsync.match` (method)](#resultasyncmatch-method)
@@ -318,6 +320,32 @@ const unwrapped: number = myResult.map(multiply).unwrapOr(10)
 
 ---
 
+#### `Result.unwrapOrElse` (method)
+
+Unwrap the `Ok` value, or return the default by function if there is an `Err`
+
+**Signature:**
+
+```typescript
+class Result<T, E> {
+  unwrapOrElse<A>(err: (e: E) => A): T | A { ... }
+}
+```
+
+**Example**:
+
+```typescript
+const myResult = err('Oh noooo')
+
+const multiply = (value: number): number => value * 2
+
+const unwrapped: number = myResult.map(multiply).unwrapOrElse(() => 10)
+```
+
+[⬆️  Back to top](#toc)
+
+---
+
 #### `Result.andThen` (method)
 
 Same idea as `map` above. Except you must return a new `Result`.
@@ -1114,6 +1142,30 @@ const unwrapped: number = await errAsync(0).unwrapOr(10)
 
 ---
 
+#### `ResultAsync.unwrapOrElse` (method)
+
+Unwrap the `Ok` value, or return the default by function if there is an `Err`.  
+Works just like `Result.unwrapOrElse` but returns a `Promise<T>` instead of `T`.
+
+**Signature:**
+
+```typescript
+class ResultAsync<T, E> {
+  unwrapOrElse<A>(err: (e: E) => A): Promise<T | A> { ... }
+}
+```
+
+**Example**:
+
+```typescript
+const unwrapped: number = await errAsync(0).unwrapOrElse(() => 10)
+// unwrapped = 10
+```
+
+[⬆️  Back to top](#toc)
+
+---
+
 #### `ResultAsync.andThen` (method)
 
 Same idea as `map` above. Except the applied function must return a `Result` or `ResultAsync`.

src/result-async.ts

@@ -191,6 +191,10 @@ export class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
     return this._promise.then((res) => res.unwrapOr(t))
   }
 
+  unwrapOrElse<A>(err: (e: E) => A): Promise<T | A> {
+    return this._promise.then((res) => res.unwrapOrElse(err))
+  }
+
   /**
    * Emulates Rust's `?` operator in `safeTry`'s body. See also `safeTry`.
    */

src/result.ts

@@ -244,6 +244,13 @@ interface IResult<T, E> {
    */
   unwrapOr<A>(v: A): T | A
 
+  /**
+   * Unwrap the `Ok` value, or return the default by function if there is an `Err`
+   *
+   * @param err the function that return if there is an `Err`
+   */
+  unwrapOrElse<A>(err: (e: E) => A): T | A
+
   /**
    *
    * Given 2 functions (one for the `Ok` variant and one for the `Err` variant)
@@ -361,6 +368,11 @@ export class Ok<T, E> implements IResult<T, E> {
     return this.value
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  unwrapOrElse<A>(_err: (e: E) => A): T | A {
+    return this.value
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   match<A, B = A>(ok: (t: T) => A, _err: (e: E) => B): A | B {
     return ok(this.value)
@@ -447,6 +459,10 @@ export class Err<T, E> implements IResult<T, E> {
     return v
   }
 
+  unwrapOrElse<A>(err: (e: E) => A): T | A {
+    return err(this.error)
+  }
+
   match<A, B = A>(_ok: (t: T) => A, err: (e: E) => B): A | B {
     return err(this.error)
   }

tests/index.test.ts

@@ -204,6 +204,11 @@ describe('Result.Ok', () => {
     expect(okVal.unwrapOr(1)).toEqual(12)
   })
 
+  it('unwrapOrElse and return the Ok value', () => {
+    const okVal = ok(12)
+    expect(okVal.unwrapOrElse(() => 1)).toEqual(12)
+  })
+
   it('Maps to a ResultAsync', async () => {
     const okVal = ok(12)
 
@@ -320,6 +325,11 @@ describe('Result.Err', () => {
     expect(okVal.unwrapOr(1)).toEqual(1)
   })
 
+  it('unwrapOrElse and return the default value', () => {
+    const okVal = err<number, string>('Oh nooo')
+    expect(okVal.unwrapOrElse(() => 1)).toEqual(1)
+  })
+
   it('Skips over andThen', () => {
     const errVal = err('Yolo')
 
@@ -1134,6 +1144,18 @@ describe('ResultAsync', () => {
     })
   })
 
+  describe('unwrapOrElse', () => {
+    it('returns a promise to the result value on an Ok', async () => {
+      const unwrapped = await okAsync(12).unwrapOrElse(() => 10)
+      expect(unwrapped).toBe(12)
+    })
+
+    it('returns a promise to the provided default function value on an Error', async () => {
+      const unwrapped = await errAsync<number, number>(12).unwrapOrElse(() => 10)
+      expect(unwrapped).toBe(10)
+    })
+  })
+
   describe('fromSafePromise', () => {
     it('Creates a ResultAsync from a Promise', async () => {
       const res = ResultAsync.fromSafePromise(Promise.resolve(12))