BigInt
Works with JavaScript bigint values.
This module exposes the native BigInt constructor together with helpers for checking, arithmetic, comparison, range checks, safe parsing and conversions that return Option, integer square roots, aggregation, ordering, equivalence, reducers, and combiners.
Constructors
Converting
fromNumber
Converts a number to a bigint.
When to use
Use to convert a JavaScript number to bigint only when it is a safe integer.
Details
If the number is outside the safe integer range for JavaScript (Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER) or if the number is not a valid bigint, it returns Option.none().
See
Signature
declare function fromNumber(n: number): Option<bigint>;fromString
Parses a string into a bigint safely.
When to use
Use to parse a string as a bigint without throwing on invalid input.
Details
If the string is empty or contains characters that cannot be converted into a bigint, it returns Option.none().
See
BigIntfor native constructor coercion that throws on invalid input
Signature
declare function fromString(s: string): Option<bigint>;Converts a bigint to a number safely.
When to use
Use to convert a bigint to a JavaScript number only when it is a safe integer.
Details
If the bigint is outside the safe integer range for JavaScript (Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER), it returns Option.none().
See
fromNumberfor converting a safe integer number tobigint
Signature
declare function toNumber(b: bigint): Option<number>;Guards
Instances
Equivalence
Equivalence instance for bigints using strict equality (===).
When to use
Use when checking bigint equality through APIs that accept an equivalence relation.
Signature
declare const Equivalence: Equ.Equivalence<bigint>;Provides an Order instance for bigint that allows comparing and sorting BigInt values.
When to use
Use when you need to sort or compare bigint values through APIs that accept an ordering instance.
Signature
declare const Order: order.Order<bigint>;Math
Determines the absolute value of a given bigint.
When to use
Use to remove the sign from a bigint while preserving its magnitude.
Signature
declare function abs(n: bigint): bigint;Restricts the given bigint to be within the range specified by the minimum and maximum values.
When to use
Use to force a bigint into an inclusive range.
Details
If the bigint is less than the minimum, the function returns the minimum. If the bigint is greater than the maximum, the function returns the maximum. Otherwise, it returns the original bigint.
See
betweenfor checking whether abigintis already inside a range
Signature
declare const clamp: {
(options: { maximum: bigint; minimum: bigint }): (self: bigint) => bigint;
(
self: bigint,
options: {
maximum: bigint;
minimum: bigint;
},
): bigint;
};CombinerMax
Combiner that returns the maximum bigint.
When to use
Use to keep the largest bigint when an API consumes a Combiner.
See
CombinerMinfor keeping the smallestbigintmaxfor comparing twobigintvalues directly
Signature
declare const CombinerMax: Combiner.Combiner<bigint>;CombinerMin
Combiner that returns the minimum bigint.
When to use
Use to keep the smallest bigint through APIs that consume a Combiner.
See
CombinerMaxfor keeping the largestbigintminfor comparing twobigintvalues directly
Signature
declare const CombinerMin: Combiner.Combiner<bigint>;Returns the result of subtracting 1n from a bigint.
When to use
Use to decrement a bigint counter by one.
Signature
declare function decrement(n: bigint): bigint;Divides one bigint by another safely.
When to use
Use to divide bigint values while representing division by zero as Option.none.
Details
Uses JavaScript bigint division, so non-exact quotients are truncated toward zero. Returns Option.none() when the divisor is 0n.
See
divideUnsafefor division that throws when the divisor is0nremainderfor the JavaScript remainder operation
Signature
declare const divide: {
(that: bigint): (self: bigint) => Option<bigint>;
(self: bigint, that: bigint): Option<bigint>;
};divideUnsafe
Divides one bigint by another, throwing if the divisor is zero.
When to use
Use to divide bigint values where the divisor is known to be non-zero and division by zero should be a thrown exception.
Details
Uses JavaScript bigint division, so non-exact quotients are truncated toward zero.
Gotchas
Throws a RangeError when the divisor is 0n.
See
dividefor division that returnsOption.nonewhen the divisor is0n
Signature
declare const divideUnsafe: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Determines the greatest common divisor of two bigints.
When to use
Use to compute the greatest common divisor of two integer values.
See
lcmfor computing the least common multiple
Signature
declare const gcd: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Returns the result of adding 1n to a bigint.
When to use
Use to increment a bigint counter by one.
Signature
declare function increment(n: bigint): bigint;Determines the least common multiple of two bigints.
When to use
Use to compute the least common multiple of two integer values.
See
gcdfor computing the greatest common divisor
Signature
declare const lcm: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Returns the maximum between two bigints.
When to use
Use to select the larger of two bigint values.
See
minfor selecting the smaller value
Signature
declare const max: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Returns the minimum between two bigints.
When to use
Use to select the smaller of two bigint values.
See
maxfor selecting the larger value
Signature
declare const min: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Provides a multiplication operation on bigints.
When to use
Use to multiply two bigint values.
See
multiplyAllfor multiplying an iterable ofbigintvalues
Signature
declare const multiply: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};multiplyAll
Takes an Iterable of bigints and returns their product as a single bigint. Returns 1n for an empty iterable.
When to use
Use to multiply all bigint values in an iterable.
See
multiplyfor multiplying twobigintvaluesReducerMultiplyfor multiplying through APIs that consume aReducer
Signature
declare function multiplyAll(collection: Iterable<bigint>): bigint;ReducerMultiply
Reducer for combining bigints using multiplication.
When to use
Use to multiply many bigint values through APIs that consume a Reducer.
Details
The initial value is 1n, so combineAll([]) returns 1n.
See
multiplyAllfor multiplying an iterable directlyReducerSumfor summingbigintvalues
Signature
declare const ReducerMultiply: Reducer.Reducer<bigint>;ReducerSum
Reducer for combining bigints using addition.
When to use
Use to sum many bigint values through APIs that consume a Reducer.
Details
The initial value is 0n, so combineAll([]) returns 0n.
See
sumAllfor summing an iterable directlyReducerMultiplyfor multiplyingbigintvalues
Signature
declare const ReducerSum: Reducer.Reducer<bigint>;Returns the JavaScript remainder of dividing one bigint by another.
When to use
Use when you want native remainder semantics, including signed remainders and a thrown division-by-zero error.
Gotchas
Throws a RangeError when the divisor is 0n.
See
dividefor quotient calculation with division-by-zero represented asOption.none
Signature
declare const remainder: {
(divisor: bigint): (self: bigint) => bigint;
(self: bigint, divisor: bigint): bigint;
};Determines the sign of a given bigint.
When to use
Use to classify a bigint as negative, zero, or positive.
Signature
declare function sign(n: bigint): Ordering;Computes the integer square root of a bigint safely.
When to use
Use to compute an integer square root while representing negative input as Option.none.
Details
For non-perfect squares, returns the largest bigint whose square is less than or equal to the input. Returns Option.none() when the input is negative.
See
sqrtUnsafefor square root computation that throws on negative input
Signature
declare function sqrt(n: bigint): Option<bigint>;sqrtUnsafe
Returns the integer square root of a non-negative bigint.
When to use
Use when you need to compute an integer square root for a bigint that has already been validated as non-negative, and you want negative input to throw instead of returning Option.none.
Details
For non-perfect squares, returns the largest bigint whose square is less than or equal to the input.
Gotchas
Throws a RangeError if the input is negative.
See
sqrtfor returningOption.nonewhen the input is negative
Signature
declare function sqrtUnsafe(n: bigint): bigint;Provides a subtraction operation on bigints.
When to use
Use to subtract one bigint value from another.
Signature
declare const subtract: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Provides an addition operation on bigints.
When to use
Use when you need a binary addition function for piping or higher-order APIs instead of the infix addition operator.
See
sumAllfor summing an iterable ofbigintvalues
Signature
declare const sum: {
(that: bigint): (self: bigint) => bigint;
(self: bigint, that: bigint): bigint;
};Takes an Iterable of bigints and returns their sum as a single bigint. Returns 0n for an empty iterable.
When to use
Use when you want an immediate aggregate from an iterable instead of a folding reducer owned by another API.
See
sumfor adding twobigintvaluesReducerSumfor summing through APIs that consume aReducer
Signature
declare function sumAll(collection: Iterable<bigint>): bigint;Predicates
Checks whether a bigint is between a minimum and maximum value (inclusive).
When to use
Use to test whether a bigint falls inside an inclusive range.
See
clampfor forcing abigintinto an inclusive range
Signature
declare const between: {
(options: { maximum: bigint; minimum: bigint }): (self: bigint) => boolean;
(
self: bigint,
options: {
maximum: bigint;
minimum: bigint;
},
): boolean;
};isGreaterThan
Returns true if the first argument is greater than the second, otherwise false.
When to use
Use to test whether one bigint is strictly greater than another.
Signature
declare const isGreaterThan: {
(that: bigint): (self: bigint) => boolean;
(self: bigint, that: bigint): boolean;
};isGreaterThanOrEqualTo
Returns a function that checks if a given bigint is greater than or equal to the provided one.
When to use
Use to test whether one bigint is greater than or equal to another.
Signature
declare const isGreaterThanOrEqualTo: {
(that: bigint): (self: bigint) => boolean;
(self: bigint, that: bigint): boolean;
};isLessThan
Returns true if the first argument is less than the second, otherwise false.
When to use
Use to test whether one bigint is strictly less than another.
Signature
declare const isLessThan: {
(that: bigint): (self: bigint) => boolean;
(self: bigint, that: bigint): boolean;
};isLessThanOrEqualTo
Returns a function that checks if a given bigint is less than or equal to the provided one.
When to use
Use to test whether one bigint is less than or equal to another.
Signature
declare const isLessThanOrEqualTo: {
(that: bigint): (self: bigint) => boolean;
(self: bigint, that: bigint): boolean;
};
Exposes the global bigint constructor for JavaScript bigint coercion.
When to use
Use to access native JavaScript bigint constructor coercion from the Effect module namespace.
Gotchas
This follows native
BigIntcoercion rules. It throws for invalid strings or non-integral numbers, and whitespace-only strings coerce to0n.See
fromStringfor parsing strings into anOptionfromNumberfor converting safe integers into anOptionExample (Constructing bigints) ``ts import.meta.vitest import { BigInt } from "effect" BigInt.BigInt(123) // => 123n BigInt.BigInt("456") // => 456n``