group

Group array elements into an object based on the specified key.

Basic Usage

import { group } from 'radash'

const users = [
  { id: 1, name: 'Alice', age: 25, city: 'Beijing' },
  { id: 2, name: 'Bob', age: 30, city: 'Shanghai' },
  { id: 3, name: 'Charlie', age: 35, city: 'Beijing' },
  { id: 4, name: 'Diana', age: 28, city: 'Shanghai' }
]

const groupedByCity = group(users, user => user.city)
// {
//   'Beijing': [
//     { id: 1, name: 'Alice', age: 25, city: 'Beijing' },
//     { id: 3, name: 'Charlie', age: 35, city: 'Beijing' }
//   ],
//   'Shanghai': [
//     { id: 2, name: 'Bob', age: 30, city: 'Shanghai' },
//     { id: 4, name: 'Diana', age: 28, city: 'Shanghai' }
//   ]
// }

Syntax

function group<T, K extends string | number | symbol>(
  array: readonly T[],
  key: (item: T, index: number, array: readonly T[]) => K
): Record<K, T[]>

Parameters

• array (readonly T[]): The array to group
• key (function): Function to generate grouping keys
  • item (T): Current element
  • index (number): Index of the current element
  • array (readonly T[]): The original array

Return Value

Returns an object where keys are grouping keys and values are arrays containing all elements of that group.

Examples

Group by Age

import { group } from 'radash'

const users = [
  { id: 1, name: 'Alice', age: 25 },
  { id: 2, name: 'Bob', age: 30 },
  { id: 3, name: 'Charlie', age: 25 },
  { id: 4, name: 'Diana', age: 30 },
  { id: 5, name: 'Eve', age: 35 }
]

const groupedByAge = group(users, user => user.age)
// {
//   25: [
//     { id: 1, name: 'Alice', age: 25 },
//     { id: 3, name: 'Charlie', age: 25 }
//   ],
//   30: [
//     { id: 2, name: 'Bob', age: 30 },
//     { id: 4, name: 'Diana', age: 30 }
//   ],
//   35: [
//     { id: 5, name: 'Eve', age: 35 }
//   ]
// }

Group by String Length

import { group } from 'radash'

const words = ['apple', 'banana', 'cherry', 'date', 'elderberry', 'fig']

const groupedByLength = group(words, word => word.length)
// {
//   5: ['apple'],
//   6: ['banana', 'cherry'],
//   4: ['date'],
//   10: ['elderberry'],
//   3: ['fig']
// }

Group by Condition

import { group } from 'radash'

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

const groupedByParity = group(numbers, num => num % 2 === 0 ? 'even' : 'odd')
// {
//   even: [2, 4, 6, 8, 10],
//   odd: [1, 3, 5, 7, 9]
// }

Group by Multiple Properties

import { group } from 'radash'

const products = [
  { id: 1, name: 'Laptop', category: 'Electronics', price: 999 },
  { id: 2, name: 'Phone', category: 'Electronics', price: 599 },
  { id: 3, name: 'Book', category: 'Books', price: 19 },
  { id: 4, name: 'Tablet', category: 'Electronics', price: 399 }
]

const groupedByCategory = group(products, product => product.category)
// {
//   'Electronics': [
//     { id: 1, name: 'Laptop', category: 'Electronics', price: 999 },
//     { id: 2, name: 'Phone', category: 'Electronics', price: 599 },
//     { id: 4, name: 'Tablet', category: 'Electronics', price: 399 }
//   ],
//   'Books': [
//     { id: 3, name: 'Book', category: 'Books', price: 19 }
//   ]
// }

Group by Index

import { group } from 'radash'

const items = ['a', 'b', 'c', 'd', 'e']

const groupedByIndex = group(items, (_, index) => Math.floor(index / 2))
// {
//   0: ['a', 'b'],
//   1: ['c', 'd'],
//   2: ['e']
// }

Notes

1. Keep the original array unchanged: group does not modify the original array, but returns a new object
2. Key uniqueness: Elements with the same key will be collected into the same array
3. Empty array handling: If the original array is empty, returns an empty object
4. Performance: Time complexity is O(n), where n is the array length

Differences from Other Methods

• reduce(): Can be used for grouping, but requires manually building the result object
• group(): Specifically designed for grouping, syntax is more concise
• groupBy(): Similar functionality, but group is more intuitive

Practical Application Scenarios

1. Data analysis: Group data by category, region, time, etc.
2. User management: Group users by role, department, status, etc.
3. Product management: Group products by category, brand, price range, etc.
4. Log analysis: Group logs by time, level, source, etc.