Merge branch 'develop'

dinerojs · Mar 9, 2019 · ea5a180 · ea5a180
2 parents fbe36ce + 912577b
commit ea5a180
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -29,11 +29,11 @@
 
 ## Features
 
-* Immutable and chainable API.
-* Global settings support.
-* Extended formatting and rounding options.
-* Native Intl support (no additional locale files).
-* Currency conversion.
+- Immutable and chainable API.
+- Global settings support.
+- Extended formatting and rounding options.
+- Native Intl support (no additional locale files).
+- Currency conversion.
 
 ## Download/install
 
@@ -191,7 +191,7 @@ Dinero({ amount: 500 })
   .toFormat('$0,0')
 ```
 
-By default, new Dinero objects represent monetary values with two decimal places. If you want to represent more, or if you're using a currency with a different [exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_(the_%22exponent%22)), you can specify a precision.
+By default, new Dinero objects represent monetary values with two decimal places. If you want to represent more, or if you're using a currency with a different [exponent](<https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_(the_%22exponent%22)>), you can specify a precision.
 
 ```js
 // represents $10.545
@@ -221,6 +221,16 @@ This is only a preview of what you can do. Dinero.js has extensive documentation
 
 Pull requests are welcome! Please check the [contributing guidelines][dinero-guidelines] for install instructions and general conventions.
 
+## Community
+
+Selected content about Dinero.js:
+
+- [JSJ 351: Dinero.js with Sarah Dayan][community:jsjabber]
+- [Build a Shopping Cart with Vue and Dinero.js][community:shoppingcart]
+- [How to Handle Monetary Values in JavaScript][community:monetaryvalues]
+- [Comparison with Numeral.js][community:numeral]
+- Submit your own blog post/tutorial!
+
 ## Support
 
 Show some love by [upvoting on Product Hunt][producthunt:dinerojs] if you like, support and/or use the library 🔼😍
@@ -253,3 +263,7 @@ Dinero.js is licensed under [MIT][license].
 [jsdelivr:landing]: https://www.jsdelivr.com/package/npm/dinero.js
 [jsdelivr:cdn]: https://cdn.jsdelivr.net/npm/dinero.js/build
 [github:desandro]: https://github.com/desandro
+[community:jsjabber]: https://devchat.tv/js-jabber/jsj-351-dinero-js-with-sarah-dayan/
+[community:shoppingcart]: https://frontstuff.io/build-a-shopping-cart-with-vue-and-dinerojs
+[community:monetaryvalues]: https://frontstuff.io/how-to-handle-monetary-values-in-javascript
+[community:numeral]: https://www.reddit.com/r/javascript/comments/84mhrw/dinerojs_an_immutable_library_to_create_calculate/
diff --git a/src/dinero.js b/src/dinero.js
@@ -170,7 +170,14 @@ const Dinero = options => {
     /**
      * Returns a new Dinero object with a new precision and a converted amount.
      *
+     * By default, fractional minor currency units are rounded using the **half to even** rule ([banker's rounding](http://wiki.c2.com/?BankersRounding)).
+     * This can be necessary when you need to convert objects to a smaller precision.
+     *
+     * Rounding *can* lead to accuracy issues as you chain many times. Consider a minimal amount of subsequent conversions for safer results.
+     * You can also specify a different `roundingMode` to better fit your needs.
+     *
      * @param {Number} newPrecision - The new precision.
+     * @param {String} [roundingMode='HALF_EVEN'] - The rounding mode to use: `'HALF_ODD'`, `'HALF_EVEN'`, `'HALF_UP'`, `'HALF_DOWN'`, `'HALF_TOWARDS_ZERO'` or `'HALF_AWAY_FROM_ZERO'`.
      *
      * @example
      * // Returns a Dinero object with precision 3 and amount 1000
@@ -180,12 +187,15 @@ const Dinero = options => {
      *
      * @return {Dinero}
      */
-    convertPrecision(newPrecision) {
+    convertPrecision(newPrecision, roundingMode = globalFormatRoundingMode) {
       assertInteger(newPrecision)
       return create.call(this, {
-        amount: calculator.multiply(
-          this.getAmount(),
-          Math.pow(10, calculator.subtract(newPrecision, this.getPrecision()))
+        amount: calculator.round(
+          calculator.multiply(
+            this.getAmount(),
+            Math.pow(10, calculator.subtract(newPrecision, this.getPrecision()))
+          ),
+          roundingMode
         ),
         precision: newPrecision
       })

diff --git a/test/unit/dinero.spec.js b/test/unit/dinero.spec.js
@@ -107,6 +107,13 @@ describe('Dinero', () => {
           .toObject()
       ).toMatchObject({ amount: 50000, precision: 4 })
     })
+    test('should return a new Dinero object with a new precision and a converted rounded amount', () => {
+      expect(
+        Dinero({ amount: 14270, precision: 2 })
+          .convertPrecision(0)
+          .toObject()
+      ).toMatchObject({ amount: 143, precision: 0 })
+    })
     test('should throw when new precision is invalid', () => {
       expect(() =>
         Dinero({ amount: 500, precision: 2 })