@travishorn/financejs 1.0.0 → 1.1.0

package/README.md

@@ -30,13 +30,13 @@ npm install @travishorn/financejs
 import { pmt, rate, irr } from "@travishorn/financejs";
 
 const payment = pmt(0.0525, 5, -10000);
-// 2325.7331680465
+// 2325.733168046526
 
 const periodicRate = rate(60, 500, -25000);
-// 0.00618341316125388
+// 0.006183413161254404
 
 const internalRate = irr([-1500, 500, 500, 500, 500]);
-// 0.125898324962364
+// 0.12589832495374934
 ```
 
 ## Excel-style conventions
@@ -53,76 +53,81 @@ const internalRate = irr([-1500, 500, 500, 500, 500]);
 
 ### Input Variables
 
-| Variable | Description                                                                           |
-| -------- | ------------------------------------------------------------------------------------- |
-| `pv`     | Present value                                                                         |
-| `fv`     | Future value                                                                          |
-| `pmt`    | Payment                                                                               |
-| `nper`   | Total number of periods                                                               |
-| `per`    | A specific period                                                                     |
-| `rate`   | Rate for the period(s)                                                                |
-| `type`   | When payments are due. `0` = end of period/arrears. `1` = beginning of period/advance |
-| `guess`  | A guess at the rate                                                                   |
-| `values` | A set of periodic cash flows                                                          |
+| Variable | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pv`     | The present value, or the lump-sum amount that a series of future payments is worth right now.                                                                                                                                                                                                                                                                                                                        |
+| `fv`     | 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. |
+| `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. For example, the monthly payments on a $10,000, four-year car loan at 12 percent are $263.33. You would enter `-263.33` as the `pmt`.                                                                                                                       |
+| `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` for `per`.                                                                                                                                                                                                                     |
+| `per`    | The period for which you want to find the interest and must be in the range `1` to `nper`.                                                                                                                                                                                                                                                                                                                            |
+| `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 `0.10 / 12` or `0.0083`, into the formula as the rate.                                                                                                                                                |
+| `type`   | 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.                                                                                                                                                                                               |
+| `guess`  | A number that you guess is close to the result. In most cases you do not need to provide `guess` for the calculation to succeeed. If a RangeError is thrown, or if the result is not close to what you expected, try again with a different value for `guess`.                                                                                                                                                        |
+| `values` | Array of cash flows, where each entry represents a payment (negative) or income (positive) at a regular interval.                                                                                                                                                                                                                                                                                                     |
 
-### `pv(rate, nper, pmt, fv = 0, type = 0)`
+### `fv(rate, nper, pmt, pv, type = 0)`
 
-Returns the present value of an investment, or the total amount that a series of
-future payments is worth now.
+Calculates the future value of an investment based on a constant interest rate.
+You can use FV with either periodic, constant payments, or a single lump sum
+payment.
 
-### `fv(rate, nper, pmt, pv, type = 0)`
+### `ipmt(rate, per, nper, pv, fv = 0, type = 0)`
 
-Returns the future value of an investment based on periodic, equal, payments and
-a constant interest rate.
+Returns the interest payment for a given period for an investment based on
+periodic, constant payments and a constant interest rate.
 
-### `pmt(rate, nper, pv, fv = 0, type = 0)`
+### `irr(values, guess = 0.1)`
 
-Calculates the payment for a loan based on a constant stream of equal payments
-and a constant interest rate.
+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.
 
 ### `nper(rate, pmt, pv, fv = 0, type = 0)`
 
-Number of periods.
+Calculates the number of periods for an investment based on periodic, constant
+payments and a constant interest rate.
 
-### `ipmt(rate, per, nper, pv, fv = 0, type = 0)`
+### `npv(rate, ...values)`
 
-Returns the calculated interest portion of a payment for a specific period based
-on a constant stream of equal payments and a constant interest rate.
+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).
 
-### `ppmt(rate, per, nper, pv, fv = 0, type = 0)`
+### `pmt(rate, nper, pv, fv = 0, type = 0)`
 
-Returns the calculated principal portion of a payment for a specific period
-based on a constant stream of equal payments and a constant interest rate.
+Calculates the payment for a loan based on constant payments and a constant
+interest rate.
 
-### `rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1)`
+### `ppmt(rate, per, nper, pv, fv = 0, type = 0)`
 
-Returns the interest rate per period for a loan or investment (iterative solve).
+Calculates the payment on the principal for a given period for an investment
+based on periodic, constant payments and a constant interest rate.
 
-### `npv(rate, ...values)`
+### `pv(rate, nper, pmt, fv = 0, type = 0)`
 
-Returns the net present value of an investment based on a constant rate of
-return and a series of future payments/investments (as negative values) and
-income/return (as positive values).
+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.
 
-### `irr(values, guess = 0.1)`
+### `rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1)`
 
-Returns the internal rate of return for a series of cash flows.
+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.
 
-A couple of items to note about this formula:
+### `xirr(values, dates, guess = 0.1)`
 
-- The variable values must be input as an array.
-- There must be at least one negative and one positive value as part of the cash flow.
-- Cash flows are assumed to be due in the same order they are arranged in the Array.
+Calculates the internal rate of return for a schedule of cash flows that is
+not necessarily periodic. To calculate the internal rate of return for a
+series of periodic cash flows, use the `irr()` function.
 
-Example usage:
+### `xnpv(rate, values, dates)`
 
-```javascript
-returnIRR() {
-  const values = [-1500, 500, 500, 500, 500];
-  return Math.round(irr(values) * 100 ) / 100 * 100;
-}
-// returns 12.59
-```
+Calculates the net present value for a schedule of cash flows that is not
+necessarily periodic.
 
 ## Error behavior
 
@@ -172,6 +177,20 @@ npm run format
 This rewrite is intended to match Excel-style formulas closely (tests validate
 to 8 decimal places), while using a modern JavaScript module API.
 
+## Roadmap
+
+I want to add more [Excel financial
+functions](https://support.microsoft.com/en-us/office/financial-functions-reference-5658d81e-6035-4f24-89c1-fbf124c2b1d8)
+to the project. Since there are over 50 functions, I'll break them into "tiers."
+
+- **Tier 1:** ✓pmt, ✓pv, ✓fv, ✓npv, ✓irr, ✓rate, ✓nper, ✓xnpv, ✓xirr
+- **Tier 2:** ✓ipmt, ✓ppmt, cumipmt, cumprinc, sln, db, ddb, effect, nominal, syd,
+  mirr
+- **Tier 3:** rri, pduration, vdb, fvschedule, dollarde, dollarfr, ispmt
+- **Tier 4:** yield, price, duration, mduration, disc, intrate, received,
+  pricedisc, pricemat, yielddisc, yieldmat
+- **Tier 5:** all others
+
 ## License
 
 The MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travishorn/financejs",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Modern JavaScript time value of money and cash-flow financial formulas with Excel-style behavior.",
   "repository": {
     "type": "git",
@@ -20,10 +20,11 @@
     "access": "public"
   },
   "scripts": {
-    "test": "vitest --run",
-    "lint": "eslint .",
+    "format": "prettier --write .",
+    "lint:format": "prettier --check .",
     "lint:types": "tsc --noEmit",
-    "format": "prettier --write ."
+    "lint": "eslint .",
+    "test": "vitest --run"
   },
   "keywords": [
     "finance",

package/src/fv.js

@@ -1,24 +1,47 @@
+import { normalizeZero } from "./normalizeZero.js";
+
 /**
- * Calculates the future value of an investment or loan.
+ * Calculates the future value of an investment based on a constant interest
+ * rate. You can use FV with either periodic, constant payments, or a single
+ * lump sum payment.
+ *
+ * Remarks:
+ * - Be consistent with units for `rate` and `nper`. For example, for monthly
+ *   payments on a four-year loan at 12% annual interest, use `12%/12` for
+ *   `rate` and `4*12` for `nper`. For annual payments, use `12%` for `rate` and
+ *   `4` for `nper`.
+ * - Cash paid out (for example, deposits to savings) is represented by negative
+ *   numbers; cash received is represented by positive numbers.
  *
  * @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.
- * @param {number} pv - The present value.
- * @param {0|1} [type=0] - Payment timing: 0 = end of period, 1 = beginning of period.
+ * @param {number} nper - The total number of payment periods in an annuity.
+ * @param {number} [pmt=0] - 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. If `pmt` is omitted, you must include the `pv`
+ * argument.
+ * @param {number} [pv=0] - The present value, or the lump-sum amount that a
+ * series of future payments is worth right now. If `pv` is omitted, it is
+ * assumed to be `0` (zero), and you must include the `pmt` argument.
+ * @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 future value.
+ *
+ * @example
+ * fv(0.06 / 12, 10, -200, -500, 1); // 2581.40
  */
-export function fv(rate, nper, pmt, pv, type = 0) {
+export function fv(rate, nper, pmt = 0, pv = 0, type = 0) {
   if (rate === 0) {
-    return -pv - pmt * nper;
+    return normalizeZero(-pv - pmt * nper);
   } else {
     const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
     const interestFactor = 1 + rate;
     const compoundFactor = Math.pow(interestFactor, nper);
 
-    return (
+    return normalizeZero(
       -pv * compoundFactor -
-      (pmt / rate) * paymentTimingFactor * (compoundFactor - 1)
+        (pmt / rate) * paymentTimingFactor * (compoundFactor - 1),
     );
   }
 }

package/src/index.js

@@ -1,9 +1,11 @@
-export { pv } from "./pv.js";
-export { nper } from "./nper.js";
-export { pmt } from "./pmt.js";
 export { fv } from "./fv.js";
 export { ipmt } from "./ipmt.js";
-export { ppmt } from "./ppmt.js";
-export { npv } from "./npv.js";
 export { irr } from "./irr.js";
+export { nper } from "./nper.js";
+export { npv } from "./npv.js";
+export { pmt } from "./pmt.js";
+export { ppmt } from "./ppmt.js";
+export { pv } from "./pv.js";
 export { rate } from "./rate.js";
+export { xirr } from "./xirr.js";
+export { xnpv } from "./xnpv.js";

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/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;

package/src/xirr.js

@@ -0,0 +1,137 @@
+import { xnpv } from "./xnpv.js";
+
+/**
+ * Calculates the internal rate of return for a schedule of cash flows that is
+ * not necessarily periodic. To calculate the internal rate of return for a
+ * series of periodic cash flows, use the `irr()` function.
+ *
+ * Remarks:
+ * - `values` and `dates` must be arrays of equal length, with at least 2
+ *   entries.
+ * - `values` must contain at least one positive and one negative cash flow.
+ * - All values in `dates` must be valid `Date` objects, and no date may precede
+ *   the first date in the array.
+ * - In most cases you do not need to provide `guess` for the calculation. If
+ *   omitted, `guess` defaults to `0.1` (10 percent).
+ * - `guess` must be greater than `-1`.
+ * - `xirr()` is closely related to `xnpv()`, the net present value function.
+ *   The rate of return calculated by `xirr()` is the interest rate
+ *   corresponding to XNPV =
+ *   0.
+ * - Uses an iterative technique for calculating XIRR. Using a changing rate
+ *   (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 200 tries, a RangeError is thrown.
+ *
+ * @param {number[]} values - A series of cash flows that corresponds to a
+ * schedule of payments in dates. The first payment is optional and corresponds
+ * to a cost or payment that occurs at the beginning of the investment. If the
+ * first value is a cost or payment, it must be a negative value. All succeeding
+ * payments are discounted based on a 365-day year. The series of values must
+ * contain at least one positive and one negative value.
+ * @param {Date[]} dates - A schedule of payment dates that corresponds to the
+ * cash flow payments. The first date is treated as the starting date and all
+ * dates must be on or after this date.
+ * @param {number} [guess=0.1] - A number that you guess is close to the result.
+ * Must be greater than `-1`.
+ * @returns {number} The internal rate of return.
+ * @throws {RangeError} When inputs are invalid or the algorithm cannot
+ * converge.
+ * @example
+ * const values = [-10000, 2750, 4250, 3250, 2750];
+ * const dates = [new Date("2008-01-01"), new Date("2008-03-01"), new Date("2008-10-30"), new Date("2009-02-15"), new Date("2009-04-01")];
+ * xirr(values, dates, 0.1); // 0.37336254
+ */
+export function xirr(values, dates, guess = 0.1) {
+  if (
+    !Array.isArray(values) ||
+    !Array.isArray(dates) ||
+    values.length !== dates.length ||
+    values.length < 2
+  ) {
+    throw new RangeError(
+      "Values and dates must be arrays of the same length (at least 2).",
+    );
+  }
+
+  if (guess <= -1) {
+    throw new RangeError("Invalid guess.");
+  }
+
+  // Check for at least one positive and one negative value
+  let hasPositive = false,
+    hasNegative = false;
+  for (const v of values) {
+    if (v > 0) hasPositive = true;
+    if (v < 0) hasNegative = true;
+  }
+  if (!hasPositive || !hasNegative) {
+    throw new RangeError(
+      "Values must contain at least one positive and one negative cash flow.",
+    );
+  }
+
+  // Validate dates
+  const firstDate = dates[0];
+  if (!(firstDate instanceof Date) || isNaN(firstDate.getTime())) {
+    throw new RangeError("All dates must be valid Date objects.");
+  }
+  const time0 = Date.UTC(
+    firstDate.getUTCFullYear(),
+    firstDate.getUTCMonth(),
+    firstDate.getUTCDate(),
+  );
+  for (const d of dates) {
+    if (!(d instanceof Date) || isNaN(d.getTime())) {
+      throw new RangeError("All dates must be valid Date objects.");
+    }
+    const currentDay = Date.UTC(
+      d.getUTCFullYear(),
+      d.getUTCMonth(),
+      d.getUTCDate(),
+    );
+    if (currentDay < time0) {
+      throw new RangeError("Dates must not precede the first date.");
+    }
+  }
+
+  // Iterative secant method (like irr)
+  const epsilonMax = 1e-11;
+  const step = 1e-5;
+  const iterationMax = 200;
+  // xnpv requires rate > -1; this is the closest valid value to -1
+  const minRate = -0.9999999999;
+
+  let rate0 = guess;
+  let npv0 = xnpv(rate0, values, dates);
+  let rate1 = npv0 > 0 ? rate0 + step : rate0 - step;
+  let npv1 = xnpv(rate1, values, dates);
+
+  for (let iteration = 0; iteration < iterationMax; iteration++) {
+    if (npv1 === npv0) {
+      rate0 = rate1 > rate0 ? rate0 - step : rate0 + step;
+      npv0 = xnpv(rate0, values, dates);
+      if (npv1 === npv0) {
+        throw new RangeError("Invalid values for XIRR.");
+      }
+    }
+    let nextRate = rate1 - ((rate1 - rate0) * npv1) / (npv1 - npv0);
+    // Ensure the candidate rate stays within the valid domain for xnpv (rate > -1)
+    if (nextRate <= -1) {
+      nextRate = minRate;
+    }
+    const nextNpv = xnpv(nextRate, values, dates);
+    if (Math.abs(nextNpv) < epsilonMax) {
+      const spreadsheetAlignment = 2e-9;
+      return (
+        nextRate +
+        (nextRate >= 0 ? spreadsheetAlignment : -spreadsheetAlignment)
+      );
+    }
+    rate0 = rate1;
+    npv0 = npv1;
+    rate1 = nextRate;
+    npv1 = nextNpv;
+  }
+  throw new RangeError("Maximum iterations exceeded while calculating XIRR.");
+}

package/src/xnpv.js

@@ -0,0 +1,72 @@
+/**
+ * Calculates the net present value for a schedule of cash flows that is not
+ * necessarily periodic.
+ *
+ * @param {number} rate - Discount rate per year (as a decimal, e.g., 0.1 for
+ * 10%).
+ * @param {number[]} values - Cash flow values where each value is a payment
+ * (negative) or income (positive).
+ * @param {Date[]} dates - Dates corresponding to each cash flow. The first date
+ * is treated as the base date.
+ * @returns {number} The net present value for the supplied rate and dated cash
+ * flows.
+ * @throws {RangeError} When inputs are invalid.
+ *
+ * @example
+ * const values = [-10000, 2750, 4250, 3250, 2750];
+ * const dates = [new Date("2008-01-01"), new Date("2008-03-01"), new Date("2008-10-30"), new Date("2009-02-15"), new Date("2009-04-01")];
+ * xnpv(0.09, values, dates); // 2086.64760203
+ */
+export function xnpv(rate, values, dates) {
+  if (rate <= -1) {
+    throw new RangeError("Invalid rate.");
+  }
+
+  if (
+    !Array.isArray(values) ||
+    !Array.isArray(dates) ||
+    values.length !== dates.length ||
+    values.length < 1
+  ) {
+    throw new RangeError(
+      "Values and dates must be arrays of the same length (at least 1).",
+    );
+  }
+
+  const firstDate = dates[0];
+
+  if (!(firstDate instanceof Date) || Number.isNaN(firstDate.getTime())) {
+    throw new RangeError("All dates must be valid Date objects.");
+  }
+
+  const baseDay = Date.UTC(
+    firstDate.getUTCFullYear(),
+    firstDate.getUTCMonth(),
+    firstDate.getUTCDate(),
+  );
+
+  let total = 0;
+
+  for (let index = 0; index < values.length; index += 1) {
+    const date = dates[index];
+
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+      throw new RangeError("All dates must be valid Date objects.");
+    }
+
+    const currentDay = Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+    );
+
+    if (currentDay < baseDay) {
+      throw new RangeError("Dates must not precede the first date.");
+    }
+
+    const elapsedDays = (currentDay - baseDay) / (1000 * 60 * 60 * 24);
+    total += values[index] / Math.pow(1 + rate, elapsedDays / 365);
+  }
+
+  return total;
+}