Add first and firstAsync

Author: gordonbrander

generator.test.ts

@@ -22,6 +22,8 @@ import {
   takeAsync,
   takeWhile,
   takeWhileAsync,
+  first,
+  firstAsync,
   toAsync,
 } from "./generator.ts";
 
@@ -107,16 +109,17 @@ Deno.test("dedupe removes duplicate values based on key", async () => {
   ]);
 });
 
-const sleep = <T>(value: T, ms: number): Promise<T> =>
+const sleep = (ms: number): Promise<void> =>
   new Promise((resolve) => {
     setTimeout(() => {
-      resolve(value);
+      resolve();
     }, ms);
   });
 
 async function* sleepyIter<T>(values: Iterable<T>): AsyncGenerator<T> {
+  await sleep(1);
   for (const n of values) {
-    yield await sleep(n, 1);
+    yield await n;
   }
 }
 
@@ -197,6 +200,33 @@ Deno.test(
   },
 );
 
+Deno.test("first returns the first item from an iterable", () => {
+  const numbers = [1, 2, 3, 4, 5];
+  const firstItem = first(numbers);
+  assertEquals(firstItem, 1);
+});
+
+Deno.test("first returns undefined for empty iterable", () => {
+  const empty: number[] = [];
+  const firstItem = first(empty);
+  assertEquals(firstItem, undefined);
+});
+
+Deno.test(
+  "firstAsync returns the first item from an async iterable",
+  async () => {
+    const numbers = [1, 2, 3, 4, 5];
+    const firstItem = await firstAsync(sleepyIter(numbers));
+    assertEquals(firstItem, 1);
+  },
+);
+
+Deno.test("firstAsync returns undefined for empty async iterable", async () => {
+  const empty: number[] = [];
+  const firstItem = await firstAsync(sleepyIter(empty));
+  assertEquals(firstItem, undefined);
+});
+
 Deno.test(
   "dedupeAsync removes duplicate values based on key asynchronously",
   async () => {

generator.ts

@@ -133,6 +133,18 @@ export function* takeWhile<T>(
   }
 }
 
+/** Takes the first item from the iterator */
+export function first<T>(iter: Iterable<T>): T | undefined {
+  for (const value of iter) {
+    return value;
+  }
+}
+
+/**
+ * Deduplicates values using `getKey` to derive a string key representing the value
+ * @param iter - an iterable of values to deduplicate
+ * @param getKey - a function that returns a string key representing the value
+ */
 export function* dedupe<T>(
   iter: Iterable<T>,
   getKey: (value: T) => string,
@@ -293,6 +305,14 @@ export async function* takeWhileAsync<T>(
   }
 }
 
+export async function firstAsync<T>(
+  iter: AwaitableIterable<T>,
+): Promise<T | undefined> {
+  for await (const value of iter) {
+    return value;
+  }
+}
+
 export async function* dedupeAsync<T>(
   iter: AwaitableIterable<T>,
   getKey: (value: T) => string,