Skip to main content Link Search Menu Expand Document (external link)
effect-libs

BigDecimal overview

Extension to the Effect BigDecimal module providing safe constructors from primitives and truncation utilities.

Mental model

  • BigDecimal is an arbitrary-precision decimal: a bigint value paired with a scale (the number of decimal digits).
  • This module focuses on safely building BigDecimal’s from JavaScript primitives and on truncating their fractional part.

Common tasks

  • Construct: {@link fromPrimitiveOption}
  • Instances: {@link zero}
  • Truncate: {@link trunc}, {@link truncatedAndFollowingParts}

Quickstart

Example (Construction and truncation)

import { Option, pipe } from "effect"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"

const bd = pipe("3.14", MBigDecimal.fromPrimitiveOption(2), Option.getOrThrow)
console.log(pipe(bd, MBigDecimal.trunc(1))) // BigDecimal(31, 1) i.e. 3.1

Table of contents

Constructors

fromPrimitiveOption

Builds a BigDecimal from a string, number or boolean paired with scale. Returns Option.none when the primitive cannot be converted to a bigint.

  • Use to build a BigDecimal from untrusted input without risking an exception.
  • scale is the number of decimal digits attached to the resulting value.

Example (Safe construction)

import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"

console.log(MBigDecimal.fromPrimitiveOption(2)("3.14")) // Some(BigDecimal(314, 2))
console.log(MBigDecimal.fromPrimitiveOption(2)("abc")) // None

Signature

export declare const fromPrimitiveOption: (
  scale: number
) => MTypes.OneArgFunction<string | number | boolean, Option.Option<BigDecimal.BigDecimal>>

Destructors

truncatedAndFollowingParts

Splits self into [truncatedPart, followingPart] where truncatedPart is self truncated after precision decimal digits and followingPart is self - truncatedPart.

  • Use when both the truncated value and its remainder are needed (e.g. when building digit-by-digit formatters).
  • precision must be a non-negative finite integer; defaults to 0.

Example (Separating truncated and remainder parts)

import { Option, pipe } from "effect"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"

const bd = pipe("3.14159", MBigDecimal.fromPrimitiveOption(5), Option.getOrThrow)
const [truncated, following] = pipe(bd, MBigDecimal.truncatedAndFollowingParts(2))
// truncated ≡ 3.14, following ≡ 0.00159

Signature

export declare const truncatedAndFollowingParts: (
  precision?: number
) => (self: Type) => [truncatedPart: BigDecimal.BigDecimal, followingPart: BigDecimal.BigDecimal]

Instances

zero

BigDecimal instance representing 0.

Signature

export declare const zero: BigDecimal.BigDecimal

Models

Type (type alias)

Type on which this module’s functions operate.

Signature

export type Type = BigDecimal.BigDecimal

Utils

trunc

Truncates a BigDecimal after precision decimal digits.

  • Use to drop fractional digits beyond a given precision.
  • Rounds towards zero.
  • precision must be a non-negative finite integer; defaults to 0.

Example (Truncate to a given precision)

import { Option, pipe } from "effect"
import * as MBigDecimal from "@parischap/effect-lib/MBigDecimal"

const bd = pipe("3.14159", MBigDecimal.fromPrimitiveOption(5), Option.getOrThrow)
console.log(pipe(bd, MBigDecimal.trunc(2))) // BigDecimal(314, 2) i.e. 3.14

Signature

export declare const trunc: (precision?: number) => MTypes.OneArgFunction<Type>