BigInt

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

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()

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()

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()

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

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

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

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

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

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>

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>

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

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()

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

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

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

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

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

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

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

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

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>

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>

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

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

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()

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

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

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

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

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

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

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

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

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