@travishorn/financejs 1.0.0 → 1.10.0

package/src/ipmt.js

@@ -1,19 +1,40 @@
-import { fv } from "./fv.js";
+import { fv as calculateFv } from "./fv.js";
 import { pmt } from "./pmt.js";
 
 /**
- * Calculates the interest portion of a payment for a specific period.
+ * Returns the interest payment for a given period for an investment based on
+ * periodic, constant payments and a constant interest rate.
+ *
+ * Remarks:
+ * - Make sure that you are consistent about the units you use for specifying
+ *   `rate` and `nper`. If you make monthly payments on a four-year loan at 12
+ *   percent annual interest, use `.12/12` for `rate` and `4*12` for `nper`. If
+ *   you make annual payments on the same loan, use `.12` for `rate` and `4` for
+ *   `nper`.
+ * - For all the arguments, cash you pay out, such as deposits to savings, is
+ *   represented by negative numbers. Cash you receive, such as dividend checks,
+ *   is represented by positive numbers.
  *
  * @param {number} rate - The interest rate per period.
- * @param {number} per - The target period (1-based).
- * @param {number} nper - The total number of payment periods.
- * @param {number} pv - The present value.
- * @param {number} [futureValue=0] - The future value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning of period.
+ * @param {number} per - The period for which you want to find the interest and
+ * must be in the range `1` to `nper`.
+ * @param {number} nper - The total number of payment periods in an annuity.
+ * @param {number} pv - The present value, or the lump-sum amount that a series
+ * of future payments is worth right now.
+ * @param {number} [fv=0] - The future value, or a cash balance you
+ * want to attain after the last payment is made. If `fv` is omitted, it is
+ * assumed to be `0` (the future value of a loan, for example, is `0`).
+ * @param {0|1} [type=0] - The number `0` or `1` and indicates when payments are
+ * due. If type is omitted, it is assumed to be `0`. Set `type` equal to `0` if
+ * payments are due at the end of the period. Set `type` equal to `1` if
+ * payments are due at the beginning of the period.
  * @returns {number} The interest payment for the specified period.
  * @throws {RangeError} When `per` is outside the valid range.
+ *
+ * @example
+ * ipmt(0.1 / 12, 1, 3, 8000); // -66.67
  */
-export function ipmt(rate, per, nper, pv, futureValue = 0, type = 0) {
+export function ipmt(rate, per, nper, pv, fv = 0, type = 0) {
   if (per <= 0 || per >= nper + 1) {
     throw new RangeError("Invalid period.");
   }
@@ -23,9 +44,9 @@ export function ipmt(rate, per, nper, pv, futureValue = 0, type = 0) {
   }
 
   const periodOffset = type !== 0 ? 2 : 1;
-  const periodicPayment = pmt(rate, nper, pv, futureValue, type);
+  const periodicPayment = pmt(rate, nper, pv, fv, type);
   const adjustedPresentValue = type !== 0 ? pv + periodicPayment : pv;
-  const periodFutureValue = fv(
+  const periodFutureValue = calculateFv(
     rate,
     per - periodOffset,
     periodicPayment,

package/src/irr.js

@@ -1,9 +1,21 @@
 /**
- * Evaluates present value for an IRR iteration guess.
+ * Computes the net present value (NPV) of a series of cash flows at a given
+ * discount rate.
  *
- * @param {number[]} values - Cash flow values.
- * @param {number} [guess=0.1] - Rate guess.
- * @returns {number} Present value at the supplied guess.
+ * Used internally by the IRR algorithm to evaluate the present value of cash
+ * flows for a specific rate guess. Skips leading zero cash flows for
+ * efficiency. Cash flows are discounted in reverse order, from last to first
+ * nonzero value.
+ *
+ * @param {number[]} values - Array of cash flows, where each entry represents a
+ * payment (negative) or income (positive) at a regular interval.
+ * @param {number} [guess=0.1] - Discount rate guess (as a decimal, e.g., 0.1
+ * for 10%).
+ * @returns {number} The net present value of the cash flows at the supplied
+ * discount rate.
+ *
+ * @example
+ * internalPv([-1000, 300, 400, 500], 0.1); // -21.036814425244188
  */
 function internalPv(values, guess = 0.1) {
   let lowerBound = 0;
@@ -24,12 +36,37 @@ function internalPv(values, guess = 0.1) {
 }
 
 /**
- * Calculates the internal rate of return for a series of cash flows.
+ * Calculates the internal rate of return for a series of cash flows represented
+ * by the numbers in `values`. These cash flows do not have to be even, as they
+ * would be for an annuity. However, the cash flows must occur at regular
+ * intervals, such as monthly or annually. The internal rate of return is the
+ * interest rate received for an investment consisting of payments (negative
+ * values) and income (positive values) that occur at regular periods.
+ *
+ * Remarks:
+ * - Uses an iterative technique for calculating IRR. Starting with guess, this
+ *   function cycles through the calculation until the result is accurate within
+ *   a small absolute threshold. If this function can't find a result that works
+ *   after 39 tries, a RangeError is thrown.
+ * - `irr()` is closely related to `npv()`, the net present value function. The
+ *   rate of return calculated by this function is the interest rate
+ *   corresponding to a 0 (zero) net present value.
  *
- * @param {number[]} values - Cash flow values where negatives are investments and positives are returns.
- * @param {number} [guess=0.1] - Initial guess for the IRR iteration.
+ * @param {number[]} values - An array that contains numbers for which you want
+ * to calculate the internal rate of return. Values must contain at least one
+ * positive value and one negative value to calculate the internal rate of
+ * return. This function uses the order of values to interpret the order of cash
+ * flows. Be sure to enter your payment and income values in the sequence you
+ * want.
+ * @param {number} [guess=0.1] - A number that you guess is close to the result
+ * of this function. In most cases you do not need to provide guess for this
+ * calculation. If a RangeError is thrown, or if the result is not close to what
+ * you expected, try again with a different value for `guess`.
  * @returns {number} The internal rate of return.
- * @throws {RangeError} When inputs are invalid or the algorithm cannot converge.
+ * @throws {RangeError} When inputs are invalid or the algorithm cannot
+ * converge.
+ * @example
+ * irr([-70000,12000,15000,18000,21000]); // -0.021244848272975403
  */
 export function irr(values, guess = 0.1) {
   if (guess <= -1) {

package/src/mirr.js

@@ -0,0 +1,59 @@
+/**
+ * Calculates the modified internal rate of return for a series of periodic cash
+ * flows. Considers both the cost of the investment and the interest received on
+ * reinvestment of cash.
+ *
+ * Remarks:
+ * - Uses the order of values to interpret the order of cash flows. Be sure to
+ *   enter your payment and income values in the sequence you want and with the
+ *   correct signs (positive values for cash received, negative values for cash
+ *   paid).
+ * - If `n` is the number of cash flows in values, `frate` is the `financeRate`,
+ *   and `rrate` is the `reinvestRate`, then the equation is: `((-NPV(rrate,
+ *   values[positive]) * (1 + rrate)) / (NPV(frate, values[negative]) * (1 +
+ *   frate)))^(1 / (n - 1)) - 1`
+ *
+ * @param {number[]} values - An array that contains numbers. These numbers
+ * represent a series of payments (negative values) and income (positive values)
+ * occurring at regular periods. Values must contain at least one positive value
+ * and one negative value to calculate the modified internal rate of return.
+ * Otherwise, an error is thrown (divide by zero).
+ * @param {number} [financeRate] - The interest rate you pay on the money used in the cash flows.
+ * @param {number} [reinvestRate] - The interest rate you receive on the cash flows as you reinvest them.
+ * @returns {number} the modified internal rate of return
+ * @throws {RangeError} If `values` is not an array of at least two elements, or if there are not both positive and negative cash flows.
+ * @throws {TypeError} If `financeRate` or `reinvestRate` is not a number.
+ *
+ * @example
+ * mirr([-120000, 39000, 30000, 21000, 37000, 46000], 0.1, 0.12); // 0.12609413
+ */
+export function mirr(values, financeRate, reinvestRate) {
+  if (!Array.isArray(values) || values.length < 2) {
+    throw new RangeError("values must be an array with at least two elements");
+  }
+
+  if (typeof financeRate !== "number" || typeof reinvestRate !== "number") {
+    throw new TypeError("financeRate and reinvestRate must be numbers");
+  }
+
+  const n = values.length;
+  let fvPos = 0;
+  let pvNeg = 0;
+
+  for (let i = 0; i < n; i++) {
+    const v = values[i];
+    if (v > 0) {
+      fvPos += v * Math.pow(1 + reinvestRate, n - 1 - i);
+    } else if (v < 0) {
+      pvNeg += v * Math.pow(1 + financeRate, i);
+    }
+  }
+
+  if (fvPos === 0 || pvNeg === 0) {
+    throw new RangeError(
+      "At least one negative and one positive cash flow required",
+    );
+  }
+
+  return Math.pow(fvPos / -pvNeg, 1 / (n - 1)) - 1;
+}

package/src/nominal.js

@@ -0,0 +1,36 @@
+/**
+ * Calculates the nominal annual interest rate, given the effective rate and the
+ * number of compounding periods per year.
+ *
+ * Remarks:
+ * - `npery` is truncated to an integer.
+ * - If either argument is nonnumeric, an error is thrown.
+ * - If `effectRate` <= `0` or if `npery` < `1`, an error is thrown.
+ * - `nominal()` is related to `effect()` through `effectiveRate = (1 +
+ *   (nominalRate / npery)) * npery - 1`.
+ *
+ * @param {number} effectRate - The effective interest rate.
+ * @param {number} npery - The number of compounding periods per year.
+ * @returns {number} the nominal annual interest rate
+ *
+ * @example
+ * nominal(0.053543, 4); // 0.05250032
+ */
+export function nominal(effectRate, npery) {
+  if (
+    typeof effectRate !== "number" ||
+    typeof npery !== "number" ||
+    isNaN(effectRate) ||
+    isNaN(npery)
+  ) {
+    throw new TypeError("Both arguments must be numbers");
+  }
+  if (effectRate <= 0) {
+    throw new RangeError("effectRate must be > 0");
+  }
+  npery = Math.trunc(npery);
+  if (npery < 1) {
+    throw new RangeError("npery must be >= 1");
+  }
+  return npery * (Math.pow(1 + effectRate, 1 / npery) - 1);
+}

package/src/normalizeZero.js

@@ -0,0 +1,22 @@
+/**
+ * Normalizes zero values to ensure consistent handling of positive and negative
+ * zero in calculations.
+ *
+ * In JavaScript, +0 and -0 are distinct values that can yield different results
+ * in equality checks (e.g., Object.is(+0, -0) is false), sign checks
+ * (Math.sign), and division (1/0 vs 1/-0). This function coerces any zero input
+ * (either +0 or -0) to positive zero (+0), providing a consistent
+ * representation for downstream calculations, comparisons, and serialization.
+ *
+ * @param {number} value - The numeric value to normalize. If the value is +0 or
+ * -0, returns +0; otherwise, returns the original value.
+ * @returns {number} The normalized value, with all zeroes represented as +0.
+ *
+ * @example
+ * normalizeZero(-0); // 0
+ * normalizeZero(+0); // 0
+ * normalizeZero(5);  // 5
+ */
+export function normalizeZero(value) {
+  return value === 0 ? 0 : value;
+}

package/src/nper.js

@@ -1,13 +1,27 @@
+import { normalizeZero } from "./normalizeZero.js";
+
 /**
- * Calculates the number of periods for an investment/loan.
+ * Calculates the number of periods for an investment based on periodic,
+ * constant payments and a constant interest rate.
  *
- * @param {number} rate - Interest rate per period.
- * @param {number} pmt - Payment made each period.
- * @param {number} pv - Present value.
- * @param {number} [fv=0] - Future value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning.
+ * @param {number} rate - The interest rate per period.
+ * @param {number} pmt - The payment made each period; it cannot change over the
+ * life of the annuity. Typically, `pmt` contains principal and interest but no
+ * other fees or taxes.
+ * @param {number} pv - The present value, or the lump-sum amount that a series
+ * of future payments is worth right now.
+ * @param {number} [fv=0] - The future value, or a cash balance you want to
+ * attain after the last payment is made. If `fv` is omitted, it is assumed to
+ * be `0` (the future value of a loan, for example, is 0).
+ * @param {0|1} [type=0] - The number 0 or 1 and indicates when payments are
+ * due. Set `type` equal to `0` or omitted if payments are due at the end of the
+ * period. Set `type` equal to `1` if payments are due at the beginning of the
+ * period.
  * @returns {number} Number of periods.
  * @throws {RangeError} When calculation is impossible with the provided inputs.
+ *
+ * @example
+ * nper(0.12 / 12, -100, -1000, 10000, 1); // 59.67386567
  */
 export function nper(rate, pmt, pv, fv = 0, type = 0) {
   if (rate === 0) {
@@ -15,7 +29,7 @@ export function nper(rate, pmt, pv, fv = 0, type = 0) {
       throw new RangeError("Payment cannot be 0 when rate is 0.");
     }
 
-    return -(pv + fv) / pmt;
+    return normalizeZero(-(pv + fv) / pmt);
   }
 
   const paymentAdjustment = type !== 0 ? pmt * (1 + rate) : pmt;
@@ -34,8 +48,8 @@ export function nper(rate, pmt, pv, fv = 0, type = 0) {
 
   const growthFactor = 1 + rate;
 
-  return (
+  return normalizeZero(
     (Math.log(futureValueTerm) - Math.log(presentValueTerm)) /
-    Math.log(growthFactor)
+      Math.log(growthFactor),
   );
 }

package/src/npv.js

@@ -1,11 +1,25 @@
 /**
- * Evaluates net present value across a bounded portion of a values array.
+ * Calculates the net present value (NPV) of a subset of cash flows at a
+ * specified discount rate.
  *
- * @param {number} rate - Discount rate per period.
- * @param {number[]} values - Cash flow values.
- * @param {number} [lowerBound=0] - Start index (inclusive).
- * @param {number} [upperBound=values.length - 1] - End index (inclusive).
- * @returns {number} The evaluated NPV for the specified range.
+ * Used internally by the `npv()` function to evaluate the present value of cash
+ * flows between given indices. Each cash flow is discounted to its present
+ * value using the supplied rate, starting from lowerBound to upperBound
+ * (inclusive).
+ *
+ * @param {number} rate - Discount rate per period (as a decimal, e.g., `0.1`
+ * for 10%).
+ * @param {number[]} values - Array of cash flows, where each entry represents a
+ * payment (negative) or income (positive) at a regular interval.
+ * @param {number} [lowerBound=0] - Start index (inclusive) for the range of
+ * values to evaluate.
+ * @param {number} [upperBound=values.length - 1] - End index (inclusive) for
+ * the range of values to evaluate.
+ * @returns {number} The net present value of the specified range of cash flows
+ * at the given discount rate.
+ *
+ * @example
+ * evalNpv(0.1, [-1000, 300, 400, 500], 0, 2); // -360.6311044327573
  */
 function evalNpv(rate, values, lowerBound = 0, upperBound = values.length - 1) {
   let discountFactor = 1;
@@ -21,12 +35,34 @@ function evalNpv(rate, values, lowerBound = 0, upperBound = values.length - 1) {
 }
 
 /**
- * Calculates the net present value of a series of cash flows.
+ * Calculates the net present value of an investment by using a discount rate
+ * and a series of future payments (negative values) and income (positive
+ * values).
  *
- * @param {number} rate - Discount rate per period.
- * @param {...number} values - Cash flow values.
+ * Remarks:
+ * - The NPV investment begins one period before the date of the first value in
+ *   the cash flow and ends with the last value in the cash flow. The NPV
+ *   calculation is based on future cash flows. If your first cash flow occurs
+ *   at the beginning of the first period, the first value must be added to the
+ *   NPV result, not included in the values arguments.
+ * - `npv()` is similar to the `pv()` function (present value). The primary
+ *   difference between `pv()` and `npv()` is that `pv()` allows cash flows to
+ *   begin either at the end or at the beginning of the period. Unlike the
+ *   variable NPV cash flow values, PV cash flows must be constant throughout
+ *   the investment.
+ * - `npv()` is also related to the `irr()` function (internal rate of return).
+ *   IRR is the rate for which NPV equals zero: `npv(irr(...), ...) = 0`.
+ *
+ * @param {number} rate - The rate of discount over the length of one period.
+ * @param {...number} values - At least one value is required. Values must be
+ * equally spaced in time and occur at the end of each period. This function
+ * uses the order of the values to interpret the order of cash flows. Be sure to
+ * enter your payment and income values in the correct sequence.
  * @returns {number} The net present value.
  * @throws {RangeError} When there are no cash flow values or rate is invalid.
+ *
+ * @example
+ * npv(0.1, -10000, 3000, 4200, 6800); // 1188.44
  */
 export function npv(rate, ...values) {
   if (values.length < 1) {

package/src/pmt.js

@@ -1,25 +1,46 @@
+import { normalizeZero } from "./normalizeZero.js";
+
 /**
- * Calculates the periodic payment for a loan or investment.
+ * Calculates the payment for a loan based on constant payments and a constant
+ * interest rate.
+ *
+ * Remarks:
+ * - The payment returned by this function includes principal and interest but
+ *   no taxes, reserve payments, or fees sometimes associated with loans.
+ * - Make sure that you are consistent about the units you use for specifying
+ *   `rate` and `nper`. If you make monthly payments on a four-year loan at an
+ *   annual interest rate of 12 percent, use `0.12 / 12` for `rate` and `4 * 12`
+ *   for `nper`. If you make annual payments on the same loan, use `0.12` for
+ *   `rate` and `4` for `nper`.
  *
- * @param {number} rate - The interest rate per period.
- * @param {number} nper - The total number of payment periods.
- * @param {number} pv - The present value.
- * @param {number} [fv=0] - The future value, or remaining balance after the last payment. Defaults to 0.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning of period. Defaults to 0.
+ * @param {number} rate - The interest rate for the loan.
+ * @param {number} nper - The total number of payments for the loan.
+ * @param {number} pv - The present value, or the total amount that a series of
+ * future payments is worth now; also known as the principal.
+ * @param {number} [fv=0] - The future value, or a cash balance you want to
+ * attain after the last payment is made. If `fv `is omitted, it is assumed to
+ * be `0 `(zero), that is, the future value of a loan is 0.
+ * @param {0|1} [type=0] - The number `0` (zero) or `1` and indicates when
+ * payments are due. Set `type` equal to `0` or omitted if payments are due at
+ * the end of the period. Set `type` equal to `1` if payments are due at the
+ * beginning of the period.
  * @returns {number} The periodic payment amount.
+ *
+ * @example
+ * pmt(0.08 / 12, 10, 10000); // -1037.03
  */
 export function pmt(rate, nper, pv, fv = 0, type = 0) {
   if (rate === 0) {
-    return (-fv - pv) / nper;
+    return normalizeZero((-fv - pv) / nper);
   } else {
     const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
     const interestFactor = 1 + rate;
     const compoundFactor = Math.pow(interestFactor, nper);
 
-    return (
+    return normalizeZero(
       ((-fv - pv * compoundFactor) /
         (paymentTimingFactor * (compoundFactor - 1))) *
-      rate
+        rate,
     );
   }
 }

package/src/ppmt.js

@@ -1,17 +1,36 @@
 import { ipmt } from "./ipmt.js";
+import { normalizeZero } from "./normalizeZero.js";
 import { pmt } from "./pmt.js";
 
 /**
- * Calculates the principal portion of a payment for a specific period.
+ * Calculates the payment on the principal for a given period for an investment
+ * based on periodic, constant payments and a constant interest rate.
+ *
+ * Remarks:
+ * - Make sure that you are consistent about the units you use for specifying
+ *   `rate` and `nper`. If you make monthly payments on a four-year loan at 12
+ *   percent annual interest, use `0.12 / 12` for `rate` and `4 * 12` for
+ *   `nper`. If you make annual payments on the same loan, use `0.12` for `rate`
+ *   and `4` for `nper`.
  *
  * @param {number} rate - The interest rate per period.
- * @param {number} per - The target period (1-based).
- * @param {number} nper - The total number of payment periods.
- * @param {number} pv - The present value.
- * @param {number} [futureValue=0] - The future value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning of period.
- * @returns {number} The principal payment for the specified period.
+ * @param {number} per - Specifies the period and must be in the range `1` to
+ * `nper`.
+ * @param {number} nper - The total number of payment periods in an annuity.
+ * @param {number} pv - The present value — the total amount that a series of
+ * future payments is worth now.
+ * @param {number} [futureValue=0] - The future value, or a cash balance you
+ * want to attain after the last payment is made. If `fv` is omitted, it is
+ * assumed to be `0` (zero), that is, the future value of a loan is 0.
+ * @param {0|1} [type=0] - The number `0` (zero) or `1` and indicates when
+ * payments are due. Set `type` equal to `0` or omitted if payments are due at
+ * the end of the period. Set `type` equal to `1` if payments are due at the
+ * beginning of the period.
+ * @returns {number} The payment on the principal for the specified period.
  * @throws {RangeError} When `per` is outside the valid range.
+ *
+ * @example
+ * ppmt(0.1 / 12, 1, 2 * 12, 2000); // -75.62
  */
 export function ppmt(rate, per, nper, pv, futureValue = 0, type = 0) {
   if (per <= 0 || per >= nper + 1) {
@@ -21,5 +40,5 @@ export function ppmt(rate, per, nper, pv, futureValue = 0, type = 0) {
   const periodicPayment = pmt(rate, nper, pv, futureValue, type);
   const interestPayment = ipmt(rate, per, nper, pv, futureValue, type);
 
-  return periodicPayment - interestPayment;
+  return normalizeZero(periodicPayment - interestPayment);
 }

package/src/pv.js

@@ -1,24 +1,61 @@
+import { normalizeZero } from "./normalizeZero.js";
+
 /**
- * Calculates the present value of an investment based on a series of regular payments and a constant interest rate.
+ * Calculates the present value of a loan or an investment, based on a constant
+ * interest rate. You can use PV with either periodic, constant payments (such
+ * as a mortgage or other loan), or a future value that's your investment goal.
+ *
+ * Remarks:
+ * - Make sure that you are consistent about the units you use for specifying
+ *   `rate` and `nper`. If you make monthly payments on a four-year loan at 12
+ *   percent annual interest, use 12%/12 for `rate` and 4*12 for `nper`. If you
+ *   make annual payments on the same loan, use 12% for `rate` and 4 for `nper`.
+ * - An annuity is a series of constant cash payments made over a continuous
+ *   period. For example, a car loan or a mortgage is an annuity.
+ * - In annuity functions, cash you pay out, such as a deposit to savings, is
+ *   represented by a negative number. Cash you receive, such as a dividend
+ *   check, is represented by a positive number. For example, a $1,000 deposit
+ *   to the bank would be represented by the argument -1000 if you are the
+ *   depositor and by the argument 1000 if you are the bank.
  *
- * @param {number} rate - The interest rate per period.
- * @param {number} nper - The total number of payment periods.
- * @param {number} pmt - The payment made each period; cannot change over the life of the annuity.
- * @param {number} fv - The future value, or a cash balance you want to attain after the last payment is made. Defaults to 0.
- * @param {0|1} [type=0] - The number 0 or 1 and indicates when payments are due. 0 = end of period, 1 = beginning of period. Defaults to 0.
+ * @param {number} rate - The interest rate per period. For example, if you
+ * obtain an automobile loan at a 10 percent annual interest rate and make
+ * monthly payments, your interest rate per month is 10%/12, or 0.83%. You would
+ * enter 10%/12, or 0.83%, or 0.0083, into the formula as the rate.
+ * @param {number} nper - The total number of payment periods in an annuity. For
+ * example, if you get a four-year car loan and make monthly payments, your loan
+ * has 4*12 (or 48) periods. You would enter 48 into the formula for nper.
+ * @param {number} [pmt=0] - The payment made each period and cannot change over
+ * the life of the annuity. Typically, pmt includes principal and interest but
+ * no other fees or taxes. For example, the monthly payments on a $10,000,
+ * four-year car loan at 12 percent are $263.33. You would enter -263.33 into
+ * the formula as the pmt. If pmt is omitted, you must include the fv argument.
+ * @param {number} [fv=0] - The future value or a cash balance you want to
+ * attain after the last payment is made. If fv is omitted, it is assumed to be
+ * 0 (the future value of a loan, for example, is 0). For example, if you want
+ * to save $50,000 to pay for a special project in 18 years, then $50,000 is the
+ * future value. You could then make a conservative guess at an interest rate
+ * and determine how much you must save each month. If fv is omitted, you must
+ * include the pmt argument.
+ * @param {0|1} [type=0] - The number 0 or 1 and indicates when payments are
+ * due. Set `type` equal to `0` or omitted if payments are due at the end of the
+ * period. Set `type` equal to `1` if payments are due at the end of the period.
  * @returns {number} The present value of the investment.
+ *
+ * @example
+ * pv(0.08 / 12, 20 * 12, 500); // -59777.15
  */
-export function pv(rate, nper, pmt, fv = 0, type = 0) {
+export function pv(rate, nper, pmt = 0, fv = 0, type = 0) {
   if (rate === 0) {
-    return -pmt * nper - fv;
+    return normalizeZero(-pmt * nper - fv);
   } else {
     const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
     const interestFactor = 1 + rate;
     const compoundFactor = Math.pow(interestFactor, nper);
 
-    return (
+    return normalizeZero(
       -(fv + pmt * paymentTimingFactor * ((compoundFactor - 1) / rate)) /
-      compoundFactor
+        compoundFactor,
     );
   }
 }

package/src/rate.js

@@ -1,13 +1,30 @@
+import { normalizeZero } from "./normalizeZero.js";
+
 /**
- * Evaluates the RATE equation for a candidate rate.
+ * Evaluates the annuity equation for a candidate interest rate.
+ *
+ * Used internally by the `rate()` function to compute the result of the annuity
+ * equation for a given rate guess. This function supports both ordinary
+ * annuities (payments at end of period) and annuities due (payments at
+ * beginning of period), and accounts for present value, future value, and
+ * periodic payments.
+ *
+ * @param {number} rate - Candidate interest rate per period (as a decimal,
+ * e.g., `0.1` for 10%).
+ * @param {number} nper - Total number of payment periods.
+ * @param {number} pmt - Payment made each period (negative for outflows,
+ * positive for inflows).
+ * @param {number} pv - Present value (the lump sum amount at the start).
+ * @param {number} [fv=0] - Future value (the desired balance after the last
+ * payment; defaults to `0`).
+ * @param {0|1} [type=0] - Payment timing: `0` = end of period (ordinary annuity),
+ * `1` = beginning of period (annuity due).
+ * @returns {number} The result of the annuity equation for the supplied rate
+ * and parameters. A value close to zero indicates a solution for the interest
+ * rate.
  *
- * @param {number} rate - Candidate rate.
- * @param {number} nper - Total number of periods.
- * @param {number} pmt - Periodic payment.
- * @param {number} pv - Present value.
- * @param {number} [fv=0] - Future value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning.
- * @returns {number} Equation result for the supplied rate.
+ * @example
+ * evalRate(0.05, 12, -100, 1000, 0, 0); // 204.1436739778701
  */
 function evalRate(rate, nper, pmt, pv, fv = 0, type = 0) {
   if (rate === 0) {
@@ -26,16 +43,43 @@ function evalRate(rate, nper, pmt, pv, fv = 0, type = 0) {
 }
 
 /**
- * Calculates the interest rate per period using iterative approximation.
+ * Calculates the interest rate per period of an annuity. The rate is calculated
+ * by iteration and can have zero or more solutions. If the successive results
+ * of this function do not converge to within 0.0000001 after 128 iterations, a
+ * RangeError is thrown.
+ *
+ * Remarks:
+ * - Make sure that you are consistent about the units you use for specifying
+ *   `rate` and `nper`. If you make monthly payments on a four-year loan at 12
+ *   percent annual interest, use `0.12 / 12` for `rate` and `4 * 12` for
+ *   `nper`. If you make annual payments on the same loan, use `0.12` for `rate`
+ *   and `4` for `nper`.
+ *
+ * @param {number} nper - The total number of payment periods in an annuity.
+ * @param {number} pmt - The payment made each period and cannot change over the
+ * life of the annuity. Typically, `pmt` includes principal and interest but no
+ * other fees or taxes. If `pmt` is omitted, you must include the `fv` argument
+ * for a meaningful equation.
+ * @param {number} pv - The present value — the total amount that a series of
+ * future payments is worth now.
+ * @param {number} [fv=0] - The future value, or a cash balance you want to
+ * attain after the last payment is made. If `fv` is omitted, it is assumed to
+ * be `0` (the future value of a loan, for example, is 0). If `fv` is omitted,
+ * you must include the `pmt` argument.
+ * @param {0|1} [type=0] - The number `0` (zero) or `1` and indicates when
+ * payments are due. Set `type` equal to `0` or omitted if payments are due at
+ * the end of the period. Set `type` equal to `1` if payments are due at the
+ * beginning of the period.
+ * @param {number} [guess=0.1] - Your guess for what the rate will be. If you
+ * omit `guess`, it is assumed to be `0.1` (10 percent). If the calculation does
+ * not converge, try different values for `guess`. The calculation usually
+ * converges if guess is between `0` and `1`.
+ * @returns {number} The calculated interest rate per period of an annuity.
+ * @throws {RangeError} When inputs are invalid or the algorithm cannot
+ * converge.
  *
- * @param {number} nper - Total number of periods.
- * @param {number} pmt - Periodic payment.
- * @param {number} pv - Present value.
- * @param {number} [fv=0] - Future value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning.
- * @param {number} [guess=0.1] - Initial guess for rate.
- * @returns {number} The calculated rate per period.
- * @throws {RangeError} When inputs are invalid or the algorithm cannot converge.
+ * @example
+ * rate(4 * 12, -200, 8000); // 0.007701472488210098
  */
 export function rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1) {
   if (nper <= 0) {
@@ -66,7 +110,7 @@ export function rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1) {
     y0 = evalRate(rate0, nper, pmt, pv, fv, type);
 
     if (Math.abs(y0) < epsilonMax) {
-      return rate0;
+      return normalizeZero(rate0);
     }
 
     const nextY = y0;