@pyverret/ratejs 1.1.0 → 1.1.2

package/README.md

@@ -8,6 +8,24 @@ Lightweight, dependency-free TypeScript financial math library providing pure ca
 npm i @pyverret/ratejs
 ```
 
+## Validate Before Push
+
+```bash
+npm run validate
+```
+
+## Automated Releases
+
+Releases are managed by `semantic-release` on pushes to `main`.
+
+Required GitHub secrets:
+- `NPM_TOKEN`: npm automation token with publish access.
+
+Behavior:
+- Conventional Commits drive version bumps (`fix` = patch, `feat` = minor, `feat!` or `BREAKING CHANGE` = major).
+- Release workflow runs `npm run validate` before publishing.
+- Git tags use format `vX.Y.Z`.
+
 ## Live Demo
 
 - GitHub Pages URL: `https://pyverret.github.io/ratejs/`
@@ -44,16 +62,19 @@ const payment = pmt({
   ratePerPeriod: 0.06 / 12,
   periods: 360,
   presentValue: 250000,
-  futureValue: 0,
-  timing: "end",
+  futureValue: 0, // optional
+  timing: "end", // optional
 });
 
 const impliedRate = rate({
   periods: 360,
   payment,
   presentValue: 250000,
-  futureValue: 0,
-  timing: "end",
+  futureValue: 0, // optional
+  timing: "end", // optional
+  guess: 0.1, // optional
+  maxIterations: 100, // optional
+  tolerance: 1e-10, // optional
   lowerBound: -0.99, // optional
   upperBound: 10, // optional
 });
@@ -62,6 +83,7 @@ const impliedRate = rate({
 Edge cases:
 - `nper` throws `RangeError` when `ratePerPeriod <= -1`.
 - `rate` throws `RangeError` when no root is found within search bounds.
+- `pmt`, `pv`, and `fv` throw `RangeError` when `ratePerPeriod <= -1`.
 
 ### Interest & growth
 
@@ -88,11 +110,11 @@ presentValue({ futureValue: 5000, rate: 0.06, timesPerYear: 12, years: 5 });
 ```ts
 investmentGrowth({
   initial: 1000,
-  contributionPerPeriod: 100,
+  contributionPerPeriod: 100, // optional
   rate: 0.06,
   timesPerYear: 12,
   years: 2,
-  contributionTiming: "end", // or "begin"
+  contributionTiming: "end", // optional ("end" | "begin")
 });
 ```
 
@@ -111,13 +133,16 @@ periodsToReachGoal({
   rate: 0.06,
   timesPerYear: 12,
   contributionPerPeriod: 0, // optional
-  contributionTiming: "end",
+  contributionTiming: "end", // optional
+  maxPeriods: 100000, // optional
 });
 ```
 
 Edge cases:
 - Returns `Infinity` when the goal is unreachable.
 - Throws `RangeError` when `rate / timesPerYear <= -1`.
+- Throws `RangeError` when `maxPeriods` is exceeded for contribution-based iteration.
+- Throws `RangeError` when `contributionTiming` is not `"end"` or `"begin"`.
 
 - **`rateToReachGoal`** - Rate per period required to reach a target future value in a given number of periods.
 
@@ -126,11 +151,19 @@ rateToReachGoal({
   principal: 1000,
   targetFutureValue: 1500,
   periods: 24,
-  contributionPerPeriod: 0,
-  contributionTiming: "end",
+  contributionPerPeriod: 0, // optional
+  contributionTiming: "end", // optional
+  maxIterations: 100, // optional
+  tolerance: 1e-10, // optional
+  lowerBound: -0.99, // optional
+  upperBound: 10, // optional
 });
 ```
 
+Edge cases:
+- Throws `RangeError` when no root is found within search bounds.
+- Throws `RangeError` when `contributionTiming` is not `"end"` or `"begin"`.
+
 - **`ruleOf72`** - Approximate years to double a lump sum at a given annual rate. Optional `constant: 69` for rule of 69.
 
 ```ts
@@ -151,8 +184,8 @@ cagr({ startValue: 1000, endValue: 2000, years: 10 });
 ```ts
 irr({
   cashFlows: [-1000, 300, 400, 500],
-  guess: 0.1,
-  maxIterations: 100,
+  guess: 0.1, // optional
+  maxIterations: 100, // optional
   lowerBound: -0.99, // optional
   upperBound: 10, // optional
 });
@@ -197,7 +230,7 @@ presentValueOfAnnuity({
   paymentPerPeriod: 100,
   ratePerPeriod: 0.01,
   periods: 36,
-  timing: "end",
+  timing: "end", // optional
 });
 ```
 
@@ -208,7 +241,7 @@ paymentFromPresentValue({
   presentValue: 100000,
   ratePerPeriod: 0.005,
   periods: 360,
-  timing: "end",
+  timing: "end", // optional
 });
 ```
 
@@ -225,6 +258,9 @@ loanPayment({
 });
 ```
 
+Edge cases:
+- Throws `RangeError` when `annualRate / paymentsPerYear <= -1`.
+
 - **`amortizationSchedule`** - Full schedule: `{ paymentPerPeriod, schedule, totalPaid, totalInterest }`. Optional `extraPaymentPerPeriod`.
 
 ```ts
@@ -233,7 +269,7 @@ amortizationSchedule({
   annualRate: 0.06,
   paymentsPerYear: 12,
   years: 30,
-  extraPaymentPerPeriod: 50,
+  extraPaymentPerPeriod: 50, // optional
 });
 ```
 
@@ -270,7 +306,7 @@ Edge cases:
 
 ```ts
 roundToCurrency({ value: 2.125 }); // 2.13
-roundToCurrency({ value: 2.125, decimals: 2, mode: "half-even" });
+roundToCurrency({ value: 2.125, decimals: 2, mode: "half-even" }); // decimals/mode optional
 ```
 
 ## Design

package/dist/index.cjs

@@ -187,32 +187,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 {
@@ -302,6 +301,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,
@@ -309,13 +313,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) {
@@ -335,13 +342,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
@@ -371,22 +378,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;
@@ -404,23 +435,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
@@ -450,8 +514,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);
 }
@@ -462,7 +530,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;
@@ -471,10 +543,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;
@@ -483,11 +565,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;
@@ -608,13 +700,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
@@ -712,13 +812,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;
 }