maxBy (for BigInts)

Returns the element of an array whose derived BigInt value is the largest.

const largest = maxBy(items, getValue);

INFO

This function is available exclusively from es-toolkit/bigint to avoid potential conflicts with similar functions for other numeric types.

Usage

maxBy(items, getValue)

Use maxBy when the BigInts you want to compare are inside objects and you want the whole object back, not just the number. Pass a function that pulls the value out of each element.

import { maxBy } from 'es-toolkit/bigint';

const accounts = [
  { owner: 'alice', balance: 10n },
  { owner: 'bob', balance: 30n },
  { owner: 'carol', balance: 20n },
];

const richest = maxBy(accounts, account => account.balance);
console.log(richest); // { owner: 'bob', balance: 30n }

When several elements tie for the largest value, the first one wins. getValue also receives the index and the whole array.

import { maxBy } from 'es-toolkit/bigint';

const first = { id: 'a', score: 30n };
const second = { id: 'b', score: 30n };
console.log(maxBy([first, second], item => item.score)); // { id: 'a', score: 30n }

// Compare by a value derived from both the element and its position
const rounds = [{ points: 5n }, { points: 5n }, { points: 5n }];
const best = maxBy(rounds, (round, index) => round.points * BigInt(index + 1));
console.log(best); // the third round, because its multiplier is the largest

An empty array has no element to return, so it throws.

import { maxBy } from 'es-toolkit/bigint';

maxBy([], () => 0n); // RangeError: Cannot find the maximum of an empty array.

Parameters

• items (readonly T[]): The array of elements to search.
• getValue ((element: T, index: number, array: readonly T[]) => bigint): A function that returns the BigInt to compare by.

Returns

(T): Returns the element with the largest derived BigInt. Returns the first of several elements that tie.

Throws

Throws a RangeError if the array is empty.