Deploy sarahdayan/dinero.js to github.com/sarahdayan/dinero.js.git:ma…

…ster
dinerojs · Mar 9, 2019 · 5f94bcd · 5f94bcd
1 parent ea5a180
commit 5f94bcd
Show file tree

Hide file tree

Showing 4 changed files with 115 additions and 32 deletions.
diff --git a/docs/dinero.js.html b/docs/dinero.js.html
@@ -278,7 +278,14 @@ <h1 class="page-title">
     /**
      * 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
@@ -288,12 +295,15 @@ <h1 class="page-title">
      *
      * @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/docs/index.html b/docs/index.html
@@ -203,7 +203,7 @@ <h2>Quick start</h2><p>Dinero.js makes it easy to create, calculate and format m
 Dinero({ amount: 500 })
   .setLocale('fr-FR')
   .add(Dinero({ amount: 500 }))
-  .toFormat('$0,0')</code></pre><p>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 <a href="https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_(the_%22exponent%22">exponent</a>), you can specify a precision.</p>
+  .toFormat('$0,0')</code></pre><p>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 <a href="https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_(the_%22exponent%22">exponent</a>&gt;), you can specify a precision.</p>
 <pre class="prettyprint source lang-js"><code>// represents $10.545
 Dinero({ amount: 10545, precision: 3 })
 
@@ -218,6 +218,14 @@ <h2>Quick start</h2><p>Dinero.js makes it easy to create, calculate and format m
 Dinero({ amount: 1000 })</code></pre><p>This is only a preview of what you can do. Dinero.js has extensive documentation with examples for all of its methods.</p>
 <p><a href="https://sarahdayan.github.io/dinero.js/module-Dinero.html">Read full documentation</a></p>
 <h2>Contributing</h2><p>Pull requests are welcome! Please check the <a href="https://github.com/sarahdayan/dinero.js/blob/master/CONTRIBUTING.md">contributing guidelines</a> for install instructions and general conventions.</p>
+<h2>Community</h2><p>Selected content about Dinero.js:</p>
+<ul>
+<li><a href="https://devchat.tv/js-jabber/jsj-351-dinero-js-with-sarah-dayan/">JSJ 351: Dinero.js with Sarah Dayan</a></li>
+<li><a href="https://frontstuff.io/build-a-shopping-cart-with-vue-and-dinerojs">Build a Shopping Cart with Vue and Dinero.js</a></li>
+<li><a href="https://frontstuff.io/how-to-handle-monetary-values-in-javascript">How to Handle Monetary Values in JavaScript</a></li>
+<li><a href="https://www.reddit.com/r/javascript/comments/84mhrw/dinerojs_an_immutable_library_to_create_calculate/">Comparison with Numeral.js</a></li>
+<li>Submit your own blog post/tutorial!</li>
+</ul>
 <h2>Support</h2><p>Show some love by <a href="https://www.producthunt.com/posts/dinero-js">upvoting on Product Hunt</a> if you like, support and/or use the library 🔼😍</p>
 <h2>Acknowledgements</h2><p>Dinero.js is inspired from <a href="https://martinfowler.com/eaaCatalog/money.html">Martin Fowler's monetary representation</a>. Design-wise, it draws inspiration from <a href="http://moneyphp.org">Money PHP</a>, <a href="https://moment.github.io/luxon">Luxon</a>, <a href="https://momentjs.com">Moment.js</a> and <a href="http://numeraljs.com">Numeral.js</a> (even though it doesn't rely on any of them).</p>
 <p>Logo by <a href="https://github.com/desandro">David DeSandro</a>.</p>

diff --git a/docs/module-Dinero.html b/docs/module-Dinero.html
@@ -1020,7 +1020,7 @@ <h5 id="getPrecision-examples">Example</h5>
       </svg>
     </a>
     <h4 class="name" id="~convertPrecision">
-      <span class="type-signature">(inner) </span>convertPrecision<span class="signature">(newPrecision)</span><span class="type-signature"> &rarr; {Dinero}</span>
+      <span class="type-signature">(inner) </span>convertPrecision<span class="signature">(newPrecision, roundingMode<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Dinero}</span>
     </h4>
   </span>
 
@@ -1030,6 +1030,10 @@ <h4 class="name" id="~convertPrecision">
 
   <div class="description">
     <p>Returns a new Dinero object with a new precision and a converted amount.</p>
+<p>By default, fractional minor currency units are rounded using the <strong>half to even</strong> rule (<a href="http://wiki.c2.com/?BankersRounding">banker's rounding</a>).
+This can be necessary when you need to convert objects to a smaller precision.</p>
+<p>Rounding <em>can</em> 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 <code>roundingMode</code> to better fit your needs.</p>
   </div>
 
 
@@ -1051,8 +1055,12 @@ <h5>Parameters:</h5>
       <th>Type</th>
 
 
+        <th>Attributes</th>
+
 
 
+        <th>Default</th>
+
 
       <th class="last">Description</th>
     </tr>
@@ -1079,7 +1087,19 @@ <h5>Parameters:</h5>
         </td>
 
 
+          <td class="attributes">
+
+
+
 
+
+          </td>
+
+
+
+          <td class="default">
+
+          </td>
 
 
         <td class="description last">
@@ -1089,6 +1109,51 @@ <h5>Parameters:</h5>
       </tr>
 
 
+      <tr>
+
+          <td class="name"><code>roundingMode</code></td>
+
+
+        <td class="type">
+
+
+    <span class="param-type">
+      String
+    </span>
+
+
+
+
+
+        </td>
+
+
+          <td class="attributes">
+
+              &lt;optional><br>
+
+
+
+
+
+          </td>
+
+
+
+          <td class="default">
+
+              'HALF_EVEN'
+
+          </td>
+
+
+        <td class="description last">
+          <p>The rounding mode to use: <code>'HALF_ODD'</code>, <code>'HALF_EVEN'</code>, <code>'HALF_UP'</code>, <code>'HALF_DOWN'</code>, <code>'HALF_TOWARDS_ZERO'</code> or <code>'HALF_AWAY_FROM_ZERO'</code>.</p>
+
+        </td>
+      </tr>
+
+
   </tbody>
 </table>
 
@@ -1127,7 +1192,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line183">line 183</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line190">line 190</a>
         </li>
       </ul>
     </dd>
@@ -1320,7 +1385,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line211">line 211</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line221">line 221</a>
         </li>
       </ul>
     </dd>
@@ -1517,7 +1582,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line237">line 237</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line247">line 247</a>
         </li>
       </ul>
     </dd>
@@ -1777,7 +1842,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line271">line 271</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line281">line 281</a>
         </li>
       </ul>
     </dd>
@@ -2011,7 +2076,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line304">line 304</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line314">line 314</a>
         </li>
       </ul>
     </dd>
@@ -2181,7 +2246,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line327">line 327</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line337">line 337</a>
         </li>
       </ul>
     </dd>
@@ -2379,7 +2444,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line359">line 359</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line369">line 369</a>
         </li>
       </ul>
     </dd>
@@ -2791,7 +2856,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line463">line 463</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line473">line 473</a>
         </li>
       </ul>
     </dd>
@@ -2987,7 +3052,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line509">line 509</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line519">line 519</a>
         </li>
       </ul>
     </dd>
@@ -3168,7 +3233,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line534">line 534</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line544">line 544</a>
         </li>
       </ul>
     </dd>
@@ -3372,7 +3437,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line567">line 567</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line577">line 577</a>
         </li>
       </ul>
     </dd>
@@ -3584,7 +3649,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line594">line 594</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line604">line 604</a>
         </li>
       </ul>
     </dd>
@@ -3788,7 +3853,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line627">line 627</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line637">line 637</a>
         </li>
       </ul>
     </dd>
@@ -3945,7 +4010,7 @@ <h4 class="name" id="~isZero">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line644">line 644</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line654">line 654</a>
         </li>
       </ul>
     </dd>
@@ -4055,7 +4120,7 @@ <h4 class="name" id="~isPositive">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line662">line 662</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line672">line 672</a>
         </li>
       </ul>
     </dd>
@@ -4169,7 +4234,7 @@ <h4 class="name" id="~isNegative">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line680">line 680</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line690">line 690</a>
         </li>
       </ul>
     </dd>
@@ -4284,7 +4349,7 @@ <h4 class="name" id="~hasSubUnits">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line696">line 696</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line706">line 706</a>
         </li>
       </ul>
     </dd>
@@ -4407,7 +4472,7 @@ <h4 class="name" id="~hasCents">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line714">line 714</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line724">line 724</a>
         </li>
       </ul>
     </dd>
@@ -4572,7 +4637,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line731">line 731</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line741">line 741</a>
         </li>
       </ul>
     </dd>
@@ -4737,7 +4802,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line754">line 754</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line764">line 764</a>
         </li>
       </ul>
     </dd>
@@ -5027,7 +5092,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line807">line 807</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line817">line 817</a>
         </li>
       </ul>
     </dd>
@@ -5149,7 +5214,7 @@ <h4 class="name" id="~toUnit">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line833">line 833</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line843">line 843</a>
         </li>
       </ul>
     </dd>
@@ -5377,7 +5442,7 @@ <h5>Parameters:</h5>
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line854">line 854</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line864">line 864</a>
         </li>
       </ul>
     </dd>
@@ -5487,7 +5552,7 @@ <h4 class="name" id="~toObject">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line873">line 873</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line883">line 883</a>
         </li>
       </ul>
     </dd>
@@ -5595,7 +5660,7 @@ <h4 class="name" id="~toJSON">
     <dd class="tag-source">
       <ul class="dummy">
         <li>
-          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line892">line 892</a>
+          <a href="dinero.js.html">dinero.js</a>, <a href="dinero.js.html#line902">line 902</a>
         </li>
       </ul>
     </dd>

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dinero.js",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "An immutable library to create, calculate and format monetary values.",
   "author": "Sarah Dayan",
   "keywords": [