dce-reactkit 3.7.3 → 3.7.5

package/src/helpers/asyncArrayFunctions/filterAsync.test.ts

@@ -0,0 +1,126 @@
+import filterAsync from './filterAsync';
+
+describe('filterAsync', () => {
+  it('should return an empty array when given an empty array', async () => {
+    const result = await filterAsync(
+      [],
+      async () => {
+        return true;
+      },
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should return the original array when all items pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return true;
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should return an empty array when no items pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return false;
+      },
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should return only the items that pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (item) => {
+        return item > 1;
+      },
+    );
+    expect(result).toEqual([2, 3]);
+  });
+
+  it('should pass the correct index to the operator function', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index) => {
+        return index === 1;
+      },
+    );
+    expect(result).toEqual([2]);
+  });
+
+  it('should allow breaking out of the loop early', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index, { breakNow }) => {
+        if (index === 1) {
+          breakNow();
+        }
+        return true;
+      },
+    );
+    expect(result).toEqual([1]);
+  });
+
+  it('should pass the original array to the operator function', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index, { array }) => {
+        return array.length === 3;
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should handle an operator function that returns a non-boolean value', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return 'hello';
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should handle an operator function that throws an error', async () => {
+    const originalArray = [1, 2, 3];
+    let error: any = null;
+    let result: number[] | null = null;
+    try {
+      result = await filterAsync(
+        originalArray,
+        async () => {
+          throw new Error('Something went wrong');
+        },
+      );
+    } catch (err) {
+      error = err;
+    }
+    expect(result).toEqual(null);
+    expect(error).not.toBe(null);
+  });
+
+  it('should handle an array of objects', async () => {
+    const originalArray = [
+      { name: 'Alice', age: 30 },
+      { name: 'Bob', age: 25 },
+      { name: 'Charlie', age: 35 },
+    ];
+    const result = await filterAsync(
+      originalArray,
+      async (item) => {
+        return (item.age > 30);
+      },
+    );
+    expect(result).toEqual([{ name: 'Charlie', age: 35 }]);
+  });
+});

package/src/helpers/asyncArrayFunctions/filterAsync.ts

@@ -0,0 +1,50 @@
+/**
+ * Run the operator function on each item in the array, returning a new array
+ *   that only contains the items that pass the filter
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply. If it returns true
+ *   for an item, the item will be included in the returned array
+ * @returns the filtered array
+ */
+const filterAsync = async <T>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => Promise<any>,
+): Promise<T[]> => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop (filtering stops here)
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item, filtering
+  const output: T[] = [];
+  for (let i = 0; i < array.length && !done; i++) {
+    const included = await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+    if (included && !done) {
+      output.push(array[i]);
+    }
+  }
+
+  // Return results
+  return output;
+};
+
+export default filterAsync;

package/src/helpers/asyncArrayFunctions/forEachAsync.test.ts

@@ -0,0 +1,136 @@
+import forEachAsync from './forEachAsync';
+
+describe('forEachAsync', () => {
+  it('should call the operator function for each item in the array', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(3);
+    expect(operatorFunction).toHaveBeenCalledWith(1, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(2, 1, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(3, 2, expect.any(Object));
+  });
+
+  it('should pass the correct arguments to the operator function', async () => {
+    const array = ['a', 'b', 'c'];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(3);
+    expect(operatorFunction).toHaveBeenCalledWith('a', 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith('b', 1, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith('c', 2, expect.any(Object));
+  });
+
+  it('should allow the operator function to break out of the loop', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn((item, index, { breakNow }) => {
+      if (item === 2) {
+        breakNow();
+      }
+    });
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(2);
+    expect(operatorFunction).toHaveBeenCalledWith(1, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(2, 1, expect.any(Object));
+  });
+
+  it('should not call the operator function if the array is empty', async () => {
+    const array: string[] = [];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).not.toHaveBeenCalled();
+  });
+
+  it('should return undefined', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn();
+
+    const result = await forEachAsync(array, operatorFunction);
+
+    expect(result).toBeUndefined();
+  });
+
+  it('should work with an array of objects', async () => {
+    const array = [
+      { name: 'Alice', age: 30 },
+      { name: 'Bob', age: 25 },
+      { name: 'Charlie', age: 40 },
+    ];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(3);
+    expect(operatorFunction).toHaveBeenCalledWith(
+      { name: 'Alice', age: 30 },
+      0,
+      expect.any(Object),
+    );
+    expect(operatorFunction).toHaveBeenCalledWith(
+      { name: 'Bob', age: 25 },
+      1,
+      expect.any(Object),
+    );
+    expect(operatorFunction).toHaveBeenCalledWith(
+      { name: 'Charlie', age: 40 },
+      2,
+      expect.any(Object),
+    );
+  });
+
+  it('should work with an array of mixed types', async () => {
+    const array = [1, 'two', { three: 3 }];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(3);
+    expect(operatorFunction).toHaveBeenCalledWith(1, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith('two', 1, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(
+      { three: 3 },
+      2,
+      expect.any(Object),
+    );
+  });
+
+  it('should work with an array of length 1', async () => {
+    const array = ['a'];
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(1);
+    expect(operatorFunction).toHaveBeenCalledWith('a', 0, expect.any(Object));
+  });
+
+  it('should work with an array of length 100', async () => {
+    const array = Array.from({ length: 100 }, (_, i) => i);
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(100);
+    expect(operatorFunction).toHaveBeenCalledWith(0, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(99, 99, expect.any(Object));
+  });
+
+  it('should work with an array of length 1000', async () => {
+    const array = Array.from({ length: 1000 }, (_, i) => i);
+    const operatorFunction = jest.fn();
+
+    await forEachAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(1000);
+    expect(operatorFunction).toHaveBeenCalledWith(0, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(999, 999, expect.any(Object));
+  });
+});

package/src/helpers/asyncArrayFunctions/forEachAsync.ts

@@ -0,0 +1,40 @@
+/**
+ * Run the operator function on each item in the array
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply
+ */
+const forEachAsync = async <T>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => void,
+) => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item
+  for (let i = 0; i < array.length && !done; i++) {
+    await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+  }
+};
+
+export default forEachAsync;

package/src/helpers/asyncArrayFunctions/mapAsync.test.ts

@@ -0,0 +1,125 @@
+import waitMs from '../waitMs';
+import mapAsync from './mapAsync';
+
+describe('mapAsync', () => {
+  it('should return an empty array when given an empty array', async () => {
+    const result = await mapAsync([], async () => {
+      // Operator function logic goes here
+    });
+
+    expect(result).toEqual([]);
+  });
+
+  it('should apply the operator function to each item in the array', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn();
+
+    await mapAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledTimes(3);
+    expect(operatorFunction).toHaveBeenCalledWith(1, 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(2, 1, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(3, 2, expect.any(Object));
+  });
+
+  it('should collect and return the results of the operator function', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = async (item: number) => {
+      return item * 2;
+    };
+
+    const result = await mapAsync(array, operatorFunction);
+
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it('should pass the correct index to the operator function', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn();
+
+    await mapAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledWith(expect.anything(), 0, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(expect.anything(), 1, expect.any(Object));
+    expect(operatorFunction).toHaveBeenCalledWith(expect.anything(), 2, expect.any(Object));
+  });
+
+  it('should pass the correct options object to the operator function', async () => {
+    const array = [1, 2, 3];
+    const operatorFunction = jest.fn();
+
+    await mapAsync(array, operatorFunction);
+
+    expect(operatorFunction).toHaveBeenCalledWith(expect.anything(), expect.anything(), {
+      breakNow: expect.any(Function),
+      array: expect.any(Array),
+    });
+  });
+
+  it('should allow the operator function to break the loop', async () => {
+    const array = [1, 2, 3];
+
+    const result = await mapAsync(
+      array,
+      async (
+        item,
+        index,
+        { breakNow },
+      ) => {
+        if (item === 2) {
+          breakNow();
+        }
+        return item;
+      },
+    );
+
+    expect(result).toEqual([1]);
+  });
+
+  it('should handle asynchronous operator function', async () => {
+    const array = [1, 2, 3];
+    const result = await mapAsync(
+      array,
+      async (item) => {
+        await waitMs(1000);
+        return item * 2;
+      },
+    );
+
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it('should handle errors thrown by the operator function', async () => {
+    const array = [1, 2, 3];
+
+    await expect(
+      mapAsync(
+        array,
+        async (item) => {
+          if (item === 2) {
+            throw new Error('Error processing item');
+          }
+          return item * 2;
+        },
+      ),
+    ).rejects.toThrow('Error processing item');
+  });
+
+  it('should handle empty array with breakNow called', async () => {
+    const array: number[] = [];
+
+    const result = await mapAsync(
+      array,
+      async (
+        item,
+        index,
+        { breakNow },
+      ) => {
+        breakNow();
+        return item;
+      },
+    );
+
+    expect(result).toEqual([]);
+  });
+});

package/src/helpers/asyncArrayFunctions/mapAsync.ts

@@ -0,0 +1,46 @@
+/**
+ * Run the operator function on each item in the array, collecting all results
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply
+ * @returns the array of results
+ */
+const mapAsync = async <T, U>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => Promise<U>,
+): Promise<U[]> => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item, collecting results
+  const results: U[] = [];
+  for (let i = 0; i < array.length && !done; i++) {
+    const result = await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+    results.push(result);
+  }
+
+  // Return results
+  return results;
+};
+
+export default mapAsync;

package/src/helpers/asyncArrayFunctions/someAsync.test.ts

@@ -0,0 +1,92 @@
+import waitMs from '../waitMs';
+import someAsync from './someAsync';
+
+describe('someAsync', () => {
+  it('should return false if the array is empty', async () => {
+    const result = await someAsync([], () => {
+      return Promise.resolve(true);
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should return false if the operator function returns false for all items', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, () => {
+      return Promise.resolve(false);
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should return true if the operator function returns true for any item', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, (item) => {
+      return Promise.resolve(item === 3);
+    });
+    expect(result).toBe(true);
+  });
+
+  it('should pass the correct index to the operator function', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, (item, index) => {
+      expect(index).toBeGreaterThanOrEqual(0);
+      expect(index).toBeLessThan(array.length);
+      return Promise.resolve(false);
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should pass the correct array to the operator function', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, (item, index, { array: arr }) => {
+      expect(arr).toBe(array);
+      return Promise.resolve(false);
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should stop iterating and return true if the operator function returns true for an item and breakNow is called', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, (item, index, { breakNow }) => {
+      if (item === 3) {
+        breakNow();
+        return Promise.resolve(true);
+      }
+      return Promise.resolve(false);
+    });
+    expect(result).toBe(true);
+  });
+
+  it('should handle asynchronous operator function', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, async (item) => {
+      await waitMs(100);
+      return Promise.resolve(item === 3);
+    });
+    expect(result).toBe(true);
+  });
+
+  it('should handle rejected promises from the operator function', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, () => {
+      return Promise.reject(new Error('Test error'));
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should handle thrown errors from the operator function', async () => {
+    const array = [1, 2, 3, 4, 5];
+    const result = await someAsync(array, () => {
+      throw new Error('Test error');
+    });
+    expect(result).toBe(false);
+  });
+
+  it('should handle empty array and asynchronous operator function', async () => {
+    const array: number[] = [];
+    const result = await someAsync(array, async () => {
+      await waitMs(100);
+      return Promise.resolve(false);
+    });
+    expect(result).toBe(false);
+  });
+});

package/src/helpers/asyncArrayFunctions/someAsync.ts

@@ -0,0 +1,49 @@
+/**
+ * Run the operator function on each item in the array, returning true if
+ *   the operator function returns true for any item in the array
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply. If it returns true
+ *   for any item, this function will return true
+ * @returns true if the operator function returns true for any item in the array
+ */
+const someAsync = async <T>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => Promise<any>,
+): Promise<boolean> => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop (checking stops here)
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item, checking
+  for (let i = 0; i < array.length && !done; i++) {
+    const passed = await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+    if (passed && !done) {
+      return true;
+    }
+  }
+
+  // Return false because none returned true
+  return false;
+};
+
+export default someAsync;

package/src/index.ts

@@ -85,6 +85,11 @@ import makeLinksClickable from './helpers/makeLinksClickable';
 import combineClassNames from './helpers/combineClassNames';
 import prefixWithAOrAn from './helpers/prefixWithAOrAn';
 import useForceRender from './helpers/useForceRender';
+import everyAsync from './helpers/asyncArrayFunctions/everyAsync';
+import filterAsync from './helpers/asyncArrayFunctions/filterAsync';
+import forEachAsync from './helpers/asyncArrayFunctions/forEachAsync';
+import mapAsync from './helpers/asyncArrayFunctions/mapAsync';
+import someAsync from './helpers/asyncArrayFunctions/someAsync';
 
 // Import types
 import ModalButtonType from './types/ModalButtonType';
@@ -181,6 +186,11 @@ export {
   idify,
   makeLinksClickable,
   prefixWithAOrAn,
+  everyAsync,
+  filterAsync,
+  forEachAsync,
+  mapAsync,
+  someAsync,
   // Client helpers
   initClient,
   visitServerEndpoint,