Documentation / @facturometro/einvoice / Decimal

Class: Decimal

Defined in: packages/core/src/decimal.ts:86

An exact decimal number: BigInt fixed-point, value = unscaled * 10^-scale.

Instances are immutable; every operation returns a new Decimal. add, sub and mul are exact (the result keeps every digit); div and round are the only operations that round, and they round the way XPath 2.0 does, which is what the EN 16931 and Peppol Schematron rules assume.

A Decimal is an opaque object, not a number and not a string: compare with cmp/eq (<, > and === do not work on it), combine with add/sub/mul/div (+ concatenates its toString()), and serialise with toString() (JSON.stringify sees only private fields and yields {}).

Example

import { Decimal } from '@facturometro/core';

Decimal.from('0.1').add(Decimal.from('0.2')).toString(); // '0.3'
Decimal.from('2.5').round().toString(); // '3', XPath rounds halves towards +infinity
Decimal.from('-2.5').round().toString(); // '-2'
Decimal.parse('1e3'); // null, not a lexical XSD decimal

Properties

ONE

readonly static ONE: Decimal

Defined in: packages/core/src/decimal.ts:88

The number one, with scale 0.

---

ZERO

readonly static ZERO: Decimal

Defined in: packages/core/src/decimal.ts:91

The number zero, with scale 0.

Methods

abs()

abs(): Decimal

Defined in: packages/core/src/decimal.ts:210

The absolute value.

Returns

Decimal

|this|, with the same scale.

Example

Decimal.from('-1.50').abs().toString(); // '1.50'

---

add()

add(other): Decimal

Defined in: packages/core/src/decimal.ts:224

Exact addition.

Parameters

other

Decimal

The value to add.

Returns

Decimal

this + other, with the larger of the two scales.

Example

Decimal.from('0.1').add(Decimal.from('0.2')).toString(); // '0.3'

---

cmp()

cmp(other): -1 | 0 | 1

Defined in: packages/core/src/decimal.ts:242

Compares two values, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

-1 | 0 | 1

-1 when this is smaller, 1 when it is larger, 0 when they are equal.

Example

Decimal.from('100').cmp(Decimal.from('100.00')); // 0

---

div()

div(other, scale?): Decimal

Defined in: packages/core/src/decimal.ts:271

Division, rounded to a fixed scale.

Follows the XPath implementation convention Saxon uses: the result keeps at least 18 decimals (more when an operand is wider) and an exact half is rounded towards zero. That is not how Decimal.round breaks a tie, so for a quotient with XPath rounding semantics divide wide first and round afterwards: a.div(b).round(n).

Parameters

other

Decimal

The divisor.

scale?

number = ...

Decimals to keep. Defaults to the largest of 18 and the two operand scales.

Returns

Decimal

this / other.

Throws

When other is zero, or scale is not an integer between 0 and 1000.

Example

Decimal.from('2').div(Decimal.from('3')).toString(); // '0.666666666666666667'
Decimal.from('1').div(Decimal.from('8'), 2).toString(); // '0.12', the half goes to zero
Decimal.from('1').div(Decimal.from('8')).round(2).toString(); // '0.13', the XPath way

---

eq()

eq(other): boolean

Defined in: packages/core/src/decimal.ts:300

Whether two values are numerically equal, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

boolean

true when this == other.

Example

Decimal.from('100').eq(Decimal.from('100.00')); // true

---

ge()

ge(other): boolean

Defined in: packages/core/src/decimal.ts:314

Whether this value is greater than or equal to another, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

boolean

true when this >= other.

Example

Decimal.from('1.50').ge(Decimal.from('1.5')); // true

---

gt()

gt(other): boolean

Defined in: packages/core/src/decimal.ts:328

Whether this value is greater than another, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

boolean

true when this > other.

Example

Decimal.from('1.51').gt(Decimal.from('1.5')); // true

---

isZero()

isZero(): boolean

Defined in: packages/core/src/decimal.ts:341

Whether the value is zero, whatever its scale.

Returns

boolean

true for 0, 0.00 and -0.0.

Example

Decimal.from('-0.00').isZero(); // true

---

le()

le(other): boolean

Defined in: packages/core/src/decimal.ts:355

Whether this value is less than or equal to another, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

boolean

true when this <= other.

Example

Decimal.from('1.5').le(Decimal.from('1.500')); // true

---

lt()

lt(other): boolean

Defined in: packages/core/src/decimal.ts:369

Whether this value is less than another, ignoring their scales.

Parameters

other

Decimal

The value to compare with.

Returns

boolean

true when this < other.

Example

Decimal.from('1.5').lt(Decimal.from('1.51')); // true

---

mul()

mul(other): Decimal

Defined in: packages/core/src/decimal.ts:383

Exact multiplication.

Parameters

other

Decimal

The value to multiply by.

Returns

Decimal

this * other, with the sum of the two scales.

Example

Decimal.from('1.5').mul(Decimal.from('2.50')).toString(); // '3.750'

---

neg()

neg(): Decimal

Defined in: packages/core/src/decimal.ts:396

The negated value.

Returns

Decimal

-this, with the same scale. Zero stays zero; there is no negative zero.

Example

Decimal.from('1.5').neg().toString(); // '-1.5'

---

round()

round(places?): Decimal

Defined in: packages/core/src/decimal.ts:416

Rounds like XPath's fn:round: halves go towards positive infinity.

round(2.5) is 3 and round(-2.5) is -2. Values that are already short enough are returned unchanged, scale included; otherwise the result takes the requested precision.

Parameters

places?

number = 0

Decimals to keep. Negative values round to tens, hundreds and so on.

Returns

Decimal

The rounded value.

Throws

When places is not an integer between -1000 and 1000.

Example

Decimal.from('1.125').round(2).toString(); // '1.13'
Decimal.from('-2.5').round().toString(); // '-2'
Decimal.from('8452').round(-2).toString(); // '8500'

---

scale()

scale(): number

Defined in: packages/core/src/decimal.ts:445

Number of digits after the decimal point.

Returns

number

The scale, which is part of how the value prints but never of how it compares.

Example

Decimal.from('100.500').scale(); // 3

---

sign()

sign(): -1 | 0 | 1

Defined in: packages/core/src/decimal.ts:458

The sign of the value.

Returns

-1 | 0 | 1

-1, 0 or 1.

Example

Decimal.from('-1.5').sign(); // -1

---

sub()

sub(other): Decimal

Defined in: packages/core/src/decimal.ts:475

Exact subtraction.

Parameters

other

Decimal

The value to subtract.

Returns

Decimal

this - other, with the larger of the two scales.

Example

Decimal.from('0.3').sub(Decimal.from('0.1')).toString(); // '0.2'

---

toFixed()

toFixed(digits): string

Defined in: packages/core/src/decimal.ts:495

Formats the value with exactly digits decimals, rounding halves towards positive infinity.

Parameters

digits

number

How many decimals to print.

Returns

string

The formatted value, padded with zeros when it is shorter.

Throws

When digits is not an integer between 0 and 1000.

Example

Decimal.from('2.345').toFixed(2); // '2.35'
Decimal.from('2').toFixed(2); // '2.00'

---

toNumber()

toNumber(): number

Defined in: packages/core/src/decimal.ts:513

Converts the value to the nearest JavaScript number.

Only for presentation and interoperability: the result is a binary float and may lose precision. Never compute invoice amounts with it.

Returns

number

The value as a number.

Example

Decimal.from('1.50').toNumber(); // 1.5

---

toString()

toString(): string

Defined in: packages/core/src/decimal.ts:526

The lexical representation, with exactly scale() decimals.

Returns

string

The value as a string; trailing zeros are preserved.

Example

Decimal.from('100.500').toString(); // '100.500'

---

from()

static from(value): Decimal

Defined in: packages/core/src/decimal.ts:128

Builds a decimal from a string, a number or a bigint.

Strings must be lexical XSD decimals, exactly as Decimal.parse accepts them. Numbers go through their shortest round-trip representation, so 0.1 becomes 0.1 and not 0.1000000000000000055511151231257827; they must be finite.

Parameters

value

string | number | bigint

The value to convert.

Returns

Decimal

The decimal.

Throws

When the string is not a lexical decimal or the number is not finite.

Example

Decimal.from('100.00').toString(); // '100.00'
Decimal.from(0.1).toString(); // '0.1'
Decimal.from(42n).toString(); // '42'

---

parse()

static parse(raw): Decimal | null

Defined in: packages/core/src/decimal.ts:157

Parses a lexical XSD decimal, keeping its scale.

Accepts an optional sign, digits and an optional fraction (1, -1.5, +.5, 1.); rejects exponents (1e3), surrounding whitespace (' 1.0') and anything else. Values that carry trailing zeros keep them: '100.500' has scale 3 and prints as 100.500.

Parameters

raw

string

The lexical representation, exactly as it appears in the document.

Returns

Decimal | null

The decimal, or null when raw is not a lexical XSD decimal.

Example

Decimal.parse('100.500')?.scale(); // 3
Decimal.parse(' 1.0'); // null