Flesch Kincaid Better

A high-performance, accurate Flesch-Kincaid Grade Level calculator.

Built with TypeScript and Bun, this library uses a hybrid syllable counter that combines dictionary lookups for accuracy (handling words like colonel or recipe) with a robust heuristic fallback for unknown words.

Features

• 🚀 Fast & Lightweight: Optimized for speed.
• 🧠 Hybrid Accuracy: Uses a dictionary lookup for common English words and a regex heuristic for rare/invented words.
• 📘 TypeScript Native: Written in TS with full type definitions (.d.ts) included.
• 📊 Detailed Stats: Returns not just the score, but the raw counts (syllables, words, sentences).

Installation

npm

npm install flesch-kincaid-better

bun

bun add flesch-kincaid-better

Usage

Basic Example

import { getGradeLevel } from 'flesch-kincaid-better';

const text = "The quick brown fox jumps over the lazy dog. This sentence is simple.";
const result = getGradeLevel(text);

console.log(result.score);  // e.g., 2.3 (Grade Level)
console.log(result.counts); // { sentences: 2, words: 14, syllables: 18 }

API Reference

getGradeLevel(text: string): ReadabilityScore

Analyzes the given text and returns the Flesch-Kincaid Grade Level score along with detailed statistics.

Parameters:

• text - The text to analyze

Returns: ReadabilityScore object:

interface ReadabilityScore {
    score: number;        // Flesch-Kincaid Grade Level
    counts: {
        sentences: number;  // Number of sentences
        words: number;      // Number of words
        syllables: number;  // Total syllable count
    };
}

Interpreting the Score

The Flesch-Kincaid Grade Level corresponds to US school grade levels:

| Score | Reading Level | |-------|---------------| | 0-5 | Elementary School | | 6-8 | Middle School | | 9-12 | High School | | 13+ | College Level |

License

This project is licensed under the MIT License - see the LICENSE file for details.