Add find, findIndex utils

Author: wojtekmaj

README.md

@@ -21,6 +21,8 @@ A collection of array-related async utilities.
 - [`asyncEveryStrict()`](#asyncEveryStrict)
 - [`asyncFilter()`](#asyncFilter)
 - [`asyncFilterStrict()`](#asyncFilterStrict)
+- [`asyncFind()`](#asyncFind)
+- [`asyncFindIndex()`](#asyncFindIndex)
 - [`asyncForEach()`](#asyncForEach)
 - [`asyncForEachStrict()`](#asyncForEachStrict)
 - [`asyncMap()`](#asyncMap)
@@ -91,6 +93,30 @@ const asyncFilteredArr = await asyncFilterStrict([1, 2, 3], async (el, index) =>
 console.log(indexes); // [0, 1, 2]
 ```
 
+### `asyncFind()`
+
+Returns the first element in the provided array that satisfies the provided testing function. If no values satisfy the testing function, `undefined` is returned.
+
+#### Sample usage
+
+```js
+import { asyncFind } from '@wojtekmaj/async-array-utils';
+
+const asyncFoundEl = await asyncFind([1, 2, 3], async (el) => el > 1); // 2
+```
+
+### `asyncFindIndex()`
+
+Returns the index of the first element in an array that satisfies the provided testing function. If no elements satisfy the testing function, `-1` is returned.
+
+#### Sample usage
+
+```js
+import { asyncFindIndex } from '@wojtekmaj/async-array-utils';
+
+const asyncFoundIndex = await asyncFindIndex([1, 2, 3], async (el) => el > 1); // 1
+```
+
 ### `asyncForEach()`
 
 Executes a provided asynchronous function once for each array element.

src/find.spec.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from 'vitest';
+import asyncFind from './find';
+
+import {
+  getTimer,
+  inputArr,
+  largerThanOneHundred,
+  largerThanOneHundredInRandomTime,
+  largerThanTwo,
+  largerThanTwoInRandomTime,
+  makeDelayed,
+  throws,
+} from '../test-utils';
+
+const firstElementLargerThanTwo = inputArr.findIndex(largerThanTwo);
+
+describe('asyncFind()', () => {
+  it('example from README works as described', async () => {
+    const asyncFoundEl = await asyncFind([1, 2, 3], async (el) => el > 1);
+
+    expect(asyncFoundEl).toEqual(2);
+  });
+
+  it('takes exactly the time necessary to execute', async () => {
+    const delay = 100;
+
+    const timer = getTimer();
+
+    timer.start();
+
+    await asyncFind(
+      [1, 2, 3],
+      makeDelayed((el) => el > 1, delay),
+    );
+
+    const timeElapsed = timer.stop();
+
+    expect(timeElapsed).toBeGreaterThanOrEqual(delay * 2);
+    expect(timeElapsed).toBeLessThan(delay * 1.25 * 2);
+  });
+
+  it('assertions below are valid for synchronous .find()', () => {
+    const filter = vi.fn().mockImplementation(largerThanTwo);
+
+    inputArr.find(filter);
+
+    expect.assertions(1 + firstElementLargerThanTwo);
+
+    expect(filter).toHaveBeenCalledTimes(firstElementLargerThanTwo + 1);
+    inputArr.slice(0, firstElementLargerThanTwo).forEach((el, idx) => {
+      expect(filter).toHaveBeenCalledWith(el, idx, inputArr);
+    });
+  });
+
+  it('iterates over values properly', async () => {
+    const filter = vi.fn().mockImplementation(largerThanTwoInRandomTime);
+
+    await asyncFind(inputArr, filter);
+
+    expect.assertions(1 + firstElementLargerThanTwo);
+
+    expect(filter).toHaveBeenCalledTimes(firstElementLargerThanTwo + 1);
+    inputArr.slice(0, firstElementLargerThanTwo).forEach((el, idx) => {
+      expect(filter).toHaveBeenCalledWith(el, idx, inputArr);
+    });
+  });
+
+  it.skip('assertions below are valid for synchronous .find()', () => {
+    const filter = vi.fn().mockImplementation(largerThanTwo);
+
+    inputArr.find(filter);
+
+    expect.assertions(1 + firstElementLargerThanTwo);
+
+    expect(filter).toHaveBeenCalledTimes(firstElementLargerThanTwo + 1);
+    inputArr.slice(0, firstElementLargerThanTwo).forEach((el, idx) => {
+      expect(filter).toHaveBeenCalledWith(el, idx, inputArr);
+    });
+  });
+
+  it('iterates over values properly', async () => {
+    const filter = vi.fn().mockImplementation(largerThanTwoInRandomTime);
+
+    await asyncFind(inputArr, filter);
+
+    expect.assertions(1 + firstElementLargerThanTwo);
+
+    expect(filter).toHaveBeenCalledTimes(firstElementLargerThanTwo + 1);
+    inputArr.slice(0, firstElementLargerThanTwo).forEach((el, idx) => {
+      expect(filter).toHaveBeenCalledWith(el, idx, inputArr);
+    });
+  });
+
+  it.skip('assertions below are valid for synchronous .find()', () => {
+    const filter = vi.fn().mockImplementation(largerThanTwo);
+
+    const result = inputArr.find(filter);
+
+    expect(result).toEqual(3);
+  });
+
+  it('returns truthy result properly', async () => {
+    const filter = vi.fn().mockImplementation(largerThanTwoInRandomTime);
+
+    const result = await asyncFind(inputArr, filter);
+
+    expect(result).toEqual(3);
+  });
+
+  it.skip('assertions below are valid for synchronous .find()', () => {
+    const filter = vi.fn().mockImplementation(largerThanOneHundred);
+
+    const result = inputArr.find(filter);
+
+    expect(result).toEqual(undefined);
+  });
+
+  it('returns undefined result properly', async () => {
+    const filter = vi.fn().mockImplementation(largerThanOneHundredInRandomTime);
+
+    const result = await asyncFind(inputArr, filter);
+
+    expect(result).toEqual(undefined);
+  });
+
+  it.skip('assertions below are valid for synchronous .find()', () => {
+    const filter = vi.fn().mockImplementation(throws);
+
+    expect(() => inputArr.find(filter)).toThrow();
+  });
+
+  it('throws if function passed throws', async () => {
+    const filter = vi.fn().mockImplementation(throws);
+
+    await expect(asyncFind(inputArr, filter)).rejects.toThrow('Some error');
+  });
+
+  it('returns type T | undefined given function that returns type Promise<boolean>', async () => {
+    // @ts-expect-no-error
+    const result: number | undefined = await asyncFind(inputArr, largerThanTwoInRandomTime);
+
+    expect(typeof result).toEqual('number');
+  });
+
+  it('returns type undefined given function that returns type Promise<false>', async () => {
+    async function falseInRandomTime() {
+      return new Promise<false>((resolve) =>
+        setTimeout(() => {
+          resolve(false);
+        }, Math.random() * 100),
+      );
+    }
+
+    // @ts-expect-no-error
+    const result: undefined = await asyncFind(inputArr, falseInRandomTime);
+
+    expect(result).toEqual(undefined);
+  });
+});

src/find.ts

@@ -0,0 +1,46 @@
+import asyncForEachStrict from './forEach_strict';
+
+function asyncFind<T>(
+  arr: T[],
+  fn: (cur: T, idx: number, arr: T[]) => Promise<false>,
+): Promise<undefined>;
+function asyncFind<T>(
+  arr: T[],
+  fn: (cur: T, idx: number, arr: T[]) => Promise<boolean>,
+): Promise<T | undefined>;
+function asyncFind<T>(
+  arr: T[],
+  fn: (cur: T, idx: number, arr: T[]) => Promise<boolean>,
+): Promise<T | undefined> {
+  let resolved: boolean;
+  return new Promise<T | undefined>((resolve, reject) => {
+    asyncForEachStrict(
+      arr,
+      (cur, idx, arr2) =>
+        new Promise<void>((resolve2, reject2) => {
+          if (resolved) {
+            return;
+          }
+          fn(cur, idx, arr2)
+            .then((result) => {
+              if (result) {
+                resolve(cur);
+                resolved = true;
+              }
+              resolve2();
+            })
+            .catch(reject2);
+        }),
+    )
+      .then(() => {
+        resolve(undefined);
+        resolved = true;
+      })
+      .catch((error) => {
+        reject(error);
+        resolved = true;
+      });
+  });
+}
+
+export default asyncFind;