Added async functions for Array.every, Array.find, and Array.some (#50)

* Added async functions for Array.every, Array.find, and Array.some

* Upgraded dependencies

Author: bameyrick

README.md

@@ -26,7 +26,10 @@ A collection of useful utility functions with associated TypeScript types.
         - [IndividualEqualityType](#individualequalitytype)
       - [randomNumberBetweenRange](#randomnumberbetweenrange)
     - [Async helpers](#async-helpers)
+      - [asyncEvery](#asyncevery)
+      - [asyncFilter](#asyncfilter)
       - [asyncForEach](#asyncforeach)
+      - [asyncSome](#asyncsome)
       - [delay](#delay)
     - [Date helpers](#date-helpers)
       - [convertTimeUnit](#converttimeunit)
@@ -379,6 +382,90 @@ const random = randomNumberBetweenRange(2, 10);
 
 ---
 
+#### asyncEvery
+
+Allows you to run Array.every() with an async predicate function and await the result.
+
+Method arguments:
+
+| Parameter | Type     | Optional | Description                               |
+| --------- | -------- | -------- | ----------------------------------------- |
+| items     | Array<T> | false    | The items to iterate over                 |
+| predicate | Function | false    | A predicate function to run for each item |
+
+Callback arguments:
+
+| Parameter | Type     | Optional | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| item      | T        | true     | The current item from the loop      |
+| index     | number   | true     | The index of the given in the array |
+| array     | Array<T> | true     | The array provided                  |
+
+Return type:
+
+```typescript
+Promise<boolean>;
+```
+
+**Example**
+
+```typescript
+import { asyncEvery } from '@qntm-code/utils';
+
+async function doAThing(): Promise<void> {
+  // Array of items to iterate over
+  const items: Array<string> = ['a', 'b', 'c'];
+
+  const result = await asyncEvery(items, async item => await someAsynchronousOperation(item));
+
+  functionToRunWhenAllItemsAreProcessed(result);
+}
+```
+
+---
+
+#### asyncFilter
+
+Allows you to run Array.filter() with an async predicate function and await the result.
+
+Method arguments:
+
+| Parameter | Type     | Optional | Description                               |
+| --------- | -------- | -------- | ----------------------------------------- |
+| items     | Array<T> | false    | The items to iterate over                 |
+| predicate | Function | false    | A predicate function to run for each item |
+
+Callback arguments:
+
+| Parameter | Type     | Optional | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| item      | T        | true     | The current item from the loop      |
+| index     | number   | true     | The index of the given in the array |
+| array     | Array<T> | true     | The array provided                  |
+
+Return type:
+
+```typescript
+Promise<T[]>;
+```
+
+**Example**
+
+```typescript
+import { asyncFilter } from '@qntm-code/utils';
+
+async function doAThing(): Promise<void> {
+  // Array of items to iterate over
+  const items: Array<string> = ['a', 'b', 'c'];
+
+  const results = await asyncFilter(items, async item => await someAsynchronousOperation(item));
+
+  functionToRunWhenAllItemsAreProcessed(results);
+}
+```
+
+---
+
 #### asyncForEach
 
 Allows you to iterate over an array asynchronously.
@@ -401,7 +488,7 @@ Callback arguments:
 Return type:
 
 ```typescript
-Promise<void>
+Promise<void>;
 ```
 
 **Example**
@@ -413,16 +500,56 @@ async function doAThing(): Promise<void> {
   // Array of items to iterate over
   const items: Array<string> = ['a', 'b', 'c'];
 
-  await asyncForEach(items, async item => {
-    const result = await someAsynchronousOperation(item);
-  });
+  await asyncForEach(items, async item => await someAsynchronousOperation(item));
 
   functionToRunWhenAllItemsAreProcessed();
 }
 ```
 
 ---
 
+#### asyncSome
+
+Allows you to run Array.some() with an async predicate function and await the result.
+
+Method arguments:
+
+| Parameter | Type     | Optional | Description                               |
+| --------- | -------- | -------- | ----------------------------------------- |
+| items     | Array<T> | false    | The items to iterate over                 |
+| predicate | Function | false    | A predicate function to run for each item |
+
+Callback arguments:
+
+| Parameter | Type     | Optional | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| item      | T        | true     | The current item from the loop      |
+| index     | number   | true     | The index of the given in the array |
+| array     | Array<T> | true     | The array provided                  |
+
+Return type:
+
+```typescript
+Promise<boolean>;
+```
+
+**Example**
+
+```typescript
+import { asyncSome } from '@qntm-code/utils';
+
+async function doAThing(): Promise<void> {
+  // Array of items to iterate over
+  const items: Array<string> = ['a', 'b', 'c'];
+
+  const result = await asyncSome(items, async item => await someAsynchronousOperation(item));
+
+  functionToRunWhenAllItemsAreProcessed(result);
+}
+```
+
+---
+
 #### delay
 
 Delays an async function using await given an optionally provided duration.
@@ -436,7 +563,7 @@ Method arguments:
 Return type:
 
 ```typescript
-Promise<void>
+Promise<void>;
 ```
 
 **Example**

src/async/asyncEvery.ts

@@ -0,0 +1,12 @@
+/**
+ * Allows you to run [Array#every](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) asynchronously
+ */
+export async function asyncEvery<T>(array: T[], predicate: (item: T, index: number, array: T[]) => Promise<boolean>): Promise<boolean> {
+  for (let index = 0, arrayLength = array.length; index < arrayLength; index++) {
+    if (!(await predicate(array[index], index, array))) {
+      return false;
+    }
+  }
+
+  return true;
+}

src/async/asyncFilter.ts

@@ -0,0 +1,8 @@
+/**
+ * Allows you to filter an array asynchronously
+ */
+export async function asyncFilter<T>(array: T[], callback: (item: T, index: number, array: T[]) => Promise<boolean>): Promise<T[]> {
+  const results = await Promise.all(array.map(callback));
+
+  return array.filter((_v, index) => results[index]);
+}

src/async/asyncForEach.ts

@@ -1,8 +1,7 @@
 /**
  * Allows you to iterate over an array asynchronously
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
-export async function asyncForEach<T>(array: T[], callback: (item: T, index: number, array: T[]) => Promise<{}>): Promise<any> {
+export async function asyncForEach<T>(array: T[], callback: (item: T, index: number, array: T[]) => Promise<unknown>): Promise<void> {
   for (let index = 0, arrayLength = array.length; index < arrayLength; index++) {
     await callback(array[index], index, array);
   }

src/async/asyncSome.ts

@@ -0,0 +1,12 @@
+/**
+ * Allows you to run [Array#some](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) asynchronously
+ */
+export async function asyncSome<T>(array: T[], predicate: (item: T, index: number, array: T[]) => Promise<boolean>): Promise<boolean> {
+  for (let index = 0, arrayLength = array.length; index < arrayLength; index++) {
+    if (await predicate(array[index], index, array)) {
+      return true;
+    }
+  }
+
+  return false;
+}

src/async/index.ts

@@ -1,2 +1,5 @@
+export { asyncEvery } from './asyncEvery';
+export { asyncFilter } from './asyncFilter';
 export { asyncForEach } from './asyncForEach';
+export { asyncSome } from './asyncSome';
 export { delay } from './delay';

tests/async/asyncEvery.spec.ts

@@ -0,0 +1,19 @@
+import { asyncEvery } from '../../src';
+
+describe(`asyncEvery`, () => {
+  it(`should return true if all items in the array match the predicate`, async () => {
+    const result = await asyncEvery([1, 2, 3, 4, 5], value => {
+      return new Promise(resolve => setTimeout(() => resolve(value % 2 === 0), 10));
+    });
+
+    expect(result).toBe(false);
+  });
+
+  it(`should return false if not all items in the array match the predicate`, async () => {
+    const result = await asyncEvery([2, 4, 6, 8, 10], value => {
+      return new Promise(resolve => setTimeout(() => resolve(value % 2 === 0), 10));
+    });
+
+    expect(result).toBe(true);
+  });
+});

tests/async/asyncFilter.spec.ts

@@ -0,0 +1,11 @@
+import { asyncFilter } from '../../src';
+
+describe(`asyncFilter`, () => {
+  it(`should filter the array`, async () => {
+    const result = await asyncFilter([1, 2, 3, 4, 5], value => {
+      return new Promise(resolve => setTimeout(() => resolve(value % 2 === 0), 10));
+    });
+
+    expect(result).toEqual([2, 4]);
+  });
+});

tests/async/asyncSome.spec.ts

@@ -0,0 +1,19 @@
+import { asyncSome } from '../../src';
+
+describe(`asyncSome`, () => {
+  it(`should return true if the predicate returns true for any value in the array`, async () => {
+    const result = await asyncSome([1, 2, 3, 4, 5], value => {
+      return new Promise(resolve => setTimeout(() => resolve(value % 2 === 0), 10));
+    });
+
+    expect(result).toBe(true);
+  });
+
+  it(`should return false if the predicate returns false for all values in the array`, async () => {
+    const result = await asyncSome([1, 3, 5], value => {
+      return new Promise(resolve => setTimeout(() => resolve(value % 2 === 0), 10));
+    });
+
+    expect(result).toBe(false);
+  });
+});