Refining types & tests around unwrap, unwrapErr, and expect

Author: kyleect

src/index.test.ts

@@ -154,8 +154,11 @@ describe("ok input", () => {
 
   test("unwrapping error throws", () => {
     try {
-      // @ts-expect-error Test
-      RsResult.unwrapErr(inputResult);
+      const result = RsResult.unwrapErr(inputResult);
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that unwrapErr throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(new Error(`Unwrapping an ok result: 123`));
@@ -249,7 +252,11 @@ describe("err input", () => {
 
   test("unwrapping throws", () => {
     try {
-      RsResult.unwrap(inputResult);
+      const result = RsResult.unwrap(inputResult);
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that unwrap throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(
@@ -260,7 +267,11 @@ describe("err input", () => {
 
   test("expecting throws", () => {
     try {
-      RsResult.expect(inputResult, "Custom error message");
+      const result = RsResult.expect(inputResult, "Custom error message");
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that expect throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(
@@ -303,10 +314,14 @@ describe("non result input", () => {
 
   test("unwrapping throws", () => {
     try {
-      RsResult.unwrap(
+      const result = RsResult.unwrap(
         // @ts-expect-error Invalid typed value for the test
         123
       );
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that unwrap throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(new Error(`Unwrapping a non-result value: 123`));
@@ -315,11 +330,15 @@ describe("non result input", () => {
 
   test("expecting throws", () => {
     try {
-      RsResult.expect(
+      const result = RsResult.expect(
         // @ts-expect-error Invalid typed value for the test
         123,
         "Custom error message"
       );
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that unwrap throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(new Error(`Unwrapping a non-result value: 123`));
@@ -328,8 +347,14 @@ describe("non result input", () => {
 
   test("unwrapping error throws", () => {
     try {
-      // @ts-expect-error Test
-      RsResult.unwrapErr(123);
+      const result = RsResult.unwrapErr(
+        // @ts-expect-error Test
+        123
+      );
+
+      expectTypeOf(result).toMatchTypeOf<never>();
+
+      // Ensure that unwrap throws
       expect.fail("Should have thrown");
     } catch (e) {
       expect(e).toStrictEqual(new Error(`Unwrapping a non-result value: 123`));

src/index.ts

@@ -225,14 +225,35 @@ export function expect<T>(result: Result<T, unknown>, message: string): T {
   return result.Ok;
 }
 
+/**
+ * Retrieve the value from an `Err` result.
+ *
+ * This override documents that an error is thrown when unwrapping an `Err` result.
+ *
+ * @param result An `Err` result value
+ * @returns Never
+ */
+export function unwrapErr(result: Result<unknown, never>): never;
+
+/**
+ * Retrieve the error from an `Ok` result.
+ *
+ * This override is required for type safety for `Ok` results.
+ *
+ * @template E - The error type of the `Err` result.
+ * @param result Result to unwrap the value from
+ * @returns The error value of `E` result
+ */
+export function unwrapErr<E = unknown>(result: Result<unknown, E>): E;
+
 /**
  * Retrieve the underlying error from an `Err` result.
  *
  * @template E - The error type of the `Err` result.
  * @param result Result to unwrap the error from
  * @returns The underlying error of the `Err` result
  */
-export function unwrapErr<E = unknown>(result: Result<never, E>): E {
+export function unwrapErr<E = unknown>(result: Result<unknown, E>): E {
   if (!isResult(result)) {
     throw new Error(`Unwrapping a non-result value: ${JSON.stringify(result)}`);
   }