feat(utils): groupAsync

Signed-off-by: Lexus Drumgold <[email protected]>

src/utils/__tests__/group-async.spec-d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Type Tests - groupAsync
+ * @module tutils/utils/tests/unit-d/groupAsync
+ */
+
+import type Vehicle from '#fixtures/types/vehicle'
+import type testSubject from '../group-async'
+
+describe('unit-d:utils/groupAsync', () => {
+  it('should return Promise<Record<K, T[number][]>>', () => {
+    // Arrange
+    type T = Vehicle[]
+    type K = Vehicle['year']
+    type Expect = Promise<Record<K, T[number][]>>
+
+    // Expect
+    expectTypeOf<typeof testSubject<T, K>>().returns.toEqualTypeOf<Expect>()
+  })
+})

src/utils/__tests__/group-async.spec.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Unit Tests - groupAsync
+ * @module tutils/utils/tests/unit/groupAsync
+ */
+
+import testSubject from '../group-async'
+
+describe('unit:utils/groupAsync', () => {
+  it('should return groups object', async () => {
+    expect(await testSubject([3.1, 4.2, 3.3], Math.floor)).to.eql({
+      3: [3.1, 3.3],
+      4: [4.2]
+    })
+  })
+})

src/utils/__tests__/group.spec.ts

@@ -7,15 +7,9 @@ import testSubject from '../group'
 
 describe('unit:utils/group', () => {
   it('should return groups object', () => {
-    // Arrange
-    const cases: [...Parameters<typeof testSubject<number[]>>, object][] = [
-      [[], vi.fn(), {}],
-      [[3.1, 4.2, 3.3], Math.floor, { 3: [3.1, 3.3], 4: [4.2] }]
-    ]
-
-    // Act + Expect
-    cases.forEach(([arr, key, expected]) => {
-      expect(testSubject(arr, key)).to.eql(expected)
+    expect(testSubject([3.1, 4.2, 3.3], Math.floor)).to.eql({
+      3: [3.1, 3.3],
+      4: [4.2]
     })
   })
 })

src/utils/group-async.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Utilities - groupAsync
+ * @module tutils/utils/groupAsync
+ */
+
+import type { Mapper, PropertyKey } from '#src/types'
+import cast from './cast'
+import isUndefined from './is-undefined'
+import reduceAsync from './reduce-async'
+
+/**
+ * Group each item in an array.
+ *
+ * The return value is a plain object with a key for each group, where each key
+ * value is an array containing group items.
+ *
+ * A `key` function is used to map array items to group keys.
+ *
+ * @see {@linkcode Mapper}
+ *
+ * @todo examples
+ *
+ * @async
+ *
+ * @template T - Array to group
+ * @template K - Identity key type
+ *
+ * @param {T} arr - Array to group
+ * @param {Mapper<T, K | Promise<K>>} key - Group key mapper
+ * @return {Promise<Record<K, T[number][]>>} Groups object
+ */
+const groupAsync = async <
+  T extends readonly unknown[],
+  K extends PropertyKey = PropertyKey
+>(
+  arr: T,
+  key: Mapper<T, K | Promise<K>>
+): Promise<{ [H in K]: T[number][] }> => {
+  return reduceAsync(arr, async (acc, item, i) => {
+    /**
+     * Group key.
+     *
+     * @const {K} k
+     */
+    const k: K = await key(item, i, arr)
+
+    // initialize group
+    isUndefined(acc[k]) && (acc[k] = [])
+
+    // add group item
+    acc[k].push(item)
+
+    return acc
+  }, cast({}))
+}
+
+export default groupAsync

src/utils/index.ts

@@ -32,6 +32,7 @@ export { default as flat } from './flat'
 export { default as fork } from './fork'
 export { default as get } from './get'
 export { default as group } from './group'
+export { default as groupAsync } from './group-async'
 export { default as hasOwn } from './has-own'
 export { default as identity } from './identity'
 export { default as ifelse } from './ifelse'