@pyverret/ratejs 1.0.0 → 1.1.1

package/dist/index.cjs

@@ -30,14 +30,14 @@ function cagr(params) {
 
 // src/interest/compound.ts
 function compound(params) {
-  const { principal, rate, timesPerYear, years } = params;
+  const { principal, rate: rate2, timesPerYear, years } = params;
   assertNonNegative(principal, "principal");
   assertPositive(timesPerYear, "timesPerYear");
   assertNonNegative(years, "years");
-  if (rate === 0 || years === 0) return principal;
+  if (rate2 === 0 || years === 0) return principal;
   const n = timesPerYear;
   const t = years;
-  return principal * (1 + rate / n) ** (n * t);
+  return principal * (1 + rate2 / n) ** (n * t);
 }
 
 // src/interest/effectiveAnnualRate.ts
@@ -51,14 +51,14 @@ function effectiveAnnualRate(params) {
 
 // src/interest/futureValue.ts
 function futureValue(params) {
-  const { presentValue: presentValue2, rate, timesPerYear, years } = params;
+  const { presentValue: presentValue2, rate: rate2, timesPerYear, years } = params;
   assertNonNegative(presentValue2, "presentValue");
   assertPositive(timesPerYear, "timesPerYear");
   assertNonNegative(years, "years");
-  if (rate === 0 || years === 0) return presentValue2;
+  if (rate2 === 0 || years === 0) return presentValue2;
   const n = timesPerYear;
   const t = years;
-  return presentValue2 * (1 + rate / n) ** (n * t);
+  return presentValue2 * (1 + rate2 / n) ** (n * t);
 }
 
 // src/interest/inflationAdjustedAmount.ts
@@ -76,7 +76,7 @@ function investmentGrowth(params) {
   const {
     initial,
     contributionPerPeriod = 0,
-    rate,
+    rate: rate2,
     timesPerYear,
     years,
     contributionTiming = "end"
@@ -93,11 +93,11 @@ function investmentGrowth(params) {
       totalInterest: 0
     };
   }
-  const r = rate / timesPerYear;
-  const fvInitial = rate === 0 ? initial : initial * (1 + r) ** periods;
+  const r = rate2 / timesPerYear;
+  const fvInitial = rate2 === 0 ? initial : initial * (1 + r) ** periods;
   let fvContrib = 0;
   if (contributionPerPeriod !== 0) {
-    if (rate === 0) {
+    if (rate2 === 0) {
       fvContrib = contributionPerPeriod * periods;
     } else {
       const ordinary = contributionPerPeriod * (((1 + r) ** periods - 1) / r);
@@ -110,38 +110,179 @@ function investmentGrowth(params) {
   return { futureValue: futureValue2, totalContributions, totalInterest };
 }
 
+// src/utils/solvers.ts
+function newtonRaphson(params) {
+  const {
+    initialGuess,
+    fn,
+    derivative,
+    tolerance = 1e-10,
+    maxIterations = 100,
+    min = Number.NEGATIVE_INFINITY,
+    max = Number.POSITIVE_INFINITY
+  } = params;
+  let x = initialGuess;
+  for (let i = 0; i < maxIterations; i++) {
+    const value = fn(x);
+    if (!Number.isFinite(value)) return void 0;
+    if (Math.abs(value) <= tolerance) return x;
+    const slope = derivative(x);
+    if (!Number.isFinite(slope) || Math.abs(slope) < 1e-14) return void 0;
+    x -= value / slope;
+    if (x < min) x = min;
+    if (x > max) x = max;
+  }
+  return void 0;
+}
+function bisection(params) {
+  const { fn, lower, upper, tolerance = 1e-10, maxIterations = 200 } = params;
+  let a = lower;
+  let b = upper;
+  let fa = fn(a);
+  let fb = fn(b);
+  if (!Number.isFinite(fa) || !Number.isFinite(fb) || fa * fb > 0) return void 0;
+  if (Math.abs(fa) <= tolerance) return a;
+  if (Math.abs(fb) <= tolerance) return b;
+  for (let i = 0; i < maxIterations; i++) {
+    const c = (a + b) / 2;
+    const fc = fn(c);
+    if (!Number.isFinite(fc)) return void 0;
+    if (Math.abs(fc) <= tolerance || Math.abs(b - a) <= tolerance) return c;
+    if (fa * fc < 0) {
+      b = c;
+      fb = fc;
+    } else {
+      a = c;
+      fa = fc;
+    }
+  }
+  return (a + b) / 2;
+}
+
 // src/interest/irr.ts
-function npv(rate, cashFlows) {
+function npvAt(rate2, cashFlows) {
   let sum = 0;
   for (let t = 0; t < cashFlows.length; t++) {
     const cf = cashFlows[t];
-    if (cf !== void 0) sum += cf / (1 + rate) ** t;
+    if (cf !== void 0) sum += cf / (1 + rate2) ** t;
   }
   return sum;
 }
-function npvDerivative(rate, cashFlows) {
+function npvDerivativeAt(rate2, cashFlows) {
   let sum = 0;
   for (let t = 1; t < cashFlows.length; t++) {
     const cf = cashFlows[t];
-    if (cf !== void 0) sum -= t * cf / (1 + rate) ** (t + 1);
+    if (cf !== void 0) sum -= t * cf / (1 + rate2) ** (t + 1);
   }
   return sum;
 }
+function hasPositiveAndNegative(cashFlows) {
+  let hasPositive = false;
+  let hasNegative = false;
+  for (const cf of cashFlows) {
+    if (cf > 0) hasPositive = true;
+    if (cf < 0) hasNegative = true;
+    if (hasPositive && hasNegative) return true;
+  }
+  return false;
+}
+function findBracket(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);
+}
 function irr(params) {
-  const { cashFlows, guess = 0.1, maxIterations = 100 } = params;
-  if (cashFlows.length === 0) return NaN;
+  const {
+    cashFlows,
+    guess = 0.1,
+    maxIterations = 100,
+    lowerBound = -0.99,
+    upperBound = 10
+  } = params;
+  if (cashFlows.length === 0) {
+    throw new RangeError("cashFlows must contain at least one value");
+  }
+  assertFiniteNumber(guess, "guess");
+  assertFiniteNumber(maxIterations, "maxIterations");
+  assertFiniteNumber(lowerBound, "lowerBound");
+  assertFiniteNumber(upperBound, "upperBound");
+  if (maxIterations <= 0 || !Number.isInteger(maxIterations)) {
+    throw new RangeError("maxIterations must be a positive integer");
+  }
+  if (lowerBound <= -1) {
+    throw new RangeError("lowerBound must be > -1");
+  }
+  if (upperBound <= lowerBound) {
+    throw new RangeError("upperBound must be greater than lowerBound");
+  }
   for (const cf of cashFlows) assertFiniteNumber(cf, "cashFlows[]");
-  let r = guess;
-  for (let i = 0; i < maxIterations; i++) {
-    const val = npv(r, cashFlows);
-    if (Math.abs(val) < 1e-10) return r;
-    const der = npvDerivative(r, cashFlows);
-    if (!Number.isFinite(der) || Math.abs(der) < 1e-15) break;
-    r = r - val / der;
-    if (r < -0.99) r = -0.99;
-    if (r > 10) r = 10;
+  if (!hasPositiveAndNegative(cashFlows)) {
+    throw new RangeError("cashFlows must include at least one positive and one negative value");
+  }
+  const fn = (rate2) => npvAt(rate2, cashFlows);
+  const derivative = (rate2) => npvDerivativeAt(rate2, cashFlows);
+  const newton = newtonRaphson({
+    initialGuess: guess,
+    fn,
+    derivative,
+    tolerance: 1e-10,
+    maxIterations,
+    min: lowerBound,
+    max: upperBound
+  });
+  if (newton !== void 0) return newton;
+  const bracket = findBracket(fn, lowerBound, upperBound);
+  if (bracket === void 0) {
+    throw new RangeError("IRR did not converge within search bounds");
   }
-  return r;
+  if (bracket.lower === bracket.upper) return bracket.lower;
+  const bisected = bisection({
+    fn,
+    lower: bracket.lower,
+    upper: bracket.upper,
+    tolerance: 1e-10,
+    maxIterations: maxIterations * 2
+  });
+  if (bisected !== void 0) return bisected;
+  throw new RangeError("IRR did not converge");
+}
+
+// src/interest/npv.ts
+function npv(params) {
+  const { rate: rate2, cashFlows } = params;
+  assertFiniteNumber(rate2, "rate");
+  if (rate2 <= -1) throw new RangeError("rate must be > -1");
+  if (cashFlows.length === 0) return 0;
+  let sum = 0;
+  for (let t = 0; t < cashFlows.length; t++) {
+    const cf = cashFlows[t];
+    if (cf === void 0) continue;
+    assertFiniteNumber(cf, `cashFlows[${t}]`);
+    sum += cf / (1 + rate2) ** t;
+  }
+  return sum;
 }
 
 // src/interest/paymentFromPresentValue.ts
@@ -151,12 +292,12 @@ function paymentFromPresentValue(params) {
   assertNonNegative(periods, "periods");
   if (presentValue2 === 0 || periods === 0) return 0;
   if (ratePerPeriod === 0) {
-    const pmt2 = presentValue2 / periods;
-    return timing === "begin" ? pmt2 / (1 + ratePerPeriod) : pmt2;
+    const pmt3 = presentValue2 / periods;
+    return timing === "begin" ? pmt3 / (1 + ratePerPeriod) : pmt3;
   }
-  let pmt = ratePerPeriod * presentValue2 / (1 - (1 + ratePerPeriod) ** -periods);
-  if (timing === "begin") pmt /= 1 + ratePerPeriod;
-  return pmt;
+  let pmt2 = ratePerPeriod * presentValue2 / (1 - (1 + ratePerPeriod) ** -periods);
+  if (timing === "begin") pmt2 /= 1 + ratePerPeriod;
+  return pmt2;
 }
 
 // src/interest/periodsToReachGoal.ts
@@ -164,54 +305,56 @@ function periodsToReachGoal(params) {
   const {
     principal,
     targetFutureValue,
-    rate,
+    rate: rate2,
     timesPerYear,
     contributionPerPeriod = 0,
-    contributionTiming = "end"
+    contributionTiming = "end",
+    maxPeriods = 1e5
   } = params;
   assertNonNegative(principal, "principal");
   assertNonNegative(targetFutureValue, "targetFutureValue");
-  assertFiniteNumber(rate, "rate");
+  assertFiniteNumber(rate2, "rate");
   assertPositive(timesPerYear, "timesPerYear");
   assertNonNegative(contributionPerPeriod, "contributionPerPeriod");
+  assertPositive(maxPeriods, "maxPeriods");
   if (targetFutureValue <= principal) return 0;
-  const r = rate / timesPerYear;
+  const r = rate2 / timesPerYear;
   if (r <= -1) {
     throw new RangeError("rate / timesPerYear must be > -1");
   }
   if (contributionPerPeriod === 0) {
     if (principal === 0) return Number.POSITIVE_INFINITY;
-    if (rate === 0) return targetFutureValue <= principal ? 0 : Number.POSITIVE_INFINITY;
+    if (rate2 === 0) return targetFutureValue <= principal ? 0 : Number.POSITIVE_INFINITY;
     if (r < 0) return Number.POSITIVE_INFINITY;
     const n = Math.log(targetFutureValue / principal) / Math.log(1 + r);
     return Number.isFinite(n) && n >= 0 ? Math.ceil(n) : Number.POSITIVE_INFINITY;
   }
-  if (rate === 0) {
+  if (rate2 === 0) {
     const needed = targetFutureValue - principal;
     if (needed <= 0) return 0;
     return Math.ceil(needed / contributionPerPeriod);
   }
-  let fv = principal;
+  let fv2 = principal;
   let periods = 0;
-  const maxPeriods = 1e4;
-  while (fv < targetFutureValue && periods < maxPeriods) {
-    if (contributionTiming === "begin") fv += contributionPerPeriod;
-    fv = fv * (1 + r) + (contributionTiming === "end" ? contributionPerPeriod : 0);
+  while (fv2 < targetFutureValue && periods < maxPeriods) {
+    if (contributionTiming === "begin") fv2 += contributionPerPeriod;
+    fv2 = fv2 * (1 + r) + (contributionTiming === "end" ? contributionPerPeriod : 0);
     periods++;
   }
-  return fv >= targetFutureValue ? periods : Number.POSITIVE_INFINITY;
+  if (fv2 >= targetFutureValue) return periods;
+  throw new RangeError("maxPeriods exceeded before reaching target");
 }
 
 // src/interest/presentValue.ts
 function presentValue(params) {
-  const { futureValue: fv, rate, timesPerYear, years } = params;
-  assertNonNegative(fv, "futureValue");
+  const { futureValue: fv2, rate: rate2, timesPerYear, years } = params;
+  assertNonNegative(fv2, "futureValue");
   assertPositive(timesPerYear, "timesPerYear");
   assertNonNegative(years, "years");
-  if (rate === 0 || years === 0) return fv;
+  if (rate2 === 0 || years === 0) return fv2;
   const n = timesPerYear;
   const t = years;
-  return fv / (1 + rate / n) ** (n * t);
+  return fv2 / (1 + rate2 / n) ** (n * t);
 }
 
 // src/interest/presentValueOfAnnuity.ts
@@ -221,11 +364,11 @@ function presentValueOfAnnuity(params) {
   assertNonNegative(periods, "periods");
   if (periods === 0) return 0;
   if (ratePerPeriod === 0) {
-    const pv2 = paymentPerPeriod * periods;
-    return timing === "begin" ? pv2 * (1 + ratePerPeriod) : pv2;
+    const pv3 = paymentPerPeriod * periods;
+    return timing === "begin" ? pv3 * (1 + ratePerPeriod) : pv3;
   }
-  const pv = paymentPerPeriod * (1 - (1 + ratePerPeriod) ** -periods) / ratePerPeriod;
-  return timing === "begin" ? pv * (1 + ratePerPeriod) : pv;
+  const pv2 = paymentPerPeriod * (1 - (1 + ratePerPeriod) ** -periods) / ratePerPeriod;
+  return timing === "begin" ? pv2 * (1 + ratePerPeriod) : pv2;
 }
 
 // src/interest/rateToReachGoal.ts
@@ -235,40 +378,102 @@ function rateToReachGoal(params) {
     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");
+  assertFiniteNumber(lowerBound, "lowerBound");
+  assertFiniteNumber(upperBound, "upperBound");
+  assertFiniteNumber(maxIterations, "maxIterations");
+  assertFiniteNumber(tolerance, "tolerance");
+  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 (periods === 0) return 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;
-  let r = (targetFutureValue / (principal + contributionPerPeriod * periods)) ** (1 / periods) - 1;
-  if (r <= -1) r = 0.01;
-  for (let i = 0; i < 100; i++) {
+  const fn = (r) => {
     const onePlusR = 1 + r;
     const onePlusRN = onePlusR ** periods;
     const fvLump = principal * onePlusRN;
-    const annuity = contributionPerPeriod * ((onePlusRN - 1) / (r || 1e-14)) * (1 + dueFactor * r);
-    const fv = fvLump + annuity;
-    const err = fv - targetFutureValue;
-    if (Math.abs(err) < 1e-10) return r;
-    const dr = r * 1e-6 || 1e-10;
-    const r2 = r + dr;
-    const onePlusR2 = 1 + r2;
-    const onePlusR2N = onePlusR2 ** periods;
-    const fv2 = principal * onePlusR2N + contributionPerPeriod * ((onePlusR2N - 1) / r2) * (1 + dueFactor * r2);
-    const dFvDr = (fv2 - fv) / dr;
-    r = r - err / dFvDr;
-    if (r <= -1) r = 0.01;
-    if (r > 10) r = 10;
-  }
-  return r;
+    const annuityBase = r === 0 ? periods : (onePlusRN - 1) / r;
+    const fvAnnuity = contributionPerPeriod * annuityBase * (1 + dueFactor * r);
+    return fvLump + fvAnnuity - targetFutureValue;
+  };
+  const derivative = (r) => {
+    const delta = Math.abs(r) > 1e-6 ? Math.abs(r) * 1e-6 : 1e-6;
+    return (fn(r + delta) - fn(r - delta)) / (2 * delta);
+  };
+  const initialGuess = (targetFutureValue / (principal + contributionPerPeriod * periods)) ** (1 / periods) - 1;
+  const newton = newtonRaphson({
+    initialGuess: Number.isFinite(initialGuess) ? Math.max(initialGuess, lowerBound) : 0.01,
+    fn,
+    derivative,
+    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: bracket.lower,
+    upper: bracket.upper,
+    tolerance,
+    maxIterations: maxIterations * 2
+  });
+  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
@@ -282,23 +487,223 @@ function realReturn(params) {
 
 // src/interest/ruleOf72.ts
 function ruleOf72(params) {
-  const { rate, constant = 72 } = params;
-  assertFiniteNumber(rate, "rate");
-  assertPositive(rate, "rate");
-  return constant / 100 / rate;
+  const { rate: rate2, constant = 72 } = params;
+  assertFiniteNumber(rate2, "rate");
+  assertPositive(rate2, "rate");
+  return constant / 100 / rate2;
+}
+
+// src/interest/tvom.ts
+function assertTiming(value, name) {
+  if (value !== "end" && value !== "begin") {
+    throw new RangeError(`${name} must be "end" or "begin"`);
+  }
+}
+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);
+}
+function fv(params) {
+  const { ratePerPeriod, periods, payment = 0, presentValue: presentValue2, timing = "end" } = params;
+  assertFiniteNumber(ratePerPeriod, "ratePerPeriod");
+  assertPositive(periods, "periods");
+  assertFiniteNumber(payment, "payment");
+  assertFiniteNumber(presentValue2, "presentValue");
+  assertTiming(timing, "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;
+  assertFiniteNumber(ratePerPeriod, "ratePerPeriod");
+  assertPositive(periods, "periods");
+  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);
+  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;
+  assertFiniteNumber(ratePerPeriod, "ratePerPeriod");
+  assertPositive(periods, "periods");
+  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);
+  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;
+  assertFiniteNumber(ratePerPeriod, "ratePerPeriod");
+  assertFiniteNumber(payment, "payment");
+  assertFiniteNumber(presentValue2, "presentValue");
+  assertFiniteNumber(futureValue2, "futureValue");
+  assertTiming(timing, "timing");
+  if (ratePerPeriodIsInvalidForDomain(ratePerPeriod)) {
+    throw new RangeError("ratePerPeriod must be > -1");
+  }
+  if (ratePerPeriod === 0) {
+    const linear = -(presentValue2 + futureValue2) / payment;
+    return Number.isFinite(linear) && linear >= 0 ? linear : Number.NaN;
+  }
+  const adjustedPayment = payment * annuityDueFactor(ratePerPeriod, timing);
+  const numerator = adjustedPayment - futureValue2 * ratePerPeriod;
+  const denominator = adjustedPayment + presentValue2 * ratePerPeriod;
+  if (numerator === 0 || denominator === 0) return Number.NaN;
+  const ratio = numerator / denominator;
+  if (ratio <= 0) return Number.NaN;
+  const periods = Math.log(ratio) / Math.log(1 + ratePerPeriod);
+  return Number.isFinite(periods) ? periods : Number.NaN;
+}
+function rate(params) {
+  const {
+    periods,
+    payment,
+    presentValue: presentValue2,
+    futureValue: futureValue2 = 0,
+    timing = "end",
+    guess = 0.1,
+    tolerance = 1e-10,
+    maxIterations = 100,
+    lowerBound = -0.999999999,
+    upperBound = 10
+  } = params;
+  assertPositive(periods, "periods");
+  assertFiniteNumber(payment, "payment");
+  assertFiniteNumber(presentValue2, "presentValue");
+  assertFiniteNumber(futureValue2, "futureValue");
+  assertFiniteNumber(guess, "guess");
+  assertFiniteNumber(maxIterations, "maxIterations");
+  assertFiniteNumber(lowerBound, "lowerBound");
+  assertFiniteNumber(upperBound, "upperBound");
+  assertTiming(timing, "timing");
+  if (ratePerPeriodIsInvalidForDomain(lowerBound)) {
+    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");
+  }
+  const fn = (r) => futureValueFromCashFlows(r, periods, payment, presentValue2, timing) - futureValue2;
+  const derivative = (r) => {
+    const delta = Math.abs(r) > 1e-5 ? Math.abs(r) * 1e-6 : 1e-6;
+    return (fn(r + delta) - fn(r - delta)) / (2 * delta);
+  };
+  const newton = newtonRaphson({
+    initialGuess: guess,
+    fn,
+    derivative,
+    tolerance,
+    maxIterations,
+    min: lowerBound,
+    max: upperBound
+  });
+  if (newton !== void 0) return newton;
+  const bracket = findRateBracket(fn, lowerBound, upperBound);
+  if (bracket === void 0) {
+    throw new RangeError("RATE did not converge within search bounds");
+  }
+  if (bracket.lower === bracket.upper) return bracket.lower;
+  const bisected = bisection({
+    fn,
+    lower: bracket.lower,
+    upper: bracket.upper,
+    tolerance,
+    maxIterations: maxIterations * 2
+  });
+  if (bisected !== void 0) return bisected;
+  throw new RangeError("RATE did not converge");
+}
+function ratePerPeriodIsInvalidForDomain(ratePerPeriod) {
+  return ratePerPeriod <= -1;
+}
+function findRateBracket(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 (prevValue !== void 0 && prevX !== 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/loans/loanPayment.ts
 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
@@ -396,31 +801,42 @@ 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;
 }
 
 exports.amortizationSchedule = amortizationSchedule;
+exports.bisection = bisection;
 exports.cagr = cagr;
 exports.compound = compound;
 exports.effectiveAnnualRate = effectiveAnnualRate;
 exports.futureValue = futureValue;
+exports.fv = fv;
 exports.inflationAdjustedAmount = inflationAdjustedAmount;
 exports.investmentGrowth = investmentGrowth;
 exports.irr = irr;
 exports.loanPayment = loanPayment;
+exports.newtonRaphson = newtonRaphson;
+exports.nper = nper;
+exports.npv = npv;
 exports.paymentFromPresentValue = paymentFromPresentValue;
 exports.payoffPeriodWithExtra = payoffPeriodWithExtra;
 exports.periodsToReachGoal = periodsToReachGoal;
+exports.pmt = pmt;
 exports.presentValue = presentValue;
 exports.presentValueOfAnnuity = presentValueOfAnnuity;
+exports.pv = pv;
+exports.rate = rate;
 exports.rateToReachGoal = rateToReachGoal;
 exports.realReturn = realReturn;
 exports.remainingBalance = remainingBalance;