@travishorn/financejs 1.18.0 → 1.19.0

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.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/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,4 +1,5 @@
 import {
+  actualDays,
   coupdaybs,
   coupdays,
   coupdaysnc,
@@ -108,13 +109,17 @@ export function price(
 
   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;
   }

package/src/util.js

@@ -283,7 +283,7 @@ export function coupdaybs(previousCouponDate, settlementDate, basis) {
  * 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) {
+  if (basis === 0 || basis === 2 || basis === 4) {
     return 360 / frequency;
   }
 

package/src/yield_.js

@@ -1,4 +1,5 @@
 import {
+  actualDays,
   coupdaybs,
   coupdays,
   coupdaysnc,
@@ -108,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;
   }