Strengthen README to make it clear that this is a prototype for proposal-decimal (#77)

* Make clear that this library is intended to match the spec

* Use TypeScript for examples

Author: jessealama

.gitignore

@@ -3,4 +3,8 @@ coverage
 dist/
 src/*.d.ts
 src/*.mjs
-src/*.d.mts
+src/*.d.mts
+/examples/*.mjs
+/examples/*.d.ts
+/examples/*.d.mts
+/examples/*.js

README.md

@@ -1,5 +1,7 @@
 # decimal128.js—A userland approximation to IEEE 754 Decimal128 in JavaScript
 
+This library is a prototype for the [decimal proposal](https://github.com/tc39/proposal-decimal). Apart from the intention of the decimal proposal for `valueOf` to unconditionally throw, there should be no observable difference between what this library does and what the proposal is [supposed to do](http://tc39.es/proposal-decimal/). If you find a mismatch, please file [an issue](https://github.com/jessealama/decimal128/issues) in this repo.
+
 ## Operations
 
 -   addition (`add`)
@@ -22,7 +24,7 @@ This package also supports minus zero, positive and negative infinity, and NaN.
 
 ### Differences with the official Decimal128
 
-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.
+This package is not literally an implementation of IEEE 754 Decimal128. This package defines 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. Moreover, this package supports the concep of quiet NaNs only. Signalling NaNs are not supported here.
 
 #### Lack of support for specifying context
 

examples/bill.js examples/bill.ts

@@ -3,17 +3,21 @@ import { Decimal128 } from "../src/decimal128.mjs";
 const zero = new Decimal128("0");
 const one = new Decimal128("1");
 
-function calculateBill(items, tax) {
-    let taxRate = new Decimal128(tax).add(one);
+interface Item {
+    price: string;
+    count: string;
+}
+
+function calculateBill(items: Item[], tax: string): Decimal128 {
     let total = items.reduce((total, { price, count }) => {
         return total.add(new Decimal128(price).multiply(new Decimal128(count)));
     }, zero);
-    return total.multiply(taxRate);
+    return total.multiply(new Decimal128(tax).add(one));
 }
 
 const items = [
     { price: "1.25", count: "5" },
     { price: "5.00", count: "1" },
 ];
 const tax = "0.0735";
-console.log(calculateBill(items, tax).toString());
+console.log(calculateBill(items, tax).toString({ numDecimalDigits: 2 }));

examples/floor.js

@@ -0,0 +1,7 @@
+import { Decimal128 } from "../src/decimal128.mjs";
+
+function floor(d: Decimal128): Decimal128 {
+    return d.round(0, "floor");
+}
+
+export { floor };

examples/floor.mts

@@ -1,17 +1,17 @@
 import { Decimal128 } from "../src/decimal128.mjs";
-import { pow } from "./pow.js";
+import { pow } from "./pow.mjs";
 
 const one = new Decimal128("1");
 const paymentsPerYear = new Decimal128("12");
 
-function calculateMonthlyPayment(p, r, y) {
+function calculateMonthlyPayment(p: string, r: string, y: string): Decimal128 {
     const principal = new Decimal128(p);
     const annualInterestRate = new Decimal128(r);
     const years = new Decimal128(y);
     const monthlyInterestRate = annualInterestRate.divide(paymentsPerYear);
     const paymentCount = paymentsPerYear.multiply(years);
     const onePlusInterestRate = monthlyInterestRate.add(one);
-    const ratePower = pow(onePlusInterestRate, paymentCount);
+    const ratePower = pow(onePlusInterestRate, Number(paymentCount));
 
     const x = principal.multiply(monthlyInterestRate);
 

examples/mortgage.js examples/mortgage.ts

@@ -0,0 +1,8 @@
+import { Decimal128 } from "../src/decimal128.mjs";
+
+function normalize(d: Decimal128): string {
+    // Decimal128 object
+    return d.toString({ normalize: true });
+}
+
+export { normalize };

examples/normalize.js

@@ -1,13 +1,9 @@
 import { Decimal128 } from "../src/decimal128.mjs";
 
-const one = new Decimal128("1");
-
-function pow(a, b) {
-    let i = one;
+function pow(a: Decimal128, b: number): Decimal128 {
     let result = a;
-    while (-1 === i.cmp(b)) {
+    for (let i = 0; i < b; i++) {
         result = result.multiply(a);
-        i = i.add(one);
     }
     return result;
 }