@travishorn/financejs 1.1.0 → 1.16.0

package/README.md

@@ -39,6 +39,9 @@ const internalRate = irr([-1500, 500, 500, 500, 500]);
 // 0.12589832495374934
 ```
 
+For full API documentation, visit
+[https://travishorn.github.io/financejs/](https://travishorn.github.io/financejs/).
+
 ## Excel-style conventions
 
 - Outputs are not rounded automatically.
@@ -49,86 +52,6 @@ const internalRate = irr([-1500, 500, 500, 500, 500]);
 - `rate` must match period frequency (e.g., annual rate divided by 12 for
   monthly periods).
 
-## API
-
-### Input Variables
-
-| 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.                                                                                                                                                                                                                                                                                                     |
-
-### `fv(rate, nper, pmt, pv, type = 0)`
-
-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.
-
-### `ipmt(rate, per, nper, pv, fv = 0, type = 0)`
-
-Returns the interest payment for a given period for an investment based on
-periodic, constant payments and a constant interest rate.
-
-### `irr(values, guess = 0.1)`
-
-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)`
-
-Calculates the number of periods for an investment based on periodic, constant
-payments and a constant interest rate.
-
-### `npv(rate, ...values)`
-
-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).
-
-### `pmt(rate, nper, pv, fv = 0, type = 0)`
-
-Calculates the payment for a loan based on constant payments and a constant
-interest rate.
-
-### `ppmt(rate, per, nper, pv, fv = 0, type = 0)`
-
-Calculates the payment on the principal for a given period for an investment
-based on periodic, constant payments and a constant interest rate.
-
-### `pv(rate, nper, pmt, fv = 0, type = 0)`
-
-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.
-
-### `rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1)`
-
-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.
-
-### `xirr(values, dates, guess = 0.1)`
-
-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.
-
-### `xnpv(rate, values, dates)`
-
-Calculates the net present value for a schedule of cash flows that is not
-necessarily periodic.
-
 ## Error behavior
 
 All functions will either return a number, or throw `RangeError` for invalid
@@ -181,12 +104,13 @@ to 8 decimal places), while using a modern JavaScript module API.
 
 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."
+to the project. Since there are over 50 functions, broke them into "tiers."
+Tiers 1-3 are complete.
 
 - **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 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travishorn/financejs",
-  "version": "1.1.0",
+  "version": "1.16.0",
   "description": "Modern JavaScript time value of money and cash-flow financial formulas with Excel-style behavior.",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
     "access": "public"
   },
   "scripts": {
+    "docs": "typedoc --entryPoints src/index.js --out docs",
     "format": "prettier --write .",
     "lint:format": "prettier --check .",
     "lint:types": "tsc --noEmit",
@@ -48,6 +49,7 @@
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.4.0",
     "prettier": "^3.8.1",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }

package/src/cumipmt.js

@@ -0,0 +1,58 @@
+import { ipmt } from "./ipmt.js";
+
+/**
+ * Calculates the cumulative interest paid on a loan between a start period and
+ * and end period.
+ *
+ * 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 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`.
+ * - If `rate` <= `0`, `nper` <= `0`, or `pv` <= `0`, this function throws a
+ *   RangeError.
+ * - If `startPeriod` < `1`, `endPeriod` < `1`, or `startPeriod` >
+ *   `endPeriod`, this function throws a RangeError.
+ *
+ * @param {number} rate - The interest rate.
+ * @param {number} nper - The total number of payment periods.
+ * @param {number} pv - The present value.
+ * @param {number} startPeriod - The first period in the calculation. Payment
+ * periods are numbered beginning with 1.
+ * @param {number} endPeriod - The last period in the calculation.
+ * @param {0|1} type - The timing of the payment. `0` (zero) = payment at
+ * the end of the period. `1` = payment at the beginning of the period.
+ * @returns {number} The cumulative interest paid
+ *
+ * @example
+ * cumipmt(0.09 / 12, 30 * 12, 125000, 13, 24, 0); // -11135.23213075
+ */
+export function cumipmt(rate, nper, pv, startPeriod, endPeriod, type) {
+  // Input validation
+  if (rate <= 0 || nper <= 0 || pv <= 0) {
+    throw new RangeError("rate, nper, and pv must be > 0");
+  }
+
+  if (
+    startPeriod < 1 ||
+    endPeriod < 1 ||
+    startPeriod > endPeriod ||
+    startPeriod > nper ||
+    endPeriod > nper
+  ) {
+    throw new RangeError("Invalid startPeriod or endPeriod");
+  }
+
+  if (type !== 0 && type !== 1) {
+    throw new RangeError("type must be 0 or 1");
+  }
+
+  let cumInterest = 0;
+
+  for (let per = startPeriod; per <= endPeriod; per++) {
+    cumInterest += ipmt(rate, per, nper, pv, 0, type);
+  }
+
+  return cumInterest;
+}

package/src/cumprinc.js

@@ -0,0 +1,62 @@
+import { pmt } from "./pmt.js";
+import { ipmt } from "./ipmt.js";
+
+/**
+ * Calculates the cumulative principal paid on a loan between a start period and
+ * an end period.
+ *
+ * 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 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`.
+ * - If `rate` <= `0`, `nper` <= `0`, or `pv` <= `0`, this function throws a
+ *   RangeError.
+ * - If `startPeriod` < `1`, `endPeriod` < `1`, or `startPeriod` > `endPeriod`,
+ *   this function throws a RangeError.
+ *
+ * @param {number} rate - The interest rate.
+ * @param {number} nper - The total number of payment periods.
+ * @param {number} pv - The present value.
+ * @param {number} startPeriod - The first period in the calculation. Payment
+ * periods are numbered beginning with 1.
+ * @param {number} endPeriod - The last period in the calculation.
+ * @param {0|1} type - The timing of the payment. `0` (zero) = payment at the
+ * end of the period. `1` = payment at the beginning of the period.
+ * @returns {number} The cumulative interest paid
+ *
+ * @example
+ * cumprinc(0.09 / 12, 30 * 12, 125000, 13, 24, 0); // -934.10712342
+ */
+export function cumprinc(rate, nper, pv, startPeriod, endPeriod, type) {
+  // Input validation
+  if (rate <= 0 || nper <= 0 || pv <= 0) {
+    throw new RangeError("rate, nper, and pv must be > 0");
+  }
+
+  if (
+    startPeriod < 1 ||
+    endPeriod < 1 ||
+    startPeriod > endPeriod ||
+    startPeriod > nper ||
+    endPeriod > nper
+  ) {
+    throw new RangeError("Invalid startPeriod or endPeriod");
+  }
+
+  if (type !== 0 && type !== 1) {
+    throw new RangeError("type must be 0 or 1");
+  }
+
+  let cumPrincipal = 0;
+
+  for (let per = startPeriod; per <= endPeriod; per++) {
+    // Principal = payment - interest for this period
+    const payment = pmt(rate, nper, pv, 0, type);
+    const interest = ipmt(rate, per, nper, pv, 0, type);
+    cumPrincipal += payment - interest;
+  }
+
+  return cumPrincipal;
+}

package/src/db.js

@@ -0,0 +1,60 @@
+/**
+ * Calculates the depreciation of an asset for a specified period using the
+ * fixed-declining balance method.
+ *
+ * Remarks:
+ * - The fixed-declining balance method computes depreciation at a fixed rate.
+ *   Uses the following formulas to calculate depreciation for a period: `(cost
+ *   - total depreciation from prior periods) * rate`, where `rate = 1 -
+ *     ((salvage / cost) ^ (1 / life))`, rounded to three decimal places.
+ * - Depreciation for the first and last periods is a special case. For the
+ *   first period, this function uses this formula: `cost * rate * month / 12`
+ * - For the last period, DB uses this formula: `((cost - total depreciation
+ *   from prior periods) * rate * (12 - month)) / 12`
+ *
+ * @param {number} cost - The initial cost of the asset.
+ * @param {number} salvage - The value at the end of the depreciation (sometimes
+ * called the salvage value of the asset).
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @param {number} period - The period for which you want to calculate the
+ * depreciation. Period must use the same units as `life`.
+ * @param {number} [month=12] - The number of months in the first year. If month
+ * is omitted, it is assumed to be `12`.
+ * @returns {number} the depreciation
+ *
+ * @example
+ * db(1000000, 100000, 6, 1, 7); // 186083.33333333
+ */
+export function db(cost, salvage, life, period, month = 12) {
+  // Calculate the fixed rate, rounded to 3 decimal places
+  const rate = +(1 - Math.pow(salvage / cost, 1 / life)).toFixed(3);
+
+  if (period === 1) {
+    // First period: prorated by month
+    return (cost * rate * month) / 12;
+  }
+
+  // Calculate value after first period (prorated)
+  let value = cost - (cost * rate * month) / 12;
+
+  // For periods > 2, apply normal declining balance for each period
+  for (let p = 2; p < period; p++) {
+    value -= value * rate;
+  }
+
+  // Determine if this is the last period (partial year)
+  // The last period is when the sum of months in all periods reaches 12*life
+  // For the test case, period 7 is the last period (since month=7, life=6)
+  const totalMonths = (period - 1) * 12 + month;
+  const isLastPeriod = totalMonths > life * 12;
+
+  let dep;
+  if (isLastPeriod) {
+    // Last period: prorate by (12 - month)
+    dep = (value * rate * (12 - month)) / 12;
+  } else {
+    dep = value * rate;
+  }
+  return dep;
+}

package/src/ddb.js

@@ -0,0 +1,49 @@
+/**
+ * Calculates the depreciation of an asset for a specified period using the
+ * double-declining balance method or some other method you specify.
+ *
+ * Remarks:
+ * - The double-declining balance method computes depreciation at an accelerated
+ *   rate. Depreciation is highest in the first period and decreases in
+ *   successive periods. This function uses the following formula to calculate
+ *   depreciation for a period: `Min( (cost - total depreciation from prior
+ *   periods) * (factor/life), (cost - salvage - total depreciation from prior
+ *   periods) )`
+ * - Change `factor` if you do not want to use the double-declining balance
+ *   method.
+ *
+ * @param {number} cost - The initial cost of the asset.
+ * @param {number} salvage - The value at the end of the depreciation (sometimes
+ * called the salvage value of the asset). This value can be `0`.
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @param {number} period - The period for which you want to calculate the
+ * depreciation. Period must use the same units as `life`.
+ * @param {number} [factor=2] - The rate at which the balance declines. If
+ * `factor` is omitted, it is assumed to be `2` (the double-declining balance
+ * method).
+ * @returns {number} the depreciation
+ * @throws {RangeError} When `period` is outside the valid range.
+ *
+ * @example
+ * ddb(2400, 300, 10 * 365, 1); // 1.31506849
+ */
+export function ddb(cost, salvage, life, period, factor = 2) {
+  let accDep = 0;
+  let value = cost;
+
+  for (let p = 1; p <= period; p++) {
+    // Calculate depreciation for this period
+    let dep = Math.min(value * (factor / life), cost - salvage - accDep);
+
+    if (p === period) {
+      return dep;
+    }
+
+    accDep += dep;
+    value -= dep;
+  }
+
+  // Period is out of range
+  throw new RangeError("Invalid period");
+}

package/src/dollarde.js

@@ -0,0 +1,47 @@
+/**
+ * Converts a dollar price expressed as an integer part and a fraction part,
+ * such as `1.02`, into a dollar price expressed as a decimal number. Fractional
+ * dollar numbers are sometimes used for security prices.
+ *
+ * The fraction part of the value is divided by an integer that you specify. For
+ * example, if you want your price to be expressed to a precision of 1/16 of a
+ * dollar, you divide the fraction part by 16. In this case, `1.02` represents
+ * `$1.125 ($1 + 2/16 = $1.125)`.
+ *
+ * Remarks:
+ * - If `fraction` is not an integer, it is truncated.
+ * - If `fraction` is less than `0`, this function will throw a RangeError.
+ * - If `fraction` is greater than or equal to `0` and less than `1`, division
+ *   by zero is impossible and this function will throw a RangeError.
+ *
+ * @param {number} fractionalDollar - A number expressed as an integer part and
+ * a fraction part, separated by a decimal symbol.
+ * @param {number} fraction - The integer to use in the denominator of the
+ * fraction.
+ * @returns {number} the converted dollar price expressed as a decimal number
+ *
+ * @example
+ * dollarde(1.02, 16); // 1.125
+ */
+export function dollarde(fractionalDollar, fraction) {
+  if (typeof fraction !== "number" || isNaN(fraction) || !isFinite(fraction)) {
+    throw new RangeError("fraction must be a finite number");
+  }
+  if (fraction < 0) throw new RangeError("fraction must be >= 0");
+  if (fraction > 0 && fraction < 1)
+    throw new RangeError("fraction must be >= 1 or 0");
+
+  // Truncate fraction to integer
+  fraction = Math.trunc(fraction);
+
+  const sign = fractionalDollar < 0 ? -1 : 1;
+  const abs = Math.abs(fractionalDollar);
+  const intPart = Math.trunc(abs);
+  const fracPart = abs - intPart;
+
+  // Multiply the decimal piece by 10 to the power of the length of fraction digits
+  const power = Math.ceil(Math.log10(fraction));
+  const result = intPart + (fracPart * Math.pow(10, power)) / fraction;
+
+  return sign * result;
+}

package/src/dollarfr.js

@@ -0,0 +1,40 @@
+/**
+ * Converts a decimal number to a fractional dollar number, such as a securities
+ * price.
+ *
+ * Remarks:
+ * - If `fraction` is not an integer, it is truncated.
+ * - If `fraction` is less than `0`, this function will throw a RangeError.
+ * - If `fraction` is `0`, division by zero is impossible and this function will
+ *   throw a RangeError.
+ *
+ * @param {number} decimalDollar - A decimal number.
+ * @param {number} fraction - The integer to use in the denominator of the
+ * fraction.
+ * @returns {number} the converted dollar price expressed as a fractional dollar
+ * number
+ *
+ * @example
+ * dollarfr(1.125, 16); // 1.02
+ */
+export function dollarfr(decimalDollar, fraction) {
+  if (typeof fraction !== "number" || isNaN(fraction) || !isFinite(fraction)) {
+    throw new RangeError("fraction must be a finite number");
+  }
+  if (fraction < 0) throw new RangeError("fraction must be >= 0");
+  if (fraction === 0) throw new RangeError("fraction must be >= 1 or 0");
+
+  // Truncate fraction to integer
+  fraction = Math.trunc(fraction);
+
+  const sign = decimalDollar < 0 ? -1 : 1;
+  const abs = Math.abs(decimalDollar);
+  const intPart = Math.trunc(abs);
+  const fracPart = abs - intPart;
+
+  // Use the same scale as dollarde() so this function is its algebraic inverse.
+  const power = Math.ceil(Math.log10(fraction));
+  const result = intPart + (fracPart * fraction) / Math.pow(10, power);
+
+  return sign * result;
+}

package/src/effect.js

@@ -0,0 +1,41 @@
+/**
+ * Calculates the effective annual interest rate, given the nominal annual
+ * interest 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 `nominalRate` <= `0` or if `npery` < `1`, an error is thrown.
+ * - Rate is calculated as follows: `(1 + nominalRate / npery)^npery - 1`
+ * - This function is related to `nominal()` through `effectiveRate = (1 +
+ *   (nominalRate / npery)) * npery - 1`.
+ *
+ * @param {number} nominalRate - The nominal interest rate.
+ * @param {number} npery - The number of compounding periods per year.
+ * @returns {number} the effective annual interest rate
+ *
+ * @example
+ * effect(0.0525, 4); // 0.05354267
+ */
+export function effect(nominalRate, npery) {
+  if (
+    typeof nominalRate !== "number" ||
+    typeof npery !== "number" ||
+    isNaN(nominalRate) ||
+    isNaN(npery)
+  ) {
+    throw new TypeError("Both arguments must be numbers");
+  }
+
+  if (nominalRate <= 0) {
+    throw new RangeError("nominalRate must be > 0");
+  }
+
+  npery = Math.trunc(npery);
+
+  if (npery < 1) {
+    throw new RangeError("npery must be >= 1");
+  }
+
+  return Math.pow(1 + nominalRate / npery, npery) - 1;
+}

package/src/fvschedule.js

@@ -0,0 +1,41 @@
+/**
+ * Calculates the future value of an initial principal after applying a series
+ * of compound interest rates. Use this function to calculate the future value
+ * of an investment with a variable or adjustable rate.
+ *
+ * Remarks:
+ * - The values in schedule can be numbers or `null`; any other value will cause
+ *   this function to throw a RangeError. Null values are taken as zeros (no
+ *   interest).
+ *
+ * @param {number} principal - The present value.
+ * @param {number[]} schedule - An array of interest rates to apply.
+ * @returns {number} the future value
+ *
+ * @example
+ * fvschedule(1, [0.09, 0.11, 0.1]); // 1.33089000
+ */
+export function fvschedule(principal, schedule) {
+  if (typeof principal !== "number" || !Array.isArray(schedule)) {
+    throw new RangeError("Invalid input types");
+  }
+
+  let fv = principal;
+
+  for (let i = 0; i < schedule.length; ++i) {
+    let rate = schedule[i];
+    if (rate === null) {
+      rate = 0;
+    } else if (
+      typeof rate !== "number" ||
+      Number.isNaN(rate) ||
+      rate === Infinity ||
+      rate === -Infinity
+    ) {
+      throw new RangeError("Schedule must contain only finite numbers or null");
+    }
+    fv *= 1 + rate;
+  }
+
+  return fv;
+}

package/src/index.js

@@ -1,11 +1,27 @@
+export { cumipmt } from "./cumipmt.js";
+export { cumprinc } from "./cumprinc.js";
+export { db } from "./db.js";
+export { ddb } from "./ddb.js";
+export { dollarde } from "./dollarde.js";
+export { dollarfr } from "./dollarfr.js";
+export { effect } from "./effect.js";
 export { fv } from "./fv.js";
+export { fvschedule } from "./fvschedule.js";
 export { ipmt } from "./ipmt.js";
 export { irr } from "./irr.js";
+export { ispmt } from "./ispmt.js";
+export { mirr } from "./mirr.js";
+export { nominal } from "./nominal.js";
 export { nper } from "./nper.js";
 export { npv } from "./npv.js";
+export { pduration } from "./pduration.js";
 export { pmt } from "./pmt.js";
 export { ppmt } from "./ppmt.js";
 export { pv } from "./pv.js";
 export { rate } from "./rate.js";
+export { rri } from "./rri.js";
+export { sln } from "./sln.js";
+export { syd } from "./syd.js";
+export { vdb } from "./vdb.js";
 export { xirr } from "./xirr.js";
 export { xnpv } from "./xnpv.js";

package/src/ispmt.js

@@ -0,0 +1,53 @@
+/**
+ * Calculates the interest paid (or received) for the specified period of a loan
+ * (or investment) with even principal payments.
+ *
+ * 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.
+ * - This function counts each period beginning with zero, not with one.
+ * - Most loans use a repayment schedule with even periodic payments. This
+ *   function returns the interest payment for a given period for this type of
+ *   loan.
+ * - Some loans use a repayment schedule with even principal payments. This
+ *   function returns the interest payment for a given period for this type of
+ *   loan.
+ * - The interest charge each period is equal to the `rate` times the unpaid
+ *   balance for the previous period. And the payment each period is equal to
+ *   the ven principal plus th einterest for the period.
+ *
+ * @param {number} rate - The interest rate for the investment.
+ * @param {number} per - The period for which you want to find the interest, and
+ * must be between `1` and `nper`.
+ * @param {number} nper - The total number of payment periods for the
+ * investment.
+ * @param {number} pv - The present value of the investment. For a loan, this is
+ * the loan amount.
+ * @returns {number} the interest paid (or received)
+ *
+ * @example
+ * ispmt(0.1, 0, 4, 4000); // -400
+ */
+export function ispmt(rate, per, nper, pv) {
+  // Validate inputs
+  if (typeof rate !== "number" || isNaN(rate) || !isFinite(rate))
+    throw new RangeError("rate must be a finite number");
+  if (typeof per !== "number" || isNaN(per) || !isFinite(per))
+    throw new RangeError("per must be a finite number");
+  if (typeof nper !== "number" || isNaN(nper) || !isFinite(nper))
+    throw new RangeError("nper must be a finite number");
+  if (typeof pv !== "number" || isNaN(pv) || !isFinite(pv))
+    throw new RangeError("pv must be a finite number");
+  if (nper <= 0) throw new RangeError("nper must be > 0");
+  if (per < 0 || per >= nper)
+    throw new RangeError("per must be between 0 and nper-1");
+
+  // ISPIMT formula: -pv * rate * (1 - per / nper)
+  return -pv * rate * (1 - per / nper);
+}

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/pduration.js

@@ -0,0 +1,19 @@
+/**
+ * Calculates the number of periods required by an investment to reach a
+ * specified value.
+ *
+ * @param {number} rate - Rate is the interest rate per period.
+ * @param {number} pv - The present value of the investment.
+ * @param {number} fv - The future value of the investment.
+ * @returns {number} the number of periods required
+ * @throws {RangeError} if `rate` is less than or equal to zero
+ * @throws {RangeError} if `pv` is zero
+ *
+ * @example
+ * pduration(0.025, 2000, 2200); // 3.86
+ */
+export function pduration(rate, pv, fv) {
+  if (rate <= 0) throw new RangeError("Rate must be positive");
+  if (pv === 0) throw new RangeError("Present value cannot be zero");
+  return Math.log(fv / pv) / Math.log(1 + rate);
+}

package/src/rri.js

@@ -0,0 +1,18 @@
+/**
+ * Calculates an equivalent interest rate for the growth of an investment.
+ *
+ * @param {number} nper - The number of periods for the investment.
+ * @param {number} pv - The present value of the investment.
+ * @param {number} fv - The future value of the investment.
+ * @returns {number} the equivalent interest rate
+ * @throws {RangeError} if `nper` is less than or equal to zero
+ * @throws {RangeError} if `pv` is zero
+ *
+ * @example
+ * rri(96, 10000, 11000); // 0.00099331
+ */
+export function rri(nper, pv, fv) {
+  if (nper <= 0) throw new RangeError("Number of periods must be positive");
+  if (pv === 0) throw new RangeError("Present value cannot be zero");
+  return Math.pow(fv / pv, 1 / nper) - 1;
+}

package/src/sln.js

@@ -0,0 +1,16 @@
+/**
+ * Calculates the straight-line depreciation of an asset for one period.
+ *
+ * @param {number} cost - The initial cost of the asset.
+ * @param {number} salvage - The value at the end of the depreciation (sometimes
+ * called the salvage value of the asset).
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @returns {number} the straight-line depreciation
+ *
+ * @example
+ * sln(30000, 7500, 10); // 2250
+ */
+export function sln(cost, salvage, life) {
+  return (cost - salvage) / life;
+}

package/src/syd.js

@@ -0,0 +1,22 @@
+/**
+ * Calculates the sum-of-years' digits depreciation of an asset for a specified
+ * period.
+ *
+ * Remarks:
+ * - The calculation is `((cost - salvage) * (life - per + 1) * 2) / (life)(life
+ *   + 1)`.
+ *
+ * @param {number} cost - The initial cost of the asset.
+ * @param {number} salvage - The value at the end of the depreciation (sometimes
+ * called the salvage value of the asset).
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @param {number} per - The period and must use the same units as `life`.
+ * @returns {number} the straight-line depreciation
+ *
+ * @example
+ * syd(30000, 7500, 10, 1); // 4090.91
+ */
+export function syd(cost, salvage, life, per) {
+  return ((cost - salvage) * (life - per + 1) * 2) / (life * (life + 1));
+}

package/src/vdb.js

@@ -0,0 +1,101 @@
+/**
+ * Calculates the depreciation of an asset for any period you specify, including
+ * partial periods, using the double-declining balance method or some other
+ * method you specify. VDB stands for variable declining balance.
+ *
+ * @param {number} cost - The initial cost of the asset.
+ * @param {number} salvage - The value at the end of the depreciation (sometimes
+ * called the salvage value of the asset). This value can be `0`.
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @param {number} startPeriod - The starting period for which you want to
+ * calculate the depreciation. `startPeriod` must use the same units as `life`.
+ * @param {number} endPeriod - The ending period for which you want to calculate
+ * the depreciation. `endPeriod` must use the same units as `life`.
+ * @param {number} [factor=2] -The rate at which the balance declines. If
+ * `factor` is omitted, it is assumed to be `2` (the double-declining balance
+ * method). Change factor if you do not want to use the double-declining balance
+ * method.
+ * @param {boolean} [noSwitch=false] - Whether to switch to straight-line
+ * depreciation when depreciation is greater than the declining balance
+ * calculation. If `noSwitch` is `true`, this function does not switch to
+ * straigh-line depreciation even when the depreciation is greater than the
+ * declining balance calculation. If `noSwitch` is `false`, this function
+ * switches to straight-line depreciation when depreciation is greater than the
+ * declining balance calculation.
+ * @returns {number} the depreciation
+ *
+ * @example
+ * vdb(2400, 300, 10 * 365, 0, 1); // 1.31506849
+ */
+export function vdb(
+  cost,
+  salvage,
+  life,
+  startPeriod,
+  endPeriod,
+  factor = 2,
+  noSwitch = false,
+) {
+  // Input validation
+  if (cost < 0) throw new RangeError("cost must be >= 0");
+  if (salvage < 0) throw new RangeError("salvage must be >= 0");
+  if (life <= 0) throw new RangeError("life must be > 0");
+  if (factor <= 0) throw new RangeError("factor must be > 0");
+  if (startPeriod < 0) throw new RangeError("startPeriod must be >= 0");
+  if (endPeriod < 0) throw new RangeError("endPeriod must be >= 0");
+  if (startPeriod > endPeriod)
+    throw new RangeError("startPeriod must be <= endPeriod");
+  if (salvage >= cost) return 0;
+
+  // Clamp periods to [0, life]
+  startPeriod = Math.max(0, Math.min(startPeriod, life));
+  endPeriod = Math.max(0, Math.min(endPeriod, life));
+  if (startPeriod === endPeriod) return 0;
+
+  // Excel returns 0 for a fractional interval wholly within the final period
+  // when it ends exactly at life (e.g. start=9.5, end=10 with life=10).
+  if (!noSwitch && endPeriod === life && startPeriod > life - 1) return 0;
+
+  let totalDep = 0;
+  let period = Math.floor(startPeriod * 1e9) / 1e9; // avoid floating point issues
+
+  while (period < endPeriod) {
+    // Calculate the portion of the period to depreciate
+    let next = Math.min(Math.floor(period + 1), endPeriod);
+    let periodLength = next - period;
+
+    // Calculate depreciation for this period
+    let book = cost;
+    let accDep = 0;
+
+    for (let i = 0; i < Math.floor(period); ++i) {
+      let d = (book * factor) / life;
+
+      if (!noSwitch) {
+        let sl = (cost - accDep - salvage) / (life - i);
+        if (sl > d) d = sl;
+      }
+
+      if (book - d < salvage) d = book - salvage;
+      accDep += d;
+      book -= d;
+    }
+
+    // For the current period (may be partial)
+    let d = (book * factor) / life;
+
+    if (!noSwitch) {
+      let sl = (cost - accDep - salvage) / (life - period);
+      if (sl > d) d = sl;
+    }
+
+    if (book - d < salvage) d = book - salvage;
+
+    let dep = d * periodLength;
+    totalDep += dep;
+    period = next;
+  }
+
+  return totalDep;
+}