@pyverret/ratejs 1.1.0 → 1.1.2

package/dist/index.js

@@ -185,32 +185,31 @@ function hasPositiveAndNegative(cashFlows) {
   return false;
 }
 function findBracket(fn, lowerBound, upperBound) {
-  const fLower = fn(lowerBound);
-  const fUpper = fn(upperBound);
-  if (!Number.isFinite(fLower) || !Number.isFinite(fUpper)) return void 0;
-  if (fLower === 0) return { lower: lowerBound, upper: lowerBound };
-  if (fUpper === 0) return { lower: upperBound, upper: upperBound };
-  if (fLower * fUpper < 0) return { lower: lowerBound, upper: upperBound };
+  const scan = (start, end, segments = 200) => {
+    let prevX;
+    let prevValue;
+    for (let i = 0; i <= segments; i++) {
+      const x = start + (end - start) * i / segments;
+      const value = fn(x);
+      if (!Number.isFinite(value)) continue;
+      if (value === 0) return { lower: x, upper: x };
+      if (prevX !== void 0 && prevValue !== void 0 && prevValue * value < 0) {
+        return { lower: prevX, upper: x };
+      }
+      prevX = x;
+      prevValue = value;
+    }
+    return void 0;
+  };
   let lower = lowerBound;
   let upper = upperBound;
-  let fLo = fLower;
-  let fHi = fUpper;
   for (let i = 0; i < 20; i++) {
-    const nextLower = Math.max(-0.999999999, (lower - 1) / 2);
-    const fNextLower = fn(nextLower);
-    if (Number.isFinite(fNextLower) && fNextLower * fHi < 0) {
-      return { lower: nextLower, upper };
-    }
-    if (Number.isFinite(fNextLower)) {
-      lower = nextLower;
-      fLo = fNextLower;
-    }
+    const bracket = scan(lower, upper);
+    if (bracket !== void 0) return bracket;
+    lower = Math.max(-0.999999999, (lower - 1) / 2);
     upper = upper * 2 + 1;
-    fHi = fn(upper);
-    if (!Number.isFinite(fHi)) continue;
-    if (fLo * fHi < 0) return { lower, upper };
   }
-  return void 0;
+  return scan(lower, upper, 400);
 }
 function irr(params) {
   const {
@@ -300,6 +299,11 @@ function paymentFromPresentValue(params) {
 }
 
 // src/interest/periodsToReachGoal.ts
+function assertContributionTiming(value, name) {
+  if (value !== "end" && value !== "begin") {
+    throw new RangeError(`${name} must be "end" or "begin"`);
+  }
+}
 function periodsToReachGoal(params) {
   const {
     principal,
@@ -307,13 +311,16 @@ function periodsToReachGoal(params) {
     rate: rate2,
     timesPerYear,
     contributionPerPeriod = 0,
-    contributionTiming = "end"
+    contributionTiming = "end",
+    maxPeriods = 1e5
   } = params;
   assertNonNegative(principal, "principal");
   assertNonNegative(targetFutureValue, "targetFutureValue");
   assertFiniteNumber(rate2, "rate");
   assertPositive(timesPerYear, "timesPerYear");
   assertNonNegative(contributionPerPeriod, "contributionPerPeriod");
+  assertPositive(maxPeriods, "maxPeriods");
+  assertContributionTiming(contributionTiming, "contributionTiming");
   if (targetFutureValue <= principal) return 0;
   const r = rate2 / timesPerYear;
   if (r <= -1) {
@@ -333,13 +340,13 @@ function periodsToReachGoal(params) {
   }
   let fv2 = principal;
   let periods = 0;
-  const maxPeriods = 1e4;
   while (fv2 < targetFutureValue && periods < maxPeriods) {
     if (contributionTiming === "begin") fv2 += contributionPerPeriod;
     fv2 = fv2 * (1 + r) + (contributionTiming === "end" ? contributionPerPeriod : 0);
     periods++;
   }
-  return fv2 >= targetFutureValue ? periods : Number.POSITIVE_INFINITY;
+  if (fv2 >= targetFutureValue) return periods;
+  throw new RangeError("maxPeriods exceeded before reaching target");
 }
 
 // src/interest/presentValue.ts
@@ -369,22 +376,46 @@ function presentValueOfAnnuity(params) {
 }
 
 // src/interest/rateToReachGoal.ts
+function assertContributionTiming2(value, name) {
+  if (value !== "end" && value !== "begin") {
+    throw new RangeError(`${name} must be "end" or "begin"`);
+  }
+}
 function rateToReachGoal(params) {
   const {
     principal,
     targetFutureValue,
     periods,
     contributionPerPeriod = 0,
-    contributionTiming = "end"
+    contributionTiming = "end",
+    lowerBound = -0.99,
+    upperBound = 10,
+    maxIterations = 100,
+    tolerance = 1e-10
   } = params;
   assertNonNegative(principal, "principal");
   assertNonNegative(targetFutureValue, "targetFutureValue");
   assertPositive(periods, "periods");
   assertNonNegative(contributionPerPeriod, "contributionPerPeriod");
-  if (periods === 0) return 0;
+  assertFiniteNumber(lowerBound, "lowerBound");
+  assertFiniteNumber(upperBound, "upperBound");
+  assertFiniteNumber(maxIterations, "maxIterations");
+  assertFiniteNumber(tolerance, "tolerance");
+  assertContributionTiming2(contributionTiming, "contributionTiming");
+  if (lowerBound <= -1) throw new RangeError("lowerBound must be > -1");
+  if (upperBound <= lowerBound) throw new RangeError("upperBound must be greater than lowerBound");
+  if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
+    throw new RangeError("maxIterations must be a positive integer");
+  }
+  if (tolerance <= 0) throw new RangeError("tolerance must be > 0");
   if (targetFutureValue <= principal && contributionPerPeriod === 0) return 0;
   if (contributionPerPeriod === 0) {
     if (targetFutureValue <= principal) return 0;
+    if (principal === 0) {
+      throw new RangeError(
+        "rateToReachGoal is undefined when principal is 0 and contributions are 0"
+      );
+    }
     return (targetFutureValue / principal) ** (1 / periods) - 1;
   }
   const dueFactor = contributionTiming === "begin" ? 1 : 0;
@@ -402,23 +433,56 @@ function rateToReachGoal(params) {
   };
   const initialGuess = (targetFutureValue / (principal + contributionPerPeriod * periods)) ** (1 / periods) - 1;
   const newton = newtonRaphson({
-    initialGuess: Number.isFinite(initialGuess) ? Math.max(initialGuess, -0.99) : 0.01,
+    initialGuess: Number.isFinite(initialGuess) ? Math.max(initialGuess, lowerBound) : 0.01,
     fn,
     derivative,
-    tolerance: 1e-10,
-    maxIterations: 100,
-    min: -0.99,
-    max: 10
+    tolerance,
+    maxIterations,
+    min: lowerBound,
+    max: upperBound
   });
   if (newton !== void 0) return newton;
+  const bracket = findBracket2(fn, lowerBound, upperBound);
+  if (bracket === void 0) {
+    throw new RangeError("rateToReachGoal did not converge within search bounds");
+  }
+  if (bracket.lower === bracket.upper) return bracket.lower;
   const bisected = bisection({
     fn,
-    lower: -0.99,
-    upper: 10,
-    tolerance: 1e-10,
-    maxIterations: 200
+    lower: bracket.lower,
+    upper: bracket.upper,
+    tolerance,
+    maxIterations: maxIterations * 2
   });
-  return bisected ?? Number.NaN;
+  if (bisected !== void 0) return bisected;
+  throw new RangeError("rateToReachGoal did not converge");
+}
+function findBracket2(fn, lowerBound, upperBound) {
+  const scan = (start, end, segments = 200) => {
+    let prevX;
+    let prevValue;
+    for (let i = 0; i <= segments; i++) {
+      const x = start + (end - start) * i / segments;
+      const value = fn(x);
+      if (!Number.isFinite(value)) continue;
+      if (value === 0) return { lower: x, upper: x };
+      if (prevX !== void 0 && prevValue !== void 0 && prevValue * value < 0) {
+        return { lower: prevX, upper: x };
+      }
+      prevX = x;
+      prevValue = value;
+    }
+    return void 0;
+  };
+  let lower = lowerBound;
+  let upper = upperBound;
+  for (let i = 0; i < 20; i++) {
+    const bracket = scan(lower, upper);
+    if (bracket !== void 0) return bracket;
+    lower = Math.max(-0.999999999, (lower - 1) / 2);
+    upper = upper * 2 + 1;
+  }
+  return scan(lower, upper, 400);
 }
 
 // src/interest/realReturn.ts
@@ -448,8 +512,12 @@ function annuityDueFactor(ratePerPeriod, timing) {
   return timing === "begin" ? 1 + ratePerPeriod : 1;
 }
 function futureValueFromCashFlows(ratePerPeriod, periods, payment, presentValue2, timing) {
+  if (ratePerPeriodIsInvalidForDomain(ratePerPeriod)) {
+    throw new RangeError("ratePerPeriod must be > -1");
+  }
   if (ratePerPeriod === 0) return -(presentValue2 + payment * periods);
   const growth = (1 + ratePerPeriod) ** periods;
+  if (!Number.isFinite(growth) || growth <= 0) return Number.NaN;
   const paymentFv = payment * ((growth - 1) / ratePerPeriod) * annuityDueFactor(ratePerPeriod, timing);
   return -(presentValue2 * growth + paymentFv);
 }
@@ -460,7 +528,11 @@ function fv(params) {
   assertFiniteNumber(payment, "payment");
   assertFiniteNumber(presentValue2, "presentValue");
   assertTiming(timing, "timing");
-  return futureValueFromCashFlows(ratePerPeriod, periods, payment, presentValue2, timing);
+  const value = futureValueFromCashFlows(ratePerPeriod, periods, payment, presentValue2, timing);
+  if (!Number.isFinite(value)) {
+    throw new RangeError("Numerical instability for given inputs");
+  }
+  return value;
 }
 function pv(params) {
   const { ratePerPeriod, periods, payment = 0, futureValue: futureValue2 = 0, timing = "end" } = params;
@@ -469,10 +541,20 @@ function pv(params) {
   assertFiniteNumber(payment, "payment");
   assertFiniteNumber(futureValue2, "futureValue");
   assertTiming(timing, "timing");
+  if (ratePerPeriodIsInvalidForDomain(ratePerPeriod)) {
+    throw new RangeError("ratePerPeriod must be > -1");
+  }
   if (ratePerPeriod === 0) return -(futureValue2 + payment * periods);
   const growth = (1 + ratePerPeriod) ** periods;
+  if (!Number.isFinite(growth) || growth <= 0) {
+    throw new RangeError("Numerical instability for given ratePerPeriod/periods");
+  }
   const paymentPv = payment * (1 - 1 / growth) / ratePerPeriod * annuityDueFactor(ratePerPeriod, timing);
-  return -futureValue2 / growth - paymentPv;
+  const value = -futureValue2 / growth - paymentPv;
+  if (!Number.isFinite(value)) {
+    throw new RangeError("Numerical instability for given inputs");
+  }
+  return value;
 }
 function pmt(params) {
   const { ratePerPeriod, periods, presentValue: presentValue2, futureValue: futureValue2 = 0, timing = "end" } = params;
@@ -481,11 +563,21 @@ function pmt(params) {
   assertFiniteNumber(presentValue2, "presentValue");
   assertFiniteNumber(futureValue2, "futureValue");
   assertTiming(timing, "timing");
+  if (ratePerPeriodIsInvalidForDomain(ratePerPeriod)) {
+    throw new RangeError("ratePerPeriod must be > -1");
+  }
   if (ratePerPeriod === 0) return -(presentValue2 + futureValue2) / periods;
   const growth = (1 + ratePerPeriod) ** periods;
+  if (!Number.isFinite(growth) || growth <= 0) {
+    throw new RangeError("Numerical instability for given ratePerPeriod/periods");
+  }
   const numerator = -(futureValue2 + presentValue2 * growth) * ratePerPeriod;
   const denominator = (growth - 1) * annuityDueFactor(ratePerPeriod, timing);
-  return numerator / denominator;
+  const value = numerator / denominator;
+  if (!Number.isFinite(value)) {
+    throw new RangeError("Numerical instability for given inputs");
+  }
+  return value;
 }
 function nper(params) {
   const { ratePerPeriod, payment, presentValue: presentValue2, futureValue: futureValue2 = 0, timing = "end" } = params;
@@ -606,13 +698,21 @@ function findRateBracket(fn, lowerBound, upperBound) {
 function loanPayment(params) {
   const { principal, annualRate, paymentsPerYear, years } = params;
   assertNonNegative(principal, "principal");
+  assertFiniteNumber(annualRate, "annualRate");
   assertPositive(paymentsPerYear, "paymentsPerYear");
   assertNonNegative(years, "years");
   const n = Math.round(paymentsPerYear * years);
   if (n === 0) return 0;
   const r = annualRate / paymentsPerYear;
+  if (r <= -1) {
+    throw new RangeError("annualRate / paymentsPerYear must be > -1");
+  }
   if (r === 0) return principal / n;
-  return r * principal / (1 - (1 + r) ** -n);
+  const value = r * principal / (1 - (1 + r) ** -n);
+  if (!Number.isFinite(value)) {
+    throw new RangeError("Numerical instability for given inputs");
+  }
+  return value;
 }
 
 // src/loans/amortizationSchedule.ts
@@ -710,13 +810,16 @@ function roundToCurrency(params) {
   const factor = 10 ** d;
   if (mode === "half-even") {
     const scaled = value * factor;
-    const rounded = Math.round(scaled);
-    const remainder = Math.abs(scaled - rounded);
-    if (remainder === 0.5) {
-      const down = Math.floor(scaled);
-      return (down % 2 === 0 ? down : down + 1) / factor;
+    const sign = scaled < 0 ? -1 : 1;
+    const absScaled = Math.abs(scaled);
+    const floorAbs = Math.floor(absScaled);
+    const fraction = absScaled - floorAbs;
+    const epsilon = 1e-12;
+    if (Math.abs(fraction - 0.5) <= epsilon) {
+      const nearestEven = floorAbs % 2 === 0 ? floorAbs : floorAbs + 1;
+      return sign * nearestEven / factor;
     }
-    return rounded / factor;
+    return Math.round(scaled) / factor;
   }
   return Math.round(value * factor) / factor;
 }