#@teakit/arith

@teakit/arith is a TypeScript arbitrary-precision decimal arithmetic package for ESM and browser environments.

Use it when JavaScript's binary floating-point behavior is not precise enough for decimal values such as money, rates, quantities, ratios, or formatted numeric output.

#What This Package Provides

• Arith as the public constructor and main API surface.
• Arbitrary-precision decimal arithmetic with method-based operations.
• Value construction from strings, numbers, bigints, Arith instances, and validated Arith instance-like objects.
• Configurable precision, rounding, modulo, exponent, formatting, and random generation behavior.
• Browser-safe ESM output with no Node runtime imports.
• Method-level documentation that is small enough to read one operation at a time.

Arith is intentionally the public name. This package does not expose BigNumber or Decimal compatibility aliases.

#Installation

Install @teakit/arith with your package manager after your project has access to @teakit packages.

npm install @teakit/arith

yarn add @teakit/arith

pnpm add @teakit/arith

bun add @teakit/arith

deno add npm:@teakit/arith

#Quick Example

import { Arith } from "@teakit/arith";

const subtotal = new Arith("19.99").times(3);
const tax = subtotal.times("0.0825");
const total = subtotal.plus(tax);

total.toFixed(2); // "64.72"

Prefer string inputs for values that must stay exact. Always construct values with new Arith(...); static helpers such as Arith.config() and Arith.clone() are valid.

#Basic Usage

#Import

import { Arith } from "@teakit/arith";

The default export is also Arith, but the named import is preferred because it is clearer in generated code and examples.

#Create Values

const a = new Arith("0.1");
const b = new Arith("0.2");

Use string inputs for exact decimal values. Do not call Arith("0.1") without new.

#Calculate

const total = new Arith("0.1").plus("0.2");

total.toString(); // "0.3"

Use methods such as plus, minus, times, dividedBy, modulo, pow, and sqrt instead of JavaScript arithmetic operators.

#Compare

const balance = new Arith("10.00");

balance.gt("0"); // true
balance.eq("10"); // true

Use comparison methods such as eq, lt, lte, gt, gte, or comparedTo. Do not compare Arith values with ===, <, or >.

#Format Output

const amount = new Arith("1234.5");

amount.toFixed(2); // "1234.50"
amount.toFormat(2); // "1,234.50"

Use toFixed for fixed decimal output, toFormat for display output, and toString for compact exact output.

#When To Use It

Use @teakit/arith for:

• money-like calculations that need predictable decimal output;
• rates, percentages, quantities, and measurements with many decimal places;
• comparisons where 0.1 + 0.2 style floating-point surprises are not acceptable;
• browser and server code that should share the same decimal behavior;
• formatting workflows where calculation and display rules must be explicit.

For approximate math, graphics, physics, or performance-sensitive numeric loops, plain JavaScript numbers may still be the better tool.

#Core Concepts

#Construction

Create values with new Arith(value).

new Arith("0.1").plus("0.2").toString(); // "0.3"

Use strings for exact decimal values. Numbers are accepted, but they first carry JavaScript's normal number semantics.

#Immutable Operations

Arithmetic methods return new Arith values.

const price = new Arith("12.50");
const discounted = price.minus("2.00");

price.toString(); // "12.5"
discounted.toString(); // "10.5"

Do not mutate internal fields such as c, e, s, or _isArith.

#Configuration

Use Arith.config() for global configuration, and prefer Arith.clone() when a module needs local rules.

const Money = Arith.clone({ DECIMAL_PLACES: 2 });

new Money("1").div("3").toFixed(); // "0.33"

#Output

Choose the output method based on intent:

• toString() for a compact exact string;
• toFixed(dp) for fixed decimal places;
• toFormat(...) for human display with separators;
• toNumber() only when precision loss is acceptable.

#Start Here

#Common Method Paths