# Number & BigInt

The `Number` and `BigInt` modules add named, pipeable operations around plain
JavaScript numeric values. Numbers stay native numbers (including `NaN`,
`Infinity`, and floating-point behavior) and bigints stay native bigints — the
modules do not introduce wrapper types. What they add is a consistent surface
for arithmetic, comparisons, range checks, parsing, conversion, and aggregation.

```ts
import { Number, pipe } from "effect"

// Pipeable arithmetic
const result = pipe(
  10,
  Number.sum(5), // 15
  Number.multiply(2), // 30
  Number.subtract(6) // 24
)
console.log(result) // => 24
```

## The safety story

The central design choice in both modules: operations that could produce `NaN`,
`Infinity`, throw, or silently lose precision instead return an
[`Option`](https://effect.plants.sh/data-types/option/). Each has an `*Unsafe` counterpart for when you
already know the input is valid (and want the raw value or a thrown error).

```ts
import { Number, BigInt } from "effect"

// Safe — never produces NaN/Infinity, surfaces failure as Option.none()
Number.divide(6, 0) // => Option.none()
Number.parse("not a number") // => Option.none()
BigInt.fromString("a") // => Option.none()
BigInt.fromNumber(1.5) // => Option.none() (not an integer)
BigInt.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + 1n) // => Option.none() (precision loss)
BigInt.sqrt(-1n) // => Option.none()

// Unsafe — assumes valid input, throws on failure
Number.divideUnsafe(6, 3) // => 2
BigInt.divideUnsafe(6n, 3n) // => 2n
BigInt.sqrtUnsafe(16n) // => 4n
```

This pairing means you choose your error model explicitly: thread an `Option`
through the happy path, or assert validity with the `*Unsafe` variant.

## Dual signatures

Almost every binary operation in both modules is **dual**: you can call it
data-first (`Number.sum(2, 3)`) or data-last for use in a `pipe`
(`Number.sum(3)` returns a function awaiting the value). See
[Dual APIs](https://effect.plants.sh/code-style/dual-apis/) for the full convention.

```ts
import { Number, pipe } from "effect"

Number.sum(2, 3) // => 5 (data-first)
pipe(2, Number.sum(3)) // => 5 (data-last)
```

---

# Number

```ts
import { Number } from "effect"
```

:::caution
`Number` here is also the namespace name, which shadows the global `Number`
constructor. The module re-exports the global as `Number.Number`. To avoid
confusion, many examples alias the `.
:::

## Guards & instances

### Number

The native JavaScript `Number` constructor, re-exported on the namespace.
Follows native coercion rules — empty strings become `0`, invalid strings
become `NaN`. For safe parsing prefer [`parse`](#parse).

```ts
import { Number as N } from "effect"

N.Number("42") // => 42
N.Number("3.14") // => 3.14
N.Number("") // => 0
```

### isNumber

Type guard that narrows an `unknown` value to `number`.

```ts
import { Number } from "effect"

Number.isNumber(2) // => true
Number.isNumber("2") // => false
```

### Order

[`Order`](https://effect.plants.sh/traits/order/) instance for numbers, returning `-1 | 0 | 1`. Use it
with sorting and comparison APIs that accept an ordering.

```ts
import { Number } from "effect"

Number.Order(1, 2) // => -1
Number.Order(2, 1) // => 1
Number.Order(1, 1) // => 0
```

### Equivalence

[`Equivalence`](https://effect.plants.sh/traits/equivalence/) instance for numbers. Unlike `===`, it
treats `NaN` as equivalent to `NaN`.

```ts
import { Number } from "effect"

Number.Equivalence(1, 1) // => true
Number.Equivalence(1, 2) // => false
Number.Equivalence(NaN, NaN) // => true
```

## Arithmetic

### sum

Adds two numbers (dual).

```ts
import { Number } from "effect"

Number.sum(2, 3) // => 5
```

### multiply

Multiplies two numbers (dual).

```ts
import { Number } from "effect"

Number.multiply(2, 3) // => 6
```

### subtract

Subtracts the second number from the first (dual).

```ts
import { Number } from "effect"

Number.subtract(2, 3) // => -1
```

### divide

Safe division returning `Option.none()` only when the divisor is `0` (dual).
Other JavaScript results, including `NaN`, still follow normal number semantics.

```ts
import { Number } from "effect"

Number.divide(6, 3) // => Option.some(2)
Number.divide(6, 0) // => Option.none()
```

### divideUnsafe

Division that throws a `RangeError("Division by zero")` when the divisor is `0`
(dual). Use when the divisor is known to be non-zero.

```ts
import { Number } from "effect"

Number.divideUnsafe(6, 3) // => 2
// Number.divideUnsafe(6, 0) throws RangeError("Division by zero")
```

### increment

Adds `1` to a number.

```ts
import { Number } from "effect"

Number.increment(2) // => 3
```

### decrement

Subtracts `1` from a number.

```ts
import { Number } from "effect"

Number.decrement(3) // => 2
```

### remainder

Returns the remainder of dividing the first operand by the second, taking the
sign of the dividend (dual). Preserves decimal precision better than the raw
JavaScript `%` operator for decimal operands.

```ts
import { Number } from "effect"

Number.remainder(2, 2) // => 0
Number.remainder(3, 2) // => 1
Number.remainder(-4, 2) // => -0
```

### sign

Classifies a number as negative (`-1`), zero (`0`), or positive (`1`).

```ts
import { Number } from "effect"

Number.sign(-5) // => -1
Number.sign(0) // => 0
Number.sign(5) // => 1
```

### round

Rounds a number to the given number of decimal places (dual).

```ts
import { Number } from "effect"

Number.round(1.1234, 2) // => 1.12
Number.round(1.567, 2) // => 1.57
```

### nextPow2

Rounds a number up to the next power of two (minimum `2`).

```ts
import { Number } from "effect"

Number.nextPow2(5) // => 8
Number.nextPow2(17) // => 32
```

## Comparison & range

### isLessThan

`true` if the first argument is strictly less than the second (dual).

```ts
import { Number } from "effect"

Number.isLessThan(2, 3) // => true
Number.isLessThan(3, 3) // => false
```

### isLessThanOrEqualTo

`true` if the first argument is less than or equal to the second (dual).

```ts
import { Number } from "effect"

Number.isLessThanOrEqualTo(3, 3) // => true
Number.isLessThanOrEqualTo(4, 3) // => false
```

### isGreaterThan

`true` if the first argument is strictly greater than the second (dual).

```ts
import { Number } from "effect"

Number.isGreaterThan(4, 3) // => true
Number.isGreaterThan(3, 3) // => false
```

### isGreaterThanOrEqualTo

`true` if the first argument is greater than or equal to the second (dual).

```ts
import { Number } from "effect"

Number.isGreaterThanOrEqualTo(3, 3) // => true
Number.isGreaterThanOrEqualTo(2, 3) // => false
```

### between

Checks whether a number falls inside an inclusive `[minimum, maximum]` range
(dual).

```ts
import { Number } from "effect"

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

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

### clamp

Forces a number into an inclusive `[minimum, maximum]` range, returning the
boundary when out of range (dual).

```ts
import { Number } from "effect"

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

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

### min

Returns the smaller of two numbers (dual).

```ts
import { Number } from "effect"

Number.min(2, 3) // => 2
```

### max

Returns the larger of two numbers (dual).

```ts
import { Number } from "effect"

Number.max(2, 3) // => 3
```

## Parsing

### parse

Parses a number from a string without throwing, returning `Option<number>`. The
strings `"NaN"`, `"Infinity"`, and `"-Infinity"` are supported; blank or invalid
text yields `Option.none()`.

```ts
import { Number } from "effect"

Number.parse("42") // => Option.some(42)
Number.parse("3.14") // => Option.some(3.14)
Number.parse("Infinity") // => Option.some(Infinity)
Number.parse("not a number") // => Option.none()
Number.parse("") // => Option.none()
```

## Aggregation

### sumAll

Sums an iterable of numbers. Returns `0` for an empty iterable.

```ts
import { Number } from "effect"

Number.sumAll([2, 3, 4]) // => 9
```

### multiplyAll

Multiplies an iterable of numbers. Returns `1` for an empty iterable, and
short-circuits to `0` as soon as it sees a `0`.

```ts
import { Number } from "effect"

Number.multiplyAll([2, 3, 4]) // => 24
```

### Reducers

A `Reducer` packages a binary `combine` operation together with an identity
value (and an optional optimized `combineAll`). It is the abstraction Effect
collection APIs consume when they need to fold values. You can use one directly
via `reducer.combineAll(iterable)`, which folds starting from the identity — so
an empty collection returns the identity rather than failing.

```ts
import { Number } from "effect"

// combineAll folds an iterable from the reducer's identity
Number.ReducerSum.combineAll([1, 2, 3]) // => 6
Number.ReducerSum.combineAll([]) // => 0 (identity)

// combine merges two values directly
Number.ReducerSum.combine(4, 5) // => 9
```

#### ReducerSum

Combines numbers with addition; identity `0`.

```ts
import { Number } from "effect"

Number.ReducerSum.combineAll([10, 20, 30]) // => 60
Number.ReducerSum.combineAll([]) // => 0
```

#### ReducerMultiply

Combines numbers with multiplication; identity `1`. Short-circuits to `0` when
it encounters a `0`.

```ts
import { Number } from "effect"

Number.ReducerMultiply.combineAll([2, 3, 4]) // => 24
Number.ReducerMultiply.combineAll([]) // => 1
```

#### ReducerMax

Keeps the maximum value; identity `-Infinity` (so an empty collection returns
`-Infinity`). `NaN` propagates through `Math.max`.

```ts
import { Number } from "effect"

Number.ReducerMax.combineAll([3, 1, 4, 1, 5]) // => 5
Number.ReducerMax.combineAll([]) // => -Infinity
```

#### ReducerMin

Keeps the minimum value; identity `Infinity` (so an empty collection returns
`Infinity`). `NaN` propagates through `Math.min`.

```ts
import { Number } from "effect"

Number.ReducerMin.combineAll([3, 1, 4, 1, 5]) // => 1
Number.ReducerMin.combineAll([]) // => Infinity
```

---

# BigInt

```ts
import { BigInt } from "effect"
```

Reach for `BigInt` when values may exceed JavaScript's safe integer range, when
conversions should make failure explicit with `Option`, or when collection APIs
need bigint-specific ordering or combining. Use the `n` literal suffix for
bigint values (`10n`).

:::caution
JavaScript does not allow mixing `number` and `bigint` in arithmetic. Cross the
boundary explicitly with [`fromNumber`](#fromnumber) and [`toNumber`](#tonumber).
Also note that bigint division truncates toward zero.
:::

## Guards & instances

### BigInt

The native `BigInt` constructor, re-exported on the namespace. Follows native
coercion — it throws for invalid strings or non-integral numbers, and
whitespace-only strings coerce to `0n`. For safe conversion prefer
[`fromString`](#fromstring) / [`fromNumber`](#fromnumber).

```ts
import { BigInt } from "effect"

BigInt.BigInt(123) // => 123n
BigInt.BigInt("456") // => 456n
```

### isBigInt

Type guard that narrows an `unknown` value to `bigint`.

```ts
import { BigInt } from "effect"

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

### Order

[`Order`](https://effect.plants.sh/traits/order/) instance for bigints.

```ts
import { BigInt } from "effect"

BigInt.Order(123n, 456n) // => -1
BigInt.Order(456n, 123n) // => 1
BigInt.Order(123n, 123n) // => 0
```

### Equivalence

[`Equivalence`](https://effect.plants.sh/traits/equivalence/) instance for bigints, using strict
equality.

```ts
import { BigInt } from "effect"

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

## Arithmetic

### sum

Adds two bigints (dual).

```ts
import { BigInt } from "effect"

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

### multiply

Multiplies two bigints (dual).

```ts
import { BigInt } from "effect"

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

### subtract

Subtracts the second bigint from the first (dual).

```ts
import { BigInt } from "effect"

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

### divide

Safe division returning `Option.none()` when the divisor is `0n` (dual).
Non-exact quotients truncate toward zero.

```ts
import { BigInt } from "effect"

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

### divideUnsafe

Division that throws when the divisor is `0n` (dual). Truncates toward zero.

```ts
import { BigInt } from "effect"

BigInt.divideUnsafe(6n, 3n) // => 2n
BigInt.divideUnsafe(6n, 4n) // => 1n (truncated toward zero)
```

### increment

Adds `1n` to a bigint.

```ts
import { BigInt } from "effect"

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

### decrement

Subtracts `1n` from a bigint.

```ts
import { BigInt } from "effect"

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

### remainder

Returns the JavaScript `%` remainder (sign of the dividend), throwing when the
divisor is `0n` (dual).

```ts
import { BigInt } from "effect"

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

### sign

Classifies a bigint as negative (`-1`), zero (`0`), or positive (`1`).

```ts
import { BigInt } from "effect"

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

### abs

Returns the absolute value (magnitude with sign removed).

```ts
import { BigInt } from "effect"

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

### gcd

Greatest common divisor of two bigints (dual).

```ts
import { BigInt } from "effect"

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

### lcm

Least common multiple of two bigints (dual).

```ts
import { BigInt } from "effect"

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

### sqrt

Safe integer square root returning `Option<bigint>`; `Option.none()` for
negative input. For non-perfect squares, returns the largest bigint whose square
is `<=` the input.

```ts
import { BigInt } from "effect"

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

### sqrtUnsafe

Integer square root that throws a `RangeError` on negative input. Use when the
input is known to be non-negative.

```ts
import { BigInt } from "effect"

BigInt.sqrtUnsafe(4n) // => 2n
BigInt.sqrtUnsafe(9n) // => 3n
// BigInt.sqrtUnsafe(-1n) throws RangeError
```

## Comparison & range

### isLessThan

`true` if the first argument is strictly less than the second (dual).

```ts
import { BigInt } from "effect"

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

### isLessThanOrEqualTo

`true` if the first argument is less than or equal to the second (dual).

```ts
import { BigInt } from "effect"

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

### isGreaterThan

`true` if the first argument is strictly greater than the second (dual).

```ts
import { BigInt } from "effect"

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

### isGreaterThanOrEqualTo

`true` if the first argument is greater than or equal to the second (dual).

```ts
import { BigInt } from "effect"

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

### between

Checks whether a bigint falls inside an inclusive `[minimum, maximum]` range
(dual).

```ts
import { BigInt } from "effect"

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

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

### clamp

Forces a bigint into an inclusive `[minimum, maximum]` range (dual).

```ts
import { BigInt } from "effect"

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

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

### min

Returns the smaller of two bigints (dual).

```ts
import { BigInt } from "effect"

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

### max

Returns the larger of two bigints (dual).

```ts
import { BigInt } from "effect"

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

## Conversion

### toNumber

Converts a bigint to a `number` safely, returning `Option.none()` when the value
falls outside the safe integer range (guarding against precision loss).

```ts
import { BigInt as BI } from "effect"

BI.toNumber(42n) // => Option.some(42)
BI.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + 1n) // => Option.none()
```

### fromString

Parses a string into a bigint safely, returning `Option.none()` for empty or
invalid input (rather than throwing like the native constructor).

```ts
import { BigInt } from "effect"

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

### fromNumber

Converts a number to a bigint safely, returning `Option.none()` for
non-integers or values outside the safe integer range.

```ts
import { BigInt } from "effect"

BigInt.fromNumber(42) // => Option.some(42n)
BigInt.fromNumber(1.5) // => Option.none() (not an integer)
BigInt.fromNumber(Number.MAX_SAFE_INTEGER + 1) // => Option.none()
```

## Aggregation

### sumAll

Sums an iterable of bigints. Returns `0n` for an empty iterable.

```ts
import { BigInt } from "effect"

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

### multiplyAll

Multiplies an iterable of bigints. Returns `1n` for an empty iterable, and
short-circuits to `0n` as soon as it sees a `0n`.

```ts
import { BigInt } from "effect"

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

### Reducers

Like the `Number` reducers, these `Reducer` instances carry an identity value
and expose `combineAll` for folding an iterable (empty iterable returns the
identity).

#### ReducerSum

Combines bigints with addition; identity `0n`.

```ts
import { BigInt } from "effect"

BigInt.ReducerSum.combineAll([10n, 20n, 30n]) // => 60n
BigInt.ReducerSum.combineAll([]) // => 0n
```

#### ReducerMultiply

Combines bigints with multiplication; identity `1n`. Short-circuits to `0n` when
it encounters a `0n`.

```ts
import { BigInt } from "effect"

BigInt.ReducerMultiply.combineAll([2n, 3n, 4n]) // => 24n
BigInt.ReducerMultiply.combineAll([]) // => 1n
```

### Combiners

A `Combiner` is the identity-free cousin of a `Reducer`: it carries only a
binary `combine` operation, so there is no identity value and no `combineAll`.
Use one to merge two values where no neutral element exists (here, max/min).

#### CombinerMax

Returns the larger of two bigints.

```ts
import { BigInt } from "effect"

BigInt.CombinerMax.combine(2n, 5n) // => 5n
```

#### CombinerMin

Returns the smaller of two bigints.

```ts
import { BigInt } from "effect"

BigInt.CombinerMin.combine(2n, 5n) // => 2n
```