Number

Exposes the global number constructor.

When to use

Use to access native JavaScript numeric coercion from the Effect module namespace.

Gotchas

This follows native Number coercion rules, including empty strings becoming 0 and invalid numeric strings becoming NaN.

See

• parse for parsing strings into an Option

declare const Number: NumberConstructor

Parses a number from a string safely using the Number() function. The following special string values are supported: "NaN", "Infinity", "-Infinity".

When to use

Use to parse numeric text without throwing on invalid input.

See

• Number for native constructor coercion

declare function parse(s: string): Option<number>

import { Number, Option } from "effect"

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

Checks whether a value is a number.

When to use

Use to validate unknown input and narrow it to number.

declare const isNumber: (input: unknown) => input is number

import { Number } from "effect"

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

Equivalence instance for numbers where NaN is considered equal to NaN.

When to use

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

declare const Equivalence: Equ.Equivalence<number>

import { Number } from "effect"

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

Order instance for number values.

When to use

Use when you need to sort or compare numbers through APIs that accept an ordering instance.

declare const Order: order.Order<number>

import { Number } from "effect"

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

Restricts the given number to be within the range specified by the minimum and maximum values.

When to use

Use to force a number into an inclusive range.

Details

• If the number is less than the minimum value, the function returns the minimum value.
• If the number is greater than the maximum value, the function returns the maximum value.
• Otherwise, it returns the original number.

See

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

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

import { Number } from "effect"

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

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

Decrements a number by 1.

When to use

Use to decrement a numeric counter by one.

declare function decrement(n: number): number

import { Number } from "effect"

Number.decrement(3) // => 2

Divides numbers safely, returning Option.none() if the divisor is 0.

When to use

Use to divide numbers while representing division by zero as Option.none.

See

• divideUnsafe for division that throws when the divisor is zero
• remainder for the numeric remainder operation

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

import { Number, Option } from "effect"

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

Divides two number values without returning an Option.

When to use

Use to divide number values where the divisor is known to be non-zero and a plain number result is preferred over handling Option.none.

Gotchas

Throws a RangeError if the divisor is 0.

See

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

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

import { Number, Result } from "effect"

Number.divideUnsafe(6, 3) // => 2

const failure = Result.try({
  try: () => Number.divideUnsafe(6, 0),
  catch: (error) => (error as Error).message
})
Result.merge(failure) // => "Division by zero"

Returns the result of adding 1 to a given number.

When to use

Use to increment a numeric counter by one.

declare function increment(n: number): number

import { Number } from "effect"

Number.increment(2) // => 3

Returns the maximum between two numbers.

When to use

Use to select the larger of two numbers.

See

• min for selecting the smaller value

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

import { Number } from "effect"

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

Returns the minimum between two numbers.

When to use

Use to select the smaller of two numbers.

See

• max for selecting the larger value

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

import { Number } from "effect"

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

Provides a multiplication operation on numbers.

When to use

Use to multiply two numbers.

See

• multiplyAll for multiplying an iterable of numbers

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

import { Number } from "effect"

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

Takes an Iterable of numbers and returns their multiplication as a single number.

When to use

Use to multiply all numbers in an iterable.

See

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

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

import { Number } from "effect"

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

Returns the next power of 2 from the given number.

When to use

Use to round a number up to the next power of two.

declare function nextPow2(n: number): number

import { Number } from "effect"

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

Reducer for reducing numbers by keeping the maximum value.

When to use

Use to keep the largest number through APIs that consume a Reducer.

Details

The reducer starts from -Infinity, so reducing an empty collection returns -Infinity.

Gotchas

NaN values propagate through Math.max.

See

• ReducerMin for keeping the smallest number
• max for comparing two numbers directly

declare const ReducerMax: Reducer.Reducer<number>

Reducer for reducing numbers by keeping the minimum value.

When to use

Use to keep the smallest number through APIs that consume a Reducer.

Details

The reducer starts from Infinity, so reducing an empty collection returns Infinity.

Gotchas

NaN values propagate through Math.min.

See

• ReducerMax for keeping the largest number
• min for comparing two numbers directly

declare const ReducerMin: Reducer.Reducer<number>

Reducer for combining numbers using multiplication.

When to use

Use to multiply many numbers through APIs that consume a Reducer.

Details

The reducer starts from 1, so reducing an empty collection returns 1.

Gotchas

Reducing an iterable short-circuits when it sees 0, so later elements are not consumed.

See

• multiplyAll for multiplying an iterable directly

declare const ReducerMultiply: Reducer.Reducer<number>

Reducer for combining numbers using addition.

When to use

Use to sum many numbers through APIs that consume a Reducer.

Details

The reducer starts from 0, so combineAll([]) returns 0.

See

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

declare const ReducerSum: Reducer.Reducer<number>

Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.

When to use

Use to compute a numeric remainder while preserving decimal precision better than direct JavaScript % for decimal operands.

See

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

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

import { Number } from "effect"

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

Returns the number rounded with the given precision.

When to use

Use to round a number to a fixed number of decimal places.

declare const round: {
  (precision: number): (self: number) => number;
  (self: number, precision: number): number;
}

import { Number } from "effect"

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

Determines the sign of a given number.

When to use

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

declare function sign(n: number): Ordering

import { Number } from "effect"

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

Provides a subtraction operation on numbers.

When to use

Use to subtract one number from another.

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

import { Number } from "effect"

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

Provides an addition operation on numbers.

When to use

Use to add two numbers.

See

• sumAll for summing an iterable of numbers

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

import { Number } from "effect"

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

Takes an Iterable of numbers and returns their sum as a single number.

When to use

Use to sum all numbers in an iterable.

See

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

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

import { Number } from "effect"

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

Checks whether a number is between a minimum and maximum value (inclusive).

When to use

Use to test whether a number falls inside an inclusive range.

See

• clamp for forcing a number into an inclusive range

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

import { Number } from "effect"

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

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

Returns true if the first argument is greater than the second, otherwise false.

When to use

Use to test whether one number is strictly greater than another.

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

import { Number } from "effect"

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

Returns a function that checks if a given number is greater than or equal to the provided one.

When to use

Use to test whether one number is greater than or equal to another.

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

import { Number } from "effect"

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

Returns true if the first argument is less than the second, otherwise false.

When to use

Use to test whether one number is strictly less than another.

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

import { Number } from "effect"

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

Returns a function that checks if a given number is less than or equal to the provided one.

When to use

Use to test whether one number is less than or equal to another.

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

import { Number } from "effect"

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