groupBy

function stable

`groupBy<T, K, R>(keySelector: (value: T) => K, elementOrOptions?: void | ((value: any) => any) | BasicGroupByOptions<K, T> | GroupByOptionsWithElement<K, R, T>, duration?: (grouped: GroupedObservable<any, any>) => ObservableInput<any>, connector?: () => SubjectLike<any>): OperatorFunction<T, GroupedObservable<K, R>>`

Parameters

keySelector	Type: `(value: T) => K`.
elementOrOptions	Optional. Default is `undefined`. Type: `void \| ((value: any) => any) \| BasicGroupByOptions \| GroupByOptionsWithElement`.
duration	Optional. Default is `undefined`. Type: `(grouped: GroupedObservable) => ObservableInput`.
connector	Optional. Default is `undefined`. Type: `() => SubjectLike`.

Returns

OperatorFunction<T, GroupedObservable<K, R>>

Overloads

`groupBy(key: (value: T) => K, options: BasicGroupByOptions<K, T>): OperatorFunction<T, GroupedObservable<K, T>>`

Parameters

key	Type: `(value: T) => K`.
options	Type: `BasicGroupByOptions`.

Returns

OperatorFunction<T, GroupedObservable<K, T>>

`groupBy(key: (value: T) => K, options: GroupByOptionsWithElement<K, E, T>): OperatorFunction<T, GroupedObservable<K, E>>`

Parameters

key	Type: `(value: T) => K`.
options	Type: `GroupByOptionsWithElement`.

Returns

OperatorFunction<T, GroupedObservable<K, E>>

`groupBy(key: (value: T) => value is K): OperatorFunction<T, GroupedObservable<true, K> | GroupedObservable<false, Exclude<T, K>>>`

Parameters

key	Type: `(value: T) => value is K`.

Returns

OperatorFunction<T, GroupedObservable<true, K> | GroupedObservable<false, Exclude<T, K>>>

`groupBy(key: (value: T) => K): OperatorFunction<T, GroupedObservable<K, T>>`

Parameters

key	Type: `(value: T) => K`.

Returns

OperatorFunction<T, GroupedObservable<K, T>>

`groupBy(key: (value: T) => K, element: void, duration: (grouped: GroupedObservable<K, T>) => Observable<any>): OperatorFunction<T, GroupedObservable<K, T>>`

Deprecation Notes

use the options parameter instead.

Parameters

key	Type: `(value: T) => K`.
element	Type: `void`.
duration	Type: `(grouped: GroupedObservable) => Observable`.

Returns

OperatorFunction<T, GroupedObservable<K, T>>

`groupBy(key: (value: T) => K, element?: (value: T) => R, duration?: (grouped: GroupedObservable<K, R>) => Observable<any>): OperatorFunction<T, GroupedObservable<K, R>>`

Deprecation Notes

use the options parameter instead.

Parameters

key

Type: (value: T) => K.

element

Optional. Default is undefined.

Type: (value: T) => R.

duration

Optional. Default is undefined.

Type: (grouped: GroupedObservable) => Observable.

Returns

OperatorFunction<T, GroupedObservable<K, R>>

`groupBy(key: (value: T) => K, element?: (value: T) => R, duration?: (grouped: GroupedObservable<K, R>) => Observable<any>, connector?: () => Subject<R>): OperatorFunction<T, GroupedObservable<K, R>>`

Groups the items emitted by an Observable according to a specified criterion, and emits these grouped items as GroupedObservables, one GroupedObservable per group.

Deprecation Notes

Use the options parameter instead.

Parameters

key	A function that extracts the key for each item.
element	Optional. Default is `undefined`. A function that extracts the return element for each item.
duration	Optional. Default is `undefined`. A function that returns an Observable to determine how long each group should exist.
connector	Optional. Default is `undefined`. Factory function to create an intermediate Subject through which grouped elements are emitted.

Returns

OperatorFunction<T, GroupedObservable<K, R>>: A function that returns an Observable that emits GroupedObservables, each of which corresponds to a unique key value and each of which emits those items from the source Observable that share that key value.

groupBy marble diagram

When the Observable emits an item, a key is computed for this item with the key function.

If a GroupedObservable for this key exists, this GroupedObservable emits. Otherwise, a new GroupedObservable for this key is created and emits.

A GroupedObservable represents values belonging to the same group represented by a common key. The common key is available as the key field of a GroupedObservable instance.

The elements emitted by GroupedObservables are by default the items emitted by the Observable, or elements returned by the element function.

Examples

Group objects by id and return as array

import { of } from 'rxjs';
import { mergeMap, groupBy, reduce } from 'rxjs/operators';

of(
  {id: 1, name: 'JavaScript'},
  {id: 2, name: 'Parcel'},
  {id: 2, name: 'webpack'},
  {id: 1, name: 'TypeScript'},
  {id: 3, name: 'TSLint'}
).pipe(
  groupBy(p => p.id),
  mergeMap((group$) => group$.pipe(reduce((acc, cur) => [...acc, cur], [])))
)
.subscribe(p => console.log(p));

// displays:
// [ { id: 1, name: 'JavaScript'},
//   { id: 1, name: 'TypeScript'} ]
//
// [ { id: 2, name: 'Parcel'},
//   { id: 2, name: 'webpack'} ]
//
// [ { id: 3, name: 'TSLint'} ]

Pivot data on the id field

import { of } from 'rxjs';
import { groupBy, map, mergeMap, reduce } from 'rxjs/operators';

of(
  { id: 1, name: 'JavaScript' },
  { id: 2, name: 'Parcel' },
  { id: 2, name: 'webpack' },
  { id: 1, name: 'TypeScript' },
  { id: 3, name: 'TSLint' }
)
  .pipe(
    groupBy(p => p.id, p => p.name),
    mergeMap(group$ =>
      group$.pipe(reduce((acc, cur) => [...acc, cur], [`${group$.key}`]))
    ),
    map(arr => ({ id: parseInt(arr[0], 10), values: arr.slice(1) }))
 )
 .subscribe(p => console.log(p));

// displays:
// { id: 1, values: [ 'JavaScript', 'TypeScript' ] }
// { id: 2, values: [ 'Parcel', 'webpack' ] }
// { id: 3, values: [ 'TSLint' ] }

© 2015–2021 Google, Inc., Netflix, Inc., Microsoft Corp. and contributors.
Code licensed under an Apache-2.0 License. Documentation licensed under CC BY 4.0.
https://rxjs.dev/api/operators/groupBy