fundamental-analysis: a financial ratios API for TypeScript
Turn income-statement, balance-sheet and cash-flow numbers into valuation, profitability, liquidity, leverage, efficiency and distress metrics, each with an optional plain-English rating. A fundamental analysis API that runs in your own code: no network calls, no dependencies, and null instead of NaN when a ratio cannot be computed.
- fundamental-analysis 1.3.2 on npm, released 29 Oct 2026
- MIT licence, tested on every change
- TypeScript
- Zero dependencies
- MIT
npm install fundamental-analysis40+
Metrics
Valuation, profitability, liquidity, leverage, efficiency, distress and quality
300+
Tests
Fixed expected values, run in CI on pushes and pull requests
0
Dependencies
Runs in Node.js, browsers and edge runtimes
MIT
Licence
Free for commercial products
Ratio formulas go wrong without a sound
Every investing app, screener and finance dashboard computes the same ratios, and each team writes them again. The formulas look simple and fail in ways nobody notices: a growth rate passed as 15 instead of 0.15, a loss-making company whose negative EBITDA reads as a healthy ratio, a division by zero that puts NaN on a chart.
fundamental-analysis puts those formulas in one tested place. Each ratio takes plain numbers and returns a number or null, never NaN. Units are fixed and written down, and an optional evaluator turns each value into Good, Neutral or Bad with a sentence a reader understands.
It does not fetch market data. Bring numbers from your own database, a CSV or any provider, and the library does the arithmetic the same way every time.
From raw statements to ratings
Use one function, a category, or the whole company at once. Every input is optional: a metric whose inputs are missing comes back as null.
Valuation
Profitability
Liquidity and debt
Distress and quality
Intrinsic value
Series and scores
One call, a rated company snapshot
Pass what you have. analyzeCompany(data, true) returns every metric it can compute, grouped by category, each with a status and an insight.
npm install fundamental-analysis1import { analyzeCompany } from 'fundamental-analysis';
2
3const data = {
4 price: 150, eps: 5, bookValuePerShare: 20, marketCap: 150_000,
5 totalDebt: 20_000, cashAndEquivalents: 5_000,
6 ebitda: 10_000, ebit: 7_500, interestExpense: 500,
7 netIncome: 5_000, operatingCashFlow: 7_500, totalRevenue: 50_000,
8 totalAssets: 100_000, totalLiabilities: 60_000, totalEquity: 40_000,
9 currentAssets: 40_000, currentLiabilities: 25_000, inventory: 10_000,
10 retainedEarnings: 20_000,
11 expectedEarningsGrowthRate: 0.15, // 15 %, as a decimal
12};
13
14const analysis = analyzeCompany(data, true);
15
16analysis.valuation.peg; // { value: 2, status: "Bad", ... }
17analysis.liquidity.currentRatio; // { value: 1.6, status: "Good", ... }
18analysis.solvency.netDebtToEbitda; // { value: 1.5, status: "Neutral", ... }The full guide, every method and more examples are on the documentation site.
What it is, and what it is not
Built for
- Fintech and investing apps that show company snapshot cards
- Stock screeners that rank and filter a watchlist on ratios
- Dashboards and reports built on your own financial data
- Back ends and edge functions that need the same numbers every time
It does not
- Fetch market data: bring your own source
- Compute technical indicators such as RSI or MACD
- Model banks, insurers or REITs, where these ratios mislead
- Give investment advice: the ratings are generic rules of thumb
Numbers you can check by hand
Every metric has a documented formula and input convention, and the tests compare results against fixed expected values, such as P/E 150 ÷ 5 = 30.
300+ tests in CI
Formulas, edge cases and ratings are tested, including zero and negative inputs, on Node 18, 20 and 22 for pushes to master and every pull request.
Written formulas
The docs give each metric's formula and input units, and explain how the generic ratings work.
Live demo
The docs site runs the analysis on real companies' figures, so any result can be tried before installing.
Changelog
The changelog lists every output 1.3.0 corrected, and says when a release changes no results.
Where this work shows up
Products that turn financial data into decisions, and the teams that build them.
Dashboards, screeners and data products built on your own data.
Reports and dashboards for finance teams, when a product is not the answer.
The team that wrote this library builds Node.js and TypeScript back ends.
The other packages we maintain
durable_queue
A persistent task queue for Dart and Flutter. Uploads, messages and syncs are saved before they run, retried with backoff and recovered after a crash, and uploads can finish after the app is closed.
ts-netstorageapi-akamai
A typed, promise-based client and command line tool for the Akamai NetStorage HTTP API: upload and download files or buffers, list, inspect and manage files, with Akamai's method names.
Every package, with its documentation and source: open source by Boffin Coders.
fundamental-analysis: common questions
Not answered here?
Building a product on financial data?
We maintain fundamental-analysis for products like yours. Tell us what your users need to see, and we will show you how we would build it.