CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-decimal-js

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/decimal.js@10.6.x
Publish Source
CLI
Badge
tessl/npm-decimal-js badge