FixedPrecision

FixedPrecision is a library for handling fixed‑precision decimal numbers in JavaScript/TypeScript. By storing scaled bigint values internally, this library enables precise arithmetic, detailed control over decimal places, and various rounding modes — ideal for avoiding floating‑point imprecision.

Features

• Configurable precision — 0 to 20 decimal places.
• 9 rounding modes — ROUND_UP, ROUND_DOWN, ROUND_CEIL, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_CEIL, ROUND_HALF_FLOOR.
• Full arithmetic — addition, subtraction, multiplication, division, modulo, exponentiation, square root, cube root, negation, integer division.
• Method chaining — arithmetic and comparison directly with number, string, or bigint without explicit instantiation.
• Flexible conversions — toString, toNumber, toFixed, toExponential, toPrecision, toFormat, toJSON, toBinary, toOctal, toHex.
• Rounding & scaling — round, prec, ceil, floor, trunc, scale, shiftedBy, clamp, toNearest.
• Comparisons — cmp, eq, gt, gte, lt, lte (plus raw variants).
• Predicates — isZero, isPositive, isNegative, isInteger; logical operations (sign, not, and, or, xor).
• Logarithms — ln, log, log2, log10, exp.
• Trigonometry — sin, cos, tan, sec, csc, cot and their inverse, hyperbolic, and inverse‑hyperbolic counterparts (26 functions total, including atan2).
• Statistics — min, max, sum, hypot, random.
• Math constants — PI, e, phi, sqrt2.
• Combinatorics — factorial, permutations, combinations.
• Vector / matrix — dot, cross.
• Fractions — num, den, fraction.
• Bitwise operations — bitAnd, bitOr, bitXor, bitNot, leftShift, rightArithShift.
• TypeScript — full type definitions included (FixedPrecisionValue, FixedPrecisionConfig, RoundingMode, Comparison).

Installation

npm install fixed-precision

Quick Start

import FixedPrecision, { fixedconfig } from "fixed-precision";

fixedconfig.configure({ places: 8, roundingMode: 4 });

const a = new FixedPrecision("1.2345");
const b = new FixedPrecision(2.3456);

const sum = a.add(b);
console.log(sum.toString()); // "3.5801"

const product = a.mul(b);
console.log(product.toString()); // "2.8955832"

// Method chaining with raw values
const result = new FixedPrecision(10.5).add(5).div(3).toNumber();
console.log(result); // 5.16666667

// Mixed input types
new FixedPrecision(100).add("50").sub(25n).mul(2).div("5").toString(); // "50"

Global Configuration

Set default decimal places and rounding mode for all new FixedPrecision() instances that don't receive an explicit context.

import { fixedconfig } from "fixed-precision";
// or: FixedPrecision.configure({ ... })

fixedconfig.configure({
  places: 8,        // 0–20
  roundingMode: 4,  // ROUND_HALF_UP (default)
});

Rounding Modes

| Code | Name | Behavior | |------|------------------|--------------------------------------------| | 0 | ROUND_UP | Rounds away from zero | | 1 | ROUND_DOWN | Rounds toward zero (truncation) | | 2 | ROUND_CEIL | Rounds toward +Infinity | | 3 | ROUND_FLOOR | Rounds toward -Infinity | | 4 | ROUND_HALF_UP | Rounds half away from zero | | 5 | ROUND_HALF_DOWN | Rounds half toward zero | | 6 | ROUND_HALF_EVEN | Rounds half to the nearest even number | | 7 | ROUND_HALF_CEIL | Rounds half toward +Infinity | | 8 | ROUND_HALF_FLOOR | Rounds half toward -Infinity |

Precision Factories (Recommended)

For applications that need multiple precisions at the same time, use immutable factories instead of mutating the global configuration.

import FixedPrecision, { fixedconfig } from "fixed-precision";

// Independent, immutable contexts
const FP8 = FixedPrecision.create({ places: 8, roundingMode: 4 });
const FP2 = FixedPrecision.create({ places: 2 });

const a = FP8("1.23456789"); // "1.23456789"
const b = FP2("1.23");       // "1.23"

// Method chaining works with factories too
const c = FP8(10.5).add(5).div(3);

// Factories are unaffected by global config changes
fixedconfig.configure({ places: 4 });
FP8("1").toString(false);                // "1.00000000" (unchanged)
FP2("1").toString(false);                // "1.00"       (unchanged)
new FixedPrecision("1").toString(false); // "1.0000"  (global default)

Why factories?

• Performance — No per‑instance option parsing; the factory captures its scale and rounding mode once.
• Clarity — The precision is explicit in the factory variable name.
• Safety — No shared mutable state; cross‑context arithmetic throws an error.
• Flexibility — Create as many contexts as needed and pass them around.

Factory API

FixedPrecision.create(config: FixedPrecisionConfig): (val: FixedPrecisionValue) => FixedPrecision

• config.places — integer 0–20 (required).
• config.roundingMode — integer 0–8 (optional, defaults to 4 / ROUND_HALF_UP).
• The returned function creates instances locked to that configuration.
• factory.format exposes the frozen { places, roundingMode } object.

Documentation

For more detailed guides and examples, see the docs/ directory:

| Category | Topics | |----------|--------| | Getting Started | Quick Start, Installation, Basic Concepts | | Core Features | Arithmetic, Raw Operations, Rounding & Scaling, Conversion, Minimal Build | | Configuration | Global Configuration, Precision Factories | | Advanced | Performance, Error Handling, BigInt Warning | | API | Full API Reference, Type Definitions | | Integration | Migration Guide, Integration, Testing |

API Reference

Constructor

new FixedPrecision(value: FixedPrecisionValue, ctx?: FPContext)

Accepts string | number | bigint | FixedPrecision.

• string / number → parsed as a decimal value and scaled to the current context.
• bigint → treated as already scaled (pre‑scaled). See BigInt Warning.
• FixedPrecision → reused directly (validation ensures same precision context).

Arithmetic

All arithmetic methods accept FixedPrecisionValue (string | number | bigint | FixedPrecision).

Scaled operations (maintain decimal precision, validate configuration):

| Instance | Static | Description | |-------------|-----------------------------|--------------------------| | add(v) | FixedPrecision.add(a, b) | Addition | | sub(v) | FixedPrecision.sub(a, b) | Subtraction | | mul(v) | FixedPrecision.mul(a, b) | Multiplication | | div(v) | FixedPrecision.div(a, b) | Division | | mod(v) | FixedPrecision.mod(a, b) | Modulo | | pow(n) | FixedPrecision.pow(v, n) | Exponentiation (integer) | | sqrt() | FixedPrecision.sqrt(v) | Square root | | square() | FixedPrecision.square(v) | Square (value²) | | cube() | FixedPrecision.cube(v) | Cube (value³) | | cbrt() | FixedPrecision.cbrt(v) | Cube root | | neg() | — | Negation (-value) | | abs() | FixedPrecision.abs(v) | Absolute value | | idiv(v) | — | Integer division | | divmod(v) | — | Division → { quotient, remainder } | | idivmod(v) | — | Integer division → { quotient, remainder } |

Raw operations (operate directly on scaled values, no configuration validation):

| Instance | Description (raw) | |------------|----------------------------| | plus(v) | Addition without scaling | | minus(v) | Subtraction without scaling| | times(v) | Multiplication without scaling | | ratio(v) | Division without scaling | | rem(v) | Remainder without scaling |

Comparison

Regular comparisons (validate configuration):

| Instance | Static | Returns | |-----------|--------------------------------|---------------| | cmp(v) | — | -1 \| 0 \| 1| | eq(v) | — | boolean | | gt(v) | — | boolean | | gte(v) | — | boolean | | lt(v) | — | boolean | | lte(v) | — | boolean |

Raw comparisons (compare scaled values directly, no validation — main build only):

cmpRaw(v), eqRaw(v), gtRaw(v), gteRaw(v), ltRaw(v), lteRaw(v).

Rounding & Scaling

| Method | Description | |-------------------------------------|-----------------------------------------------------| | round(dp?, rm?) | Round to dp decimal places | | prec(sd, rm?) | Round to sd significant digits | | ceil() | Round up to integer | | floor() | Round down to integer | | trunc() | Truncate toward zero | | scale(newScale, rm?) | Rescale to newScale decimal places | | shiftedBy(n) | Shift decimal point by n places | | clamp(min, max) | Clamp value between min and max (main only) | | toNearest(increment, rm?) | Round to nearest multiple of increment (main only)|

Formatting & Conversion

| Method | Description | |---------------------------------------|--------------------------------------------------| | toString() | Decimal string representation | | toNumber(places?) | Convert to number | | toFixed(places?, rm?) | Fixed‑point notation string | | toExponential(dp?, rm?) | Scientific notation string | | toPrecision(sd, rm?) | Format to significant digits | | toFormat(dp?, rm?) | String with thousands separators (minimal build) | | toJSON() | JSON serialization (same as toString()) | | valueOf() | Returns toString() | | toBinary(sd?, rm?) | Binary string (main only) | | toOctal(sd?, rm?) | Octal string (main only) | | toHex(sd?, rm?) / toHexadecimal() | Hex string (main only) |

Predicates & Inspection

| Method | Description | |---------------------------|----------------------------------------------| | isZero() | true if value is exactly zero | | isPositive() | true if value > 0 | | isNegative() | true if value < 0 | | isInteger() | true if value has no fractional part | | sign() | Returns -1, 0, 1, or NaN (main only) | | not() | Logical NOT — true if zero (main only) | | and(v), or(v), xor(v) | Logical AND / OR / XOR (main only) | | places() / decimalPlaces() | Returns context decimal places (main only) | | precision(z?) / sd(z?) | Returns significant digits (main only) | | raw() | Returns the internal bigint (main only) | | typeof() | Returns "FixedPrecision" (main only) |

Logarithms (main build only)

| Instance | Static | Description | |-------------|------------------------------|---------------------------| | ln() | FixedPrecision.ln(v) | Natural logarithm | | log(b?) | FixedPrecision.log(v, b?) | Logarithm (base optional) | | log2() | FixedPrecision.log2(v) | Base‑2 logarithm | | log10() | FixedPrecision.log10(v) | Base‑10 logarithm | | exp() | FixedPrecision.exp(v) | e raised to the value |

Trigonometry (main build only)

Standard: sin(), cos(), tan()
Reciprocal: sec(), csc(), cot()
Inverse: asin(), acos(), atan(), atan2(x)
Inverse reciprocal: acot(), asec(), acsc()
Hyperbolic: sinh(), cosh(), tanh()
Reciprocal hyperbolic: sech(), csch(), coth()
Inverse hyperbolic: asinh(), acosh(), atanh()
Inverse reciprocal hyperbolic: asech(), acsch(), acoth()

All are available as both instance (value.sin()) and static (FixedPrecision.sin(value)) methods.

Statistics

| Static method | Description | |---------------------------------------------|-----------------------------------| | FixedPrecision.min(...vals) | Minimum value (array or rest) | | FixedPrecision.max(...vals) | Maximum value (array or rest) | | FixedPrecision.sum(...vals) | Sum of values (array or rest) | | FixedPrecision.hypot(...vals) | Hypotenuse — sqrt(sum of squares) | | FixedPrecision.random(decimalPlaces?) | Random value 0–1 at given places |

Constants (main build only)

| Static method | Value | |--------------------------|------------------------------------| | FixedPrecision.PI() | π (pi) | | FixedPrecision.e() | Euler's number | | FixedPrecision.phi() | Golden ratio (1+√5)/2 | | FixedPrecision.sqrt2() | √2 |

Combinatorics (main build only)

FixedPrecision.factorial(n), FixedPrecision.permutations(n, k), FixedPrecision.combinations(n, k).

Fraction (main build only)

| Instance | Description | |-----------------|-------------------------------------------------| | .num() | Numerator of the reduced fraction | | .den() | Denominator of the reduced fraction | | .fraction(maxDen?) | Best rational approximation [num, den] |

Bitwise Operations (main build only)

bitAnd(v), bitOr(v), bitXor(v), bitNot(), leftShift(n), rightArithShift(n) — operate directly on the raw scaled bigint.

Vector Operations (main build only)

FixedPrecision.dot(a, b) → scalar dot product.
FixedPrecision.cross(a, b) → returns an array (cross product).

Method Chaining with Raw Values

All arithmetic and comparison methods accept FixedPrecisionValue (string | number | bigint | FixedPrecision), enabling concise chaining without explicit instantiation:

new FixedPrecision(100).add("50").sub(25n).mul(2).div("5");       // "50"
new FixedPrecision(10.5).add(5).div(3).gt(5);                     // true
new FixedPrecision("1.23").plus("2.00").times("3.00");           // raw chain

Type behavior:

• string / number → decimal values, automatically scaled.
• bigint → treated as already scaled (pre‑scaled). See below.
• FixedPrecision → requires matching precision context (for scaled operations).

BigInt Warning

critical: bigint values are treated as pre‑scaled, not as decimal values.

new FixedPrecision("1.23");    // value = 123000000 (assuming 8 decimal places)
new FixedPrecision(1.23);      // value = 123000000
new FixedPrecision(123000000n); // value = 123000000 (pre‑scaled)
new FixedPrecision(123n);      // value = 123 (0.00000123 — NOT 123.00!)

When chaining:

const a = new FixedPrecision("1.23");

a.add(2);            // adds 2.00000000   (number → scaled)
a.add(2n);           // adds 0.00000002   (bigint → pre‑scaled!)
a.add("2.00");       // adds 2.00000000   (string → scaled)
a.add(200000000n);   // adds 2.00000000   (bigint → pre‑scaled correctly)

Use bigint only when you have pre‑calculated scaled values. For literal decimal values, use number or string.

Minimal Build

Import a smaller entry point when you only need core decimal operations:

import FixedPrecision, { fixedconfig } from "fixed-precision/minimal";

The minimal build includes: creation, arithmetic, comparison, rounding/scaling, sqrt, random/min/max/sum, predicates, and common formatting/conversion. It omits the larger extended APIs: trigonometry, logarithms, matrix/vector, bitwise, combinatorics, fractions, constants, logical operations, raw comparisons, and advanced inspection methods.

Contributing

1. Fork the repository.
2. Create a new branch: git checkout -b feature-name.
3. Commit your changes: git commit -m 'Add some feature'.
4. Push to the branch: git push origin feature-name.
5. Open a pull request.

License

Distributed under the MIT License. See the LICENSE file for more details.