@travishorn/financejs 1.17.1 → 1.19.0

package/README.md

@@ -111,9 +111,9 @@ 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
+- **Tier 5:** ✓coupdaybs, ✓coupdays, ✓coupdaysnc, all others
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travishorn/financejs",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "description": "Modern JavaScript time value of money and cash-flow financial formulas with Excel-style behavior.",
   "repository": {
     "type": "git",

package/src/coupdaybs.js

@@ -0,0 +1,64 @@
+import {
+  coupdaybs as coupdaybsUtil,
+  getCouponBounds,
+  toUtcDate,
+} from "./util.js";
+
+/**
+ * Returns the number of days from the beginning of the coupon period to the
+ * settlement date.
+ *
+ * Remarks:
+ * - `settlement`, `maturity`, `frequency`, and `basis` are truncated to
+ *   integers.
+ * - If `settlement` or `maturity` is not a valid date, 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`, an error is thrown.
+ * - If `settlement` >= `maturity`, an error is thrown.
+ *
+ * @param {Date} settlement - The security's settlement date.
+ * @param {Date} maturity - The security's maturity date.
+ * @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 number of days from the beginning of the coupon period
+ * to the settlement date.
+ *
+ * @example
+ * coupdaybs(new Date("2011-01-25"), new Date("2011-11-15"), 2, 1); // 71
+ */
+export function coupdaybs(settlement, maturity, 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 (![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 } = getCouponBounds(
+    settlementDate,
+    maturityDate,
+    monthsPerCoupon,
+  );
+
+  return coupdaybsUtil(previousCouponDate, settlementDate, normalizedBasis);
+}

package/src/coupdays.js

@@ -0,0 +1,69 @@
+import {
+  coupdays as coupdaysUtil,
+  getCouponBounds,
+  toUtcDate,
+} from "./util.js";
+
+/**
+ * Returns the number of days in the coupon period that contains the settlement
+ * date.
+ *
+ * Remarks:
+ * - `settlement`, `maturity`, `frequency`, and `basis` are truncated to
+ *   integers.
+ * - If `settlement` or `maturity` is not a valid date, 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`, an error is thrown.
+ * - If `settlement` >= `maturity`, an error is thrown.
+ *
+ * @param {Date} settlement - The security's settlement date.
+ * @param {Date} maturity - The security's maturity date.
+ * @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 number of days in the coupon period that contains the
+ * settlement date.
+ *
+ * @example
+ * coupdays(new Date("2011-01-25"), new Date("2011-11-15"), 2, 1); // 184
+ */
+export function coupdays(settlement, maturity, 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 (![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,
+  );
+
+  return coupdaysUtil(
+    previousCouponDate,
+    nextCouponDate,
+    frequency,
+    normalizedBasis,
+  );
+}

package/src/coupdaysnc.js

@@ -0,0 +1,63 @@
+import {
+  coupdaysnc as coupdaysncUtil,
+  getCouponBounds,
+  toUtcDate,
+} from "./util.js";
+
+/**
+ * Returns the number of days from the settlement date to the next coupon date.
+ *
+ * Remarks:
+ * - `settlement`, `maturity`, `frequency`, and `basis` are truncated to
+ *   integers.
+ * - If `settlement` or `maturity` is not a valid date, 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`, an error is thrown.
+ * - If `settlement` >= `maturity`, an error is thrown.
+ *
+ * @param {Date} settlement - The security's settlement date.
+ * @param {Date} maturity - The security's maturity date.
+ * @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 number of days from the settlement date to the next
+ * coupon date.
+ *
+ * @example
+ * coupdaysnc(new Date("2011-01-25"), new Date("2011-11-15"), 2, 1); // 113
+ */
+export function coupdaysnc(settlement, maturity, 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 (![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 { nextCouponDate } = getCouponBounds(
+    settlementDate,
+    maturityDate,
+    monthsPerCoupon,
+  );
+
+  return coupdaysncUtil(settlementDate, nextCouponDate, normalizedBasis);
+}

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

@@ -1,3 +1,6 @@
+export { coupdaybs } from "./coupdaybs.js";
+export { coupdays } from "./coupdays.js";
+export { coupdaysnc } from "./coupdaysnc.js";
 export { cumipmt } from "./cumipmt.js";
 export { cumprinc } from "./cumprinc.js";
 export { db } from "./db.js";
@@ -15,6 +18,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";

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,149 @@
+import {
+  actualDays,
+  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);
+  let e = coupdays(
+    previousCouponDate,
+    nextCouponDate,
+    frequency,
+    normalizedBasis,
+  );
+
+  if (normalizedBasis === 2) {
+    e = actualDays(previousCouponDate, nextCouponDate);
+  }
+
+  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 === 2 || 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

@@ -1,3 +1,14 @@
+import {
+  actualDays,
+  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.
@@ -98,13 +109,17 @@ export function yield_(
 
   const a = coupdaybs(previousCouponDate, settlementDate, normalizedBasis);
   let dsc = coupdaysnc(settlementDate, nextCouponDate, normalizedBasis);
-  const e = coupdays(
+  let e = coupdays(
     previousCouponDate,
     nextCouponDate,
     frequency,
     normalizedBasis,
   );
 
+  if (normalizedBasis === 2) {
+    e = actualDays(previousCouponDate, nextCouponDate);
+  }
+
   if (normalizedBasis === 3) {
     dsc = e - a;
   }
@@ -118,7 +133,7 @@ export function yield_(
       (pr / 100 + (a / e) * (rate / frequency));
     const denominator = pr / 100 + (a / e) * (rate / frequency);
     const result = (numerator / denominator) * ((frequency * e) / dsc);
-    return normalizeNegativeZero(result);
+    return normalizeZero(result);
   }
 
   /** @param {number} candidateYield */
@@ -150,17 +165,12 @@ export function yield_(
 
   for (let iteration = 0; iteration < maxIterations; iteration += 1) {
     if (Math.abs(f1) < epsilon) {
-      return normalizeNegativeZero(y1);
+      return normalizeZero(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);
@@ -168,7 +178,7 @@ export function yield_(
     const f2 = priceFromYield(y2) - pr;
 
     if (Math.abs(f2) < epsilon) {
-      return normalizeNegativeZero(y2);
+      return normalizeZero(y2);
     }
 
     y0 = y1;
@@ -179,207 +189,3 @@ export function yield_(
 
   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;
-}

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