range (for BigInts)

Returns an array of BigInts counting from a start value up to, but not including, an end value.

const numbers = range(end);
const numbers = range(start, end);
const numbers = range(start, end, step);

INFO

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

Usage

range(end)

Use range with one argument to count from 0n up to, but not including, the end value.

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

console.log(range(4n)); // [0n, 1n, 2n, 3n]
console.log(range(0n)); // []

Parameters

• end (bigint): The end of the range, exclusive.

Returns

(bigint[]): Returns an array of BigInts from 0n up to, but not including, end.

range(start, end)

Use range with two arguments to count from a start value instead of 0n.

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

console.log(range(2n, 5n)); // [2n, 3n, 4n]
console.log(range(-3n, 0n)); // [-3n, -2n, -1n]

// Nothing to count when start and end are the same
console.log(range(3n, 3n)); // []

Because BigInts stay exact at any size, you can build ranges past Number.MAX_SAFE_INTEGER without values silently colliding.

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

console.log(range(9007199254740993n, 9007199254740996n));
// [9007199254740993n, 9007199254740994n, 9007199254740995n]

Parameters

• start (bigint): The start of the range, inclusive.
• end (bigint): The end of the range, exclusive.

Returns

(bigint[]): Returns an array of BigInts from start up to, but not including, end.

range(start, end, step)

Use range with three arguments to count by something other than 1n. A negative step counts down.

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

console.log(range(0n, 10n, 2n)); // [0n, 2n, 4n, 6n, 8n]
console.log(range(5n, 0n, -1n)); // [5n, 4n, 3n, 2n, 1n]
console.log(range(5n, 0n, -2n)); // [5n, 3n, 1n]

If the step points away from the end value, there is nothing to produce and you get an empty array.

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

console.log(range(0n, 5n, -1n)); // []
console.log(range(5n, 0n, 1n)); // []

Parameters

• start (bigint): The start of the range, inclusive.
• end (bigint): The end of the range, exclusive.
• step (bigint, optional): The amount to count by. Defaults to 1n.

Returns

(bigint[]): Returns an array of BigInts from start up to, but not including, end, counting by step.

Throws

Throws an error if step is 0n.