or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arithmetic.mdcomparison-utility.mdconfiguration.mdformatting.mdindex.mdmath-functions.mdtrig-functions.md
tile.json

tessl/npm-decimal.js

An arbitrary-precision Decimal type for JavaScript providing accurate mathematical calculations without floating-point precision errors.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/decimal.js@10.6.x

To install, run

npx @tessl/cli install tessl/npm-decimal.js@10.6.0

index.mddocs/

Decimal.js

Decimal.js is an arbitrary-precision decimal arithmetic library for JavaScript that enables accurate mathematical calculations without floating-point precision errors. It provides a comprehensive API that replicates and extends JavaScript's Number.prototype and Math object methods with precise decimal calculations.

Package Information

  • Package Name: decimal.js
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install decimal.js

Core Imports

import Decimal from "decimal.js";

For named imports:

import { Decimal } from "decimal.js";

CommonJS:

const Decimal = require("decimal.js");

Basic Usage

import Decimal from "decimal.js";

// Create Decimal instances from various types
const a = new Decimal(123.4567);
const b = new Decimal('0.1');
const c = new Decimal(0.2);

// Accurate decimal arithmetic (no floating-point errors)
const sum = b.plus(c);           // '0.3' (not 0.30000000000000004)
const product = a.times('2.5');  // '308.64175'
const quotient = a.div(3);       // '41.1522333333333333333'

// Method chaining
const result = new Decimal(100)
  .times(1.1)
  .plus(50)
  .sqrt()
  .toFixed(2);                   // '12.25'

// High precision calculations
Decimal.set({ precision: 50 });
const pi = new Decimal('3.1415926535897932384626433832795028841971693993751');
const area = pi.times(5).pow(2); // Circle area with radius 5

Architecture

Decimal.js is built around several key components:

  • Decimal Constructor: Main class for creating arbitrary-precision decimal numbers
  • Instance Methods: Over 65 methods for arithmetic, mathematical, and utility operations
  • Static Methods: Over 45 utility functions accessible directly from the Decimal class
  • Configuration System: Global and per-constructor configuration options for precision, rounding, and behavior
  • Type System: Full TypeScript support with comprehensive type definitions
  • Immutability: All operations return new Decimal instances, preserving original values

Capabilities

Core Arithmetic Operations

Essential arithmetic operations with arbitrary precision including addition, subtraction, multiplication, division, and modulo operations.

class Decimal {
  constructor(value: Decimal.Value);
  
  plus(n: Decimal.Value): Decimal;
  minus(n: Decimal.Value): Decimal;
  times(n: Decimal.Value): Decimal;
  dividedBy(n: Decimal.Value): Decimal;
  modulo(n: Decimal.Value): Decimal;
  negated(): Decimal;
  absoluteValue(): Decimal;
}

type Decimal.Value = string | number | bigint | Decimal;

Core Arithmetic Operations

Mathematical Functions

Advanced mathematical functions including roots, exponentials, logarithms, and power operations with configurable precision.

squareRoot(): Decimal;
cubeRoot(): Decimal;
naturalExponential(): Decimal;
naturalLogarithm(): Decimal;
logarithm(base?: Decimal.Value): Decimal;
toPower(n: Decimal.Value): Decimal;

static sqrt(n: Decimal.Value): Decimal;
static cbrt(n: Decimal.Value): Decimal;
static exp(n: Decimal.Value): Decimal;
static ln(n: Decimal.Value): Decimal;
static log(n: Decimal.Value, base?: Decimal.Value): Decimal;
static pow(base: Decimal.Value, exponent: Decimal.Value): Decimal;

Mathematical Functions

Trigonometric and Hyperbolic Functions

Complete trigonometric and hyperbolic function suite including sine, cosine, tangent and their inverse functions.

sine(): Decimal;
cosine(): Decimal;
tangent(): Decimal;
inverseSine(): Decimal;
inverseCosine(): Decimal;
inverseTangent(): Decimal;
hyperbolicSine(): Decimal;
hyperbolicCosine(): Decimal;
hyperbolicTangent(): Decimal;

static sin(n: Decimal.Value): Decimal;
static cos(n: Decimal.Value): Decimal;
static tan(n: Decimal.Value): Decimal;
static asin(n: Decimal.Value): Decimal;
static acos(n: Decimal.Value): Decimal;
static atan(n: Decimal.Value): Decimal;
static atan2(y: Decimal.Value, x: Decimal.Value): Decimal;

Trigonometric and Hyperbolic Functions

Comparison and Utility Methods

Comparison operations, type checking methods, and utility functions for working with Decimal instances.

comparedTo(n: Decimal.Value): number;
equals(n: Decimal.Value): boolean;
greaterThan(n: Decimal.Value): boolean;
lessThan(n: Decimal.Value): boolean;
isInteger(): boolean;
isNaN(): boolean;
isFinite(): boolean;
isPositive(): boolean;
isNegative(): boolean;
isZero(): boolean;

static max(...n: Decimal.Value[]): Decimal;
static min(...n: Decimal.Value[]): Decimal;
static isDecimal(obj: any): boolean;

Comparison and Utility Methods

Formatting and Conversion

Comprehensive formatting and conversion methods for different number representations and output formats.

toString(): string;
toFixed(decimalPlaces?: number, rounding?: Decimal.Rounding): string;
toExponential(decimalPlaces?: number, rounding?: Decimal.Rounding): string;
toPrecision(significantDigits?: number, rounding?: Decimal.Rounding): string;
toBinary(significantDigits?: number, rounding?: Decimal.Rounding): string;
toHexadecimal(significantDigits?: number, rounding?: Decimal.Rounding): string;
toOctal(significantDigits?: number, rounding?: Decimal.Rounding): string;
toFraction(maxDenominator?: Decimal.Value): Decimal[];
toNumber(): number;

Formatting and Conversion

Configuration and Constructor Methods

Configuration management, constructor cloning, and precision control for advanced usage scenarios.

interface Decimal.Config {
  precision?: number;
  rounding?: Decimal.Rounding;
  toExpNeg?: number;
  toExpPos?: number;
  minE?: number;
  maxE?: number;
  crypto?: boolean;
  modulo?: Decimal.Modulo;
}

static config(options: Decimal.Config): Decimal.Constructor;
static clone(options?: Decimal.Config): Decimal.Constructor;
static set(options: Decimal.Config): Decimal.Constructor;
static random(significantDigits?: number): Decimal;

Configuration and Constructor Methods

Constants and Types

// Rounding mode constants
static readonly ROUND_UP: 0;
static readonly ROUND_DOWN: 1;
static readonly ROUND_CEIL: 2;
static readonly ROUND_FLOOR: 3;
static readonly ROUND_HALF_UP: 4;
static readonly ROUND_HALF_DOWN: 5;
static readonly ROUND_HALF_EVEN: 6;
static readonly ROUND_HALF_CEIL: 7;
static readonly ROUND_HALF_FLOOR: 8;
static readonly EUCLID: 9;

// Static readonly properties (optional, browser compatibility)
static readonly default?: Decimal.Constructor;
static readonly Decimal?: Decimal.Constructor;

// Current configuration properties (read-only access)
static readonly precision: number;
static readonly rounding: Decimal.Rounding;
static readonly toExpNeg: number;
static readonly toExpPos: number;
static readonly minE: number;
static readonly maxE: number;
static readonly crypto: boolean;
static readonly modulo: Decimal.Modulo;

// Internal instance properties (read-only, for advanced usage)
readonly d: number[];  // Internal digits array
readonly e: number;    // Exponent
readonly s: number;    // Sign (-1, 0, or 1)

// Type definitions
type Decimal.Rounding = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
type Decimal.Modulo = Decimal.Rounding | 9;
type Decimal.Value = string | number | bigint | Decimal;
type Decimal.Constructor = typeof Decimal;

Error Handling

Decimal.js throws errors for:

  • Invalid configuration values outside specified ranges
  • Invalid input values that cannot be converted to Decimal numbers
  • Mathematical operations that result in undefined values (e.g., division by zero in certain contexts)
  • Out-of-range exponent values that exceed configured limits