@travishorn/financejs 1.16.0 → 1.18.0

package/README.md

@@ -111,7 +111,7 @@ Tiers 1-3 are complete.
 - **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 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.16.0",
+  "version": "1.18.0",
   "description": "Modern JavaScript time value of money and cash-flow financial formulas with Excel-style behavior.",
   "repository": {
     "type": "git",

package/src/fv.js

@@ -1,4 +1,4 @@
-import { normalizeZero } from "./normalizeZero.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Calculates the future value of an investment based on a constant interest

package/src/index.js

@@ -15,6 +15,7 @@ export { nominal } from "./nominal.js";
 export { nper } from "./nper.js";
 export { npv } from "./npv.js";
 export { pduration } from "./pduration.js";
+export { price } from "./price.js";
 export { pmt } from "./pmt.js";
 export { ppmt } from "./ppmt.js";
 export { pv } from "./pv.js";
@@ -25,3 +26,4 @@ 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/nper.js

@@ -1,4 +1,4 @@
-import { normalizeZero } from "./normalizeZero.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Calculates the number of periods for an investment based on periodic,

package/src/pmt.js

@@ -1,4 +1,4 @@
-import { normalizeZero } from "./normalizeZero.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Calculates the payment for a loan based on constant payments and a constant

package/src/ppmt.js

@@ -1,6 +1,6 @@
 import { ipmt } from "./ipmt.js";
-import { normalizeZero } from "./normalizeZero.js";
 import { pmt } from "./pmt.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Calculates the payment on the principal for a given period for an investment

package/src/price.js

@@ -0,0 +1,144 @@
+import {
+  coupdaybs,
+  coupdays,
+  coupdaysnc,
+  couponsRemaining,
+  getCouponBounds,
+  normalizeZero,
+  toUtcDate,
+} from "./util.js";
+
+/**
+ * Calculates the price per $100 face value of a security that pays periodic
+ * interest.
+ *
+ * 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 `yld` < `0` or if `rate` < `0`, an error is thrown.
+ * - 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.
+ * - When N > 1 (N is the number of coupons payable between the settlement date
+ *   and redemption date), the calculation is: `PRICE =[redemption / (1 +
+ *   yld/frequency)^(N-1 + DSC/E)] +[SUM(k=1 to N) (100 * rate/frequency) / (1 +
+ *   yld/frequency)^(k-1 + DSC/E)] - (100 * rate/frequency * A/E)`, where:
+ *    - DSC = number of days from settlement to next coupon date.
+ *    - E = number of days in coupon period in which the settlement date falls.
+ *    - A = number of days from beginning of coupon period to settlement date.
+ * - When N = 1, the calculation is: `DSR = E - A; T1 = 100 * (rate / frequency)
+ *   + redemption; T2 = (yld / frequency) * (DSR / E) + 1; T3 = 100 * (rate /
+ *   frequency) * (A / E); Price = (T1 / T2) - T3`.
+ *
+ * @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} yld - The security's annual yield.
+ * @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 price per $100 face value
+ *
+ * @example
+ * price(new Date("2008-02-15"), new Date("2017-11-15"), 0.0575, 0.065, 100, 2, 0); // 94.63436162
+ */
+export function price(
+  settlement,
+  maturity,
+  rate,
+  yld,
+  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 || yld < 0) {
+    throw new RangeError(
+      "Rate and yield must be greater than or equal to zero.",
+    );
+  }
+
+  if (redemption <= 0) {
+    throw new RangeError("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 t1 = coupon + redemption;
+    const t2 = (yld / frequency) * (dsc / e) + 1;
+    const t3 = coupon * (a / e);
+    return normalizeZero(t1 / t2 - t3);
+  }
+
+  const base = 1 + yld / 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 normalizeZero(presentValue);
+}

package/src/pv.js

@@ -1,4 +1,4 @@
-import { normalizeZero } from "./normalizeZero.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Calculates the present value of a loan or an investment, based on a constant

package/src/rate.js

@@ -1,4 +1,4 @@
-import { normalizeZero } from "./normalizeZero.js";
+import { normalizeZero } from "./util.js";
 
 /**
  * Evaluates the annuity equation for a candidate interest rate.

package/src/util.js

@@ -0,0 +1,342 @@
+/**
+ * Gets the last calendar day number for the month that contains `date`.
+ *
+ * This helper is UTC-based, so results are not affected by local timezone or
+ * daylight-saving transitions.
+ *
+ * @param {Date} date - The date whose month should be inspected.
+ * @returns {number} The month-end day of month, from 28 to 31.
+ *
+ * @example
+ * lastDayOfMonthUtc(new Date("2024-02-10")); // 29
+ * lastDayOfMonthUtc(new Date("2023-02-10")); // 28
+ */
+export function lastDayOfMonthUtc(date) {
+  return new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0),
+  ).getUTCDate();
+}
+
+/**
+ * Adds or subtracts whole months from a UTC date while preserving end-of-month
+ * behavior.
+ *
+ * If the input date is the last day of its month, the result is also forced to
+ * the last day of the destination month. Otherwise, the day is clamped to the
+ * destination month when needed (for example, Jan 30 + 1 month => Feb 28/29).
+ *
+ * @param {Date} date - The starting date.
+ * @param {number} months - Number of months to add. Use negative values to
+ * subtract months.
+ * @returns {Date} A new UTC date shifted by `months`.
+ *
+ * @example
+ * addMonthsUtc(new Date("2021-01-31"), 1); // 2021-02-28T00:00:00.000Z
+ * addMonthsUtc(new Date("2024-01-31"), 1); // 2024-02-29T00:00:00.000Z
+ */
+export 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));
+}
+
+/**
+ * Computes day count using Excel/NASD 30/360 convention.
+ *
+ * This convention applies special normalization around month-end boundaries,
+ * especially for February and day 31 handling, to produce a synthetic
+ * 360-day-year day count.
+ *
+ * @param {Date} start - Start date (inclusive boundary for convention logic).
+ * @param {Date} end - End date.
+ * @returns {number} Day count between `start` and `end` under US 30/360 rules.
+ *
+ * @example
+ * days360Us(new Date("2024-01-30"), new Date("2024-03-31")); // 60
+ */
+export 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);
+}
+
+/**
+ * Computes day count using European 30/360 convention.
+ *
+ * Unlike NASD 30/360, this method simply converts day 31 to day 30 for both
+ * dates, then calculates using a 360-day year basis.
+ *
+ * @param {Date} start - Start date.
+ * @param {Date} end - End date.
+ * @returns {number} Day count between `start` and `end` under EU 30/360 rules.
+ *
+ * @example
+ * days360Eu(new Date("2024-01-31"), new Date("2024-03-31")); // 60
+ */
+export 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);
+}
+
+/**
+ * Computes the actual elapsed days between two dates using UTC timestamps.
+ *
+ * @param {Date} start - Start date.
+ * @param {Date} end - End date.
+ * @returns {number} Exact day difference as `(end - start)` in days.
+ *
+ * @example
+ * actualDays(new Date("2024-01-01"), new Date("2024-01-11")); // 10
+ */
+export function actualDays(start, end) {
+  const msPerDay = 24 * 60 * 60 * 1000;
+  return (end.getTime() - start.getTime()) / msPerDay;
+}
+
+/**
+ * Finds coupon period boundaries around a settlement date.
+ *
+ * Starting from maturity and stepping backward by coupon interval, this helper
+ * returns the coupon date immediately before settlement and the next coupon
+ * date after settlement. If settlement lands exactly on a coupon date, it is
+ * treated as the start of the next period (Excel-compatible behavior).
+ *
+ * @param {Date} settlementDate - Security settlement date.
+ * @param {Date} maturityDate - Security maturity date.
+ * @param {number} monthsPerCoupon - Coupon interval in months (e.g., 12, 6, or
+ * 3).
+ * @returns {{ previousCouponDate: Date, nextCouponDate: Date }} Coupon bounds
+ * containing settlement.
+ *
+ * @example
+ * getCouponBounds(new Date("2021-01-15"), new Date("2022-01-31"), 6);
+ */
+export 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 };
+}
+
+/**
+ * Counts remaining coupon payments from `nextCouponDate` through maturity.
+ *
+ * The count includes the coupon on `nextCouponDate` itself, then steps by the
+ * coupon interval until the maturity date is reached.
+ *
+ * @param {Date} nextCouponDate - Next coupon date after settlement.
+ * @param {Date} maturityDate - Security maturity date.
+ * @param {number} monthsPerCoupon - Coupon interval in months.
+ * @returns {number} Number of remaining coupon payments.
+ *
+ * @example
+ * couponsRemaining(new Date("2025-01-01"), new Date("2026-01-01"), 6); // 3
+ */
+export 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;
+}
+
+/**
+ * Computes days from settlement to next coupon date (`DSC`) by day-count basis.
+ *
+ * Basis mapping:
+ * - `0`: US (NASD) 30/360
+ * - `1`: Actual/actual
+ * - `2`: Actual/360
+ * - `3`: Actual/365
+ * - `4`: European 30/360
+ *
+ * @param {Date} settlementDate - Settlement date.
+ * @param {Date} nextCouponDate - Next coupon date.
+ * @param {0|1|2|3|4} basis - Day-count basis code.
+ * @returns {number} Days between settlement and next coupon under `basis`.
+ *
+ * @example
+ * coupdaysnc(new Date("2024-01-15"), new Date("2024-04-15"), 0);
+ */
+export function coupdaysnc(settlementDate, nextCouponDate, basis) {
+  if (basis === 0) {
+    return days360Us(settlementDate, nextCouponDate);
+  }
+
+  if (basis === 4) {
+    return days360Eu(settlementDate, nextCouponDate);
+  }
+
+  return actualDays(settlementDate, nextCouponDate);
+}
+
+/**
+ * Computes days from previous coupon date to settlement (`A`) by day-count
+ * basis.
+ *
+ * Basis mapping:
+ * - `0`: US (NASD) 30/360
+ * - `1`: Actual/actual
+ * - `2`: Actual/360
+ * - `3`: Actual/365
+ * - `4`: European 30/360
+ *
+ * @param {Date} previousCouponDate - Coupon date immediately before settlement.
+ * @param {Date} settlementDate - Settlement date.
+ * @param {0|1|2|3|4} basis - Day-count basis code.
+ * @returns {number} Days between previous coupon and settlement under `basis`.
+ *
+ * @example
+ * coupdaybs(new Date("2023-10-15"), new Date("2024-01-15"), 1);
+ */
+export function coupdaybs(previousCouponDate, settlementDate, basis) {
+  if (basis === 0) {
+    return days360Us(previousCouponDate, settlementDate);
+  }
+
+  if (basis === 4) {
+    return days360Eu(previousCouponDate, settlementDate);
+  }
+
+  return actualDays(previousCouponDate, settlementDate);
+}
+
+/**
+ * Computes total days in the coupon period (`E`) by basis and payment
+ * frequency.
+ *
+ * For 30/360 bases (`0` and `4`), period length is fixed at `360/frequency`.
+ * For basis `3` (Actual/365), period length is fixed at `365/frequency`.
+ * Otherwise, calendar days between coupon boundaries are used.
+ *
+ * @param {Date} previousCouponDate - Coupon date before settlement.
+ * @param {Date} nextCouponDate - Coupon date after settlement.
+ * @param {number} frequency - Coupon payments per year.
+ * @param {0|1|2|3|4} basis - Day-count basis code.
+ * @returns {number} Coupon period length in days.
+ *
+ * @example
+ * coupdays(new Date("2024-01-01"), new Date("2024-07-01"), 2, 3); // 182.5
+ */
+export function coupdays(previousCouponDate, nextCouponDate, frequency, basis) {
+  if (basis === 0 || basis === 4) {
+    return 360 / frequency;
+  }
+
+  if (basis === 3) {
+    return 365 / frequency;
+  }
+
+  return actualDays(previousCouponDate, nextCouponDate);
+}
+
+/**
+ * Converts a `Date` to a UTC-midnight date-only representation.
+ *
+ * This helper is used to remove time-of-day components so financial date
+ * calculations operate on whole UTC dates.
+ *
+ * @param {Date} value - Input date value.
+ * @returns {Date} A new date at `00:00:00.000Z` for the same UTC
+ * year/month/day.
+ * @throws {RangeError} If `value` is not a valid `Date` instance.
+ *
+ * @example
+ * toUtcDate(new Date("2024-04-03T15:45:12.250Z")); // 2024-04-03T00:00:00.000Z
+ */
+export 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()),
+  );
+}
+
+/**
+ * Normalizes zero values to ensure consistent handling of positive and negative
+ * zero in calculations.
+ *
+ * In JavaScript, +0 and -0 are distinct values that can yield different results
+ * in equality checks (e.g., Object.is(+0, -0) is false), sign checks
+ * (Math.sign), and division (1/0 vs 1/-0). This function coerces any zero input
+ * (either +0 or -0) to positive zero (+0), providing a consistent
+ * representation for downstream calculations, comparisons, and serialization.
+ *
+ * @param {number} value - The numeric value to normalize. If the value is +0 or
+ * -0, returns +0; otherwise, returns the original value.
+ * @returns {number} The normalized value, with all zeroes represented as +0.
+ *
+ * @example
+ * normalizeZero(-0); // 0
+ * normalizeZero(+0); // 0
+ * normalizeZero(5);  // 5
+ */
+export function normalizeZero(value) {
+  return value === 0 ? 0 : value;
+}

package/src/yield_.js

@@ -0,0 +1,186 @@
+import {
+  coupdaybs,
+  coupdays,
+  coupdaysnc,
+  couponsRemaining,
+  getCouponBounds,
+  normalizeZero,
+  toUtcDate,
+} from "./util.js";
+
+/**
+ * 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 normalizeZero(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 normalizeZero(y1);
+    }
+
+    if (f1 === f0) {
+      y0 = Math.max(y0 + step, minYield);
+      f0 = priceFromYield(y0) - pr;
+    }
+
+    let y2 = y1 - ((y1 - y0) * f1) / (f1 - f0);
+    y2 = Math.max(y2, minYield);
+    const f2 = priceFromYield(y2) - pr;
+
+    if (Math.abs(f2) < epsilon) {
+      return normalizeZero(y2);
+    }
+
+    y0 = y1;
+    f0 = f1;
+    y1 = y2;
+    f1 = f2;
+  }
+
+  throw new RangeError("Maximum iterations exceeded while calculating YIELD.");
+}

package/src/normalizeZero.js

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