For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/bigint/maxBy.md.
Install massaman

    maxBy (for BigInts) es-toolkit

    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

    itemsreadonly T[]required

    The array of elements to search.

    getValue(element: T, index: number, array: readonly T[]) => bigintrequired

    A function that returns the BigInt to compare by.

    Returns

    Returns the element with the largest derived BigInt. Returns the first of several elements that tie.

    T

    Throws

    Throws a RangeError if the array is empty.

    Source: es-toolkit

    Re-exported verbatim from es-toolkit. Implementation, edge cases, and performance behavior are owned upstream. This page mirrors the documentation at the pinned version; the linked source is authoritative.