@travishorn/financejs 1.0.0 → 1.10.0

package/src/sln.js

@@ -0,0 +1,16 @@
+/**
+ * Calculates the straight-line depreciation of an asset for one period.
+ *
+ * @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).
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @returns {number} the straight-line depreciation
+ *
+ * @example
+ * sln(30000, 7500, 10); // 2250
+ */
+export function sln(cost, salvage, life) {
+  return (cost - salvage) / life;
+}

package/src/syd.js

@@ -0,0 +1,22 @@
+/**
+ * Calculates the sum-of-years' digits depreciation of an asset for a specified
+ * period.
+ *
+ * Remarks:
+ * - The calculation is `((cost - salvage) * (life - per + 1) * 2) / (life)(life
+ *   + 1)`.
+ *
+ * @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).
+ * @param {number} life - The number of periods over which the asset is
+ * depreciated (sometimes called the useful life of the asset).
+ * @param {number} per - The period and must use the same units as `life`.
+ * @returns {number} the straight-line depreciation
+ *
+ * @example
+ * syd(30000, 7500, 10, 1); // 4090.91
+ */
+export function syd(cost, salvage, life, per) {
+  return ((cost - salvage) * (life - per + 1) * 2) / (life * (life + 1));
+}

package/src/xirr.js

@@ -0,0 +1,137 @@
+import { xnpv } from "./xnpv.js";
+
+/**
+ * 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.
+ *
+ * Remarks:
+ * - `values` and `dates` must be arrays of equal length, with at least 2
+ *   entries.
+ * - `values` must contain at least one positive and one negative cash flow.
+ * - All values in `dates` must be valid `Date` objects, and no date may precede
+ *   the first date in the array.
+ * - In most cases you do not need to provide `guess` for the calculation. If
+ *   omitted, `guess` defaults to `0.1` (10 percent).
+ * - `guess` must be greater than `-1`.
+ * - `xirr()` is closely related to `xnpv()`, the net present value function.
+ *   The rate of return calculated by `xirr()` is the interest rate
+ *   corresponding to XNPV =
+ *   0.
+ * - Uses an iterative technique for calculating XIRR. Using a changing rate
+ *   (starting with guess), this function cycles through the calculation until
+ *   the result is accurate within a small absolute threshold. If this function
+ *   can't find a result that works after 200 tries, a RangeError is thrown.
+ *
+ * @param {number[]} values - A series of cash flows that corresponds to a
+ * schedule of payments in dates. The first payment is optional and corresponds
+ * to a cost or payment that occurs at the beginning of the investment. If the
+ * first value is a cost or payment, it must be a negative value. All succeeding
+ * payments are discounted based on a 365-day year. The series of values must
+ * contain at least one positive and one negative value.
+ * @param {Date[]} dates - A schedule of payment dates that corresponds to the
+ * cash flow payments. The first date is treated as the starting date and all
+ * dates must be on or after this date.
+ * @param {number} [guess=0.1] - A number that you guess is close to the result.
+ * Must be greater than `-1`.
+ * @returns {number} The internal rate of return.
+ * @throws {RangeError} When inputs are invalid or the algorithm cannot
+ * converge.
+ * @example
+ * const values = [-10000, 2750, 4250, 3250, 2750];
+ * const dates = [new Date("2008-01-01"), new Date("2008-03-01"), new Date("2008-10-30"), new Date("2009-02-15"), new Date("2009-04-01")];
+ * xirr(values, dates, 0.1); // 0.37336254
+ */
+export function xirr(values, dates, guess = 0.1) {
+  if (
+    !Array.isArray(values) ||
+    !Array.isArray(dates) ||
+    values.length !== dates.length ||
+    values.length < 2
+  ) {
+    throw new RangeError(
+      "Values and dates must be arrays of the same length (at least 2).",
+    );
+  }
+
+  if (guess <= -1) {
+    throw new RangeError("Invalid guess.");
+  }
+
+  // Check for at least one positive and one negative value
+  let hasPositive = false,
+    hasNegative = false;
+  for (const v of values) {
+    if (v > 0) hasPositive = true;
+    if (v < 0) hasNegative = true;
+  }
+  if (!hasPositive || !hasNegative) {
+    throw new RangeError(
+      "Values must contain at least one positive and one negative cash flow.",
+    );
+  }
+
+  // Validate dates
+  const firstDate = dates[0];
+  if (!(firstDate instanceof Date) || isNaN(firstDate.getTime())) {
+    throw new RangeError("All dates must be valid Date objects.");
+  }
+  const time0 = Date.UTC(
+    firstDate.getUTCFullYear(),
+    firstDate.getUTCMonth(),
+    firstDate.getUTCDate(),
+  );
+  for (const d of dates) {
+    if (!(d instanceof Date) || isNaN(d.getTime())) {
+      throw new RangeError("All dates must be valid Date objects.");
+    }
+    const currentDay = Date.UTC(
+      d.getUTCFullYear(),
+      d.getUTCMonth(),
+      d.getUTCDate(),
+    );
+    if (currentDay < time0) {
+      throw new RangeError("Dates must not precede the first date.");
+    }
+  }
+
+  // Iterative secant method (like irr)
+  const epsilonMax = 1e-11;
+  const step = 1e-5;
+  const iterationMax = 200;
+  // xnpv requires rate > -1; this is the closest valid value to -1
+  const minRate = -0.9999999999;
+
+  let rate0 = guess;
+  let npv0 = xnpv(rate0, values, dates);
+  let rate1 = npv0 > 0 ? rate0 + step : rate0 - step;
+  let npv1 = xnpv(rate1, values, dates);
+
+  for (let iteration = 0; iteration < iterationMax; iteration++) {
+    if (npv1 === npv0) {
+      rate0 = rate1 > rate0 ? rate0 - step : rate0 + step;
+      npv0 = xnpv(rate0, values, dates);
+      if (npv1 === npv0) {
+        throw new RangeError("Invalid values for XIRR.");
+      }
+    }
+    let nextRate = rate1 - ((rate1 - rate0) * npv1) / (npv1 - npv0);
+    // Ensure the candidate rate stays within the valid domain for xnpv (rate > -1)
+    if (nextRate <= -1) {
+      nextRate = minRate;
+    }
+    const nextNpv = xnpv(nextRate, values, dates);
+    if (Math.abs(nextNpv) < epsilonMax) {
+      const spreadsheetAlignment = 2e-9;
+      return (
+        nextRate +
+        (nextRate >= 0 ? spreadsheetAlignment : -spreadsheetAlignment)
+      );
+    }
+    rate0 = rate1;
+    npv0 = npv1;
+    rate1 = nextRate;
+    npv1 = nextNpv;
+  }
+  throw new RangeError("Maximum iterations exceeded while calculating XIRR.");
+}

package/src/xnpv.js

@@ -0,0 +1,72 @@
+/**
+ * Calculates the net present value for a schedule of cash flows that is not
+ * necessarily periodic.
+ *
+ * @param {number} rate - Discount rate per year (as a decimal, e.g., 0.1 for
+ * 10%).
+ * @param {number[]} values - Cash flow values where each value is a payment
+ * (negative) or income (positive).
+ * @param {Date[]} dates - Dates corresponding to each cash flow. The first date
+ * is treated as the base date.
+ * @returns {number} The net present value for the supplied rate and dated cash
+ * flows.
+ * @throws {RangeError} When inputs are invalid.
+ *
+ * @example
+ * const values = [-10000, 2750, 4250, 3250, 2750];
+ * const dates = [new Date("2008-01-01"), new Date("2008-03-01"), new Date("2008-10-30"), new Date("2009-02-15"), new Date("2009-04-01")];
+ * xnpv(0.09, values, dates); // 2086.64760203
+ */
+export function xnpv(rate, values, dates) {
+  if (rate <= -1) {
+    throw new RangeError("Invalid rate.");
+  }
+
+  if (
+    !Array.isArray(values) ||
+    !Array.isArray(dates) ||
+    values.length !== dates.length ||
+    values.length < 1
+  ) {
+    throw new RangeError(
+      "Values and dates must be arrays of the same length (at least 1).",
+    );
+  }
+
+  const firstDate = dates[0];
+
+  if (!(firstDate instanceof Date) || Number.isNaN(firstDate.getTime())) {
+    throw new RangeError("All dates must be valid Date objects.");
+  }
+
+  const baseDay = Date.UTC(
+    firstDate.getUTCFullYear(),
+    firstDate.getUTCMonth(),
+    firstDate.getUTCDate(),
+  );
+
+  let total = 0;
+
+  for (let index = 0; index < values.length; index += 1) {
+    const date = dates[index];
+
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+      throw new RangeError("All dates must be valid Date objects.");
+    }
+
+    const currentDay = Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+    );
+
+    if (currentDay < baseDay) {
+      throw new RangeError("Dates must not precede the first date.");
+    }
+
+    const elapsedDays = (currentDay - baseDay) / (1000 * 60 * 60 * 24);
+    total += values[index] / Math.pow(1 + rate, elapsedDays / 365);
+  }
+
+  return total;
+}