Deterministic Readability Formulas for Editorial Clarity
Measure how readable your English text is. Get stable, AI-ready scores for Flesch-Kincaid, Gunning Fog, and other standard metrics with a rule-based library.
Lightweight, ESM-ready, and math-safe. Built for writing analysis tools and content governance pipelines.
Overview
Measure how readable your English text is. Get stable, AI-ready scores for Flesch-Kincaid, Gunning Fog, and other standard metrics with a rule-based library.
Frequently asked questions
What are readability algorithms?
Readability algorithms turn text measurements into grade-level scores. The standard ones are Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, Dale-Chall, and the Automated Readability Index. @veldica/readability implements each as a deterministic function and also computes a consensus grade across all of them.
What is the automated readability index formula?
ARI = 4.71 x (characters / words) + 0.5 x (words / sentences) - 21.43. The result approximates the US grade level needed to understand the text. @veldica/readability computes it with math-safe handling for short or empty input.
Where can I check my writing with these formulas?
PublishReady runs the same formulas as MCP tools your writing agents can call. It adds revision targets and AI-marker audits on top of the raw scores. See the PublishReady MCP server to try it.
Pure functions that give the same math output every time. Stay consistent across large datasets and keep your editorial standards high.
Ultra-lightweight design with only one tiny dependency. Built for ESM environments and precise tree-shaking to keep your app fast.
Built for AI agents and LLM pipelines. Documented formulas and safe math help avoid errors in automated workflows.
Current workflow
Manual readability checks are slow and prone to errors. Heavy linguistic tools often add too much complexity for scoring tasks.
- Calculating grades by hand is slow and often leads to human error.
- Old libraries often have heavy dependencies that bloat your project.
- Edge cases like decimals or empty text can cause math errors in basic tools.
- Floating point issues in naive code can lead to inconsistent scores between servers.
- Lack of a single 'consensus' grade makes it difficult to get a balanced view of your text.
Where it breaks
These issues can hurt your content quality and make your editorial tools harder to trust.
- Inconsistent scores make it difficult to set measurable goals for your writing team.
- Large packages slow down web editors and increase latency on the edge.
- Fragile code can crash your pipelines when it hits malformed prose.
- Fragmented tools force developers to use multiple libraries for one task.
The Readability Engine
@veldica/readability gives you a formula suite with repeatable, math-checked output.
Access Flesch-Kincaid, Gunning Fog, SMOG, Dale-Chall, and more from one interface.
Automatically calculate an aggregate grade level and band across all formulas for a fair assessment.
Stop runtime errors before they start. Built-in math safety keeps your production pipelines stable.
ESM package structure supports tree-shaking. Import only the specific formulas your app needs.
Verified request
# Install the package
npm install @veldica/readability
# Usage in your project
import { runAllFormulas } from '@veldica/readability';
const stats = {
counts: {
word_count: 120,
sentence_count: 6,
syllable_count: 185,
complex_word_count: 22,
polysyllable_count: 18,
character_count: 650,
letter_count: 540
}
};
const results = runAllFormulas(stats);Verified response
The library returns a metric overview of all metrics, including a calculated consensus grade.
{
"consensus_grade": 9,
"readability_band": "High School / Average",
"formulas": {
"flesch_kincaid_grade_level": 9.2,
"flesch_reading_ease": 58.4,
"gunning_fog": 10.1,
"smog": 9.5,
"coleman_liau": 8.8,
"automated_readability_index": 9.1
}
}Output interpretation
The library is built for clarity. It provides both raw scores and human-readable interpretations.
- Unified Schema: All formulas return a consistent result with the raw score and metadata.
- Consensus Logic: Get a fair view of text difficulty by averaging multiple scores automatically.
- Readability Bands: Maps numeric scores to labels like 'Easy', 'Conversational', or 'Technical'.
- Safe Math: We handle short or empty text carefully to prevent calculation errors.
- Zero Config: Ready to use out of the box with standard English rules and Dale-Chall lists.
Practical Usage: Content Governance
Use readability checks in your CMS to ensure content stays within your target bounds.
- Get linguistic counts using a tool like @veldica/prose-tokenizer.
- Pass the counts into the readability library to get a full score report.
- Compare the results against your internal style guide or audience goals.
- Flag sections that are too complex for editorial review.
- Track readability over time to maintain long-term content quality.
import { fleschReadingEase } from '@veldica/readability/formulas';
const result = fleschReadingEase(stats);
if (result.score < 60) {
console.log("Warning: Content might be too difficult for a general audience.");
}Choosing a Readability Library
While many tools exist, @veldica/readability is built for editorial pipelines.
Often old and unmaintained. They rely on outdated patterns and heavy dependencies that bloat your app.
Capable but slow and use too much memory. Often overkill for basic math-based scoring.
Focused and stable. Optimized for speed, math accuracy, and zero-bloat integration in JavaScript.
Keep Exploring
Use the Workflow Library to browse more guides, comparisons, and integration examples to continue your evaluation.
See the solutions, comparisons, and integration guides collected in one place.
Review grounded audit, compare, fix-plan, and report excerpts before you wire the API into anything.
Jump from the workflow page into the quickstart, endpoint guides, and full OpenAPI reference.
Quantify your content quality
Explore the package on GitHub or install via NPM. Build the foundation for deterministic writing analysis.