financial - npm Package Compare versions

Comparing version 0.0.15 to 0.0.16

dist/financial.cjs.development.js

@@ -10,5 +10,5 @@ 'use strict';
 (function (PaymentDueTime) {
-  /** Payments due at the beginning of a period */
+  /** Payments due at the beginning of a period (1) */
   PaymentDueTime["Begin"] = "begin";
-  /** Payments are due at the end of a period */
+  /** Payments are due at the end of a period (0) */
 
@@ -379,2 +379,85 @@ PaymentDueTime["End"] = "end"; // 0
 /**
+ * Compute the rate of interest per period
+ *
+ * @param nper - Number of compounding periods
+ * @param pmt - Payment
+ * @param pv - Present value
+ * @param fv - Future value
+ * @param when - When payments are due ('begin' or 'end')
+ * @param guess - Starting guess for solving the rate of interest
+ * @param tol - Required tolerance for the solution
+ * @param maxIter - Maximum iterations in finding the solution
+ *
+ * @returns the rate of interest per period (or `NaN` if it could
+ *  not be computed within the number of iterations provided)
+ *
+ * ## Notes
+ *
+ * Use Newton's iteration until the change is less than 1e-6
+ * for all values or a maximum of 100 iterations is reached.
+ * Newton's rule is:
+ *
+ * ```
+ * r_{n+1} = r_{n} - g(r_n)/g'(r_n)
+ * ```
+ *
+ * where:
+ *
+ * - `g(r)` is the formula
+ * - `g'(r)` is the derivative with respect to r.
+ *
+ *
+ * The rate of interest is computed by iteratively solving the
+ * (non-linear) equation:
+ *
+ * ```
+ * fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper - 1) = 0
+ * ```
+ *
+ * for `rate.
+ *
+ * ## References
+ *
+ * [Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May)](http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt).
+ */
+
+function rate(nper, pmt, pv, fv, when, guess, tol, maxIter) {
+  if (when === void 0) {
+    when = exports.PaymentDueTime.End;
+  }
+
+  if (guess === void 0) {
+    guess = 0.1;
+  }
+
+  if (tol === void 0) {
+    tol = 1e-6;
+  }
+
+  if (maxIter === void 0) {
+    maxIter = 100;
+  }
+
+  var rn = guess;
+  var iterator = 0;
+  var close = false;
+
+  while (iterator < maxIter && !close) {
+    var rnp1 = rn - _gDivGp(rn, nper, pmt, pv, fv, when);
+
+    var diff = Math.abs(rnp1 - rn);
+    close = diff < tol;
+    iterator++;
+    rn = rnp1;
+  } // if exausted all the iterations and the result is not
+  // close enough, returns `NaN`
+
+
+  if (!close) {
+    return Number.NaN;
+  }
+
+  return rn;
+}
+/**
  * This function is here to simply have a different name for the 'fv'
@@ -391,3 +474,22 @@ * function to not interfere with the 'fv' keyword argument within the 'ipmt'
 }
+/**
+ * Evaluates `g(r_n)/g'(r_n)`, where:
+ *
+ * ```
+ * g = fv + pv * (1+rate) ** nper + pmt * (1+rate * when)/rate * ((1+rate) ** nper - 1)
+ * ```
+ *
+ * @private
+ */
 
+
+function _gDivGp(r, n, p, x, y, when) {
+  var w = when === exports.PaymentDueTime.Begin ? 1 : 0;
+  var t1 = Math.pow(r + 1, n);
+  var t2 = Math.pow(r + 1, n - 1);
+  var g = y + t1 * x + p * (t1 - 1) * (r * w + 1) / r;
+  var gp = n * t2 * x - p * (t1 - 1) * (r * w + 1) / Math.pow(r, 2) + n * p * t2 * (r * w + 1) / r + p * (t1 - 1) * w / r;
+  return g / gp;
+}
+
 exports.fv = fv;
@@ -399,2 +501,3 @@ exports.ipmt = ipmt;
 exports.pv = pv;
+exports.rate = rate;
 //# sourceMappingURL=financial.cjs.development.js.map

dist/financial.cjs.production.min.js

@@ -1,2 +0,2 @@
-"use strict";var e;function t(e,t,n,r,i){if(void 0===i&&(i=exports.PaymentDueTime.End),0===e)return-(r+n*t);var o=Math.pow(1+e,t);return-r*o-n*(1+e*(i===exports.PaymentDueTime.Begin?1:0))/e*(o-1)}function n(e,t,n,r,i){void 0===r&&(r=0),void 0===i&&(i=exports.PaymentDueTime.End);var o=0===e,u=Math.pow(1+e,t),m=i===exports.PaymentDueTime.Begin?1:0,p=o?1:e;return-(r+n*u)/(o?t:(1+p*m)*(u-1)/p)}function r(e,t,r,o,u,m){if(void 0===u&&(u=0),void 0===m&&(m=exports.PaymentDueTime.End),t<1)return Number.NaN;if(m===exports.PaymentDueTime.Begin&&1===t)return 0;var p=i(e,t,n(e,r,o,u,m),o,m)*e;return m===exports.PaymentDueTime.Begin&&t>1&&(p/=1+e),p}function i(e,n,r,i,o){return t(e,n-1,r,i,o)}Object.defineProperty(exports,"__esModule",{value:!0}),(e=exports.PaymentDueTime||(exports.PaymentDueTime={})).Begin="begin",e.End="end",exports.fv=t,exports.ipmt=r,exports.nper=function(e,t,n,r,i){if(void 0===r&&(r=0),void 0===i&&(i=exports.PaymentDueTime.End),0===e)return-(r+n)/t;var o=t*(1+e*(i===exports.PaymentDueTime.Begin?1:0))/e;return Math.log((-r+o)/(n+o))/Math.log(1+e)},exports.pmt=n,exports.ppmt=function(e,t,i,o,u,m){return void 0===u&&(u=0),void 0===m&&(m=exports.PaymentDueTime.End),n(e,i,o,u,m)-r(e,t,i,o,u,m)},exports.pv=function(e,t,n,r,i){void 0===r&&(r=0),void 0===i&&(i=exports.PaymentDueTime.End);var o=i===exports.PaymentDueTime.Begin?1:0,u=0===e,m=Math.pow(1+e,t);return-(r+n*(u?t:(1+e*o)*(m-1)/e))/m};
+"use strict";var e;function t(e,t,n,r,o){if(void 0===o&&(o=exports.PaymentDueTime.End),0===e)return-(r+n*t);var i=Math.pow(1+e,t);return-r*i-n*(1+e*(o===exports.PaymentDueTime.Begin?1:0))/e*(i-1)}function n(e,t,n,r,o){void 0===r&&(r=0),void 0===o&&(o=exports.PaymentDueTime.End);var i=0===e,u=Math.pow(1+e,t),a=o===exports.PaymentDueTime.Begin?1:0,m=i?1:e;return-(r+n*u)/(i?t:(1+m*a)*(u-1)/m)}function r(e,t,r,i,u,a){if(void 0===u&&(u=0),void 0===a&&(a=exports.PaymentDueTime.End),t<1)return Number.NaN;if(a===exports.PaymentDueTime.Begin&&1===t)return 0;var m=o(e,t,n(e,r,i,u,a),i,a)*e;return a===exports.PaymentDueTime.Begin&&t>1&&(m/=1+e),m}function o(e,n,r,o,i){return t(e,n-1,r,o,i)}function i(e,t,n,r,o,i){var u=i===exports.PaymentDueTime.Begin?1:0,a=Math.pow(e+1,t),m=Math.pow(e+1,t-1);return(o+a*r+n*(a-1)*(e*u+1)/e)/(t*m*r-n*(a-1)*(e*u+1)/Math.pow(e,2)+t*n*m*(e*u+1)/e+n*(a-1)*u/e)}Object.defineProperty(exports,"__esModule",{value:!0}),(e=exports.PaymentDueTime||(exports.PaymentDueTime={})).Begin="begin",e.End="end",exports.fv=t,exports.ipmt=r,exports.nper=function(e,t,n,r,o){if(void 0===r&&(r=0),void 0===o&&(o=exports.PaymentDueTime.End),0===e)return-(r+n)/t;var i=t*(1+e*(o===exports.PaymentDueTime.Begin?1:0))/e;return Math.log((-r+i)/(n+i))/Math.log(1+e)},exports.pmt=n,exports.ppmt=function(e,t,o,i,u,a){return void 0===u&&(u=0),void 0===a&&(a=exports.PaymentDueTime.End),n(e,o,i,u,a)-r(e,t,o,i,u,a)},exports.pv=function(e,t,n,r,o){void 0===r&&(r=0),void 0===o&&(o=exports.PaymentDueTime.End);var i=o===exports.PaymentDueTime.Begin?1:0,u=0===e,a=Math.pow(1+e,t);return-(r+n*(u?t:(1+e*i)*(a-1)/e))/a},exports.rate=function(e,t,n,r,o,u,a,m){void 0===o&&(o=exports.PaymentDueTime.End),void 0===u&&(u=.1),void 0===a&&(a=1e-6),void 0===m&&(m=100);for(var p=u,s=0,v=!1;s<m&&!v;){var d=p-i(p,e,t,n,r,o);v=Math.abs(d-p)<a,s++,p=d}return v?p:Number.NaN};
 //# sourceMappingURL=financial.cjs.production.min.js.map

dist/financial.d.ts

@@ -5,5 +5,5 @@ /**
 export declare enum PaymentDueTime {
-    /** Payments due at the beginning of a period */
+    /** Payments due at the beginning of a period (1) */
     Begin = "begin",
-    /** Payments are due at the end of a period */
+    /** Payments are due at the end of a period (0) */
     End = "end"
@@ -264,1 +264,46 @@ }
 export declare function pv(rate: number, nper: number, pmt: number, fv?: number, when?: PaymentDueTime): number;
+/**
+ * Compute the rate of interest per period
+ *
+ * @param nper - Number of compounding periods
+ * @param pmt - Payment
+ * @param pv - Present value
+ * @param fv - Future value
+ * @param when - When payments are due ('begin' or 'end')
+ * @param guess - Starting guess for solving the rate of interest
+ * @param tol - Required tolerance for the solution
+ * @param maxIter - Maximum iterations in finding the solution
+ *
+ * @returns the rate of interest per period (or `NaN` if it could
+ *  not be computed within the number of iterations provided)
+ *
+ * ## Notes
+ *
+ * Use Newton's iteration until the change is less than 1e-6
+ * for all values or a maximum of 100 iterations is reached.
+ * Newton's rule is:
+ *
+ * ```
+ * r_{n+1} = r_{n} - g(r_n)/g'(r_n)
+ * ```
+ *
+ * where:
+ *
+ * - `g(r)` is the formula
+ * - `g'(r)` is the derivative with respect to r.
+ *
+ *
+ * The rate of interest is computed by iteratively solving the
+ * (non-linear) equation:
+ *
+ * ```
+ * fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper - 1) = 0
+ * ```
+ *
+ * for `rate.
+ *
+ * ## References
+ *
+ * [Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May)](http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt).
+ */
+export declare function rate(nper: number, pmt: number, pv: number, fv: number, when?: PaymentDueTime, guess?: number, tol?: number, maxIter?: number): number;

dist/financial.esm.js

@@ -7,5 +7,5 @@ /**
 (function (PaymentDueTime) {
-  /** Payments due at the beginning of a period */
+  /** Payments due at the beginning of a period (1) */
   PaymentDueTime["Begin"] = "begin";
-  /** Payments are due at the end of a period */
+  /** Payments are due at the end of a period (0) */
 
@@ -376,2 +376,85 @@ PaymentDueTime["End"] = "end"; // 0
 /**
+ * Compute the rate of interest per period
+ *
+ * @param nper - Number of compounding periods
+ * @param pmt - Payment
+ * @param pv - Present value
+ * @param fv - Future value
+ * @param when - When payments are due ('begin' or 'end')
+ * @param guess - Starting guess for solving the rate of interest
+ * @param tol - Required tolerance for the solution
+ * @param maxIter - Maximum iterations in finding the solution
+ *
+ * @returns the rate of interest per period (or `NaN` if it could
+ *  not be computed within the number of iterations provided)
+ *
+ * ## Notes
+ *
+ * Use Newton's iteration until the change is less than 1e-6
+ * for all values or a maximum of 100 iterations is reached.
+ * Newton's rule is:
+ *
+ * ```
+ * r_{n+1} = r_{n} - g(r_n)/g'(r_n)
+ * ```
+ *
+ * where:
+ *
+ * - `g(r)` is the formula
+ * - `g'(r)` is the derivative with respect to r.
+ *
+ *
+ * The rate of interest is computed by iteratively solving the
+ * (non-linear) equation:
+ *
+ * ```
+ * fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper - 1) = 0
+ * ```
+ *
+ * for `rate.
+ *
+ * ## References
+ *
+ * [Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May)](http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt).
+ */
+
+function rate(nper, pmt, pv, fv, when, guess, tol, maxIter) {
+  if (when === void 0) {
+    when = PaymentDueTime.End;
+  }
+
+  if (guess === void 0) {
+    guess = 0.1;
+  }
+
+  if (tol === void 0) {
+    tol = 1e-6;
+  }
+
+  if (maxIter === void 0) {
+    maxIter = 100;
+  }
+
+  var rn = guess;
+  var iterator = 0;
+  var close = false;
+
+  while (iterator < maxIter && !close) {
+    var rnp1 = rn - _gDivGp(rn, nper, pmt, pv, fv, when);
+
+    var diff = Math.abs(rnp1 - rn);
+    close = diff < tol;
+    iterator++;
+    rn = rnp1;
+  } // if exausted all the iterations and the result is not
+  // close enough, returns `NaN`
+
+
+  if (!close) {
+    return Number.NaN;
+  }
+
+  return rn;
+}
+/**
  * This function is here to simply have a different name for the 'fv'
@@ -388,4 +471,23 @@ * function to not interfere with the 'fv' keyword argument within the 'ipmt'
 }
+/**
+ * Evaluates `g(r_n)/g'(r_n)`, where:
+ *
+ * ```
+ * g = fv + pv * (1+rate) ** nper + pmt * (1+rate * when)/rate * ((1+rate) ** nper - 1)
+ * ```
+ *
+ * @private
+ */
 
-export { PaymentDueTime, fv, ipmt, nper, pmt, ppmt, pv };
+
+function _gDivGp(r, n, p, x, y, when) {
+  var w = when === PaymentDueTime.Begin ? 1 : 0;
+  var t1 = Math.pow(r + 1, n);
+  var t2 = Math.pow(r + 1, n - 1);
+  var g = y + t1 * x + p * (t1 - 1) * (r * w + 1) / r;
+  var gp = n * t2 * x - p * (t1 - 1) * (r * w + 1) / Math.pow(r, 2) + n * p * t2 * (r * w + 1) / r + p * (t1 - 1) * w / r;
+  return g / gp;
+}
+
+export { PaymentDueTime, fv, ipmt, nper, pmt, ppmt, pv, rate };
 //# sourceMappingURL=financial.esm.js.map

package.json

@@ -5,3 +5,3 @@ {
   "author": "Luciano Mammino <[e-mail]> (https://loige.co)",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "repository": {
@@ -8,0 +8,0 @@ "type": "git",

README.md

@@ -90,3 +90,3 @@ # Financial
  - [X] `pv`
- - [ ] `rate`
+ - [X] `rate`
  - [ ] `irr`
@@ -93,0 +93,0 @@ - [ ] `npv`

src/financial.ts

@@ -5,5 +5,5 @@ /**
 export enum PaymentDueTime {
-  /** Payments due at the beginning of a period */
+  /** Payments due at the beginning of a period (1) */
   Begin = 'begin', // 1
-  /** Payments are due at the end of a period */
+  /** Payments are due at the end of a period (0) */
   End = 'end' // 0
@@ -334,2 +334,68 @@ }
 /**
+ * Compute the rate of interest per period
+ *
+ * @param nper - Number of compounding periods
+ * @param pmt - Payment
+ * @param pv - Present value
+ * @param fv - Future value
+ * @param when - When payments are due ('begin' or 'end')
+ * @param guess - Starting guess for solving the rate of interest
+ * @param tol - Required tolerance for the solution
+ * @param maxIter - Maximum iterations in finding the solution
+ *
+ * @returns the rate of interest per period (or `NaN` if it could
+ *  not be computed within the number of iterations provided)
+ *
+ * ## Notes
+ *
+ * Use Newton's iteration until the change is less than 1e-6
+ * for all values or a maximum of 100 iterations is reached.
+ * Newton's rule is:
+ *
+ * ```
+ * r_{n+1} = r_{n} - g(r_n)/g'(r_n)
+ * ```
+ *
+ * where:
+ *
+ * - `g(r)` is the formula
+ * - `g'(r)` is the derivative with respect to r.
+ *
+ *
+ * The rate of interest is computed by iteratively solving the
+ * (non-linear) equation:
+ *
+ * ```
+ * fv + pv * (1+rate) ** nper + pmt * (1+rate * when) / rate * ((1+rate) ** nper - 1) = 0
+ * ```
+ *
+ * for `rate.
+ *
+ * ## References
+ *
+ * [Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May)](http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt).
+ */
+export function rate (nper: number, pmt: number, pv: number, fv: number, when = PaymentDueTime.End, guess = 0.1, tol = 1e-6, maxIter = 100) : number {
+  let rn = guess
+  let iterator = 0
+  let close = false
+
+  while (iterator < maxIter && !close) {
+    const rnp1 = rn - _gDivGp(rn, nper, pmt, pv, fv, when)
+    const diff = Math.abs(rnp1 - rn)
+    close = diff < tol
+    iterator++
+    rn = rnp1
+  }
+
+  // if exausted all the iterations and the result is not
+  // close enough, returns `NaN`
+  if (!close) {
+    return Number.NaN
+  }
+
+  return rn
+}
+
+/**
  * This function is here to simply have a different name for the 'fv'
@@ -345,1 +411,23 @@ * function to not interfere with the 'fv' keyword argument within the 'ipmt'
 }
+
+/**
+ * Evaluates `g(r_n)/g'(r_n)`, where:
+ *
+ * ```
+ * g = fv + pv * (1+rate) ** nper + pmt * (1+rate * when)/rate * ((1+rate) ** nper - 1)
+ * ```
+ *
+ * @private
+ */
+function _gDivGp (r: number, n: number, p: number, x: number, y: number, when: PaymentDueTime): number {
+  const w = when === PaymentDueTime.Begin ? 1 : 0
+
+  const t1 = (r + 1) ** n
+  const t2 = (r + 1) ** (n - 1)
+  const g = y + t1 * x + p * (t1 - 1) * (r * w + 1) / r
+  const gp = (n * t2 * x -
+    p * (t1 - 1) * (r * w + 1) / (r ** 2) +
+    n * p * t2 * (r * w + 1) / r +
+    p * (t1 - 1) * w / r)
+  return g / gp
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

111026

increased by23.27%

Lines of code

1634

increased by23.41%

No dependency changes