@travishorn/financejs 1.18.0 → 1.19.1

package/README.md

@@ -113,7 +113,7 @@ Tiers 1-3 are complete.
 - **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
+- **Tier 5:** ✓coupdaybs, ✓coupdays, ✓coupdaysnc, all others
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travishorn/financejs",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "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,74 @@
+import {
+  actualDays,
+  days360Eu,
+  days360Us,
+  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,
+  );
+
+  if (normalizedBasis === 0) {
+    return days360Us(previousCouponDate, settlementDate);
+  }
+
+  if (normalizedBasis === 4) {
+    return days360Eu(previousCouponDate, settlementDate);
+  }
+
+  return actualDays(previousCouponDate, settlementDate);
+}

package/src/coupdays.js

@@ -0,0 +1,68 @@
+import { actualDays, 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,
+  );
+
+  if (normalizedBasis === 0 || normalizedBasis === 2 || normalizedBasis === 4) {
+    return 360 / frequency;
+  }
+
+  if (normalizedBasis === 3) {
+    return 365 / frequency;
+  }
+
+  return actualDays(previousCouponDate, nextCouponDate);
+}

package/src/coupdaysnc.js

@@ -0,0 +1,73 @@
+import {
+  actualDays,
+  days360Eu,
+  days360Us,
+  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,
+  );
+
+  if (normalizedBasis === 0) {
+    return days360Us(settlementDate, nextCouponDate);
+  }
+
+  if (normalizedBasis === 4) {
+    return days360Eu(settlementDate, nextCouponDate);
+  }
+
+  return actualDays(settlementDate, nextCouponDate);
+}

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

package/src/price.js

@@ -1,12 +1,13 @@
 import {
-  coupdaybs,
-  coupdays,
-  coupdaysnc,
+  actualDays,
   couponsRemaining,
   getCouponBounds,
   normalizeZero,
   toUtcDate,
 } from "./util.js";
+import { coupdaybs } from "./coupdaybs.js";
+import { coupdays } from "./coupdays.js";
+import { coupdaysnc } from "./coupdaysnc.js";
 
 /**
  * Calculates the price per $100 face value of a security that pays periodic
@@ -106,14 +107,18 @@ export function price(
     monthsPerCoupon,
   );
 
-  const a = coupdaybs(previousCouponDate, settlementDate, normalizedBasis);
-  let dsc = coupdaysnc(settlementDate, nextCouponDate, normalizedBasis);
-  const e = coupdays(
-    previousCouponDate,
-    nextCouponDate,
+  const a = coupdaybs(settlementDate, maturityDate, frequency, normalizedBasis);
+  let dsc = coupdaysnc(
+    settlementDate,
+    maturityDate,
     frequency,
     normalizedBasis,
   );
+  let e = coupdays(settlementDate, maturityDate, frequency, normalizedBasis);
+
+  if (normalizedBasis === 2) {
+    e = actualDays(previousCouponDate, nextCouponDate);
+  }
 
   if (normalizedBasis === 3) {
     dsc = e - a;

package/src/util.js

@@ -204,96 +204,6 @@ export function couponsRemaining(
   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.
  *

package/src/yield_.js

@@ -1,12 +1,13 @@
 import {
-  coupdaybs,
-  coupdays,
-  coupdaysnc,
+  actualDays,
   couponsRemaining,
   getCouponBounds,
   normalizeZero,
   toUtcDate,
 } from "./util.js";
+import { coupdaybs } from "./coupdaybs.js";
+import { coupdays } from "./coupdays.js";
+import { coupdaysnc } from "./coupdaysnc.js";
 
 /**
  * Calculates the yield on a security that pays periodic interest. Use to
@@ -106,14 +107,18 @@ export function yield_(
     monthsPerCoupon,
   );
 
-  const a = coupdaybs(previousCouponDate, settlementDate, normalizedBasis);
-  let dsc = coupdaysnc(settlementDate, nextCouponDate, normalizedBasis);
-  const e = coupdays(
-    previousCouponDate,
-    nextCouponDate,
+  const a = coupdaybs(settlementDate, maturityDate, frequency, normalizedBasis);
+  let dsc = coupdaysnc(
+    settlementDate,
+    maturityDate,
     frequency,
     normalizedBasis,
   );
+  let e = coupdays(settlementDate, maturityDate, frequency, normalizedBasis);
+
+  if (normalizedBasis === 2) {
+    e = actualDays(previousCouponDate, nextCouponDate);
+  }
 
   if (normalizedBasis === 3) {
     dsc = e - a;