#chunkBy es-toolkit

Splits an array into chunks of consecutive elements that share the same key.

const chunked = chunkBy(arr, iteratee)

#Usage

#chunkBy(arr, iteratee)

Walking left to right, each element's key is derived by iteratee. Whenever the key differs from the previous element's key, a new chunk is started; otherwise the element is appended to the current chunk. Keys are compared with !== (strict inequality), so equal primitives stay together while distinct object references always start a new chunk.

Unlike chunk, which splits by a fixed size, chunkBy splits by a boundary condition, keeping runs of same-keyed elements together. Reach for it when the grouping is positional rather than global — collapsing repeated log levels, segmenting a timeline by status, or batching sorted rows by their sort key.

import { chunkBy } from 'massaman'
// or:  import { chunkBy } from 'massaman/array'

// Group consecutive equal numbers
chunkBy([1, 1, 2, 3, 3, 3], (value) => value)
// Returns: [[1, 1], [2], [3, 3, 3]]

// Group consecutive words by their length
chunkBy(['a', 'b', 'cd', 'ef', 'g'], (word) => word.length)
// Returns: [['a', 'b'], ['cd', 'ef'], ['g']]

Note that only consecutive runs are grouped. Non-adjacent elements sharing a key land in separate chunks — use groupBy when you want a global grouping.

chunkBy([1, 2, 1], (value) => value)
// Returns: [[1], [2], [1]] — not [[1, 1], [2]]

#Parameters

#Returns

A two-dimensional array where each sub-array is a run of consecutive elements that produced the same key.

T[][]

#Examples

import { chunkBy } from 'massaman/array'

const entries = [
  { level: 'info', msg: 'boot' },
  { level: 'info', msg: 'ready' },
  { level: 'warn', msg: 'retrying' },
  { level: 'info', msg: 'recovered' },
]

chunkBy(entries, (entry) => entry.level)
// Returns:
// [
//   [{ level: 'info', msg: 'boot' }, { level: 'info', msg: 'ready' }],
//   [{ level: 'warn', msg: 'retrying' }],
//   [{ level: 'info', msg: 'recovered' }],
// ]

A data-last version for use with pipe is available from massaman/fp.