Implement {Option,Result}.unwrapOrElse

docs/reference/api/option.rst

@@ -192,5 +192,26 @@ Throws if the value is ``None``.
 
 Returns the contained ``Some`` value or a provided default.
 
+``unwrapOrElse()``
+------------------
+
+.. code-block:: typescript
+
+    unwrapOrElse<T2>(f: () => T2): T | T2
+
+Returns the contained ``Some`` value or computes a value with a provided function.
+
+The function is called at most one time, only if needed.
+
+Example:
+
+.. code-block:: typescript
+
+    Some('OK').unwrapOrElse(
+        () => { console.log('Called'); return 'UGH'; }
+    ) // => 'OK', nothing printed
+
+    None.unwrapOrElse(() => 'UGH') // => 'UGH'
+
 
 .. _cause: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause

docs/reference/api/result.rst

@@ -459,4 +459,26 @@ Example:
     goodResult.unwrapOr(5); // 1
     badResult.unwrapOr(5); // 5
 
+``unwrapOrElse()``
+------------------
+
+.. code-block:: typescript
+
+    unwrapOrElse<T2>(f: (error: E) => T2): T | T2
+
+Returns the contained ``Ok`` value or computes a value with a provided function.
+
+The function is called at most one time, only if needed.
+
+Example:
+
+.. code-block:: typescript
+
+    Ok('OK').unwrapOrElse(
+        (error) => { console.log(`Called, got ${error}`); return 'UGH'; }
+    ) // => 'OK', nothing printed
+
+    Err('A03B').unwrapOrElse((error) => `UGH, got ${error}`) // => 'UGH, got A03B'
+
+
 .. _cause: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause

src/option.ts

@@ -42,6 +42,22 @@ interface BaseOption<T> extends Iterable<T extends Iterable<infer U> ? U : never
      */
     unwrapOr<T2>(val: T2): T | T2;
 
+    /**
+     * Returns the contained `Some` value or computes a value with a provided function.
+     *
+     * The function is called at most one time, only if needed.
+     *
+     * @example
+     * ```
+     * Some('OK').unwrapOrElse(
+     *     () => { console.log('Called'); return 'UGH'; }
+     * ) // => 'OK', nothing printed
+     *
+     * None.unwrapOrElse(() => 'UGH') // => 'UGH'
+     * ```
+     */
+    unwrapOrElse<T2>(f: () => T2): T | T2;
+
     /**
      * Calls `mapper` if the Option is `Some`, otherwise returns `None`.
      * This function can be used for control flow based on `Option` values.
@@ -134,6 +150,10 @@ class NoneImpl implements BaseOption<never> {
         return val;
     }
 
+    unwrapOrElse<T2>(f: () => T2): T2 {
+        return f();
+    }
+
     expect(msg: string): never {
         throw new Error(`${msg}`);
     }
@@ -227,6 +247,10 @@ class SomeImpl<T> implements BaseOption<T> {
         return this.value;
     }
 
+    unwrapOrElse(_f: unknown): T {
+        return this.value;
+    }
+
     expect(_msg: string): T {
         return this.value;
     }

src/result.ts

@@ -7,7 +7,6 @@ import { AsyncResult } from './asyncresult.js';
  * pub fn contains<U>(&self, x: &U) -> bool
  * pub fn contains_err<F>(&self, f: &F) -> bool
  * pub fn and<U>(self, res: Result<U, E>) -> Result<U, E>
- * pub fn unwrap_or_else<F>(self, op: F) -> T
  * pub fn expect_err(self, msg: &str) -> E
  * pub fn unwrap_or_default(self) -> T
  */
@@ -82,6 +81,22 @@ interface BaseResult<T, E> extends Iterable<T extends Iterable<infer U> ? U : ne
      */
     unwrapOr<T2>(val: T2): T | T2;
 
+    /**
+     * Returns the contained `Ok` value or computes a value with a provided function.
+     *
+     * The function is called at most one time, only if needed.
+     *
+     * @example
+     * ```
+     * Ok('OK').unwrapOrElse(
+     *     (error) => { console.log(`Called, got ${error}`); return 'UGH'; }
+     * ) // => 'OK', nothing printed
+     *
+     * Err('A03B').unwrapOrElse((error) => `UGH, got ${error}`) // => 'UGH, got A03B'
+     * ```
+     */
+    unwrapOrElse<T2>(f: (error: E) => T2): T | T2;
+
     /**
      * Calls `mapper` if the result is `Ok`, otherwise returns the `Err` value of self.
      * This function can be used for control flow based on `Result` values.
@@ -218,6 +233,10 @@ export class ErrImpl<E> implements BaseResult<never, E> {
         return val;
     }
 
+    unwrapOrElse<T2>(f: (error: E) => T2): T2 {
+        return f(this.error);
+    }
+
     expect(msg: string): never {
         // The cause casting required because of the current TS definition being overly restrictive
         // (the definition says it has to be an Error while it can be anything).
@@ -340,6 +359,10 @@ export class OkImpl<T> implements BaseResult<T, never> {
         return this.value;
     }
 
+    unwrapOrElse(_f: unknown): T {
+        return this.value;
+    }
+
     expect(_msg: string): T {
         return this.value;
     }

test/option.test.ts

@@ -1,5 +1,5 @@
 import { Err, None, Ok, Option, OptionSomeType, Result, Some } from '../src/index.js';
-import { eq } from './util.js';
+import { eq, notSupposedToBeCalled } from './util.js';
 
 const someString = Some('foo');
 const someNum = new Some(10);
@@ -67,6 +67,11 @@ test('unwrap', () => {
     expect(None.unwrapOr('honk')).toBe('honk');
 });
 
+test('unwrapOrElse', () => {
+    expect(Some('1').unwrapOrElse(notSupposedToBeCalled)).toEqual('1');
+    expect(None.unwrapOrElse(() => '2')).toEqual('2');
+});
+
 test('map / andThen', () => {
     expect(None.map(() => 1)).toBe(None);
     expect(None.andThen(() => 1)).toBe(None);

test/result.test.ts

@@ -10,7 +10,7 @@ import {
     ResultOkTypes,
     Some,
 } from '../src/index.js';
-import { eq } from './util.js';
+import { eq, notSupposedToBeCalled } from './util.js';
 
 test('Err<E> | Ok<T> should be Result<T, E>', () => {
     const r1 = Err(0);
@@ -333,3 +333,8 @@ test('toAsyncResult()', async () => {
     const err = Err('error');
     expect(await err.toAsyncResult().promise).toEqual(err);
 });
+
+test('unwrapOrElse', () => {
+    expect(Ok({ data: 'user data' }).unwrapOrElse(notSupposedToBeCalled)).toEqual({ data: 'user data' });
+    expect(Err('bad error').unwrapOrElse((error) => ({ error }))).toEqual({ error: 'bad error' });
+});

test/util.ts

@@ -94,3 +94,7 @@ expect.extend({
         };
     },
 });
+
+export function notSupposedToBeCalled() {
+    throw new Error('This is not supposed to be called');
+}