BigInt

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 BigInt coercion rules. It throws for invalid strings or non-integral numbers, and whitespace-only strings coerce to 0n.

See

• fromString for parsing strings into an Option
• fromNumber for converting safe integers into an Option

declare const BigInt: BigIntConstructor

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

• toNumber for converting bigint values back to safe integer numbers
• BigInt for native constructor coercion

declare function fromNumber(n: number): Option<bigint>

import { BigInt, Option } from "effect"

BigInt.fromNumber(42) // => Option.some(42n)
BigInt.fromNumber(Number.MAX_SAFE_INTEGER + 1) // => Option.none()
BigInt.fromNumber(Number.MIN_SAFE_INTEGER - 1) // => Option.none()

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

• BigInt for native constructor coercion that throws on invalid input

declare function fromString(s: string): Option<bigint>

import { BigInt, Option } from "effect"

BigInt.fromString("42") // => Option.some(42n)
BigInt.fromString(" ") // => Option.none()
BigInt.fromString("a") // => Option.none()

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

• fromNumber for converting a safe integer number to bigint

declare function toNumber(b: bigint): Option<number>

import { BigInt as BI, Option } from "effect"

BI.toNumber(42n) // => Option.some(42)
BI.toNumber(9007199254740992n) // => Option.none()
BI.toNumber(-9007199254740992n) // => Option.none()

Checks whether a value is a bigint.

When to use

Use to validate unknown input and narrow it to bigint.

declare const isBigInt: (u: unknown) => u is bigint

import { BigInt } from "effect"

BigInt.isBigInt(1n) // => true
BigInt.isBigInt(1) // => false

Equivalence instance for bigints using strict equality (===).

When to use

Use when checking bigint equality through APIs that accept an equivalence relation.

declare const Equivalence: Equ.Equivalence<bigint>

import { BigInt } from "effect"

BigInt.Equivalence(1n, 1n) // => true
BigInt.Equivalence(1n, 2n) // => false

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.

declare const Order: order.Order<bigint>

import { BigInt } from "effect"

const a = 123n
const b = 456n
const c = 123n

BigInt.Order(a, b) // => -1
BigInt.Order(b, a) // => 1
BigInt.Order(a, c) // => 0

Determines the absolute value of a given bigint.

When to use

Use to remove the sign from a bigint while preserving its magnitude.

declare function abs(n: bigint): bigint

import { BigInt } from "effect"

BigInt.abs(-5n) // => 5n
BigInt.abs(0n) // => 0n
BigInt.abs(5n) // => 5n

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

• between for checking whether a bigint is already inside a range

declare const clamp: {
  (options: {
    maximum: bigint;
    minimum: bigint;
  }): (self: bigint) => bigint;
  (self: bigint, options: {
    maximum: bigint;
    minimum: bigint;
  }): bigint;
}

import { BigInt } from "effect"

const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })

clamp(3n) // => 3n
clamp(0n) // => 1n
clamp(6n) // => 5n

Combiner that returns the maximum bigint.

When to use

Use to keep the largest bigint when an API consumes a Combiner.

See

• CombinerMin for keeping the smallest bigint
• max for comparing two bigint values directly

declare const CombinerMax: Combiner.Combiner<bigint>

Combiner that returns the minimum bigint.

When to use

Use to keep the smallest bigint through APIs that consume a Combiner.

See

• CombinerMax for keeping the largest bigint
• min for comparing two bigint values directly

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.

declare function decrement(n: bigint): bigint

import { BigInt } from "effect"

BigInt.decrement(3n) // => 2n

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

• divideUnsafe for division that throws when the divisor is 0n
• remainder for the JavaScript remainder operation

declare const divide: {
  (that: bigint): (self: bigint) => Option<bigint>;
  (self: bigint, that: bigint): Option<bigint>;
}

import { BigInt, Option } from "effect"

BigInt.divide(6n, 3n) // => Option.some(2n)
BigInt.divide(6n, 0n) // => Option.none()

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

• divide for division that returns Option.none when the divisor is 0n

declare const divideUnsafe: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.divideUnsafe(6n, 3n) // => 2n
BigInt.divideUnsafe(6n, 4n) // => 1n

Determines the greatest common divisor of two bigints.

When to use

Use to compute the greatest common divisor of two integer values.

See

• lcm for computing the least common multiple

declare const gcd: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.gcd(2n, 3n) // => 1n
BigInt.gcd(2n, 4n) // => 2n
BigInt.gcd(16n, 24n) // => 8n

Returns the result of adding 1n to a bigint.

When to use

Use to increment a bigint counter by one.

declare function increment(n: bigint): bigint

import { BigInt } from "effect"

BigInt.increment(2n) // => 3n

Determines the least common multiple of two bigints.

When to use

Use to compute the least common multiple of two integer values.

See

• gcd for computing the greatest common divisor

declare const lcm: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.lcm(2n, 3n) // => 6n
BigInt.lcm(2n, 4n) // => 4n
BigInt.lcm(16n, 24n) // => 48n

Returns the maximum between two bigints.

When to use

Use to select the larger of two bigint values.

See

• min for selecting the smaller value

declare const max: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.max(2n, 3n) // => 3n

Returns the minimum between two bigints.

When to use

Use to select the smaller of two bigint values.

See

• max for selecting the larger value

declare const min: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.min(2n, 3n) // => 2n

Provides a multiplication operation on bigints.

When to use

Use to multiply two bigint values.

See

• multiplyAll for multiplying an iterable of bigint values

declare const multiply: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.multiply(2n, 3n) // => 6n

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

• multiply for multiplying two bigint values
• ReducerMultiply for multiplying through APIs that consume a Reducer

declare function multiplyAll(collection: Iterable<bigint>): bigint

import { BigInt } from "effect"

BigInt.multiplyAll([2n, 3n, 4n]) // => 24n

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

• multiplyAll for multiplying an iterable directly
• ReducerSum for summing bigint values

declare const ReducerMultiply: Reducer.Reducer<bigint>

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

• sumAll for summing an iterable directly
• ReducerMultiply for multiplying bigint values

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

• divide for quotient calculation with division-by-zero represented as Option.none

declare const remainder: {
  (divisor: bigint): (self: bigint) => bigint;
  (self: bigint, divisor: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.remainder(10n, 3n) // => 1n
BigInt.remainder(15n, 4n) // => 3n

Determines the sign of a given bigint.

When to use

Use to classify a bigint as negative, zero, or positive.

declare function sign(n: bigint): Ordering

import { BigInt } from "effect"

BigInt.sign(-5n) // => -1
BigInt.sign(0n) // => 0
BigInt.sign(5n) // => 1

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

• sqrtUnsafe for square root computation that throws on negative input

declare function sqrt(n: bigint): Option<bigint>

import { BigInt, Option } from "effect"

BigInt.sqrt(4n) // => Option.some(2n)
BigInt.sqrt(9n) // => Option.some(3n)
BigInt.sqrt(16n) // => Option.some(4n)
BigInt.sqrt(-1n) // => Option.none()

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

• sqrt for returning Option.none when the input is negative

declare function sqrtUnsafe(n: bigint): bigint

import { BigInt } from "effect"

BigInt.sqrtUnsafe(4n) // => 2n
BigInt.sqrtUnsafe(9n) // => 3n
BigInt.sqrtUnsafe(16n) // => 4n

Provides a subtraction operation on bigints.

When to use

Use to subtract one bigint value from another.

declare const subtract: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.subtract(2n, 3n) // => -1n

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

• sumAll for summing an iterable of bigint values

declare const sum: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

import { BigInt } from "effect"

BigInt.sum(2n, 3n) // => 5n

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

• sum for adding two bigint values
• ReducerSum for summing through APIs that consume a Reducer

declare function sumAll(collection: Iterable<bigint>): bigint

import { BigInt } from "effect"

BigInt.sumAll([2n, 3n, 4n]) // => 9n

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

• clamp for forcing a bigint into an inclusive range

declare const between: {
  (options: {
    maximum: bigint;
    minimum: bigint;
  }): (self: bigint) => boolean;
  (self: bigint, options: {
    maximum: bigint;
    minimum: bigint;
  }): boolean;
}

import { BigInt } from "effect"

const between = BigInt.between({ minimum: 0n, maximum: 5n })

between(3n) // => true
between(-1n) // => false
between(6n) // => false

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.

declare const isGreaterThan: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

import { BigInt } from "effect"

BigInt.isGreaterThan(2n, 3n) // => false
BigInt.isGreaterThan(3n, 3n) // => false
BigInt.isGreaterThan(4n, 3n) // => true

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.

declare const isGreaterThanOrEqualTo: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

import { BigInt } from "effect"

BigInt.isGreaterThanOrEqualTo(2n, 3n) // => false
BigInt.isGreaterThanOrEqualTo(3n, 3n) // => true
BigInt.isGreaterThanOrEqualTo(4n, 3n) // => true

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.

declare const isLessThan: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

import { BigInt } from "effect"

BigInt.isLessThan(2n, 3n) // => true
BigInt.isLessThan(3n, 3n) // => false
BigInt.isLessThan(4n, 3n) // => false

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.

declare const isLessThanOrEqualTo: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

import { BigInt } from "effect"

BigInt.isLessThanOrEqualTo(2n, 3n) // => true
BigInt.isLessThanOrEqualTo(3n, 3n) // => true
BigInt.isLessThanOrEqualTo(4n, 3n) // => false