Fundamental Analysis

fundamental-analysis

Maintained by Boffin Coders.

Formerly published as finance-calculator-pro. Switching: npm uninstall finance-calculator-pro && npm install fundamental-analysis, then change your imports to 'fundamental-analysis'. The functions and their names are the same; see the CHANGELOG for outputs that changed in 1.3.0 (PEG, intrinsic value, net debt/EBITDA and others).

📖 Documentation & live playground →

Zero-dependency fundamental analysis for JavaScript and TypeScript. Financial ratio analysis from raw income-statement, balance-sheet and cash-flow numbers: valuation (P/E, PEG, EV/EBITDA, DCF and intrinsic value), profitability, liquidity, leverage, efficiency and financial-distress metrics (Altman Z-Score, Piotroski score) — each with an optional plain-English rating. No API calls, no runtime dependencies. Runs in Node.js, browsers and edge runtimes.

Contents

• What it is (and is not)
• Who it's for
• Installation
• Quick start
• Input conventions — read this first
• About the ratings
• Metrics reference
• Individual functions
• Composite scores
• TypeScript
• Changelog · License

What it is (and is not)

fundamental-analysis is a library of financial-statement ratios plus a small analysis layer:

1. Pure metric functions — pe(), roe(), netDebtToEbitda(), altmanZScore(), calculateDCF() … Each takes plain numbers and returns number | null.
2. Analyzers — analyzeCompany() takes one flat object of fundamentals and returns every metric it can compute, grouped into valuation, profitability, liquidity, solvency, efficiency, risk and quality.
3. Evaluator — evaluate.* turns a value into { value, status: "Good" | "Neutral" | "Bad" | "N/A", insight }.
4. Series helpers — growth rates, CAGR, median growth, trailing-twelve-month (TTM) and multi-year aggregation.
5. Composite scores — Quality, Growth, Value and Momentum scores (0–100) and a weighted G-Factor.

It does not:

• fetch market data (bring your own: yahoo-finance2, Alpha Vantage, Financial Modeling Prep, Polygon.io, your database, a CSV…);
• compute technical indicators (RSI, MACD, moving averages…). computeMomentumScore() expects you to supply RSI, ADX and SMA values computed elsewhere;
• provide time-value-of-money (NPV/IRR/PMT) or portfolio statistics beyond the Sharpe ratio;
• model banks, insurers or REITs. Ratios such as current ratio, EV/EBITDA and Altman Z are not meaningful for financial companies.

Who it's for

Works for companies in any market (US, UK, EU, Canada, Australia, India …) as long as all amounts in one snapshot use the same currency and unit.

Installation

npm install fundamental-analysis

Ships as CommonJS + ES modules + TypeScript declarations, marked side-effect-free for tree-shaking. Node.js ≥ 16.

Quick start

import { analyzeCompany } from 'fundamental-analysis';

const data = {
  price: 150, eps: 5, bookValuePerShare: 20, marketCap: 150_000,
  totalDebt: 20_000, cashAndEquivalents: 5_000,
  ebitda: 10_000, ebit: 7_500, interestExpense: 500,
  netIncome: 5_000, operatingCashFlow: 7_500, totalRevenue: 50_000,
  totalAssets: 100_000, totalLiabilities: 60_000, totalEquity: 40_000,
  currentAssets: 40_000, currentLiabilities: 25_000, inventory: 10_000,
  retainedEarnings: 20_000,
  expectedEarningsGrowthRate: 0.15,   // 15 %, as a decimal
};

const analysis = analyzeCompany(data, true); // true → { value, status, insight } per metric

analysis.valuation.pe;
// { value: 30, status: "Bad", insight: "Expensive by generic standards. High growth is priced in; normal for some sectors." }

analysis.valuation.peg;              // { value: 2, status: "Bad", ... }        P/E 30 ÷ 15 % growth
analysis.valuation.evEbitda;         // { value: 16.5, status: "Bad", ... }     (150k + 20k − 5k) / 10k
analysis.liquidity.currentRatio;     // { value: 1.6, status: "Good", ... }     40k / 25k
analysis.solvency.netDebtToEbitda;   // { value: 1.5, status: "Neutral", ... }  (20k − 5k) / 10k
analysis.quality.cashConversionRatio;// { value: 1.5, status: "Good", ... }     7.5k / 5k
analysis.risk.altmanZScore;          // { value: 2.7075, status: "Neutral", insight: "Grey Zone (original Z, manufacturers)..." }
analysis.risk.altmanZScoreDoublePrime; // { value: 2.84, status: "Good", insight: "Safe Zone (Z'', non-manufacturers)..." }
analysis.risk.piotroski;
// { value: 3, status: "Good", insight: "Strong fundamentals (3/3). Partial score: only 3 of 9 signals had data (prior-year inputs missing)." }

Call analyzeCompany(data) without true to get raw numbers only. Every input is optional; metrics whose inputs are missing come back as null.

Analyzing one category: analyzeValuation, analyzeProfitability, analyzeLiquidity, analyzeSolvency, analyzeEfficiency, analyzeRisk, analyzeQuality take the same input. analyzeBatch(companies, true) runs a whole watchlist:

import { analyzeBatch } from 'fundamental-analysis';

const results = analyzeBatch(watchlist, true);
const cheapestFirst = results
  .filter(r => r.valuation.pe.value !== null)
  .sort((a, b) => a.valuation.pe.value! - b.valuation.pe.value!);

Growth trends from time series

import { analyzeFundamentalTrends } from 'fundamental-analysis';

const trends = analyzeFundamentalTrends({
  revenue:   [365_817, 394_328, 383_285],   // oldest → newest
  netIncome: [ 94_680,  99_803,  96_995],
}, 'annual');

trends.growth.revenueCagr;     // 0.0236  (+2.36 % a year)
trends.growth.revenueGrowth;   // [0.0779, -0.0280]
trends.margins.netMargins;     // [0.2588, 0.2531, 0.2531]

Input conventions — read this first

About the ratings

The status and insight returned by evaluate.* and by the analyzers with withInsights = true come from fixed, generic rules of thumb. For example, P/E < 15 is "Good", current ratio 1.2–2.0 is "Good" and net debt/EBITDA < 1.5 is "Good".

These thresholds do not know the company's sector, market or the interest-rate environment. A P/E of 30 is ordinary for a software company and high for a utility; a current ratio of 0.8 is normal for a supermarket. Use the ratings as a first-pass screen, compare against sector peers, and do not use them as investment advice.

Metrics reference

Valuation

Intrinsic value

Profitability

Liquidity and leverage

Efficiency

Earnings quality

Risk and financial distress

Growth, TTM and history

Individual functions

import {
  pe, peg, priceToCashFlow, earningsYield, grahamNumber, marketCapToDebtCap,
  netDebtToEbitda, netCash, debtToAssets,
  daysSalesOutstanding, payableDays, cashConversionCycle,
  altmanZScore, altmanZScoreDoublePrime, sharpe, sharpeFromReturns, piotroski,
  calculateDCF, computeNCVPS, computeIntrinsicValue,
  cagr, medianGrowth, computeTTM, evaluate,
} from 'fundamental-analysis';

pe(150, 5);                                // 30
peg(30, 0.15);                             // 2      (P/E 30 with 15 % growth)
priceToCashFlow(150_000, 7_000);           // 21.43
earningsYield(5, 150);                     // 0.0333 (3.33 %)
grahamNumber(5, 20);                       // 47.43
marketCapToDebtCap(150_000, 20_000);       // 0.882

netDebtToEbitda(20_000, 5_000, 10_000);    // 1.5
netDebtToEbitda(100, 10, -20);             // null   (negative EBITDA: not meaningful)
netCash(10, 100);                          // 90
debtToAssets(20_000, 100_000);             // 0.2

daysSalesOutstanding(50_000, 6_250);       // 45.6 days
payableDays(30_000, 200_000);              // 54.75 days
cashConversionCycle(45, 60, 55);           // 50 days

altmanZScore(15_000, 20_000, 7_500, 250_000, 50_000, 100_000, 60_000);  // 3.7075 (safe)
altmanZScoreDoublePrime(15_000, 20_000, 7_500, 40_000, 100_000, 60_000); // 2.84   (safe)
sharpe(0.12, 0.04, 0.15);                  // 0.533
sharpeFromReturns([0.02, 0.01, -0.01, 0.03], 0, 12); // 2.54 (monthly returns, annualised)

piotroski({
  netIncome: 5_000, totalAssets: 100_000, operatingCashFlow: 7_000,
  priorNetIncome: 4_000, priorTotalAssets: 100_000,
});                                        // { score: 4, maxScore: 4, signals: {...} }

calculateDCF([1_000, 1_100, 1_210], 0.10, 0.025); // 15151.5 (enterprise value)
computeNCVPS(500_000, 300_000, 100_000);   // 2
computeIntrinsicValue(10, 0.15, 0.25);     // 140.50  per share, after a 25 % margin of safety
computeIntrinsicValue(10, 0.15, 0.25, { terminalPE: 20, discountRate: 0.08 }); // 205.33

cagr(1_000, 2_000, 5);                     // 0.1487 (14.87 %)
medianGrowth([800, 900, 1_100, 1_050, 1_300]); // 0.1736
computeTTM([2_200, 2_400, 2_600, 2_800]);  // 10000

evaluate.pe(pe(150, 5));
// { value: 30, status: "Bad", insight: "Expensive by generic standards. High growth is priced in; normal for some sectors." }

computeIntrinsicValue(10, 0.15, 0.25) step by step: 10 × 1.15⁵ = 20.11 EPS in year 5 → × 15 = 301.70 → ÷ 1.10⁵ = 187.33 today → × 0.75 = 140.50.

Composite scores

All four scores return 0–100. Weights are this library's heuristics, not an academic standard.

import { computeQualityScore, computeGrowthScore, computeValueScore, computeMomentumScore, computeGFactor } from 'fundamental-analysis';

computeQualityScore({
  piotroskiScore: 7, piotroskiMaxScore: 9,   // pass PiotroskiResult.score / .maxScore
  roeVsSector: 1.1,                          // company ROE ÷ sector median ROE
  marginsImproving: true,
  insiderPledgeFree: true,                   // optional: insider/promoter shares pledged ≈ 0
  insiderHoldingStable: true,                // optional: insider/promoter holding stable or rising
});                                          // 93.33

computeQualityScore({ piotroskiScore: 7, roeVsSector: 1.1, marginsImproving: true }); // 90.48
// The insider/promoter signals are optional (common in India, rarely reported elsewhere).
// When omitted, the remaining weights are rescaled so the score still spans 0–100.

computeGrowthScore({ revenueGrowthVsSector: 1.3, profitGrowthRate: 0.20,
  epsGrowthRate: 0.18, cfoPositive: true, revenueAccelerating: true });  // 86.07
computeValueScore({ peVs3yrAvg: 0.8, pbVsSector: 0.75, peg: 0.9,
  historicalPePercentile: 30 });                                         // 65.96
computeMomentumScore({ priceVsSma200: 1.08, rsi: 58, adx: 28,
  volumeRatio: 1.2, roc125: 0.18 });                                     // 81.67 (RSI/ADX/SMA computed elsewhere)
computeGFactor(82, 78, 67);                  // 76.85 = 0.40 × Quality + 0.35 × Growth + 0.25 × Momentum

The older field names pledgeFree and promoterStable are still accepted.

TypeScript

Full declarations are included. With withInsights = true the analyzers are typed as { value, status, insight } per metric; without it, as number | null:

import { analyzeCompany, type CompanySnapshotInput } from 'fundamental-analysis';

const snapshot: CompanySnapshotInput = { price: 150, eps: 5 };

const raw = analyzeCompany(snapshot);          // raw.valuation.pe: number | null
const rated = analyzeCompany(snapshot, true);  // rated.valuation.pe.status: "Good" | "Neutral" | "Bad" | "N/A"

CompanySnapshotInput fields — all optional numbers:

• Market data: price, marketCap, eps, bookValuePerShare, revenuePerShare, annualDividendPerShare, analystTargetPrice, expectedEarningsGrowthRate (decimal, for PEG), sharesOutstanding
• Income statement: totalRevenue, costOfRevenue, grossProfit, operatingIncome, ebit, ebitda, interestExpense, netIncome, taxRate
• Cash flow: operatingCashFlow, freeCashFlow
• Balance sheet: totalAssets, totalLiabilities, totalEquity, currentAssets, currentLiabilities (current & quick ratio, working capital), totalDebt, longTermDebt, cashAndEquivalents, inventory, tradeReceivables, workingCapital, retainedEarnings
• Precomputed risk inputs (same period basis): returns, riskFree, stdDev

Changelog

See CHANGELOG.md. Version 1.3.0 corrects several outputs (PEG, intrinsic value, net debt/EBITDA, current ratio in the analyzer and others); read it before upgrading.

License

MIT © 2026 Boffin Coders

About Boffin Coders

fundamental-analysis is built and maintained by Boffin Coders. We design and build websites, web applications and mobile apps, and run their SEO, for businesses and agencies. Building a screener, a finance dashboard or fundamentals into your product? See our web application development work or talk to us.

More open source by Boffin Coders: ts-netstorageapi-akamai · durable_queue · all Boffin Coders open source · github.com/boffincoders

Issues and pull requests: github.com/boffincoders/fundamental-analysis.

This library computes financial ratios from the numbers you supply. It is not investment advice.