Remove normalization option in constructor in favor of normalizing in toString (#72)

* Specify beginning-of-document

* Ensure README matches actual API

Also, fix the description of how normalization is handled.

* lint

* Add constructor and arithmetic options

* Specify rounding mode

* Use npx to ensure we're using the intended TS rather than an ambient one

Author: jessealama

.github/workflows/push.yaml

@@ -1,3 +1,4 @@
+---
 on: push
 name: CI
 jobs:
@@ -21,7 +22,7 @@ jobs:
             - name: lint
               run: npm run lint
             - name: compile typescript
-              run: tsc
+              run: npx tsc
             - name: test
               run: npm run test
             - name: generate coverage

README.md

@@ -7,36 +7,39 @@
 -   multiplication (`multiply`)
 -   division (`divide`)
 -   remainder (`remainder`)
--   absolute value (`abs`)
+-   rounding (`round`)
 -   `toString`
--   `toExponential`
 
 ## Implementation
 
-This package is written in TypeScript. Unit tests are in (typed) Jest. There are no other external dependencies.
+This package is written in TypeScript. Unit tests are in Jest. There are no other external dependencies.
 
 ## Data model
 
 This package aims to reproduce the IEEE 754 [Decimal128](https://en.wikipedia.org/wiki/Decimal128_floating-point_format) decimal floating-point numbers in JavaScript. These **decimal** (not binary!) numbers take up 128 bits of information per number. This format allows for an exact representation of decimal numbers with 34 (decimal) significant digits and an exponent between -6143 and 6144. That's a _vast_ amount of range and precision! Decimal128 is a fantastic standard. Let's implement it in JavaScript.
 
-This package also supports minus zero, positive and negative infinity, and NaN.
-
-This package aims to work with only _normalized_ values in the Decimal128 universe. With this package, there is no way to represent, say, `1.2` and `1.20` as distinct values. Digit strings are normalized right away, so `1.20` becomes `1.2`.
+This package also supports minus zero, positive and negative infinity, and NaN. These values are distinct from JS's built-in `-0`, `Infinity`, `-Infinity`, and `NaN`, since those are all JS Numbers.
 
 ### Differences with the official Decimal128
 
-This package is not literally an implementation of Decimal128. In time, it may _become_ one, but initially, this package is working with a subspace of Decimal128 that makes sense for the use cases we have in mind (mainly, finance).
+This package is not literally an implementation of Decimal128. This package is working with a subset of Decimal128 that makes sense for the use cases we have in mind (mainly, though not exclusively, finance). Only a handful of arithmetic operations are implemented. We do not offer, for instance, the various trigonometric functions.
 
 #### Lack of support for specifying context
 
-IEEE 754 Decimal128 allows one to globally specify configuration values (e.g., precision) that control all mathematical operations on Decimal128 values. This JavaScript package does not support that. Calculations are always done using all available digits.
+IEEE 754 Decimal128 allows one to globally specify configuration values (e.g., precision) that control all mathematical operations on Decimal128 values. This JavaScript package does not support that. This package offers a purely functional subset of Decimal128; there's no ambient context to specify and set. If one wishes to control, e.g., rounding, then one needs to specify that when constructing Decimal128 values or doing arithmetic operations.
+
+Think of this package as providing, basically, arbitrary-precision decimal numbers limited to those that fit into 128 bits the way that Decimal128 does it. No need to specify context. Just imagine that you're working in an ideal arbitrary-precision world, do the operation, and enjoy the results. If you need to cut off a calculation after a certain point, just perform the operation (e.g., addition) and use `round`.
 
-Think of this package as providing, basically, arbitrary-precision decimal numbers limited to those that fit into 128 bits the way that Decimal128 does it. No need to specify context. Just imagine that you're working in an ideal arbitrary-precision world, do the operation, and enjoy the results. If you need to cut off a calculation after a certain point, just perform the operation (e.g., addition) and then use `toDecimalDigits` on the result.
+#### Serialized values normalized by default
 
-#### Values always normalized
+Decimal128 is a universe of **unnormalized** values. In the Decimal128 world, `1.2` and `1.20` are _distinct_ values. There's good reason for adopting such an approach, and has some benefits. But there can be surprises when working with non-normal values. This package supports IEEE 754 Decimal128, but it also aims to minimize surprises. In IEEE 754 Decimal128, if one adds, say, 1.2 and 3.8, the result is 5.0, not 5. (Again, those are _distinct_ values in IEEE 754 Decimal128.) Reproducing that example with this package, one has
 
-Decimal128 is a universe of **unnormalized** values. In the Decimal128 world, `1.2` and `1.20` are _distinct_ values. There's good reason for adopting such an approach, and some benefits. But this package deliberately works in a world of _normalized_ values. Given the string `1.20`, this package will turn that into `1.2`; that extra trailing zero will be lost. To recover the string `1.20`, additional, out-of-band information needs to be supplied. For instance: if you're working with numbers as financial quantities, you know, out-of-band, how to interpret your numbers. Thus, if I tell you that the cost of something is `1.2` USD, you know that means, and you know that, if you need to present that data to someone, you'd add an extra digit there. This package provides a `toDecimalDigits` method that allows you to generate `1.20` from the underlying `1.2`.
+```javascript
+new Decimal128("1.2").add(new Decimal128("3.8")).toString(); // "5"
+```
 
-#### Missing operations
+One can switch off normalization by setting the `normalize` option to `false` in `toString`, like this:
 
-This package focuses on the bread and butter of arithmetic: addition, multiplication, subtraction, and division. To round things out from there (ha!), we have the absolute value function, trunction, floor/ceiling.
+```javascript
+new Decimal128("1.2").add(new Decimal128("3.8")).toString({ normalize: false }); // "5.0"
+```

src/decimal128.mts

@@ -865,10 +865,24 @@ interface FullySpecifiedConstructorOptions {
     normalize: boolean;
 }
 
-const DEFAULT_CONSTRUCTOR_OPTIONS: FullySpecifiedConstructorOptions = {
-    roundingMode: ROUNDING_MODE_DEFAULT,
-    normalize: CONSTRUCTOR_SHOULD_NORMALIZE,
-};
+const DEFAULT_CONSTRUCTOR_OPTIONS: FullySpecifiedConstructorOptions =
+    Object.freeze({
+        roundingMode: ROUNDING_MODE_DEFAULT,
+        normalize: CONSTRUCTOR_SHOULD_NORMALIZE,
+    });
+
+interface ArithmeticOperationOptions {
+    roundingMode?: RoundingMode;
+}
+
+interface FullySpecifiedArithmeticOperationOptions {
+    roundingMode: RoundingMode;
+}
+
+const DEFAULT_ARITHMETIC_OPERATION_OPTIONS: FullySpecifiedArithmeticOperationOptions =
+    Object.freeze({
+        roundingMode: ROUNDING_MODE_DEFAULT,
+    });
 
 type ToStringFormat = "decimal" | "exponential";
 const TOSTRING_FORMATS: string[] = ["decimal", "exponential"];
@@ -883,10 +897,10 @@ interface FullySpecifiedToStringOptions {
     numDecimalDigits: number | undefined;
 }
 
-const DEFAULT_TOSTRING_OPTIONS: FullySpecifiedToStringOptions = {
+const DEFAULT_TOSTRING_OPTIONS: FullySpecifiedToStringOptions = Object.freeze({
     format: "decimal",
     numDecimalDigits: undefined,
-};
+});
 
 function ensureFullySpecifiedConstructorOptions(
     options?: ConstructorOptions
@@ -911,6 +925,25 @@ function ensureFullySpecifiedConstructorOptions(
     return opts;
 }
 
+function ensureFullySpecifiedArithmeticOperationOptions(
+    options?: ArithmeticOperationOptions
+): FullySpecifiedArithmeticOperationOptions {
+    let opts = { ...DEFAULT_ARITHMETIC_OPERATION_OPTIONS };
+
+    if (undefined === options) {
+        return opts;
+    }
+
+    if (
+        "string" === typeof options.roundingMode &&
+        ROUNDING_MODES.includes(options.roundingMode)
+    ) {
+        opts.roundingMode = options.roundingMode;
+    }
+
+    return opts;
+}
+
 function ensureFullySpecifiedToStringOptions(
     options?: ToStringOptions
 ): FullySpecifiedToStringOptions {
@@ -1144,8 +1177,9 @@ export class Decimal128 {
      * Add this Decimal128 value to one or more Decimal128 values.
      *
      * @param x
+     * @param opts
      */
-    add(x: Decimal128): Decimal128 {
+    add(x: Decimal128, opts?: ArithmeticOperationOptions): Decimal128 {
         if (this.isNaN() || x.isNaN()) {
             return new Decimal128(NAN);
         }
@@ -1167,12 +1201,14 @@ export class Decimal128 {
         }
 
         if (this.isNegative && x.isNegative) {
-            return this.negate().add(x.negate()).negate();
+            return this.negate().add(x.negate(), opts).negate();
         }
 
         let resultRat = Rational.add(this.rat, x.rat);
+        let options = ensureFullySpecifiedArithmeticOperationOptions(opts);
         let initialResult = new Decimal128(
-            resultRat.toDecimalPlaces(MAX_SIGNIFICANT_DIGITS + 1)
+            resultRat.toDecimalPlaces(MAX_SIGNIFICANT_DIGITS + 1),
+            { roundingMode: options.roundingMode }
         );
         let adjusted = initialResult.setExponent(
             Math.min(this.exponent, x.exponent)
@@ -1185,8 +1221,9 @@ export class Decimal128 {
      * Subtract another Decimal128 value from one or more Decimal128 values.
      *
      * @param x
+     * @param opts
      */
-    subtract(x: Decimal128): Decimal128 {
+    subtract(x: Decimal128, opts?: ArithmeticOperationOptions): Decimal128 {
         if (this.isNaN() || x.isNaN()) {
             return new Decimal128(NAN);
         }
@@ -1215,7 +1252,9 @@ export class Decimal128 {
             MAX_SIGNIFICANT_DIGITS + 1
         );
 
-        let initialResult = new Decimal128(rendered);
+        let options = ensureFullySpecifiedArithmeticOperationOptions(opts);
+
+        let initialResult = new Decimal128(rendered, options);
         let adjusted = initialResult.setExponent(
             Math.min(this.exponent, x.exponent)
         );
@@ -1228,8 +1267,9 @@ export class Decimal128 {
      * If no arguments are given, return this value.
      *
      * @param x
+     * @param opts
      */
-    multiply(x: Decimal128): Decimal128 {
+    multiply(x: Decimal128, opts?: ArithmeticOperationOptions): Decimal128 {
         if (this.isNaN() || x.isNaN()) {
             return new Decimal128(NAN);
         }
@@ -1268,7 +1308,8 @@ export class Decimal128 {
 
         let resultRat = Rational.multiply(this.rat, x.rat);
         let initialResult = new Decimal128(
-            resultRat.toDecimalPlaces(MAX_SIGNIFICANT_DIGITS + 1)
+            resultRat.toDecimalPlaces(MAX_SIGNIFICANT_DIGITS + 1),
+            ensureFullySpecifiedArithmeticOperationOptions(opts)
         );
         let adjusted = initialResult.setExponent(this.exponent + x.exponent);
 
@@ -1291,8 +1332,9 @@ export class Decimal128 {
      * If only one argument is given, just return the first argument.
      *
      * @param x
+     * @param opts
      */
-    divide(x: Decimal128): Decimal128 {
+    divide(x: Decimal128, opts?: ArithmeticOperationOptions): Decimal128 {
         if (this.isNaN() || x.isNaN()) {
             return new Decimal128(NAN);
         }
@@ -1375,7 +1417,10 @@ export class Decimal128 {
         }
 
         let resultExponent = this.exponent - (x.exponent + adjust);
-        return new Decimal128(`${resultCoefficient}E${resultExponent}`);
+        return new Decimal128(
+            `${resultCoefficient}E${resultExponent}`,
+            ensureFullySpecifiedArithmeticOperationOptions(opts)
+        );
     }
 
     /**
@@ -1453,9 +1498,10 @@ export class Decimal128 {
      * Return the remainder of this Decimal128 value divided by another Decimal128 value.
      *
      * @param d
+     * @param opts
      * @throws RangeError If argument is zero
      */
-    remainder(d: Decimal128): Decimal128 {
+    remainder(d: Decimal128, opts?: ArithmeticOperationOptions): Decimal128 {
         if (this.isNaN() || d.isNaN()) {
             return new Decimal128(NAN);
         }
@@ -1481,7 +1527,7 @@ export class Decimal128 {
         }
 
         let q = this.divide(d).round(0, ROUNDING_MODE_TRUNCATE);
-        return this.subtract(d.multiply(q));
+        return this.subtract(d.multiply(q), opts);
     }
 
     normalize(): Decimal128 {

tests/add.test.js

@@ -117,6 +117,16 @@ describe("addition", () => {
     });
 });
 
+describe("specify rounding mode", () => {
+    test("truncate rounding mode", () => {
+        expect(
+            new Decimal128("1234567890123456789012345678901234")
+                .add(new Decimal128("0.5"), { roundingMode: "trunc" })
+                .toString()
+        ).toStrictEqual("1234567890123456789012345678901234");
+    });
+});
+
 describe("examples from the General Decimal Arithmetic specification", () => {
     test("example one", () => {
         expect(