ielts-writing-tools

Zero-dependency TypeScript utilities and a command-line tool for deterministic IELTS Writing checks.

Built and maintained by IELTS Writing Checker, an independent practice tool for estimated scores, criterion-level feedback, and inline corrections.

Features

• Practical English word counting with configurable hyphen handling
• Task 1 and Task 2 minimum-word checks
• Paragraph and sentence statistics
• Repeated content-word and phrase detection
• Four-criterion task score calculation
• Combined Writing score calculation with Task 2 weighted twice
• TypeScript declarations and an ESM API
• A CLI for local files and standard input
• No runtime dependencies, network requests, or essay uploads

This package performs deterministic structural checks. It does not estimate a score from essay text.

Install

npm install ielts-writing-tools

Node.js 18 or newer is required.

Quick start

import { analyzeEssay } from "ielts-writing-tools";

const result = analyzeEssay(
  `Some people believe public transport should be free.

This essay discusses the possible benefits and drawbacks.`,
  { task: 2 },
);

console.log(result.wordCount);
console.log(result.requirements.wordsNeeded);
console.log(result.structure.paragraphCount);
console.log(result.repeatedWords);

Word counting

import { countWords, tokenizeWords } from "ielts-writing-tools";

countWords("A well-written response doesn't need inflated language.");
// 7

tokenizeWords("Long-term planning", { hyphenatedWords: "separate" });
// ["Long", "term", "planning"]

Hyphenated compounds count as one word by default. Set hyphenatedWords to "separate" when a different convention is required.

Task requirements

import { checkTaskRequirements } from "ielts-writing-tools";

checkTaskRequirements("A short response.", 1);
// {
//   task: 1,
//   minimumWordCount: 150,
//   wordCount: 3,
//   meetsMinimumWordCount: false,
//   wordsNeeded: 147
// }

The package uses 150 words for Task 1 and 250 words for Task 2.

Score calculations

import {
  calculateTaskScore,
  calculateWritingScore,
} from "ielts-writing-tools";

calculateTaskScore([6.5, 7, 6, 6.5]);
// { raw: 6.5, rounded: 6.5 }

calculateWritingScore({
  task1Score: 6,
  task2Score: 7,
});
// { raw: 6.666..., rounded: 6.5 }

Accepted input scores range from 0 to 9 in half-point increments. A single task calculation requires exactly four criterion scores.

Repetition analysis

import {
  findRepeatedPhrases,
  findRepeatedWords,
} from "ielts-writing-tools";

findRepeatedWords(essay, {
  minimumOccurrences: 3,
  minimumLength: 4,
  limit: 10,
});

findRepeatedPhrases(essay, {
  phraseLength: 2,
  minimumOccurrences: 2,
  limit: 10,
});

Repetition results are descriptive counts, not quality judgments. Common English function words are excluded from repeated-word results.

CLI

Analyze a local file:

npx ielts-writing-tools essay.txt --task 2

Read from standard input:

cat essay.txt | npx ielts-writing-tools - --task 2

Return JSON:

npx ielts-writing-tools essay.txt --task 1 --json

See every option:

npx ielts-writing-tools --help

Privacy

All analysis runs locally. The package does not make network requests or send essay text anywhere.

For a full AI-assisted practice review with estimated scores and inline corrections, use IELTS Writing Checker.

Development

npm install
npm test
npm run check

npm run check compiles the package, runs the test suite, and checks the files that would be published.

Disclaimer

IELTS is a trademark of its respective owner. This project is independent and is not affiliated with, approved by, or endorsed by IELTS or its owners. Calculations and checks are provided for practice and software-development purposes only.

Useful official references:

• IELTS Writing test preparation resources
• IELTS scoring in detail

License

MIT