@travishorn/financejs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright 2020 kgkars  
+Copyright 2026 Travis Horn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# financejs
+
+Excel-style time value of money and cash-flow formulas. This is a modern rewrite
+of [tvm-financejs](https://github.com/kgkars/tvm-financejs/) by
+[kgkars](https://github.com/kgkars).
+
+## Why this rewrite
+
+This project keeps the formula behavior and conventions from the original
+library, but modernizes the implementation and tooling:
+
+- Native ESM
+- Named function exports (no class wrapper)
+- Native error handling
+- Strict type-checking
+- JSDoc documentation
+- Vitest-based test suite
+- 100% test coverage
+- ESLint + Prettier setup
+
+## Installation
+
+```bash
+npm install @travishorn/financejs
+```
+
+## Usage
+
+```js
+import { pmt, rate, irr } from "@travishorn/financejs";
+
+const payment = pmt(0.0525, 5, -10000);
+// 2325.7331680465
+
+const periodicRate = rate(60, 500, -25000);
+// 0.00618341316125388
+
+const internalRate = irr([-1500, 500, 500, 500, 500]);
+// 0.125898324962364
+```
+
+## Excel-style conventions
+
+- Outputs are not rounded automatically.
+- `pv` is typically negative for loans/investments (same convention as Excel).
+- `type` means payment timing:
+  - `0` = end of period (arrears)
+  - `1` = beginning of period (advance)
+- `rate` must match period frequency (e.g., annual rate divided by 12 for
+  monthly periods).
+
+## API
+
+### 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                                                          |
+
+### `pv(rate, nper, pmt, fv = 0, type = 0)`
+
+Returns the present value of an investment, or the total amount that a series of
+future payments is worth now.
+
+### `fv(rate, nper, pmt, pv, type = 0)`
+
+Returns the future value of an investment based on periodic, equal, payments and
+a constant interest rate.
+
+### `pmt(rate, nper, pv, fv = 0, type = 0)`
+
+Calculates the payment for a loan based on a constant stream of equal payments
+and a constant interest rate.
+
+### `nper(rate, pmt, pv, fv = 0, type = 0)`
+
+Number of periods.
+
+### `ipmt(rate, per, nper, pv, fv = 0, type = 0)`
+
+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.
+
+### `ppmt(rate, per, 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.
+
+### `rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1)`
+
+Returns the interest rate per period for a loan or investment (iterative solve).
+
+### `npv(rate, ...values)`
+
+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).
+
+### `irr(values, guess = 0.1)`
+
+Returns the internal rate of return for a series of cash flows.
+
+A couple of items to note about this formula:
+
+- 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.
+
+Example usage:
+
+```javascript
+returnIRR() {
+  const values = [-1500, 500, 500, 500, 500];
+  return Math.round(irr(values) * 100 ) / 100 * 100;
+}
+// returns 12.59
+```
+
+## Error behavior
+
+All functions will either return a number, or throw `RangeError` for invalid
+inputs or non-convergent iterative solves.
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/travishorn/financejs
+```
+
+Change into the directory:
+
+```bash
+cd financejs
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Lint with ESLint:
+
+```bash
+npm run lint
+```
+
+Check types:
+
+```bash
+npm run lint:types
+```
+
+Format with Prettier:
+
+```bash
+npm run format
+```
+
+## Notes on compatibility
+
+This rewrite is intended to match Excel-style formulas closely (tests validate
+to 8 decimal places), while using a modern JavaScript module API.
+
+## License
+
+The MIT License
+
+Copyright 2020 kgkars  
+Copyright 2026 Travis Horn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@travishorn/financejs",
+  "version": "1.0.0",
+  "description": "Modern JavaScript time value of money and cash-flow financial formulas with Excel-style behavior.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/travishorn/financejs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/travishorn/financejs/issues"
+  },
+  "homepage": "https://github.com/travishorn/financejs#readme",
+  "exports": "./src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "lint": "eslint .",
+    "lint:types": "tsc --noEmit",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "finance",
+    "financial",
+    "tvm",
+    "time-value-of-money",
+    "excel",
+    "npv",
+    "irr",
+    "rate",
+    "loan",
+    "amortization"
+  ],
+  "author": "Travis Horn <travis@travishorn.com> (https://travishorn.com/)",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/fv.js

@@ -0,0 +1,24 @@
+/**
+ * Calculates the future value of an investment or loan.
+ *
+ * @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.
+ * @returns {number} The future value.
+ */
+export function fv(rate, nper, pmt, pv, type = 0) {
+  if (rate === 0) {
+    return -pv - pmt * nper;
+  } else {
+    const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
+    const interestFactor = 1 + rate;
+    const compoundFactor = Math.pow(interestFactor, nper);
+
+    return (
+      -pv * compoundFactor -
+      (pmt / rate) * paymentTimingFactor * (compoundFactor - 1)
+    );
+  }
+}

package/src/index.js

@@ -0,0 +1,9 @@
+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 { rate } from "./rate.js";

package/src/ipmt.js

@@ -0,0 +1,36 @@
+import { fv } from "./fv.js";
+import { pmt } from "./pmt.js";
+
+/**
+ * Calculates the interest portion of a payment for a specific period.
+ *
+ * @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 interest payment for the specified period.
+ * @throws {RangeError} When `per` is outside the valid range.
+ */
+export function ipmt(rate, per, nper, pv, futureValue = 0, type = 0) {
+  if (per <= 0 || per >= nper + 1) {
+    throw new RangeError("Invalid period.");
+  }
+
+  if (type !== 0 && per === 1) {
+    return 0;
+  }
+
+  const periodOffset = type !== 0 ? 2 : 1;
+  const periodicPayment = pmt(rate, nper, pv, futureValue, type);
+  const adjustedPresentValue = type !== 0 ? pv + periodicPayment : pv;
+  const periodFutureValue = fv(
+    rate,
+    per - periodOffset,
+    periodicPayment,
+    adjustedPresentValue,
+  );
+
+  return periodFutureValue * rate;
+}

package/src/irr.js

@@ -0,0 +1,104 @@
+/**
+ * Evaluates present value for an IRR iteration guess.
+ *
+ * @param {number[]} values - Cash flow values.
+ * @param {number} [guess=0.1] - Rate guess.
+ * @returns {number} Present value at the supplied guess.
+ */
+function internalPv(values, guess = 0.1) {
+  let lowerBound = 0;
+  const upperBound = values.length - 1;
+  let total = 0;
+  const discountRate = 1 + guess;
+
+  while (lowerBound <= upperBound && values[lowerBound] === 0) {
+    lowerBound += 1;
+  }
+
+  for (let index = upperBound; index >= lowerBound; index -= 1) {
+    total /= discountRate;
+    total += values[index];
+  }
+
+  return total;
+}
+
+/**
+ * Calculates the internal rate of return for a series of cash flows.
+ *
+ * @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.
+ * @returns {number} The internal rate of return.
+ * @throws {RangeError} When inputs are invalid or the algorithm cannot converge.
+ */
+export function irr(values, guess = 0.1) {
+  if (guess <= -1) {
+    throw new RangeError("Invalid guess.");
+  }
+
+  if (values.length < 1) {
+    throw new RangeError("Invalid values.");
+  }
+
+  const epsilonMax = 0.0000001;
+  const step = 0.00001;
+  const iterationMax = 39;
+
+  let maxAbsoluteValue = Math.abs(values[0]);
+
+  for (let index = 0; index < values.length; index += 1) {
+    const absoluteValue = Math.abs(values[index]);
+
+    if (absoluteValue > maxAbsoluteValue) {
+      maxAbsoluteValue = absoluteValue;
+    }
+  }
+
+  const npvEpsilon = maxAbsoluteValue * epsilonMax * 0.01;
+
+  let rate0 = guess;
+  let npv0 = internalPv(values, rate0);
+  let rate1 = npv0 > 0 ? rate0 + step : rate0 - step;
+
+  if (rate1 <= -1) {
+    throw new RangeError("Invalid values.");
+  }
+
+  let npv1 = internalPv(values, rate1);
+
+  for (let iteration = 0; iteration <= iterationMax; iteration += 1) {
+    if (npv1 === npv0) {
+      rate0 = rate1 > rate0 ? rate0 - step : rate0 + step;
+      npv0 = internalPv(values, rate0);
+
+      if (npv1 === npv0) {
+        throw new RangeError("Invalid values.");
+      }
+    }
+
+    rate0 = rate1 - ((rate1 - rate0) * npv1) / (npv1 - npv0);
+
+    if (rate0 <= -1) {
+      rate0 = (rate1 - 1) * 0.5;
+    }
+
+    npv0 = internalPv(values, rate0);
+
+    const rateDelta = Math.abs(rate0 - rate1);
+    const absoluteNpv = Math.abs(npv0);
+
+    if (absoluteNpv < npvEpsilon && rateDelta < epsilonMax) {
+      return rate0;
+    }
+
+    const nextNpv = npv0;
+    npv0 = npv1;
+    npv1 = nextNpv;
+
+    const nextRate = rate0;
+    rate0 = rate1;
+    rate1 = nextRate;
+  }
+
+  throw new RangeError("Maximum iterations exceeded while calculating IRR.");
+}

package/src/nper.js

@@ -0,0 +1,41 @@
+/**
+ * Calculates the number of periods for an investment/loan.
+ *
+ * @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.
+ * @returns {number} Number of periods.
+ * @throws {RangeError} When calculation is impossible with the provided inputs.
+ */
+export function nper(rate, pmt, pv, fv = 0, type = 0) {
+  if (rate === 0) {
+    if (pmt === 0) {
+      throw new RangeError("Payment cannot be 0 when rate is 0.");
+    }
+
+    return -(pv + fv) / pmt;
+  }
+
+  const paymentAdjustment = type !== 0 ? pmt * (1 + rate) : pmt;
+  const paymentOverRate = paymentAdjustment / rate;
+
+  let futureValueTerm = -fv + paymentOverRate;
+  let presentValueTerm = pv + paymentOverRate;
+
+  // Ensure values are valid for logarithms.
+  if (futureValueTerm < 0 && presentValueTerm < 0) {
+    futureValueTerm *= -1;
+    presentValueTerm *= -1;
+  } else if (futureValueTerm <= 0 || presentValueTerm <= 0) {
+    throw new RangeError("Cannot calculate NPER with the provided values.");
+  }
+
+  const growthFactor = 1 + rate;
+
+  return (
+    (Math.log(futureValueTerm) - Math.log(presentValueTerm)) /
+    Math.log(growthFactor)
+  );
+}

package/src/npv.js

@@ -0,0 +1,41 @@
+/**
+ * Evaluates net present value across a bounded portion of a values array.
+ *
+ * @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.
+ */
+function evalNpv(rate, values, lowerBound = 0, upperBound = values.length - 1) {
+  let discountFactor = 1;
+  let total = 0;
+
+  for (let index = lowerBound; index <= upperBound; index += 1) {
+    const value = values[index];
+    discountFactor += discountFactor * rate;
+    total += value / discountFactor;
+  }
+
+  return total;
+}
+
+/**
+ * Calculates the net present value of a series of cash flows.
+ *
+ * @param {number} rate - Discount rate per period.
+ * @param {...number} values - Cash flow values.
+ * @returns {number} The net present value.
+ * @throws {RangeError} When there are no cash flow values or rate is invalid.
+ */
+export function npv(rate, ...values) {
+  if (values.length < 1) {
+    throw new RangeError("Invalid values.");
+  }
+
+  if (rate === -1) {
+    throw new RangeError("Invalid rate.");
+  }
+
+  return evalNpv(rate, values, 0, values.length - 1);
+}

package/src/pmt.js

@@ -0,0 +1,25 @@
+/**
+ * Calculates the periodic payment for a loan or investment.
+ *
+ * @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.
+ * @returns {number} The periodic payment amount.
+ */
+export function pmt(rate, nper, pv, fv = 0, type = 0) {
+  if (rate === 0) {
+    return (-fv - pv) / nper;
+  } else {
+    const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
+    const interestFactor = 1 + rate;
+    const compoundFactor = Math.pow(interestFactor, nper);
+
+    return (
+      ((-fv - pv * compoundFactor) /
+        (paymentTimingFactor * (compoundFactor - 1))) *
+      rate
+    );
+  }
+}

package/src/ppmt.js

@@ -0,0 +1,25 @@
+import { ipmt } from "./ipmt.js";
+import { pmt } from "./pmt.js";
+
+/**
+ * Calculates the principal portion of a payment for a specific period.
+ *
+ * @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.
+ * @throws {RangeError} When `per` is outside the valid range.
+ */
+export function ppmt(rate, per, nper, pv, futureValue = 0, type = 0) {
+  if (per <= 0 || per >= nper + 1) {
+    throw new RangeError("Invalid period.");
+  }
+
+  const periodicPayment = pmt(rate, nper, pv, futureValue, type);
+  const interestPayment = ipmt(rate, per, nper, pv, futureValue, type);
+
+  return periodicPayment - interestPayment;
+}

package/src/pv.js

@@ -0,0 +1,24 @@
+/**
+ * Calculates the present value of an investment based on a series of regular payments and a constant interest rate.
+ *
+ * @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.
+ * @returns {number} The present value of the investment.
+ */
+export function pv(rate, nper, pmt, fv = 0, type = 0) {
+  if (rate === 0) {
+    return -pmt * nper - fv;
+  } else {
+    const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
+    const interestFactor = 1 + rate;
+    const compoundFactor = Math.pow(interestFactor, nper);
+
+    return (
+      -(fv + pmt * paymentTimingFactor * ((compoundFactor - 1) / rate)) /
+      compoundFactor
+    );
+  }
+}

package/src/rate.js

@@ -0,0 +1,82 @@
+/**
+ * Evaluates the RATE equation for a candidate 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.
+ */
+function evalRate(rate, nper, pmt, pv, fv = 0, type = 0) {
+  if (rate === 0) {
+    return pv + pmt * nper + fv;
+  } else {
+    const interestFactor = 1 + rate;
+    const compoundFactor = Math.pow(interestFactor, nper);
+    const paymentTimingFactor = type !== 0 ? 1 + rate : 1;
+
+    return (
+      pv * compoundFactor +
+      (pmt * paymentTimingFactor * (compoundFactor - 1)) / rate +
+      fv
+    );
+  }
+}
+
+/**
+ * Calculates the interest rate per period using iterative approximation.
+ *
+ * @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.
+ */
+export function rate(nper, pmt, pv, fv = 0, type = 0, guess = 0.1) {
+  if (nper <= 0) {
+    throw new RangeError("Invalid period.");
+  }
+
+  const epsilonMax = 0.0000001;
+  const step = 0.00001;
+  const iterationMax = 128;
+
+  let rate0 = guess;
+  let y0 = evalRate(rate0, nper, pmt, pv, fv, type);
+
+  let rate1 = y0 > 0 ? rate0 / 2 : rate0 * 2;
+  let y1 = evalRate(rate1, nper, pmt, pv, fv, type);
+
+  for (let iteration = 0; iteration < iterationMax; iteration += 1) {
+    if (y1 === y0) {
+      rate0 = rate0 < rate1 ? rate0 - step : rate0 + step;
+      y0 = evalRate(rate0, nper, pmt, pv, fv, type);
+    }
+
+    if (y1 === y0) {
+      throw new RangeError("Cannot calculate RATE with the provided values.");
+    }
+
+    rate0 = rate1 - ((rate1 - rate0) * y1) / (y1 - y0);
+    y0 = evalRate(rate0, nper, pmt, pv, fv, type);
+
+    if (Math.abs(y0) < epsilonMax) {
+      return rate0;
+    }
+
+    const nextY = y0;
+    y0 = y1;
+    y1 = nextY;
+
+    const nextRate = rate0;
+    rate0 = rate1;
+    rate1 = nextRate;
+  }
+
+  throw new RangeError("Maximum iterations exceeded while calculating RATE.");
+}