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/percentile.md.
Install massaman

    percentile (for BigInts) es-toolkit

    Returns the BigInt at a given percentile of an array.

    const value = percentile(numbers, 90);
    Info

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

    Usage

    percentile(arr, percentile)

    Use percentile when you want to know the value below which a given share of your data falls — a p90 latency, for example. It sorts a copy of the array — your array is left untouched — and picks the value at the matching rank.

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

const latencies = [1n, 2n, 3n, 4n, 5n];

console.log(percentile(latencies, 50)); // 3n
console.log(percentile(latencies, 90)); // 5n

// The array does not need to be sorted beforehand
console.log(percentile([30n, 10n, 20n], 50)); // 20n

    This uses the nearest-rank method, so the answer is always a value that is already in the array. It never interpolates between two values, which means it never has to round.

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

// The midpoint of 1n and 2n would be 1.5, which no BigInt can hold,
// so the nearest rank is returned instead.
console.log(percentile([1n, 2n], 50)); // 1n

// 0 always gives the smallest value and 100 always gives the largest
console.log(percentile([5n, 1n, 3n], 0)); // 1n
console.log(percentile([5n, 1n, 3n], 100)); // 5n

    The percentile itself is an ordinary number between 0 and 100, not a BigInt, because it is a percentage rather than a quantity being measured.

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

percentile([1n, 2n, 3n], 101); // Error: Expected percentile to be <= 100 but got "101".
percentile([], 50); // RangeError: Cannot compute the percentile of an empty array.

    Parameters

    arrreadonly bigint[]required

    The array of BigInts to calculate the percentile of.

    percentilenumberrequired

    The percentile to look up, between 0 and 100.

    Returns

    Returns the BigInt at the given percentile. Always one of the values already in the array.

    bigint

    Throws

    Throws an error if percentile is NaN, less than 0, or greater than 100. 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.