feat(asyncIndexOnce): add asyncIndexOnce function

Author: djcsdy

index.test.ts

@@ -12,6 +12,7 @@ import {
     asyncFilterOnce,
     asyncFold1Once,
     asyncFoldOnce,
+    asyncIndexOnce,
     asyncInitialOnce,
     asyncIterator,
     asyncLastOnce,
@@ -415,3 +416,8 @@ test("asyncFoldOnce", async t => {
 test("asyncFold1Once", async t => {
     t.is(await asyncFold1Once(asyncIterator([1, 2, 3]), (a, e, i) => a + e * i), 9);
 });
+
+test("asyncIndexOnce", async t => {
+    t.is(await asyncIndexOnce(asyncIterator([1, 2, 3, 4, 3, 2, 1]), 2), 3);
+    t.is(await asyncIndexOnce(asyncIterator([1, 2, 3, 4, 3, 2, 1]), 7), null);
+});

index.ts

@@ -1,7 +1,7 @@
 import {equal as defaultEqual} from "@softwareventures/ordered";
 import type {AsyncIterableLike} from "@softwareventures/async-iterable";
-import {hasProperty} from "unknown";
 import {asyncIterable} from "@softwareventures/async-iterable";
+import {hasProperty} from "unknown";
 import {isNotNull} from "@softwareventures/nullable";
 
 export type AsyncIteratorLike<T> =
@@ -672,3 +672,32 @@ export function asyncFold1OnceFn<T>(
 ): (iterator: AsyncIteratorLike<T>) => Promise<T> {
     return async iterator => asyncFold1Once(iterator, f);
 }
+
+export async function asyncIndexOnce<T>(
+    iterator: AsyncIteratorLike<T>,
+    index: number | Promise<number>
+): Promise<T | null> {
+    const it = asyncIterator(iterator);
+    const [i, e] = await Promise.all([index, it.next()] as const);
+
+    if (i < 0 || !isFinite(i) || Math.floor(i) !== i) {
+        throw new RangeError("illegal index");
+    }
+
+    let element = e;
+    for (let j = 0; element.done !== true && j < i; ++j) {
+        element = await it.next();
+    }
+
+    if (element.done === true) {
+        return null;
+    } else {
+        return element.value;
+    }
+}
+
+export function asyncIndexOnceFn<T>(
+    index: number | Promise<number>
+): (iterator: AsyncIteratorLike<T>) => Promise<T | null> {
+    return async iterator => asyncIndexOnce(iterator, index);
+}