add getOrThrowWith to Option, Either, These

fp-ts · Feb 8, 2023 · c48d2f5 · c48d2f5
1 parent 5efa9c0
commit c48d2f5
Show file tree

Hide file tree

Showing 10 changed files with 402 additions and 32 deletions.
diff --git a/.changeset/sharp-sloths-compete.md b/.changeset/sharp-sloths-compete.md
@@ -0,0 +1,5 @@
+---
+"@fp-ts/core": patch
+---
+
+add getOrThrowWith to Option, Either, These
diff --git a/docs/modules/Either.ts.md b/docs/modules/Either.ts.md
@@ -89,6 +89,7 @@ Added in v1.0.0
 - [interop](#interop)
   - [fromNullable](#fromnullable)
   - [getOrThrow](#getorthrow)
+  - [getOrThrowWith](#getorthrowwith)
   - [liftNullable](#liftnullable)
   - [liftThrowable](#liftthrowable)
   - [merge](#merge)
@@ -1101,12 +1102,54 @@ Added in v1.0.0
 
 ## getOrThrow
 
+Extracts the value of an `Either` or throws if the `Either` is `Left`.
+
+The thrown error is a default error. To configure the error thrown, see {@link getOrThrowWith}.
+
 **Signature**
 
 ```ts
 export declare const getOrThrow: <E, A>(self: Either<E, A>) => A
 ```
 
+**Example**
+
+```ts
+import * as E from '@fp-ts/core/Either'
+
+assert.deepStrictEqual(E.getOrThrow(E.right(1)), 1)
+assert.throws(() => E.getOrThrow(E.left('error')))
+```
+
+Added in v1.0.0
+
+## getOrThrowWith
+
+Extracts the value of an `Either` or throws if the `Either` is `Left`.
+
+If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+
+**Signature**
+
+```ts
+export declare const getOrThrowWith: {
+  <E>(onLeft: (e: E) => unknown): <A>(self: Either<E, A>) => A
+  <E, A>(self: Either<E, A>, onLeft: (e: E) => unknown): A
+}
+```
+
+**Example**
+
+```ts
+import * as E from '@fp-ts/core/Either'
+
+assert.deepStrictEqual(
+  E.getOrThrowWith(E.right(1), () => new Error('Unexpected Left')),
+  1
+)
+assert.throws(() => E.getOrThrowWith(E.left('error'), () => new Error('Unexpected Left')))
+```
+
 Added in v1.0.0
 
 ## liftNullable

diff --git a/docs/modules/Option.ts.md b/docs/modules/Option.ts.md
@@ -81,6 +81,7 @@ Added in v1.0.0
   - [fromNullable](#fromnullable)
   - [getOrNull](#getornull)
   - [getOrThrow](#getorthrow)
+  - [getOrThrowWith](#getorthrowwith)
   - [getOrUndefined](#getorundefined)
   - [liftNullable](#liftnullable)
   - [liftThrowable](#liftthrowable)
@@ -1108,7 +1109,9 @@ Added in v1.0.0
 
 ## getOrThrow
 
-Returns the contained value if the `Option` is `Some`, otherwise throws an error.
+Extracts the value of an `Option` or throws if the `Option` is `None`.
+
+The thrown error is a default error. To configure the error thrown, see {@link getOrThrowWith}.
 
 **Signature**
 
@@ -1119,11 +1122,39 @@ export declare const getOrThrow: <A>(self: Option<A>) => A
 **Example**
 
 ```ts
-import { pipe } from '@fp-ts/core/Function'
 import * as O from '@fp-ts/core/Option'
 
-assert.deepStrictEqual(pipe(O.some(1), O.getOrThrow), 1)
-assert.throws(() => pipe(O.none(), O.getOrThrow))
+assert.deepStrictEqual(O.getOrThrow(O.some(1)), 1)
+assert.throws(() => O.getOrThrow(O.none()))
+```
+
+Added in v1.0.0
+
+## getOrThrowWith
+
+Extracts the value of an `Option` or throws if the `Option` is `None`.
+
+If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+
+**Signature**
+
+```ts
+export declare const getOrThrowWith: {
+  (onNone: () => unknown): <A>(self: Option<A>) => A
+  <A>(self: Option<A>, onNone: () => unknown): A
+}
+```
+
+**Example**
+
+```ts
+import * as O from '@fp-ts/core/Option'
+
+assert.deepStrictEqual(
+  O.getOrThrowWith(O.some(1), () => new Error('Unexpected None')),
+  1
+)
+assert.throws(() => O.getOrThrowWith(O.none(), () => new Error('Unexpected None')))
 ```
 
 Added in v1.0.0

diff --git a/docs/modules/These.ts.md b/docs/modules/These.ts.md
@@ -104,7 +104,9 @@ Added in v1.0.0
   - [Traversable](#traversable)
 - [interop](#interop)
   - [getOrThrow](#getorthrow)
+  - [getOrThrowWith](#getorthrowwith)
   - [getRightOnlyOrThrow](#getrightonlyorthrow)
+  - [getRightOnlyOrThrowWith](#getrightonlyorthrowwith)
   - [liftThrowable](#liftthrowable)
 - [lifting](#lifting)
   - [lift2](#lift2)
@@ -1208,22 +1210,113 @@ Added in v1.0.0
 
 ## getOrThrow
 
+Extracts the value of a `These` or throws if the `These` is `Left`.
+
+The thrown error is a default error. To configure the error thrown, see {@link getOrThrowWith}.
+
 **Signature**
 
 ```ts
 export declare const getOrThrow: <E, A>(self: These<E, A>) => A
 ```
 
+**Example**
+
+```ts
+import * as T from '@fp-ts/core/These'
+
+assert.deepStrictEqual(T.getOrThrow(T.right(1)), 1)
+assert.deepStrictEqual(T.getOrThrow(T.both('warning', 1)), 1)
+assert.throws(() => T.getOrThrow(T.left('error')))
+```
+
+Added in v1.0.0
+
+## getOrThrowWith
+
+Extracts the value of a `These` or throws if the `These` is `Left`.
+
+If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+
+**Signature**
+
+```ts
+export declare const getOrThrowWith: {
+  <E>(onLeft: (e: E) => unknown): <A>(self: These<E, A>) => A
+  <E, A>(self: These<E, A>, onLeft: (e: E) => unknown): A
+}
+```
+
+**Example**
+
+```ts
+import * as E from '@fp-ts/core/These'
+
+assert.deepStrictEqual(
+  E.getOrThrowWith(E.right(1), () => new Error('Unexpected Left')),
+  1
+)
+assert.deepStrictEqual(
+  E.getOrThrowWith(E.both('warning', 1), () => new Error('Unexpected Left')),
+  1
+)
+assert.throws(() => E.getOrThrowWith(E.left('error'), () => new Error('Unexpected Left')))
+```
+
 Added in v1.0.0
 
 ## getRightOnlyOrThrow
 
+Extracts the value of a `These` or throws if the `These` is not a `Right`.
+
+The thrown error is a default error. To configure the error thrown, see {@link getRightOnlyOrThrowWith}.
+
 **Signature**
 
 ```ts
 export declare const getRightOnlyOrThrow: <E, A>(self: These<E, A>) => A
 ```
 
+**Example**
+
+```ts
+import * as T from '@fp-ts/core/These'
+
+assert.deepStrictEqual(T.getRightOnlyOrThrow(T.right(1)), 1)
+assert.throws(() => T.getRightOnlyOrThrow(T.both('error', 1)))
+assert.throws(() => T.getRightOnlyOrThrow(T.left('error')))
+```
+
+Added in v1.0.0
+
+## getRightOnlyOrThrowWith
+
+Extracts the value of a `These` or throws if the `These` is `Left`.
+
+If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+
+**Signature**
+
+```ts
+export declare const getRightOnlyOrThrowWith: {
+  <E>(onLeftOrBoth: (e: E) => unknown): <A>(self: These<E, A>) => A
+  <E, A>(self: These<E, A>, onLeftOrBoth: (e: E) => unknown): A
+}
+```
+
+**Example**
+
+```ts
+import * as E from '@fp-ts/core/These'
+
+assert.deepStrictEqual(
+  E.getRightOnlyOrThrowWith(E.right(1), () => new Error('Unexpected Left or Both')),
+  1
+)
+assert.throws(() => E.getRightOnlyOrThrowWith(E.both('warning', 1), () => new Error('Unexpected Left or Both')))
+assert.throws(() => E.getRightOnlyOrThrowWith(E.left('error'), () => new Error('Unexpected Left or Both')))
+```
+
 Added in v1.0.0
 
 ## liftThrowable

diff --git a/src/Either.ts b/src/Either.ts
@@ -943,15 +943,55 @@ export const flatMapNullable: {
 ): Either<E1 | E2, NonNullable<B>> => flatMap(self, liftNullable(f, onNullable)))
 
 /**
+ * Extracts the value of an `Either` or throws if the `Either` is `Left`.
+ *
+ * If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
+ *
+ * @param self - The `Either` to extract the value from.
+ * @param onLeft - A function that will be called if the `Either` is `Left`. It returns the error to be thrown.
+ *
+ * @example
+ * import * as E from "@fp-ts/core/Either"
+ *
+ * assert.deepStrictEqual(
+ *   E.getOrThrowWith(E.right(1), () => new Error('Unexpected Left')),
+ *   1
+ * )
+ * assert.throws(() => E.getOrThrowWith(E.left("error"), () => new Error('Unexpected Left')))
+ *
  * @category interop
  * @since 1.0.0
  */
-export const getOrThrow = <E, A>(self: Either<E, A>): A => {
+export const getOrThrowWith: {
+  <E>(onLeft: (e: E) => unknown): <A>(self: Either<E, A>) => A
+  <E, A>(self: Either<E, A>, onLeft: (e: E) => unknown): A
+} = dual(2, <E, A>(self: Either<E, A>, onLeft: (e: E) => unknown): A => {
   if (isRight(self)) {
     return self.right
   }
-  throw new Error("getOrThrow called on a Left")
-}
+  throw onLeft(self.left)
+})
+
+/**
+ * Extracts the value of an `Either` or throws if the `Either` is `Left`.
+ *
+ * The thrown error is a default error. To configure the error thrown, see  {@link getOrThrowWith}.
+ *
+ * @param self - The `Either` to extract the value from.
+ * @throws `Error("getOrThrow called on a Left")`
+ *
+ * @example
+ * import * as E from "@fp-ts/core/Either"
+ *
+ * assert.deepStrictEqual(E.getOrThrow(E.right(1)), 1)
+ * assert.throws(() => E.getOrThrow(E.left("error")))
+ *
+ * @category interop
+ * @since 1.0.0
+ */
+export const getOrThrow: <E, A>(self: Either<E, A>) => A = getOrThrowWith(() =>
+  new Error("getOrThrow called on a Left")
+)
 
 /**
  * Lifts a function that may throw to one returning a `Either`.

diff --git a/src/Option.ts b/src/Option.ts
@@ -546,27 +546,55 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
   }
 
 /**
- * Returns the contained value if the `Option` is `Some`, otherwise throws an error.
+ * Extracts the value of an `Option` or throws if the `Option` is `None`.
+ *
+ * If a default error is sufficient for your use case and you don't need to configure the thrown error, see {@link getOrThrow}.
  *
  * @param self - The `Option` to extract the value from.
- * @throws `Error("getOrThrow called on a None")`
+ * @param onNone - A function that will be called if the `Option` is `None`. It returns the error to be thrown.
  *
  * @example
- * import { pipe } from '@fp-ts/core/Function'
  * import * as O from '@fp-ts/core/Option'
  *
- * assert.deepStrictEqual(pipe(O.some(1), O.getOrThrow), 1)
- * assert.throws(() => pipe(O.none(), O.getOrThrow))
+ * assert.deepStrictEqual(
+ *   O.getOrThrowWith(O.some(1), () => new Error('Unexpected None')),
+ *   1
+ * )
+ * assert.throws(() => O.getOrThrowWith(O.none(), () => new Error('Unexpected None')))
  *
  * @category interop
  * @since 1.0.0
  */
-export const getOrThrow = <A>(self: Option<A>): A => {
+export const getOrThrowWith: {
+  (onNone: () => unknown): <A>(self: Option<A>) => A
+  <A>(self: Option<A>, onNone: () => unknown): A
+} = dual(2, <A>(self: Option<A>, onNone: () => unknown): A => {
   if (isSome(self)) {
     return self.value
   }
-  throw new Error("getOrThrow called on a None")
-}
+  throw onNone()
+})
+
+/**
+ * Extracts the value of an `Option` or throws if the `Option` is `None`.
+ *
+ * The thrown error is a default error. To configure the error thrown, see  {@link getOrThrowWith}.
+ *
+ * @param self - The `Option` to extract the value from.
+ * @throws `Error("getOrThrow called on a None")`
+ *
+ * @example
+ * import * as O from '@fp-ts/core/Option'
+ *
+ * assert.deepStrictEqual(O.getOrThrow(O.some(1)), 1)
+ * assert.throws(() => O.getOrThrow(O.none()))
+ *
+ * @category interop
+ * @since 1.0.0
+ */
+export const getOrThrow: <A>(self: Option<A>) => A = getOrThrowWith(() =>
+  new Error("getOrThrow called on a None")
+)
 
 // -------------------------------------------------------------------------------------
 // mapping