@wirms/calculator-engine 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+interface DSCRInput {
+    /** Purchase price or current value */
+    purchasePrice: number;
+    /** Loan-to-value ratio as decimal (e.g. 0.75) */
+    ltv: number;
+    /** Annual interest rate as decimal (e.g. 0.08 for 8%) */
+    interestRate: number;
+    /** Loan term in years */
+    loanTermYears: number;
+    /** Amortization period in years */
+    amortizationYears: number;
+    /** Monthly gross rental income */
+    monthlyRent: number;
+    /** Monthly vacancy allowance (dollar amount) */
+    vacancyAmount?: number;
+    /** Monthly management fee (dollar amount) */
+    managementAmount?: number;
+    /** Monthly insurance */
+    monthlyInsurance?: number;
+    /** Monthly property taxes */
+    monthlyTaxes?: number;
+    /** Monthly HOA */
+    monthlyHOA?: number;
+    /** Other monthly expenses */
+    otherMonthlyExpenses?: number;
+    /** Whether this is an interest-only loan */
+    interestOnly?: boolean;
+}
+interface DSCRResult {
+    dscr: number;
+    loanAmount: number;
+    monthlyPayment: number;
+    annualNOI: number;
+    annualDebtService: number;
+    monthlyNOI: number;
+    grossMonthlyIncome: number;
+    totalMonthlyExpenses: number;
+    cashFlow: number;
+    /** DSCR tier label */
+    tier: 'excellent' | 'good' | 'acceptable' | 'weak' | 'negative';
+}
+interface SolverResult {
+    value: number;
+    resultingDSCR: number;
+    feasible: boolean;
+}
+
+declare function clamp(value: number, min: number, max: number): number;
+declare function formatCurrency(value: number, decimals?: number): string;
+declare function calculateDSCR(input: DSCRInput): DSCRResult;
+/** Find max loan amount that achieves targetDSCR */
+declare function solveMaxLoan(input: Omit<DSCRInput, 'ltv'>, targetDSCR: number): SolverResult;
+/** Find minimum monthly rent to achieve targetDSCR */
+declare function solveMinRent(input: DSCRInput, targetDSCR: number): SolverResult;
+
+export { type DSCRInput, type DSCRResult, type SolverResult, calculateDSCR, clamp, formatCurrency, solveMaxLoan, solveMinRent };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+interface DSCRInput {
+    /** Purchase price or current value */
+    purchasePrice: number;
+    /** Loan-to-value ratio as decimal (e.g. 0.75) */
+    ltv: number;
+    /** Annual interest rate as decimal (e.g. 0.08 for 8%) */
+    interestRate: number;
+    /** Loan term in years */
+    loanTermYears: number;
+    /** Amortization period in years */
+    amortizationYears: number;
+    /** Monthly gross rental income */
+    monthlyRent: number;
+    /** Monthly vacancy allowance (dollar amount) */
+    vacancyAmount?: number;
+    /** Monthly management fee (dollar amount) */
+    managementAmount?: number;
+    /** Monthly insurance */
+    monthlyInsurance?: number;
+    /** Monthly property taxes */
+    monthlyTaxes?: number;
+    /** Monthly HOA */
+    monthlyHOA?: number;
+    /** Other monthly expenses */
+    otherMonthlyExpenses?: number;
+    /** Whether this is an interest-only loan */
+    interestOnly?: boolean;
+}
+interface DSCRResult {
+    dscr: number;
+    loanAmount: number;
+    monthlyPayment: number;
+    annualNOI: number;
+    annualDebtService: number;
+    monthlyNOI: number;
+    grossMonthlyIncome: number;
+    totalMonthlyExpenses: number;
+    cashFlow: number;
+    /** DSCR tier label */
+    tier: 'excellent' | 'good' | 'acceptable' | 'weak' | 'negative';
+}
+interface SolverResult {
+    value: number;
+    resultingDSCR: number;
+    feasible: boolean;
+}
+
+declare function clamp(value: number, min: number, max: number): number;
+declare function formatCurrency(value: number, decimals?: number): string;
+declare function calculateDSCR(input: DSCRInput): DSCRResult;
+/** Find max loan amount that achieves targetDSCR */
+declare function solveMaxLoan(input: Omit<DSCRInput, 'ltv'>, targetDSCR: number): SolverResult;
+/** Find minimum monthly rent to achieve targetDSCR */
+declare function solveMinRent(input: DSCRInput, targetDSCR: number): SolverResult;
+
+export { type DSCRInput, type DSCRResult, type SolverResult, calculateDSCR, clamp, formatCurrency, solveMaxLoan, solveMinRent };

package/dist/index.js

@@ -0,0 +1,141 @@
+"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, {
+  calculateDSCR: () => calculateDSCR,
+  clamp: () => clamp,
+  formatCurrency: () => formatCurrency,
+  solveMaxLoan: () => solveMaxLoan,
+  solveMinRent: () => solveMinRent
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/dscr/engine.ts
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+function formatCurrency(value, decimals = 0) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(value);
+}
+function calcMonthlyPayment(principal, annualRate, amortYears, interestOnly) {
+  if (principal <= 0 || annualRate <= 0) return 0;
+  const monthlyRate = annualRate / 12;
+  if (interestOnly) return principal * monthlyRate;
+  const n = amortYears * 12;
+  return principal * monthlyRate * Math.pow(1 + monthlyRate, n) / (Math.pow(1 + monthlyRate, n) - 1);
+}
+function getDSCRTier(dscr) {
+  if (dscr >= 1.5) return "excellent";
+  if (dscr >= 1.25) return "good";
+  if (dscr >= 1) return "acceptable";
+  if (dscr >= 0) return "weak";
+  return "negative";
+}
+function calculateDSCR(input) {
+  const loanAmount = input.purchasePrice * input.ltv;
+  const monthlyPayment = calcMonthlyPayment(
+    loanAmount,
+    input.interestRate,
+    input.amortizationYears,
+    input.interestOnly ?? false
+  );
+  const grossMonthly = input.monthlyRent;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const monthlyNOI = grossMonthly - totalExpenses;
+  const annualNOI = monthlyNOI * 12;
+  const annualDebtService = monthlyPayment * 12;
+  const dscr = annualDebtService > 0 ? annualNOI / annualDebtService : 0;
+  const cashFlow = monthlyNOI - monthlyPayment;
+  return {
+    dscr: Math.round(dscr * 100) / 100,
+    loanAmount: Math.round(loanAmount),
+    monthlyPayment: Math.round(monthlyPayment * 100) / 100,
+    annualNOI: Math.round(annualNOI),
+    annualDebtService: Math.round(annualDebtService),
+    monthlyNOI: Math.round(monthlyNOI * 100) / 100,
+    grossMonthlyIncome: grossMonthly,
+    totalMonthlyExpenses: totalExpenses,
+    cashFlow: Math.round(cashFlow * 100) / 100,
+    tier: getDSCRTier(dscr)
+  };
+}
+function solveMaxLoan(input, targetDSCR) {
+  const grossMonthly = input.monthlyRent;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const monthlyNOI = grossMonthly - totalExpenses;
+  const annualNOI = monthlyNOI * 12;
+  const maxAnnualDebtService = annualNOI / targetDSCR;
+  const maxMonthlyPayment = maxAnnualDebtService / 12;
+  if (maxMonthlyPayment <= 0) {
+    return { value: 0, resultingDSCR: 0, feasible: false };
+  }
+  const monthlyRate = input.interestRate / 12;
+  let maxLoan;
+  if (input.interestOnly) {
+    maxLoan = maxMonthlyPayment / monthlyRate;
+  } else {
+    const n = input.amortizationYears * 12;
+    maxLoan = maxMonthlyPayment * (Math.pow(1 + monthlyRate, n) - 1) / (monthlyRate * Math.pow(1 + monthlyRate, n));
+  }
+  const result = calculateDSCR({
+    ...input,
+    purchasePrice: maxLoan,
+    ltv: 1
+  });
+  return {
+    value: Math.round(maxLoan),
+    resultingDSCR: result.dscr,
+    feasible: maxLoan > 0
+  };
+}
+function solveMinRent(input, targetDSCR) {
+  const loanAmount = input.purchasePrice * input.ltv;
+  const monthlyPayment = calcMonthlyPayment(
+    loanAmount,
+    input.interestRate,
+    input.amortizationYears,
+    input.interestOnly ?? false
+  );
+  const annualDebtService = monthlyPayment * 12;
+  const requiredAnnualNOI = targetDSCR * annualDebtService;
+  const requiredMonthlyNOI = requiredAnnualNOI / 12;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const minRent = requiredMonthlyNOI + totalExpenses;
+  const result = calculateDSCR({ ...input, monthlyRent: minRent });
+  return {
+    value: Math.round(minRent),
+    resultingDSCR: result.dscr,
+    feasible: minRent > 0
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calculateDSCR,
+  clamp,
+  formatCurrency,
+  solveMaxLoan,
+  solveMinRent
+});

package/dist/index.mjs

@@ -0,0 +1,110 @@
+// src/dscr/engine.ts
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+function formatCurrency(value, decimals = 0) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(value);
+}
+function calcMonthlyPayment(principal, annualRate, amortYears, interestOnly) {
+  if (principal <= 0 || annualRate <= 0) return 0;
+  const monthlyRate = annualRate / 12;
+  if (interestOnly) return principal * monthlyRate;
+  const n = amortYears * 12;
+  return principal * monthlyRate * Math.pow(1 + monthlyRate, n) / (Math.pow(1 + monthlyRate, n) - 1);
+}
+function getDSCRTier(dscr) {
+  if (dscr >= 1.5) return "excellent";
+  if (dscr >= 1.25) return "good";
+  if (dscr >= 1) return "acceptable";
+  if (dscr >= 0) return "weak";
+  return "negative";
+}
+function calculateDSCR(input) {
+  const loanAmount = input.purchasePrice * input.ltv;
+  const monthlyPayment = calcMonthlyPayment(
+    loanAmount,
+    input.interestRate,
+    input.amortizationYears,
+    input.interestOnly ?? false
+  );
+  const grossMonthly = input.monthlyRent;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const monthlyNOI = grossMonthly - totalExpenses;
+  const annualNOI = monthlyNOI * 12;
+  const annualDebtService = monthlyPayment * 12;
+  const dscr = annualDebtService > 0 ? annualNOI / annualDebtService : 0;
+  const cashFlow = monthlyNOI - monthlyPayment;
+  return {
+    dscr: Math.round(dscr * 100) / 100,
+    loanAmount: Math.round(loanAmount),
+    monthlyPayment: Math.round(monthlyPayment * 100) / 100,
+    annualNOI: Math.round(annualNOI),
+    annualDebtService: Math.round(annualDebtService),
+    monthlyNOI: Math.round(monthlyNOI * 100) / 100,
+    grossMonthlyIncome: grossMonthly,
+    totalMonthlyExpenses: totalExpenses,
+    cashFlow: Math.round(cashFlow * 100) / 100,
+    tier: getDSCRTier(dscr)
+  };
+}
+function solveMaxLoan(input, targetDSCR) {
+  const grossMonthly = input.monthlyRent;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const monthlyNOI = grossMonthly - totalExpenses;
+  const annualNOI = monthlyNOI * 12;
+  const maxAnnualDebtService = annualNOI / targetDSCR;
+  const maxMonthlyPayment = maxAnnualDebtService / 12;
+  if (maxMonthlyPayment <= 0) {
+    return { value: 0, resultingDSCR: 0, feasible: false };
+  }
+  const monthlyRate = input.interestRate / 12;
+  let maxLoan;
+  if (input.interestOnly) {
+    maxLoan = maxMonthlyPayment / monthlyRate;
+  } else {
+    const n = input.amortizationYears * 12;
+    maxLoan = maxMonthlyPayment * (Math.pow(1 + monthlyRate, n) - 1) / (monthlyRate * Math.pow(1 + monthlyRate, n));
+  }
+  const result = calculateDSCR({
+    ...input,
+    purchasePrice: maxLoan,
+    ltv: 1
+  });
+  return {
+    value: Math.round(maxLoan),
+    resultingDSCR: result.dscr,
+    feasible: maxLoan > 0
+  };
+}
+function solveMinRent(input, targetDSCR) {
+  const loanAmount = input.purchasePrice * input.ltv;
+  const monthlyPayment = calcMonthlyPayment(
+    loanAmount,
+    input.interestRate,
+    input.amortizationYears,
+    input.interestOnly ?? false
+  );
+  const annualDebtService = monthlyPayment * 12;
+  const requiredAnnualNOI = targetDSCR * annualDebtService;
+  const requiredMonthlyNOI = requiredAnnualNOI / 12;
+  const totalExpenses = (input.vacancyAmount ?? 0) + (input.managementAmount ?? 0) + (input.monthlyInsurance ?? 0) + (input.monthlyTaxes ?? 0) + (input.monthlyHOA ?? 0) + (input.otherMonthlyExpenses ?? 0);
+  const minRent = requiredMonthlyNOI + totalExpenses;
+  const result = calculateDSCR({ ...input, monthlyRent: minRent });
+  return {
+    value: Math.round(minRent),
+    resultingDSCR: result.dscr,
+    feasible: minRent > 0
+  };
+}
+export {
+  calculateDSCR,
+  clamp,
+  formatCurrency,
+  solveMaxLoan,
+  solveMinRent
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@wirms/calculator-engine",
+  "version": "1.0.1",
+  "description": "Pure TypeScript DSCR and investor calculator engine — zero dependencies",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roasst/investor-tools.git",
+    "directory": "packages/calculator-engine"
+  },
+  "author": "WIRMS <luke@roasst.com>",
+  "license": "UNLICENSED"
+}