@travishorn/financejs 1.10.0 → 1.17.1

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,145 +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                                                                                                                                                                                                                                                                                                                                                                                                           |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cost`         | The initial cost of the asset.                                                                                                                                                                                                                                                                                                                                                                                        |
-| `dates`        | A schedule of payment dates that corresponds to the cash flow payments. The first payment date indicates the beginning of the schedule of payments. All other dates must be later than this date, but they may occur in any order.                                                                                                                                                                                    |
-| `effectRate`   | The effective interest rate.                                                                                                                                                                                                                                                                                                                                                                                          |
-| `endPeriod`    | The last period in the calculation.                                                                                                                                                                                                                                                                                                                                                                                   |
-| `factor`       | The rate at which the balance declines.                                                                                                                                                                                                                                                                                                                                                                               |
-| `financeRate`  | The interest rate you pay on the money used in the cash flows.                                                                                                                                                                                                                                                                                                                                                        |
-| `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. |
-| `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`.                                                                                                                                                        |
-| `life`         | The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).                                                                                                                                                                                                                                                                                                            |
-| `month`        | The number of months in the first year.                                                                                                                                                                                                                                                                                                                                                                               |
-| `nominalRate`  | The nominal interest rate.                                                                                                                                                                                                                                                                                                                                                                                            |
-| `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`.                                                                                                                                                                                                                     |
-| `npery`        | The number of compounding periods per year.                                                                                                                                                                                                                                                                                                                                                                           |
-| `per`          | The period for which you want to find the interest and must be in the range `1` to `nper`.                                                                                                                                                                                                                                                                                                                            |
-| `period`       | The period for which you want to calculate the depreciation. Period must use the same units as `life`.                                                                                                                                                                                                                                                                                                                |
-| `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`.                                                                                                                       |
-| `pv`           | The present value, or the lump-sum amount that a series of future payments is worth right now.                                                                                                                                                                                                                                                                                                                        |
-| `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.                                                                                                                                                |
-| `reinvestRate` | The interest rate you receive on the cash flows as you reinvest them.                                                                                                                                                                                                                                                                                                                                                 |
-| `salvage`      | The value at the end of the depreciation (sometimes called the salvage value of the asset).                                                                                                                                                                                                                                                                                                                           |
-| `startPeriod`  | The first period in the calculation. Payment periods are numbered beginning with 1.                                                                                                                                                                                                                                                                                                                                   |
-| `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.                                                                                                                                                                                               |
-| `values`       | Array of cash flows, where each entry represents a payment (negative) or income (positive) at a regular interval.                                                                                                                                                                                                                                                                                                     |
-
-### `cumipmt(rate, nper, pv, startPeriod, endPeriod, type)`
-
-Calculates the the cumulative interest paid on a loan between a start period and
-an end period.
-
-### `cumprinc(rate, nper, pv, startPeriod, endPeriod, type)`
-
-Calculates the cumulative principal paid on a loan between a start period and an
-end period.
-
-### `db(cost, salvage, life, period, month = 12)`
-
-Calculates the depreciation of an asset for a specified period using the
-fixed-declining balance method.
-
-### `ddb(cost, salvage, life, period, factor = 2)`
-
-Calculates the depreciation of an asset for a specified period using the
-double-declining balance method or some other method you specify.
-
-### `effect(nominalRate, npery)`
-
-Calculates the effective annual interest rate, given the nominal annual interest
-rate and the number of compounding periods per year.
-
-### `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.
-
-### `mirr(values, financeRate, reinvestRate)`
-
-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.
-
-### `nominal(effectRate, npery)`
-
-Calculates the nominal annual interest rate, given the effective rate and the
-number of compounding periods per year.
-
-### `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.
-
-### `sln(cost, salvage, life)`
-
-Calculates the straight-line depreciation of an asset for one period.
-
-### `syd(cost, salvage, life, per)`
-
-Calculates the sum-of-years' digits depreciation of an asset for a specified
-period.
-
-### `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
@@ -240,13 +104,14 @@ 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 4:** yield, price, duration, mduration, disc, intrate, received,
+- **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.10.0",
+  "version": "1.17.1",
   "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/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/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

@@ -2,19 +2,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";
+export { yield_ } from "./yield_.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/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/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;
+}

package/src/yield_.js

@@ -0,0 +1,385 @@
+/**
+ * Calculates the yield on a security that pays periodic interest. Use to
+ * calculate bond yield.
+ *
+ * Remarks:
+ * - The settlement date is the date a buyer purchases a coupon, such as a bond.
+ *   The maturity date is the date when a coupon expires. For example, suppose a
+ *   30-year bond is issued on January 1, 2008, and is purchased by a buyer six
+ *   months later. The issue date would be January 1, 2008, the settlement date
+ *   would be July 1, 2008, and the maturity date would be January 1, 2038,
+ *   which is 30 years after the January 1, 2008, issue date.
+ * - `settlement`, `maturity`, `frequency`, and `basis` are truncated to
+ *   integers.
+ * - If `settlement` or `maturity` is not a valid date, an error is thrown.
+ * - If `rate` < `0`, an error is thrown.
+ * - If `pr` ≤ `0` or if `redemption` ≤ `0`, an error is thrown.
+ * - If `frequency` is any number other than `1`, `2`, or `4`, an error is
+ *   thrown.
+ * - If `basis` < `0` or if `basis` > `4` and error is thrown.
+ * - If `settlement` ≥ `maturity`, an error is thrown.
+ * - If there is one coupon period or less until redemption, the yield is
+ *   calculated as follows: `yield = ((redemption/100 + rate/frequency) -
+ *   (par/100 + (A/E * rate/frequency))) / (par/100 + (A/E * rate/frequency)) *
+ *   (frequency * E) / DSR`, where:
+ *      - `A` = number of days from the beginning of the coupon period to the
+ *        settlement date (accrued days).
+ *      - `DSR` = number of days from the settlement date to the redemption date.
+ *      - `E` = number of days in the coupon period.
+ *  - If there is more than one coupon period until redemption, the yield is
+ *    calculated through a hundred iterations. The resolution uses the Newton
+ *    method. The yield is changed until the estimated price given the yield is
+ *    close to price.
+ *
+ * @param {Date} settlement - The security's settlement date. The security
+ * settlement date is the date after the issue date when the security is traded
+ * to the buyer.
+ * @param {Date} maturity - The security's maturity date. The maturity date is
+ * the date when the security expires.
+ * @param {number} rate - The security's annual coupon rate.
+ * @param {number} pr - The security's price per $100 face value.
+ * @param {number} redemption - The security's redemption value per $100 face
+ * value.
+ * @param {1|2|4} frequency - The number of coupon payments per year. For
+ * annual payments, frequency = `1`; for semiannual, frequency = `2`; for
+ * quarterly, frequency = `4`.
+ * @param {0|1|2|3|4} [basis=0] - The type of day count basis to use. `0` or
+ * omitted = US (NASD 30/360), `1` = actual/actual, `2` = actual/360, `3` =
+ * actual/365, `4` = European 30/360.
+ * @returns {number} The yield
+ *
+ * @example
+ * yield_(new Date("2008-02-15"), new Date("2016-11-15"), 0.0575, 95.04287, 100, 2, 0); // 0.06500001
+ */
+export function yield_(
+  settlement,
+  maturity,
+  rate,
+  pr,
+  redemption,
+  frequency,
+  basis = 0,
+) {
+  const settlementDate = toUtcDate(settlement);
+  const maturityDate = toUtcDate(maturity);
+
+  frequency = /** @type {1|2|4} */ (Math.trunc(frequency));
+  const basisNumber = Math.trunc(basis ?? 0);
+
+  if (rate < 0) {
+    throw new RangeError("Invalid rate.");
+  }
+
+  if (pr <= 0 || redemption <= 0) {
+    throw new RangeError("Price and redemption must be greater than zero.");
+  }
+
+  if (![1, 2, 4].includes(frequency)) {
+    throw new RangeError("Invalid frequency.");
+  }
+
+  if (basisNumber < 0 || basisNumber > 4) {
+    throw new RangeError("Invalid basis.");
+  }
+
+  /** @type {0|1|2|3|4} */
+  const normalizedBasis = /** @type {0|1|2|3|4} */ (basisNumber);
+
+  if (settlementDate >= maturityDate) {
+    throw new RangeError("Settlement must be before maturity.");
+  }
+
+  const monthsPerCoupon = 12 / frequency;
+  const { previousCouponDate, nextCouponDate } = getCouponBounds(
+    settlementDate,
+    maturityDate,
+    monthsPerCoupon,
+  );
+
+  const a = coupdaybs(previousCouponDate, settlementDate, normalizedBasis);
+  let dsc = coupdaysnc(settlementDate, nextCouponDate, normalizedBasis);
+  const e = coupdays(
+    previousCouponDate,
+    nextCouponDate,
+    frequency,
+    normalizedBasis,
+  );
+
+  if (normalizedBasis === 3) {
+    dsc = e - a;
+  }
+  const n = couponsRemaining(nextCouponDate, maturityDate, monthsPerCoupon);
+  const coupon = (100 * rate) / frequency;
+
+  if (n <= 1) {
+    const numerator =
+      redemption / 100 +
+      rate / frequency -
+      (pr / 100 + (a / e) * (rate / frequency));
+    const denominator = pr / 100 + (a / e) * (rate / frequency);
+    const result = (numerator / denominator) * ((frequency * e) / dsc);
+    return normalizeNegativeZero(result);
+  }
+
+  /** @param {number} candidateYield */
+  const priceFromYield = (candidateYield) => {
+    const base = 1 + candidateYield / frequency;
+    const firstExponent = dsc / e;
+
+    let presentValue = 0;
+    for (let k = 1; k <= n; k += 1) {
+      presentValue += coupon / Math.pow(base, k - 1 + firstExponent);
+    }
+
+    presentValue += redemption / Math.pow(base, n - 1 + firstExponent);
+    presentValue -= (coupon * a) / e;
+
+    return presentValue;
+  };
+
+  const epsilon = 1e-11;
+  const maxIterations = 100;
+  const minYield = -frequency + 1e-10;
+  const step = 0.01;
+
+  let y0 = Math.max(rate, minYield + step);
+  let f0 = priceFromYield(y0) - pr;
+  let y1 = y0 + (f0 > 0 ? step : -step);
+  y1 = Math.max(y1, minYield);
+  let f1 = priceFromYield(y1) - pr;
+
+  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+    if (Math.abs(f1) < epsilon) {
+      return normalizeNegativeZero(y1);
+    }
+
+    if (f1 === f0) {
+      y0 = Math.max(y0 + step, minYield);
+      f0 = priceFromYield(y0) - pr;
+      if (f1 === f0) {
+        throw new RangeError(
+          "Cannot calculate YIELD with the provided values.",
+        );
+      }
+    }
+
+    let y2 = y1 - ((y1 - y0) * f1) / (f1 - f0);
+    y2 = Math.max(y2, minYield);
+    const f2 = priceFromYield(y2) - pr;
+
+    if (Math.abs(f2) < epsilon) {
+      return normalizeNegativeZero(y2);
+    }
+
+    y0 = y1;
+    f0 = f1;
+    y1 = y2;
+    f1 = f2;
+  }
+
+  throw new RangeError("Maximum iterations exceeded while calculating YIELD.");
+}
+
+/** @param {Date} date */
+function lastDayOfMonthUtc(date) {
+  return new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0),
+  ).getUTCDate();
+}
+
+/**
+ * Month arithmetic that preserves end-of-month behavior for coupon schedules.
+ *
+ * @param {Date} date
+ * @param {number} months
+ */
+function addMonthsUtc(date, months) {
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth();
+  const day = date.getUTCDate();
+  const isEndOfMonth = day === lastDayOfMonthUtc(date);
+
+  const monthIndex = month + months;
+  const newYear = year + Math.floor(monthIndex / 12);
+  const newMonth = ((monthIndex % 12) + 12) % 12;
+  const monthEndDay = new Date(Date.UTC(newYear, newMonth + 1, 0)).getUTCDate();
+  const newDay = isEndOfMonth ? monthEndDay : Math.min(day, monthEndDay);
+
+  return new Date(Date.UTC(newYear, newMonth, newDay));
+}
+
+/**
+ * @param {Date} settlementDate
+ * @param {Date} maturityDate
+ * @param {number} monthsPerCoupon
+ */
+function getCouponBounds(settlementDate, maturityDate, monthsPerCoupon) {
+  let nextCouponDate = new Date(maturityDate.getTime());
+  let previousCouponDate = addMonthsUtc(nextCouponDate, -monthsPerCoupon);
+
+  while (settlementDate < previousCouponDate) {
+    nextCouponDate = previousCouponDate;
+    previousCouponDate = addMonthsUtc(nextCouponDate, -monthsPerCoupon);
+  }
+
+  // Excel treats settlement on a coupon date as the start of the next period.
+  if (settlementDate >= nextCouponDate) {
+    previousCouponDate = nextCouponDate;
+    nextCouponDate = addMonthsUtc(nextCouponDate, monthsPerCoupon);
+  }
+
+  return { previousCouponDate, nextCouponDate };
+}
+
+/**
+ * @param {Date} nextCouponDate
+ * @param {Date} maturityDate
+ * @param {number} monthsPerCoupon
+ */
+function couponsRemaining(nextCouponDate, maturityDate, monthsPerCoupon) {
+  let n = 1;
+  let current = new Date(nextCouponDate.getTime());
+
+  while (current < maturityDate) {
+    current = addMonthsUtc(current, monthsPerCoupon);
+    n += 1;
+  }
+
+  return n;
+}
+
+/**
+ * @param {Date} settlementDate
+ * @param {Date} nextCouponDate
+ * @param {0|1|2|3|4} basis
+ */
+function coupdaysnc(settlementDate, nextCouponDate, basis) {
+  if (basis === 0) {
+    return days360Us(settlementDate, nextCouponDate);
+  }
+
+  if (basis === 4) {
+    return days360Eu(settlementDate, nextCouponDate);
+  }
+
+  return actualDays(settlementDate, nextCouponDate);
+}
+
+/**
+ * @param {Date} previousCouponDate
+ * @param {Date} settlementDate
+ * @param {0|1|2|3|4} basis
+ */
+function coupdaybs(previousCouponDate, settlementDate, basis) {
+  if (basis === 0) {
+    return days360Us(previousCouponDate, settlementDate);
+  }
+
+  if (basis === 4) {
+    return days360Eu(previousCouponDate, settlementDate);
+  }
+
+  return actualDays(previousCouponDate, settlementDate);
+}
+
+/**
+ * @param {Date} previousCouponDate
+ * @param {Date} nextCouponDate
+ * @param {number} frequency
+ * @param {0|1|2|3|4} basis
+ */
+function coupdays(previousCouponDate, nextCouponDate, frequency, basis) {
+  if (basis === 0 || basis === 4) {
+    return 360 / frequency;
+  }
+
+  if (basis === 3) {
+    return 365 / frequency;
+  }
+
+  return actualDays(previousCouponDate, nextCouponDate);
+}
+
+/**
+ * Excel/NASD 30/360 day count.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ */
+function days360Us(start, end) {
+  let d1 = start.getUTCDate();
+  let d2 = end.getUTCDate();
+  const m1 = start.getUTCMonth() + 1;
+  const m2 = end.getUTCMonth() + 1;
+  const y1 = start.getUTCFullYear();
+  const y2 = end.getUTCFullYear();
+
+  const startIsMonthEnd = d1 === lastDayOfMonthUtc(start);
+  const endIsMonthEnd = d2 === lastDayOfMonthUtc(end);
+
+  if (m1 === 2 && startIsMonthEnd) {
+    d1 = 30;
+  }
+  if (m2 === 2 && endIsMonthEnd && m1 === 2 && startIsMonthEnd) {
+    d2 = 30;
+  }
+
+  if (d2 === 31 && d1 >= 30) {
+    d2 = 30;
+  }
+  if (d1 === 31) {
+    d1 = 30;
+  }
+
+  return 360 * (y2 - y1) + 30 * (m2 - m1) + (d2 - d1);
+}
+
+/**
+ * European 30/360 day count.
+ *
+ * @param {Date} start
+ * @param {Date} end
+ */
+function days360Eu(start, end) {
+  let d1 = start.getUTCDate();
+  let d2 = end.getUTCDate();
+
+  if (d1 === 31) {
+    d1 = 30;
+  }
+  if (d2 === 31) {
+    d2 = 30;
+  }
+
+  const m1 = start.getUTCMonth() + 1;
+  const m2 = end.getUTCMonth() + 1;
+  const y1 = start.getUTCFullYear();
+  const y2 = end.getUTCFullYear();
+
+  return 360 * (y2 - y1) + 30 * (m2 - m1) + (d2 - d1);
+}
+
+/**
+ * @param {Date} start
+ * @param {Date} end
+ */
+function actualDays(start, end) {
+  const msPerDay = 24 * 60 * 60 * 1000;
+  return (end.getTime() - start.getTime()) / msPerDay;
+}
+
+/** @param {Date} value */
+function toUtcDate(value) {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new RangeError("Settlement and maturity must be valid Date objects.");
+  }
+
+  return new Date(
+    Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate()),
+  );
+}
+
+/** @param {number} value */
+function normalizeNegativeZero(value) {
+  return Object.is(value, -0) ? 0 : value;
+}