feat: add first op to Maybe and MaybeAsync

Author: lohmander

src/AsyncMaybe.ts

@@ -1,5 +1,5 @@
 import { Maybe } from "./Maybe";
-import type { ReturnMaybeType } from "./types";
+import type { ExtractMaybeArrayValue, ReturnMaybeType } from "./types";
 import { isJust, isNothing } from "./utils";
 
 /**
@@ -246,6 +246,28 @@ export class AsyncMaybe<T> {
     return new AsyncMaybe(next);
   }
 
+  first<Us extends ReadonlyArray<AsyncMaybe<unknown> | Maybe<unknown>>>(
+    fn: (value: T) => Us,
+  ): AsyncMaybe<ExtractMaybeArrayValue<Us>> {
+    const next = (async () => {
+      const value = await this._value;
+
+      if (isNothing(value)) return value as unknown as ExtractMaybeArrayValue<Us>;
+
+      const maybes = fn(value);
+
+      for (const m of maybes) {
+        const maybeValue = await Promise.resolve(m.value());
+
+        if (isJust(maybeValue)) return maybeValue as ExtractMaybeArrayValue<Us>;
+      }
+
+      return null as unknown as ExtractMaybeArrayValue<Us>;
+    })();
+
+    return new AsyncMaybe(next);
+  }
+
   /**
    * withDefault - Provides a default value if Nothing.
    *

src/Maybe.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import type { ReturnMaybeType } from "./types";
+import type { ExtractMaybeArrayValue, ReturnMaybeType } from "./types";
 import { isJust, isNothing } from "./utils";
 
 /**
@@ -179,6 +179,28 @@ export class Maybe<T> {
     return new Maybe(result);
   }
 
+  /**
+   * Returns the first Maybe to produce a non-Nothing value
+   *
+   * @typeParam U - The element type of the resulting Maybe.
+   * @param fn - A function mapping the contained value to an array of Maybes.
+   * @returns The first Maybe<U> from the array, or Nothing if none found or if this is Nothing.
+   */
+  first<Us extends ReadonlyArray<Maybe<any>>>(
+    fn: (value: T) => Us,
+  ): Maybe<ExtractMaybeArrayValue<Us>> {
+    if (isNothing(this._value)) return new Maybe<ExtractMaybeArrayValue<Us>>(null);
+
+    const maybes = fn(this._value as T);
+
+    for (const m of maybes) {
+      if (!(m instanceof Maybe)) return new Maybe<ExtractMaybeArrayValue<Us>>(null);
+      if (isJust(m.value())) return m;
+    }
+
+    return new Maybe<ExtractMaybeArrayValue<Us>>(null);
+  }
+
   /**
    * Access the raw inner value.
    *

src/__tests__/AsyncMaybe.test.ts

@@ -100,21 +100,21 @@ describe("AsyncMaybe", () => {
     });
 
     it("short circuits if Nothing", async () => {
-      // @ts-expect-error
+      // @ts-expect-error: testing null case
       const m = AsyncMaybe.fromPromise<number[] | null>(Promise.resolve(null)).filterMap((x) =>
         Maybe.fromNullable(x * 10),
       );
       expect(await m.value()).toBeNull();
 
-      // @ts-expect-error
+      // @ts-expect-error: testing undefined case
       const m2 = AsyncMaybe.fromPromise<number[] | undefined>(Promise.resolve(undefined)).filterMap(
         (x) => Maybe.fromNullable(x * 10),
       );
       expect(await m2.value()).toBeUndefined();
     });
 
     it("returns null if the value is not an array", async () => {
-      // @ts-expect-error
+      // @ts-expect-error: testing non-array case
       const m = AsyncMaybe.fromPromise(Promise.resolve(123)).filterMap((x) =>
         Maybe.fromNullable(x),
       );
@@ -132,15 +132,15 @@ describe("AsyncMaybe", () => {
 
     it("short circuits if the value is not an object", async () => {
       const m = AsyncMaybe.fromPromise(Promise.resolve(5)).extend("greet", (o) =>
-        // @ts-expect-error
+        // @ts-expect-error: testing non-object case
         AsyncMaybe.fromNullable(`Hello ${o.num}`),
       );
       expect(await m.value()).toBeNull();
     });
 
     it("does not confuse null for an object", async () => {
       const m = AsyncMaybe.fromPromise(Promise.resolve(null)).extend("greet", (o) =>
-        // @ts-expect-error
+        // @ts-expect-error: testing null case
         AsyncMaybe.fromNullable(`Hello ${o.num}`),
       );
       expect(await m.value()).toBeNull();
@@ -155,7 +155,7 @@ describe("AsyncMaybe", () => {
 
     it("short circuits if the function returns Nothing", async () => {
       const m = AsyncMaybe.fromPromise(Promise.resolve({ num: 2 }))
-        .extend("greet", (o) => AsyncMaybe.fromNullable<string>(null))
+        .extend("greet", () => AsyncMaybe.fromNullable<string>(null))
         .map((obj) => `${obj.greet} stranger!`);
       expect(await m.value()).toBeNull();
     });
@@ -260,6 +260,43 @@ describe("AsyncMaybe", () => {
     });
   });
 
+  describe("first", () => {
+    it("returns the first Just value from an array", async () => {
+      const m = AsyncMaybe.fromNullable(1);
+      const first = m.first((value) => [
+        AsyncMaybe.fromNullable(null),
+        AsyncMaybe.fromNullable(2),
+        AsyncMaybe.fromNullable(value + 10),
+      ]);
+      expect(await first.value()).toBe(2);
+    });
+
+    it("returns Nothing if all are Nothing", async () => {
+      const m = AsyncMaybe.fromNullable(1);
+      const first = m.first(() => [
+        AsyncMaybe.fromNullable<number | null>(null),
+        AsyncMaybe.fromNullable<number | undefined>(undefined),
+      ]);
+      expect(await first.value()).toBeNull();
+    });
+
+    it("short circuits if the original is Nothing", async () => {
+      const m = AsyncMaybe.fromNullable<number>(null);
+      const first = m.first(() => [AsyncMaybe.fromNullable(2), AsyncMaybe.fromNullable(3)]);
+      expect(await first.value()).toBeNull();
+    });
+
+    it("handles both AsyncMaybe and Maybe values", async () => {
+      const m = AsyncMaybe.fromNullable(5);
+      const first = m.first((value) => [
+        Maybe.fromNullable<number>(null),
+        AsyncMaybe.fromPromise(Promise.resolve(value * 2)),
+        Maybe.fromNullable(value + 3),
+      ]);
+      expect(await first.value()).toBe(10);
+    });
+  });
+
   describe("withDefault / getOrElse", () => {
     it("withDefault supplies a value if Nothing", async () => {
       const absent = AsyncMaybe.fromPromise<number | null>(Promise.resolve(null)).withDefault(42);

src/__tests__/Maybe.test.ts

@@ -119,7 +119,7 @@ describe("Maybe", () => {
 
     it("short circuits if the `Just` value is not an object", () => {
       const result = Maybe.fromNullable(5)
-        // @ts-expect-error
+        // @ts-expect-error: should error because 5 is not an object
         .extend("greet", (o) => Maybe.fromNullable(`Hello ${o.num}`))
         .value();
 
@@ -224,7 +224,7 @@ describe("Maybe", () => {
     it("fails if the result of the filterMap callback does not return a Maybe instance", () => {
       const arr = [{ greet: "a" }, { greet: "b" }];
       const maybeArr = Maybe.fromNullable(arr)
-        // @ts-expect-error
+        // @ts-expect-error: should error because the callback does not return a Maybe
         .filterMap((x) => x.greet) // Incorrect: should return Maybe
         .value();
 
@@ -234,6 +234,7 @@ describe("Maybe", () => {
 
   describe("effect", () => {
     it("calls a function with the value and ignores its result", () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       const effectFn = mock((x: number) => {});
       const result = Maybe.fromNullable(10)
         .effect(effectFn)
@@ -246,6 +247,7 @@ describe("Maybe", () => {
     });
 
     it("does not call a function when the value is Nothing", () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       const effectFn = mock((x: number) => {});
       const result = Maybe.fromNullable<number>(null).effect(effectFn).value();
 
@@ -254,6 +256,37 @@ describe("Maybe", () => {
     });
   });
 
+  describe("first", () => {
+    it("returns the first Just value from an array of Maybes", () => {
+      const maybe = Maybe.fromNullable(1);
+      const first = maybe
+        .first((value) => [
+          Maybe.fromNullable(null as null | boolean),
+          Maybe.fromNullable(value * 3),
+          Maybe.fromNullable("test"),
+        ])
+        .value();
+      expect(first).toBe(3);
+    });
+
+    it("returns Nothing if all Maybes are Nothing", () => {
+      const maybe = Maybe.fromNullable(1);
+      const first = maybe
+        .first(() => [
+          Maybe.fromNullable(null as null | boolean),
+          Maybe.fromNullable(undefined as undefined | number),
+        ])
+        .value();
+      expect(first).toBeNull();
+    });
+
+    it("short circuits if the original Maybe is Nothing", () => {
+      const maybe = Maybe.fromNullable<number>(null);
+      const first = maybe.first(() => [Maybe.fromNullable(1), Maybe.fromNullable(2)]).value();
+      expect(first).toBeNull();
+    });
+  });
+
   it("complex chaining example behaves as expected", () => {
     const x: number | null = 10;
     const result = Maybe.fromNullable(x)

src/types.ts

@@ -12,3 +12,7 @@ export type ExtractValue<M> =
         : never;
 
 export type ReturnMaybeType<Fn extends (...args: any[]) => any> = ExtractValue<ReturnType<Fn>>;
+
+export type AnyMaybe<T> = Maybe<T> | AsyncMaybe<T>;
+export type ExtractMaybeArrayValue<M extends ReadonlyArray<Maybe<any> | AsyncMaybe<any>>> =
+  M[number] extends AnyMaybe<infer T> ? T : never;