fundamental-js 1.0.0

package/dist/index.cjs

@@ -0,0 +1,360 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  absoluteReturn: () => absoluteReturn,
+  amortizationSchedule: () => amortizationSchedule,
+  annualizedReturn: () => annualizedReturn,
+  cagr: () => cagr,
+  emi: () => emi,
+  fv: () => fv,
+  inflationAdjustedValue: () => inflationAdjustedValue,
+  irr: () => irr,
+  lumpsumFutureValue: () => lumpsumFutureValue,
+  maxDrawdown: () => maxDrawdown,
+  npv: () => npv,
+  prepaymentImpact: () => prepaymentImpact,
+  pv: () => pv,
+  realReturn: () => realReturn,
+  rebalance: () => rebalance,
+  requiredLumpsumForGoal: () => requiredLumpsumForGoal,
+  requiredMonthlyInvestmentForGoal: () => requiredMonthlyInvestmentForGoal,
+  safeNum: () => safeNum,
+  sharpe: () => sharpe,
+  sipFutureValue: () => sipFutureValue,
+  sortino: () => sortino,
+  swpPlan: () => swpPlan,
+  volatility: () => volatility,
+  weightedReturn: () => weightedReturn
+});
+module.exports = __toCommonJS(index_exports);
+function safeNum(v, fallback = 0) {
+  if (v === null || v === void 0 || isNaN(v) || !isFinite(v)) return fallback;
+  return v;
+}
+function emi(principal, annualRate, months) {
+  principal = safeNum(principal, 0);
+  months = safeNum(months, 1);
+  annualRate = safeNum(annualRate, 0);
+  if (principal <= 0 || months <= 0) return { emi: 0, totalPayment: 0, totalInterest: 0 };
+  if (annualRate === 0) {
+    const e2 = principal / months;
+    return { emi: e2, totalPayment: principal, totalInterest: 0 };
+  }
+  const r = annualRate / 12;
+  const factor = Math.pow(1 + r, months);
+  const e = principal * r * factor / (factor - 1);
+  const totalPayment = e * months;
+  return { emi: safeNum(e), totalPayment: safeNum(totalPayment), totalInterest: safeNum(totalPayment - principal) };
+}
+function amortizationSchedule(params) {
+  let { principal, annualRate, months, extraPaymentMonthly = 0, extraPayments = [] } = params;
+  principal = safeNum(principal, 0);
+  annualRate = safeNum(annualRate, 0);
+  months = safeNum(months, 1);
+  if (principal <= 0 || months <= 0) return { emi: 0, schedule: [], totalInterest: 0, totalPaid: 0, payoffMonth: 0 };
+  const r = annualRate / 12;
+  const baseEmi = annualRate === 0 ? principal / months : principal * r * Math.pow(1 + r, months) / (Math.pow(1 + r, months) - 1);
+  const extraMap = new Map(extraPayments.map((ep) => [ep.month, ep.amount]));
+  let balance = principal;
+  const schedule = [];
+  let totalInterest = 0;
+  let totalPaid = 0;
+  for (let m = 1; m <= months && balance > 0.01; m++) {
+    const interest = balance * r;
+    let principalPortion = baseEmi - interest;
+    const extra = extraPaymentMonthly + (extraMap.get(m) || 0);
+    if (principalPortion + extra >= balance) {
+      principalPortion = balance;
+      const payment2 = principalPortion + interest;
+      totalInterest += interest;
+      totalPaid += payment2;
+      schedule.push({
+        month: m,
+        payment: payment2,
+        principalPaid: principalPortion,
+        interestPaid: interest,
+        extraPayment: 0,
+        balance: 0
+      });
+      break;
+    }
+    balance -= principalPortion + extra;
+    if (balance < 0) balance = 0;
+    const payment = baseEmi + extra;
+    totalInterest += interest;
+    totalPaid += payment;
+    schedule.push({
+      month: m,
+      payment,
+      principalPaid: principalPortion + extra,
+      interestPaid: interest,
+      extraPayment: extra,
+      balance
+    });
+  }
+  return {
+    emi: baseEmi,
+    schedule,
+    totalInterest,
+    totalPaid,
+    payoffMonth: schedule.length
+  };
+}
+function prepaymentImpact(params) {
+  const { principal, annualRate, months, prepayments } = params;
+  const original = emi(principal, annualRate, months);
+  const withPrepay = amortizationSchedule({
+    principal,
+    annualRate,
+    months,
+    extraPayments: prepayments
+  });
+  return {
+    original: { emi: original.emi, totalInterest: original.totalInterest, totalPaid: original.totalPayment },
+    new: {
+      emi: withPrepay.emi,
+      totalInterest: withPrepay.totalInterest,
+      totalPaid: withPrepay.totalPaid,
+      payoffMonth: withPrepay.payoffMonth
+    },
+    savings: {
+      interestSaved: original.totalInterest - withPrepay.totalInterest,
+      monthsSaved: months - withPrepay.payoffMonth
+    }
+  };
+}
+function sipFutureValue(params) {
+  const { monthlyInvestment, annualRate, months, stepUpPercentAnnual = 0, investmentAt = "end" } = params;
+  const r = annualRate / 12;
+  let totalInvested = 0;
+  let futureValue = 0;
+  let currentMonthly = monthlyInvestment;
+  for (let m = 1; m <= months; m++) {
+    if (stepUpPercentAnnual > 0 && m > 1 && (m - 1) % 12 === 0) {
+      currentMonthly *= 1 + stepUpPercentAnnual / 100;
+    }
+    totalInvested += currentMonthly;
+    if (investmentAt === "begin") {
+      futureValue = (futureValue + currentMonthly) * (1 + r);
+    } else {
+      futureValue = futureValue * (1 + r) + currentMonthly;
+    }
+  }
+  return {
+    futureValue,
+    totalInvested,
+    estimatedGains: futureValue - totalInvested
+  };
+}
+function lumpsumFutureValue(principal, annualRate, years) {
+  const futureValue = principal * Math.pow(1 + annualRate, years);
+  return { futureValue, gains: futureValue - principal };
+}
+function swpPlan(params) {
+  const { initialCorpus, monthlyWithdrawal, annualRate, months, inflationRateAnnual = 0, withdrawalAt = "end" } = params;
+  const r = annualRate / 12;
+  let balance = initialCorpus;
+  let totalWithdrawn = 0;
+  let currentWithdrawal = monthlyWithdrawal;
+  const schedule = [];
+  for (let m = 1; m <= months; m++) {
+    if (inflationRateAnnual > 0 && m > 1 && (m - 1) % 12 === 0) {
+      currentWithdrawal *= 1 + inflationRateAnnual / 100;
+    }
+    let interest;
+    let withdrawal = currentWithdrawal;
+    if (withdrawalAt === "begin") {
+      withdrawal = Math.min(withdrawal, balance);
+      balance -= withdrawal;
+      interest = balance * r;
+      balance += interest;
+    } else {
+      interest = balance * r;
+      balance += interest;
+      withdrawal = Math.min(withdrawal, balance);
+      balance -= withdrawal;
+    }
+    totalWithdrawn += withdrawal;
+    schedule.push({
+      month: m,
+      withdrawal,
+      interestEarned: interest,
+      endingBalance: Math.max(0, balance)
+    });
+    if (balance <= 0) break;
+  }
+  return {
+    endingCorpus: Math.max(0, balance),
+    totalWithdrawn,
+    schedule
+  };
+}
+function inflationAdjustedValue(value, inflationRateAnnual, years) {
+  return value / Math.pow(1 + inflationRateAnnual, years);
+}
+function realReturn(nominalRateAnnual, inflationRateAnnual) {
+  return (1 + nominalRateAnnual) / (1 + inflationRateAnnual) - 1;
+}
+function requiredMonthlyInvestmentForGoal(params) {
+  const { goalAmountFuture, annualRate, months, stepUpPercentAnnual = 0, investmentAt = "end" } = params;
+  let lo = 0;
+  let hi = goalAmountFuture;
+  for (let i = 0; i < 100; i++) {
+    const mid = (lo + hi) / 2;
+    const result = sipFutureValue({
+      monthlyInvestment: mid,
+      annualRate,
+      months,
+      stepUpPercentAnnual,
+      investmentAt
+    });
+    if (result.futureValue < goalAmountFuture) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return {
+    requiredMonthlyInvestment: (lo + hi) / 2,
+    assumptions: `Rate: ${(annualRate * 100).toFixed(1)}% p.a., Duration: ${months} months${stepUpPercentAnnual ? `, Step-up: ${stepUpPercentAnnual}% annually` : ""}`
+  };
+}
+function requiredLumpsumForGoal(goalAmountFuture, annualRate, years) {
+  return goalAmountFuture / Math.pow(1 + annualRate, years);
+}
+function cagr(beginValue, endValue, years) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  years = safeNum(years, 1);
+  if (beginValue <= 0 || years <= 0) return 0;
+  return Math.pow(endValue / beginValue, 1 / years) - 1;
+}
+function absoluteReturn(beginValue, endValue) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  if (beginValue <= 0) return 0;
+  return (endValue - beginValue) / beginValue;
+}
+function annualizedReturn(beginValue, endValue, days) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  days = safeNum(days, 1);
+  if (beginValue <= 0 || days <= 0) return 0;
+  return Math.pow(endValue / beginValue, 365 / days) - 1;
+}
+function pv(rate, nper, pmt, fv2 = 0, type = 0) {
+  if (rate === 0) return -(pmt * nper + fv2);
+  const factor = Math.pow(1 + rate, nper);
+  return -(pmt * (1 + rate * type) * ((factor - 1) / rate) + fv2) / factor;
+}
+function fv(rate, nper, pmt, pvVal = 0, type = 0) {
+  if (rate === 0) return -(pvVal + pmt * nper);
+  const factor = Math.pow(1 + rate, nper);
+  return -(pvVal * factor + pmt * (1 + rate * type) * ((factor - 1) / rate));
+}
+function volatility(returns, periodsPerYear = 252) {
+  if (returns.length < 2) return 0;
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const variance = returns.reduce((s, r) => s + (r - mean) ** 2, 0) / (returns.length - 1);
+  return Math.sqrt(variance) * Math.sqrt(periodsPerYear);
+}
+function sharpe(returns, riskFreeRateAnnual = 0, periodsPerYear = 252) {
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const annualReturn = mean * periodsPerYear;
+  const vol = volatility(returns, periodsPerYear);
+  if (vol === 0) return 0;
+  return (annualReturn - riskFreeRateAnnual) / vol;
+}
+function sortino(returns, riskFreeRateAnnual = 0, periodsPerYear = 252) {
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const rfPerPeriod = riskFreeRateAnnual / periodsPerYear;
+  const downside = returns.filter((r) => r < rfPerPeriod);
+  if (downside.length === 0) return Infinity;
+  const downsideVariance = downside.reduce((s, r) => s + (r - rfPerPeriod) ** 2, 0) / downside.length;
+  const downsideDev = Math.sqrt(downsideVariance) * Math.sqrt(periodsPerYear);
+  const annualReturn = mean * periodsPerYear;
+  if (downsideDev === 0) return 0;
+  return (annualReturn - riskFreeRateAnnual) / downsideDev;
+}
+function maxDrawdown(values) {
+  if (values.length < 2) return { maxDrawdown: 0, peakIndex: 0, troughIndex: 0 };
+  let peak = values[0];
+  let maxDd = 0;
+  let peakIdx = 0;
+  let troughIdx = 0;
+  let currentPeakIdx = 0;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i] > peak) {
+      peak = values[i];
+      currentPeakIdx = i;
+    }
+    const dd = (peak - values[i]) / peak;
+    if (dd > maxDd) {
+      maxDd = dd;
+      peakIdx = currentPeakIdx;
+      troughIdx = i;
+    }
+  }
+  return { maxDrawdown: maxDd, peakIndex: peakIdx, troughIndex: troughIdx };
+}
+function npv(rate, cashflows) {
+  return cashflows.reduce((sum, cf, i) => sum + cf / Math.pow(1 + rate, i), 0);
+}
+function irr(cashflows, guess = 0.1) {
+  let rate = guess;
+  const maxIter = 1e3;
+  const tol = 1e-10;
+  for (let i = 0; i < maxIter; i++) {
+    let f = 0;
+    let df = 0;
+    for (let j = 0; j < cashflows.length; j++) {
+      const denom = Math.pow(1 + rate, j);
+      f += cashflows[j] / denom;
+      if (j > 0) df -= j * cashflows[j] / Math.pow(1 + rate, j + 1);
+    }
+    if (Math.abs(f) < tol) return rate;
+    if (Math.abs(df) < tol) break;
+    rate -= f / df;
+  }
+  let lo = -0.99;
+  let hi = 10;
+  for (let i = 0; i < 1e3; i++) {
+    const mid = (lo + hi) / 2;
+    const f = cashflows.reduce((s, cf, j) => s + cf / Math.pow(1 + mid, j), 0);
+    if (Math.abs(f) < tol) return mid;
+    const fLo = cashflows.reduce((s, cf, j) => s + cf / Math.pow(1 + lo, j), 0);
+    if (f * fLo > 0) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}
+function weightedReturn(returns, weights) {
+  if (returns.length !== weights.length || returns.length === 0) return 0;
+  return returns.reduce((s, r, i) => s + r * weights[i], 0);
+}
+function rebalance(targetWeights, currentValues) {
+  if (targetWeights.length !== currentValues.length || targetWeights.length === 0) return { trades: [], newValues: [], total: 0 };
+  const total = currentValues.reduce((s, v) => s + v, 0);
+  const newValues = targetWeights.map((w) => w * total);
+  const trades = newValues.map((nv, i) => nv - currentValues[i]);
+  return { trades, newValues, total };
+}

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+export declare function safeNum(v: number, fallback?: number): number;
+export declare function emi(principal: number, annualRate: number, months: number): {
+    emi: number;
+    totalPayment: number;
+    totalInterest: number;
+};
+export declare function amortizationSchedule(params: {
+    principal: number;
+    annualRate: number;
+    months: number;
+    extraPaymentMonthly?: number;
+    extraPayments?: {
+        month: number;
+        amount: number;
+    }[];
+}): {
+    emi: number;
+    schedule: {
+        month: number;
+        payment: number;
+        principalPaid: number;
+        interestPaid: number;
+        extraPayment: number;
+        balance: number;
+    }[];
+    totalInterest: number;
+    totalPaid: number;
+    payoffMonth: number;
+};
+export declare function prepaymentImpact(params: {
+    principal: number;
+    annualRate: number;
+    months: number;
+    prepayments: {
+        month: number;
+        amount: number;
+    }[];
+    mode: "reduceTenure" | "reduceEmi";
+}): {
+    original: {
+        emi: number;
+        totalInterest: number;
+        totalPaid: number;
+    };
+    new: {
+        emi: number;
+        totalInterest: number;
+        totalPaid: number;
+        payoffMonth: number;
+    };
+    savings: {
+        interestSaved: number;
+        monthsSaved: number;
+    };
+};
+export declare function sipFutureValue(params: {
+    monthlyInvestment: number;
+    annualRate: number;
+    months: number;
+    stepUpPercentAnnual?: number;
+    investmentAt?: "begin" | "end";
+}): {
+    futureValue: number;
+    totalInvested: number;
+    estimatedGains: number;
+};
+export declare function lumpsumFutureValue(principal: number, annualRate: number, years: number): {
+    futureValue: number;
+    gains: number;
+};
+export declare function swpPlan(params: {
+    initialCorpus: number;
+    monthlyWithdrawal: number;
+    annualRate: number;
+    months: number;
+    inflationRateAnnual?: number;
+    withdrawalAt?: "begin" | "end";
+}): {
+    endingCorpus: number;
+    totalWithdrawn: number;
+    schedule: {
+        month: number;
+        withdrawal: number;
+        interestEarned: number;
+        endingBalance: number;
+    }[];
+};
+export declare function inflationAdjustedValue(value: number, inflationRateAnnual: number, years: number): number;
+export declare function realReturn(nominalRateAnnual: number, inflationRateAnnual: number): number;
+export declare function requiredMonthlyInvestmentForGoal(params: {
+    goalAmountFuture: number;
+    annualRate: number;
+    months: number;
+    stepUpPercentAnnual?: number;
+    investmentAt?: "begin" | "end";
+}): {
+    requiredMonthlyInvestment: number;
+    assumptions: string;
+};
+export declare function requiredLumpsumForGoal(goalAmountFuture: number, annualRate: number, years: number): number;
+export declare function cagr(beginValue: number, endValue: number, years: number): number;
+export declare function absoluteReturn(beginValue: number, endValue: number): number;
+export declare function annualizedReturn(beginValue: number, endValue: number, days: number): number;
+export declare function pv(rate: number, nper: number, pmt: number, fv?: number, type?: number): number;
+export declare function fv(rate: number, nper: number, pmt: number, pvVal?: number, type?: number): number;
+export declare function volatility(returns: number[], periodsPerYear?: number): number;
+export declare function sharpe(returns: number[], riskFreeRateAnnual?: number, periodsPerYear?: number): number;
+export declare function sortino(returns: number[], riskFreeRateAnnual?: number, periodsPerYear?: number): number;
+export declare function maxDrawdown(values: number[]): {
+    maxDrawdown: number;
+    peakIndex: number;
+    troughIndex: number;
+};
+export declare function npv(rate: number, cashflows: number[]): number;
+export declare function irr(cashflows: number[], guess?: number): number;
+export declare function weightedReturn(returns: number[], weights: number[]): number;
+export declare function rebalance(targetWeights: number[], currentValues: number[]): {
+    trades: number[];
+    newValues: number[];
+    total: number;
+};

package/dist/index.mjs

@@ -0,0 +1,339 @@
+// src/index.ts
+function safeNum(v, fallback = 0) {
+  if (v === null || v === void 0 || isNaN(v) || !isFinite(v)) return fallback;
+  return v;
+}
+function emi(principal, annualRate, months) {
+  principal = safeNum(principal, 0);
+  months = safeNum(months, 1);
+  annualRate = safeNum(annualRate, 0);
+  if (principal <= 0 || months <= 0) return { emi: 0, totalPayment: 0, totalInterest: 0 };
+  if (annualRate === 0) {
+    const e2 = principal / months;
+    return { emi: e2, totalPayment: principal, totalInterest: 0 };
+  }
+  const r = annualRate / 12;
+  const factor = Math.pow(1 + r, months);
+  const e = principal * r * factor / (factor - 1);
+  const totalPayment = e * months;
+  return { emi: safeNum(e), totalPayment: safeNum(totalPayment), totalInterest: safeNum(totalPayment - principal) };
+}
+function amortizationSchedule(params) {
+  let { principal, annualRate, months, extraPaymentMonthly = 0, extraPayments = [] } = params;
+  principal = safeNum(principal, 0);
+  annualRate = safeNum(annualRate, 0);
+  months = safeNum(months, 1);
+  if (principal <= 0 || months <= 0) return { emi: 0, schedule: [], totalInterest: 0, totalPaid: 0, payoffMonth: 0 };
+  const r = annualRate / 12;
+  const baseEmi = annualRate === 0 ? principal / months : principal * r * Math.pow(1 + r, months) / (Math.pow(1 + r, months) - 1);
+  const extraMap = new Map(extraPayments.map((ep) => [ep.month, ep.amount]));
+  let balance = principal;
+  const schedule = [];
+  let totalInterest = 0;
+  let totalPaid = 0;
+  for (let m = 1; m <= months && balance > 0.01; m++) {
+    const interest = balance * r;
+    let principalPortion = baseEmi - interest;
+    const extra = extraPaymentMonthly + (extraMap.get(m) || 0);
+    if (principalPortion + extra >= balance) {
+      principalPortion = balance;
+      const payment2 = principalPortion + interest;
+      totalInterest += interest;
+      totalPaid += payment2;
+      schedule.push({
+        month: m,
+        payment: payment2,
+        principalPaid: principalPortion,
+        interestPaid: interest,
+        extraPayment: 0,
+        balance: 0
+      });
+      break;
+    }
+    balance -= principalPortion + extra;
+    if (balance < 0) balance = 0;
+    const payment = baseEmi + extra;
+    totalInterest += interest;
+    totalPaid += payment;
+    schedule.push({
+      month: m,
+      payment,
+      principalPaid: principalPortion + extra,
+      interestPaid: interest,
+      extraPayment: extra,
+      balance
+    });
+  }
+  return {
+    emi: baseEmi,
+    schedule,
+    totalInterest,
+    totalPaid,
+    payoffMonth: schedule.length
+  };
+}
+function prepaymentImpact(params) {
+  const { principal, annualRate, months, prepayments } = params;
+  const original = emi(principal, annualRate, months);
+  const withPrepay = amortizationSchedule({
+    principal,
+    annualRate,
+    months,
+    extraPayments: prepayments
+  });
+  return {
+    original: { emi: original.emi, totalInterest: original.totalInterest, totalPaid: original.totalPayment },
+    new: {
+      emi: withPrepay.emi,
+      totalInterest: withPrepay.totalInterest,
+      totalPaid: withPrepay.totalPaid,
+      payoffMonth: withPrepay.payoffMonth
+    },
+    savings: {
+      interestSaved: original.totalInterest - withPrepay.totalInterest,
+      monthsSaved: months - withPrepay.payoffMonth
+    }
+  };
+}
+function sipFutureValue(params) {
+  const { monthlyInvestment, annualRate, months, stepUpPercentAnnual = 0, investmentAt = "end" } = params;
+  const r = annualRate / 12;
+  let totalInvested = 0;
+  let futureValue = 0;
+  let currentMonthly = monthlyInvestment;
+  for (let m = 1; m <= months; m++) {
+    if (stepUpPercentAnnual > 0 && m > 1 && (m - 1) % 12 === 0) {
+      currentMonthly *= 1 + stepUpPercentAnnual / 100;
+    }
+    totalInvested += currentMonthly;
+    if (investmentAt === "begin") {
+      futureValue = (futureValue + currentMonthly) * (1 + r);
+    } else {
+      futureValue = futureValue * (1 + r) + currentMonthly;
+    }
+  }
+  return {
+    futureValue,
+    totalInvested,
+    estimatedGains: futureValue - totalInvested
+  };
+}
+function lumpsumFutureValue(principal, annualRate, years) {
+  const futureValue = principal * Math.pow(1 + annualRate, years);
+  return { futureValue, gains: futureValue - principal };
+}
+function swpPlan(params) {
+  const { initialCorpus, monthlyWithdrawal, annualRate, months, inflationRateAnnual = 0, withdrawalAt = "end" } = params;
+  const r = annualRate / 12;
+  let balance = initialCorpus;
+  let totalWithdrawn = 0;
+  let currentWithdrawal = monthlyWithdrawal;
+  const schedule = [];
+  for (let m = 1; m <= months; m++) {
+    if (inflationRateAnnual > 0 && m > 1 && (m - 1) % 12 === 0) {
+      currentWithdrawal *= 1 + inflationRateAnnual / 100;
+    }
+    let interest;
+    let withdrawal = currentWithdrawal;
+    if (withdrawalAt === "begin") {
+      withdrawal = Math.min(withdrawal, balance);
+      balance -= withdrawal;
+      interest = balance * r;
+      balance += interest;
+    } else {
+      interest = balance * r;
+      balance += interest;
+      withdrawal = Math.min(withdrawal, balance);
+      balance -= withdrawal;
+    }
+    totalWithdrawn += withdrawal;
+    schedule.push({
+      month: m,
+      withdrawal,
+      interestEarned: interest,
+      endingBalance: Math.max(0, balance)
+    });
+    if (balance <= 0) break;
+  }
+  return {
+    endingCorpus: Math.max(0, balance),
+    totalWithdrawn,
+    schedule
+  };
+}
+function inflationAdjustedValue(value, inflationRateAnnual, years) {
+  return value / Math.pow(1 + inflationRateAnnual, years);
+}
+function realReturn(nominalRateAnnual, inflationRateAnnual) {
+  return (1 + nominalRateAnnual) / (1 + inflationRateAnnual) - 1;
+}
+function requiredMonthlyInvestmentForGoal(params) {
+  const { goalAmountFuture, annualRate, months, stepUpPercentAnnual = 0, investmentAt = "end" } = params;
+  let lo = 0;
+  let hi = goalAmountFuture;
+  for (let i = 0; i < 100; i++) {
+    const mid = (lo + hi) / 2;
+    const result = sipFutureValue({
+      monthlyInvestment: mid,
+      annualRate,
+      months,
+      stepUpPercentAnnual,
+      investmentAt
+    });
+    if (result.futureValue < goalAmountFuture) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return {
+    requiredMonthlyInvestment: (lo + hi) / 2,
+    assumptions: `Rate: ${(annualRate * 100).toFixed(1)}% p.a., Duration: ${months} months${stepUpPercentAnnual ? `, Step-up: ${stepUpPercentAnnual}% annually` : ""}`
+  };
+}
+function requiredLumpsumForGoal(goalAmountFuture, annualRate, years) {
+  return goalAmountFuture / Math.pow(1 + annualRate, years);
+}
+function cagr(beginValue, endValue, years) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  years = safeNum(years, 1);
+  if (beginValue <= 0 || years <= 0) return 0;
+  return Math.pow(endValue / beginValue, 1 / years) - 1;
+}
+function absoluteReturn(beginValue, endValue) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  if (beginValue <= 0) return 0;
+  return (endValue - beginValue) / beginValue;
+}
+function annualizedReturn(beginValue, endValue, days) {
+  beginValue = safeNum(beginValue, 0);
+  endValue = safeNum(endValue, 0);
+  days = safeNum(days, 1);
+  if (beginValue <= 0 || days <= 0) return 0;
+  return Math.pow(endValue / beginValue, 365 / days) - 1;
+}
+function pv(rate, nper, pmt, fv2 = 0, type = 0) {
+  if (rate === 0) return -(pmt * nper + fv2);
+  const factor = Math.pow(1 + rate, nper);
+  return -(pmt * (1 + rate * type) * ((factor - 1) / rate) + fv2) / factor;
+}
+function fv(rate, nper, pmt, pvVal = 0, type = 0) {
+  if (rate === 0) return -(pvVal + pmt * nper);
+  const factor = Math.pow(1 + rate, nper);
+  return -(pvVal * factor + pmt * (1 + rate * type) * ((factor - 1) / rate));
+}
+function volatility(returns, periodsPerYear = 252) {
+  if (returns.length < 2) return 0;
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const variance = returns.reduce((s, r) => s + (r - mean) ** 2, 0) / (returns.length - 1);
+  return Math.sqrt(variance) * Math.sqrt(periodsPerYear);
+}
+function sharpe(returns, riskFreeRateAnnual = 0, periodsPerYear = 252) {
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const annualReturn = mean * periodsPerYear;
+  const vol = volatility(returns, periodsPerYear);
+  if (vol === 0) return 0;
+  return (annualReturn - riskFreeRateAnnual) / vol;
+}
+function sortino(returns, riskFreeRateAnnual = 0, periodsPerYear = 252) {
+  const mean = returns.reduce((s, r) => s + r, 0) / returns.length;
+  const rfPerPeriod = riskFreeRateAnnual / periodsPerYear;
+  const downside = returns.filter((r) => r < rfPerPeriod);
+  if (downside.length === 0) return Infinity;
+  const downsideVariance = downside.reduce((s, r) => s + (r - rfPerPeriod) ** 2, 0) / downside.length;
+  const downsideDev = Math.sqrt(downsideVariance) * Math.sqrt(periodsPerYear);
+  const annualReturn = mean * periodsPerYear;
+  if (downsideDev === 0) return 0;
+  return (annualReturn - riskFreeRateAnnual) / downsideDev;
+}
+function maxDrawdown(values) {
+  if (values.length < 2) return { maxDrawdown: 0, peakIndex: 0, troughIndex: 0 };
+  let peak = values[0];
+  let maxDd = 0;
+  let peakIdx = 0;
+  let troughIdx = 0;
+  let currentPeakIdx = 0;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i] > peak) {
+      peak = values[i];
+      currentPeakIdx = i;
+    }
+    const dd = (peak - values[i]) / peak;
+    if (dd > maxDd) {
+      maxDd = dd;
+      peakIdx = currentPeakIdx;
+      troughIdx = i;
+    }
+  }
+  return { maxDrawdown: maxDd, peakIndex: peakIdx, troughIndex: troughIdx };
+}
+function npv(rate, cashflows) {
+  return cashflows.reduce((sum, cf, i) => sum + cf / Math.pow(1 + rate, i), 0);
+}
+function irr(cashflows, guess = 0.1) {
+  let rate = guess;
+  const maxIter = 1e3;
+  const tol = 1e-10;
+  for (let i = 0; i < maxIter; i++) {
+    let f = 0;
+    let df = 0;
+    for (let j = 0; j < cashflows.length; j++) {
+      const denom = Math.pow(1 + rate, j);
+      f += cashflows[j] / denom;
+      if (j > 0) df -= j * cashflows[j] / Math.pow(1 + rate, j + 1);
+    }
+    if (Math.abs(f) < tol) return rate;
+    if (Math.abs(df) < tol) break;
+    rate -= f / df;
+  }
+  let lo = -0.99;
+  let hi = 10;
+  for (let i = 0; i < 1e3; i++) {
+    const mid = (lo + hi) / 2;
+    const f = cashflows.reduce((s, cf, j) => s + cf / Math.pow(1 + mid, j), 0);
+    if (Math.abs(f) < tol) return mid;
+    const fLo = cashflows.reduce((s, cf, j) => s + cf / Math.pow(1 + lo, j), 0);
+    if (f * fLo > 0) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}
+function weightedReturn(returns, weights) {
+  if (returns.length !== weights.length || returns.length === 0) return 0;
+  return returns.reduce((s, r, i) => s + r * weights[i], 0);
+}
+function rebalance(targetWeights, currentValues) {
+  if (targetWeights.length !== currentValues.length || targetWeights.length === 0) return { trades: [], newValues: [], total: 0 };
+  const total = currentValues.reduce((s, v) => s + v, 0);
+  const newValues = targetWeights.map((w) => w * total);
+  const trades = newValues.map((nv, i) => nv - currentValues[i]);
+  return { trades, newValues, total };
+}
+export {
+  absoluteReturn,
+  amortizationSchedule,
+  annualizedReturn,
+  cagr,
+  emi,
+  fv,
+  inflationAdjustedValue,
+  irr,
+  lumpsumFutureValue,
+  maxDrawdown,
+  npv,
+  prepaymentImpact,
+  pv,
+  realReturn,
+  rebalance,
+  requiredLumpsumForGoal,
+  requiredMonthlyInvestmentForGoal,
+  safeNum,
+  sharpe,
+  sipFutureValue,
+  sortino,
+  swpPlan,
+  volatility,
+  weightedReturn
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "fundamental-js",
+  "version": "1.0.0",
+  "description": "Comprehensive financial calculator library for investing, loans, and personal finance. Includes EMI, SIP, SWP, amortization, CAGR, IRR, NPV, risk metrics, and more.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "finance",
+    "financial",
+    "calculator",
+    "emi",
+    "sip",
+    "swp",
+    "amortization",
+    "cagr",
+    "irr",
+    "npv",
+    "sharpe",
+    "sortino",
+    "volatility",
+    "investment",
+    "loan",
+    "returns"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "node build.mjs"
+  }
+}