Number

# Number

This module provides utility functions and type class instances for working with the number type in TypeScript. It includes functions for basic arithmetic operations, as well as type class instances for Equivalence and Order.

## Operations Reference

| Category | Operation | Description | Domain | Co-domain | | ------------ | ------------------------------------------ | ------------------------------------------------------- | ------------------------------ | --------------------- | | constructors | module:Number.parse | Safely parses a string to a number | string | Option<number> | | | | | | | | math | module:Number.sum | Adds two numbers | number, number | number | | math | module:Number.sumAll | Sums all numbers in a collection | Iterable<number> | number | | math | module:Number.subtract | Subtracts one number from another | number, number | number | | math | module:Number.multiply | Multiplies two numbers | number, number | number | | math | module:Number.multiplyAll | Multiplies all numbers in a collection | Iterable<number> | number | | math | module:Number.divide | Safely divides handling division by zero | number, number | Option<number> | | math | module:Number.unsafeDivide | Divides but misbehaves for division by zero | number, number | number | | math | module:Number.remainder | Calculates remainder of division | number, number | number | | math | module:Number.increment | Adds 1 to a number | number | number | | math | module:Number.decrement | Subtracts 1 from a number | number | number | | math | module:Number.sign | Determines the sign of a number | number | Ordering | | math | module:Number.nextPow2 | Finds the next power of 2 | number | number | | math | module:Number.round | Rounds a number with specified precision | number, number | number | | | | | | | | predicates | module:Number.between | Checks if a number is in a range | number, {minimum, maximum} | boolean | | predicates | module:Number.lessThan | Checks if one number is less than another | number, number | boolean | | predicates | module:Number.lessThanOrEqualTo | Checks if one number is less than or equal | number, number | boolean | | predicates | module:Number.greaterThan | Checks if one number is greater than another | number, number | boolean | | predicates | module:Number.greaterThanOrEqualTo | Checks if one number is greater or equal | number, number | boolean | | | | | | | | guards | module:Number.isNumber | Type guard for JavaScript numbers | unknown | boolean | | | | | | | | comparison | module:Number.min | Returns the minimum of two numbers | number, number | number | | comparison | module:Number.max | Returns the maximum of two numbers | number, number | number | | comparison | module:Number.clamp | Restricts a number to a range | number, {minimum, maximum} | number | | | | | | | | instances | module:Number.Equivalence | Equivalence instance for numbers | | Equivalence<number> | | instances | module:Number.Order | Order instance for numbers | | Order<number> | | | | | | | | errors | module:Number.DivisionByZeroError | Error thrown by unsafeDivide | | |

## Composition Patterns and Type Safety

When building function pipelines, understanding how types flow through operations is critical:

### Composing with type-preserving operations

Most operations in this module are type-preserving (number → number), making them easily composable in pipelines:

### Working with Option results

Operations that might fail (like division by zero) return Option types and require Option combinators:

### Composition best practices

- Chain type-preserving operations for maximum composability - Use Option combinators when working with potentially failing operations - Consider using Effect for operations that might fail with specific errors - Remember that all operations maintain JavaScript's floating-point precision limitations

See

module:BigInt for more similar operations on bigint types
module:BigDecimal for more similar operations on BigDecimal types

26 exports Added in v2.0.0 Source

Constructors

parse

Added in v2.0.0 Source

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

Signature

declare const parse: (s: string) => Option<number>;

Guards

isNumber

Added in v2.0.0 Source

Type guard that tests if a value is a member of the set of JavaScript numbers.

Signature

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

Example

import * as assert from "node:assert/strict"
import * as Number from "effect/Number"

// Regular numbers
assert.equal(Number.isNumber(2), true)
assert.equal(Number.isNumber(-3.14), true)
assert.equal(Number.isNumber(0), true)

// Special numeric values
assert.equal(Number.isNumber(Infinity), true)
assert.equal(Number.isNumber(NaN), true)

// Non-number values
assert.equal(Number.isNumber("2"), false)
assert.equal(Number.isNumber(true), false)
assert.equal(Number.isNumber(null), false)
assert.equal(Number.isNumber(undefined), false)
assert.equal(Number.isNumber({}), false)
assert.equal(Number.isNumber([]), false)

// Using as a type guard in conditionals
function processValue(value: unknown): string {
  if (Number.isNumber(value)) {
    // TypeScript now knows 'value' is a number
    return `Numeric value: ${value.toFixed(2)}`
  }
  return "Not a number"
}

assert.strictEqual(processValue(42), "Numeric value: 42.00")
assert.strictEqual(processValue("hello"), "Not a number")

// Filtering for numbers in an array
const mixed = [1, "two", 3, false, 5]
const onlyNumbers = mixed.filter(Number.isNumber)
assert.equal(onlyNumbers, [1, 3, 5])

Instances

Equivalence

Added in v2.0.0 Source

Signature

declare const Equivalence: equivalence.Equivalence<number>;

Order

Added in v2.0.0 Source

Signature

declare const Order: order.Order<number>;

Math

decrement

Added in v2.0.0 Source

Decrements a number by 1.

Signature

declare function decrement(n: number): number;

divide

Added in v2.0.0 Source

Performs division in the set of JavaScript numbers, returning the result wrapped in an Option to handle division by zero.

Signature

declare const divide: {
  (divisor: number): (dividend: number) => Option<number>;
  (dividend: number, divisor: number): Option<number>;
};

Example

import * as assert from "node:assert/strict"
import { pipe, Option } from "effect"
import * as Number from "effect/Number"

// Data-first style (direct application)
assert.equal(Number.divide(6, 3), Option.some(2)) // 6 ÷ 3 = 2
assert.equal(Number.divide(-8, 4), Option.some(-2)) // (-8) ÷ 4 = -2
assert.equal(Number.divide(-10, -5), Option.some(2)) // (-10) ÷ (-5) = 2
assert.equal(Number.divide(1, 3), Option.some(0.3333333333333333)) // Note: floating-point approximation

// Handling division by zero
assert.equal(Number.divide(6, 0), Option.none()) // 6 ÷ 0 is undefined

// Data-last style (pipeable)
assert.equal(
  pipe(
    10,
    Number.divide(2), // 10 ÷ 2 = 5
  ),
  Option.some(5),
)

// Chaining multiple divisions using Option combinators
assert.equal(
  pipe(
    Option.some(24),
    Option.flatMap((n) => Number.divide(n, 2)), // 24 ÷ 2 = 12
    Option.flatMap(Number.divide(3)), // 12 ÷ 3 = 4
    Option.flatMap(Number.divide(2)), // 4 ÷ 2 = 2
  ),
  Option.some(2),
)

// Division-by-one property: a ÷ 1 = a
assert.equal(Number.divide(42, 1), Option.some(42))

// Self-division property: a ÷ a = 1 (for a ≠ 0)
assert.equal(Number.divide(42, 42), Option.some(1))

// Non-commutative property: a ÷ b ≠ b ÷ a
assert.notDeepStrictEqual(
  Number.divide(6, 3), // 6 ÷ 3 = 2
  Number.divide(3, 6), // 3 ÷ 6 = 0.5
)

increment

Added in v2.0.0 Source

Returns the result of adding 1 to a given number.

Signature

declare function increment(n: number): number;

multiply

Added in v2.0.0 Source

Performs multiplication in the set of JavaScript numbers.

Signature

declare const multiply: {
  (multiplicand: number): (multiplier: number) => number;
  (multiplier: number, multiplicand: number): number;
};

Example

import * as assert from "node:assert/strict"
import { pipe } from "effect"
import * as Number from "effect/Number"

// Data-first style (direct application)
assert.equal(Number.multiply(2, 3), 6) // 2 × 3 = 6
assert.equal(Number.multiply(-4, 5), -20) // (-4) × 5 = -20
assert.equal(Number.multiply(-3, -2), 6) // (-3) × (-2) = 6
assert.equal(Number.multiply(0.1, 0.2), 0.020000000000000004) // Note: floating-point precision limitation

// Data-last style (pipeable)
assert.equal(
  pipe(
    10,
    Number.multiply(5), // 10 × 5 = 50
  ),
  50,
)

// Chaining multiple multiplications
assert.equal(
  pipe(
    2,
    Number.multiply(3), // 2 × 3 = 6
    Number.multiply(4), // 6 × 4 = 24
    Number.multiply(0.5), // 24 × 0.5 = 12
  ),
  12,
)

// Identity property: a × 1 = a
assert.equal(Number.multiply(42, 1), 42)

// Zero property: a × 0 = 0
assert.equal(Number.multiply(42, 0), 0)

// Commutative property: a × b = b × a
assert.equal(Number.multiply(5, 3), Number.multiply(3, 5))

// Associative property: (a × b) × c = a × (b × c)
const a = 2,
  b = 3,
  c = 4
assert.equal(Number.multiply(Number.multiply(a, b), c), Number.multiply(a, Number.multiply(b, c)))

multiplyAll

Added in v2.0.0 Source

Computes the product of all elements in an iterable collection of numbers.

Signature

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

nextPow2

Added in v2.0.0 Source

Returns the next power of 2 greater than or equal to the given number.

- For positive inputs, returns the smallest power of 2 that is >= the input - For zero, returns 2 - For negative inputs, returns NaN (as logarithms of negative numbers are undefined) - For NaN input, returns NaN - For Infinity, returns Infinity

Signature

declare function nextPow2(n: number): number;

remainder

Added in v2.0.0 Source

Returns the remainder left over when one operand is divided by a second operand.

It always takes the sign of the dividend.

Signature

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

Example

import * as assert from "node:assert/strict"
import { remainder } from "effect/Number"

assert.equal(remainder(2, 2), 0)
assert.equal(remainder(3, 2), 1)
assert.equal(remainder(-4, 2), -0)

round

Added in v3.8.0 Source

Returns the number rounded with the given precision.

Signature

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

Example

import * as assert from "node:assert/strict"
import { round } from "effect/Number"

assert.equal(round(1.1234, 2), 1.12)
assert.equal(round(1.567, 2), 1.57)

sign

Added in v2.0.0 Source

Determines the sign of a given number.

Signature

declare function sign(n: number): Ordering;

subtract

Added in v2.0.0 Source

Performs subtraction in the set of JavaScript numbers.

Signature

declare const subtract: {
  (subtrahend: number): (minuend: number) => number;
  (minuend: number, subtrahend: number): number;
};

Example

import * as assert from "node:assert/strict"
import { pipe } from "effect"
import * as Number from "effect/Number"

// Data-first style (direct application)
assert.equal(Number.subtract(2, 3), -1) // 2 - 3 = -1
assert.equal(Number.subtract(10, 5), 5) // 10 - 5 = 5
assert.equal(Number.subtract(0.3, 0.1), 0.19999999999999998) // Note: floating-point precision limitation

// Data-last style (pipeable)
assert.equal(
  pipe(
    10,
    Number.subtract(5), // 10 - 5 = 5
  ),
  5,
)

// Chaining multiple subtractions
assert.equal(
  pipe(
    20,
    Number.subtract(5), // 20 - 5 = 15
    Number.subtract(3), // 15 - 3 = 12
    Number.subtract(2), // 12 - 2 = 10
  ),
  10,
)

// Right identity property: a - 0 = a
assert.equal(Number.subtract(42, 0), 42)

// Self-annihilation property: a - a = 0
assert.equal(Number.subtract(42, 42), 0)

// Non-commutative property: a - b ≠ b - a
assert.equal(Number.subtract(5, 3), 2) // 5 - 3 = 2
assert.equal(Number.subtract(3, 5), -2) // 3 - 5 = -2

// Inverse relation: a - b = -(b - a)
assert.equal(Number.subtract(5, 3), -Number.subtract(3, 5))

sum

Added in v2.0.0 Source

Performs addition in the set of JavaScript numbers.

Signature

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

Example

import * as assert from "node:assert/strict"
import { pipe } from "effect"
import * as Number from "effect/Number"

// Data-first style (direct application)
assert.equal(Number.sum(2, 3), 5)
assert.equal(Number.sum(-10, 5), -5)
assert.equal(Number.sum(0.1, 0.2), 0.30000000000000004) // Note: floating-point precision limitation

// Data-last style (pipeable)
assert.equal(
  pipe(
    10,
    Number.sum(5), // 10 + 5 = 15
  ),
  15,
)

// Chaining multiple additions
assert.equal(
  pipe(
    1,
    Number.sum(2), // 1 + 2 = 3
    Number.sum(3), // 3 + 3 = 6
    Number.sum(4), // 6 + 4 = 10
  ),
  10,
)

// Identity property: a + 0 = a
assert.equal(Number.sum(42, 0), 42)

// Commutative property: a + b = b + a
assert.equal(Number.sum(5, 3), Number.sum(3, 5))

sumAll

Added in v2.0.0 Source

Computes the sum of all elements in an iterable collection of numbers.

Signature

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

unsafeDivide

Added in v2.0.0 Source

Performs division in the set of JavaScript numbers, but misbehaves for division by zero.

Unlike module:Number.divide which returns an Option, this function directly returns a number or Infinity or NaN.

- If the divisor is zero, it returns Infinity. - If both the dividend and the divisor are zero, then it returns NaN.

See

module:Number.divide - Safe division returning an Option

Signature

declare const unsafeDivide: {
  (divisor: number): (dividend: number) => number;
  (dividend: number, divisor: number): number;
};

Example

import * as assert from "node:assert/strict"
import { pipe } from "effect"
import * as Number from "effect/Number"

// Data-first style (direct application)
assert.equal(Number.unsafeDivide(6, 3), 2) // 6 ÷ 3 = 2
assert.equal(Number.unsafeDivide(-8, 4), -2) // (-8) ÷ 4 = -2
assert.equal(Number.unsafeDivide(-10, -5), 2) // (-10) ÷ (-5) = 2
assert.equal(Number.unsafeDivide(1, 3), 0.3333333333333333)

// Data-last style (pipeable)
assert.equal(
  pipe(
    10,
    Number.unsafeDivide(2), // 10 ÷ 2 = 5
  ),
  5,
)

// Chaining multiple divisions
assert.equal(
  pipe(
    24,
    Number.unsafeDivide(2), // 24 ÷ 2 = 12
    Number.unsafeDivide(3), // 12 ÷ 3 = 4
    Number.unsafeDivide(2), // 4 ÷ 2 = 2
  ),
  2,
)

assert.equal(Number.unsafeDivide(6, 0), Infinity)

assert.equal(Number.unsafeDivide(0, 0), NaN)

// Compare with safe division
const safeResult = Number.divide(6, 3) // Option.some(2)
const unsafeResult = Number.unsafeDivide(6, 3) // 2 directly

Other

clamp

Added in v2.0.0 Source

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

- 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.

Signature

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

Example

import * as assert from "node:assert/strict"
import { Number } from "effect"

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

assert.equal(clamp(3), 3)
assert.equal(clamp(0), 1)
assert.equal(clamp(6), 5)

max

Added in v2.0.0 Source

Returns the maximum between two numbers.

Signature

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

Example

import * as assert from "node:assert/strict"
import { max } from "effect/Number"

assert.equal(max(2, 3), 3)

min

Added in v2.0.0 Source

Returns the minimum between two numbers.

Signature

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

Example

import * as assert from "node:assert/strict"
import { min } from "effect/Number"

assert.equal(min(2, 3), 2)

negate

Added in v3.14.6 Source

Returns the additive inverse of a number, effectively negating it.

Signature

declare function negate(n: number): number;

Predicates

between

Added in v2.0.0 Source

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

Signature

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

Example

import * as assert from "node:assert/strict"
import { Number } from "effect"

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

assert.equal(between(3), true)
assert.equal(between(-1), false)
assert.equal(between(6), false)

greaterThan

Added in v2.0.0 Source

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

Signature

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

Example

import * as assert from "node:assert/strict"
import { greaterThan } from "effect/Number"

assert.equal(greaterThan(2, 3), false)
assert.equal(greaterThan(3, 3), false)
assert.equal(greaterThan(4, 3), true)

greaterThanOrEqualTo

Added in v2.0.0 Source

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

Signature

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

Example

import * as assert from "node:assert/strict"
import { greaterThanOrEqualTo } from "effect/Number"

assert.equal(greaterThanOrEqualTo(2, 3), false)
assert.equal(greaterThanOrEqualTo(3, 3), true)
assert.equal(greaterThanOrEqualTo(4, 3), true)

lessThan

Added in v2.0.0 Source

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

Signature

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

Example

import * as assert from "node:assert/strict"
import { lessThan } from "effect/Number"

assert.equal(lessThan(2, 3), true)
assert.equal(lessThan(3, 3), false)
assert.equal(lessThan(4, 3), false)

lessThanOrEqualTo

Added in v2.0.0 Source

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

Signature

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

Example

import * as assert from "node:assert/strict"
import { lessThanOrEqualTo } from "effect/Number"

assert.equal(lessThanOrEqualTo(2, 3), true)
assert.equal(lessThanOrEqualTo(3, 3), true)
assert.equal(lessThanOrEqualTo(4, 3), false)