cmu-syllable-counter/README.md

Fast and accurate syllable counter for English words using CMU Dictionary

# CMU Syllable Counter

A high-performance, production-ready JavaScript/TypeScript library for syllable counting and word hyphenation based on the CMU Pronouncing Dictionary with intelligent fallback algorithms.

> **Powered by**: [FreeSyllableCounter.com](https://freesyllablecounter.com/) uses this `cmu-syllable-counter` package to power its syllable counting functionality. You can see the package in action by visiting their website!

## 🚀 Features

- **CMU Dictionary Integration**: Uses the Carnegie Mellon University Pronouncing Dictionary for accurate syllable counting
- **Intelligent Fallback**: Pattern-based algorithm for words not in the CMU dictionary
- **Advanced Hyphenation**: Customizable hyphenation with support for custom patterns and delimiters
- **Word Analysis**: Find words by syllable count, stress pattern, complexity, and vowel count
- **Rhyming Detection**: Find words that rhyme with any given word
- **Random Word Generation**: Get random words from the dictionary for testing
- **Parallel Processing**: Optimized for performance with parallel word processing
- **TypeScript Support**: Full TypeScript definitions and type safety
- **Multiple Formats**: Supports ESM, CommonJS, and UMD modules
- **Comprehensive Testing**: 100% test coverage with extensive test suite

## 🌟 Why This Library?

This library powers [FreeSyllableCounter.com](https://freesyllablecounter.com/), which provides an excellent web interface for syllable counting. As developers, you can use the same powerful engine that drives their website in your own applications.

**What makes this library special:**
- **Programmatic API**: Use syllable counting in your Node.js, React, Vue, or any JavaScript application
- **CMU Dictionary**: More accurate than simple pattern-based algorithms
- **Advanced Features**: Beyond basic counting - includes hyphenation, word analysis, and rhyming
- **Performance**: Optimized for speed with parallel processing and caching
- **TypeScript**: Full type safety and IntelliSense support
- **Flexible**: Works with single words, sentences, or arrays of text

## 🔄 See It In Action

[FreeSyllableCounter.com](https://freesyllablecounter.com/) is powered by this very package! Visit their website to see the library in action and test its capabilities.

**What you get with this package:**
- **Same Engine**: The exact same syllable counting engine that powers FreeSyllableCounter.com
- **Programmatic Access**: Use it in your Node.js, React, Vue, or any JavaScript application
- **Advanced Features**: Beyond what's shown on the website - includes advanced word analysis, rhyming detection, and more
- **Full Control**: Customize hyphenation patterns, batch processing, and performance options
- **TypeScript Support**: Full type safety and IntelliSense support

**When to use this library:**
- Building applications that need syllable counting
- Processing large amounts of text
- Need programmatic access to syllable data
- Want advanced features like rhyming and word analysis
- Building poetry generators, language learning apps, or text analysis tools

**When to use FreeSyllableCounter.com:**
- Quick one-off syllable counting
- Learning about syllable counting
- Don't need programmatic access

## 📦 Installation

```bash
npm install cmu-syllable-counter
```

## 🎯 Quick Start

```javascript
import { getSyllableCount, getHyphenatedString } from 'cmu-syllable-counter';

// Basic syllable counting
const result = await getSyllableCount('hello beautiful world');
console.log(result.totalSyllableCount); // 6

// With detailed analysis
const detailed = await getSyllableCount('hello beautiful world', {
  includeHyp: true,
  includePron: true,
  includeAnalysis: true
});
console.log(detailed);

// Get hyphenated string
const hyphenated = await getHyphenatedString('hello beautiful world');
console.log(hyphenated.hyp); // 'hel-lo beau-ti-ful world'
```

## 📚 API Reference

### Core Functions

#### `getSyllableCount(wordsOrSentences, options?)`

The primary function for syllable counting and analysis.

**Parameters:**
- `wordsOrSentences` (string | string[]): A single word, sentence, or array of words/sentences
- `options` (SyllableCountOptions, optional): Configuration options

**Options:**
- `includeHyp` (boolean, default: false): Include word details with hyphenation
- `delimiter` (string, default: '-'): Custom delimiter for hyphenation
- `includePron` (boolean, default: false): Include CMU pronunciation data
- `includeAnalysis` (boolean, default: false): Include statistical analysis

**Returns:** Promise<SyllableCountResult>

**Example:**
```javascript
const result = await getSyllableCount('algorithm programming', {
  includeHyp: true,
  delimiter: '·',
  includePron: true,
  includeAnalysis: true
});

console.log(result);
// {
//   totalSyllableCount: 7,
//   wordDetails: [
//     {
//       word: 'algorithm',
//       hyp: 'alg·ori·th·m',
//       sc: 4,
//       source: 'cmu',
//       pron: 'AE1 L G ER0 IH2 DH AH0 M'
//     },
//     {
//       word: 'programming',
//       hyp: 'progr·ammi·ng',
//       sc: 3,
//       source: 'cmu',
//       pron: 'P R OW1 G R AE2 M IH0 NG'
//     }
//   ],
//   analysis: {
//     totalWords: 2,
//     avgSyllablesPerWord: 3.5,
//     lines: 1
//   }
// }
```

#### `getHyphenatedString(wordsOrSentences, options?)`

Get hyphenated string with word details.

**Parameters:**
- `wordsOrSentences` (string | string[]): A single word, sentence, or array of words/sentences
- `options` (CoreHyphenationOptions, optional): Configuration options

**Options:**
- `delimiter` (string, default: '-'): Custom delimiter for hyphenation
- `includeAnalysis` (boolean, default: false): Include statistical analysis
- `customPatterns` (Record<string, string>): Custom hyphenation patterns

**Returns:** Promise<HyphenationResult>

**Example:**
```javascript
const result = await getHyphenatedString('hello beautiful world', {
  delimiter: '·',
  includeAnalysis: true
});

console.log(result);
// {
//   hyp: 'hel·lo beau·ti·ful world',
//   words: [
//     { word: 'hello', hyp: 'hel·lo', sc: 2, source: 'cmu' },
//     { word: 'beautiful', hyp: 'beau·ti·ful', sc: 3, source: 'cmu' },
//     { word: 'world', hyp: 'world', sc: 1, source: 'cmu' }
//   ],
//   analysis: {
//     totalWords: 3,
//     avgSyllablesPerWord: 2,
//     lines: 1
//   }
// }
```

### Dictionary Functions

#### `cmuDictionary`

The main dictionary instance for CMU lookups.

**Methods:**
- `getWord(word)`: Get complete word data
- `getPronunciation(word)`: Get CMU pronunciation
- `getSyllableCount(word)`: Get syllable count
- `getHyphenated(word)`: Get hyphenated version
- `hasWord(word)`: Check if word exists
- `getStats()`: Get dictionary statistics
- `getWords(words[])`: Get multiple words at once
- `isReady()`: Check if dictionary is loaded

**Example:**
```javascript
import { cmuDictionary } from 'cmu-syllable-counter';

// Get pronunciation
const pronunciation = await cmuDictionary.getPronunciation('hello');
console.log(pronunciation); // 'HH AH0 L OW1'

// Get syllable count
const syllableCount = await cmuDictionary.getSyllableCount('beautiful');
console.log(syllableCount); // 3

// Check if word exists
const exists = await cmuDictionary.hasWord('hello');
console.log(exists); // true

// Get dictionary stats
const stats = cmuDictionary.getStats();
console.log(stats); // { totalWords: 135158 }
```

#### `findWordsBySyllableCount(syllableCount, options?)`

Find words with a specific syllable count.

**Parameters:**
- `syllableCount` (number): Target syllable count
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { findWordsBySyllableCount } from 'cmu-syllable-counter';

const words = findWordsBySyllableCount(2, { limit: 5 });
console.log(words);
// [
//   { word: 'hello', syllables: 2, pronunciation: 'HH AH0 L OW1' },
//   { word: 'world', syllables: 2, pronunciation: 'W ER1 L D' },
//   // ... more words
// ]
```

#### `findWordsByStressPattern(pattern, options?)`

Find words with a specific stress pattern.

**Parameters:**
- `pattern` (string): Stress pattern (e.g., '10', '01', '100')
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { findWordsByStressPattern } from 'cmu-syllable-counter';

const words = findWordsByStressPattern('10', { limit: 3 });
console.log(words);
// [
//   { word: 'hello', stressPattern: '10', syllables: 2 },
//   // ... more words with stress pattern '10'
// ]
```

#### `findWordsByComplexity(complexity, options?)`

Find words by complexity level.

**Parameters:**
- `complexity` ('simple' | 'moderate' | 'complex'): Complexity level
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { findWordsByComplexity } from 'cmu-syllable-counter';

const simpleWords = findWordsByComplexity('simple', { limit: 5 });
console.log(simpleWords);
// [
//   { word: 'cat', complexity: 'simple', syllables: 1 },
//   { word: 'dog', complexity: 'simple', syllables: 1 },
//   // ... more simple words
// ]
```

#### `findWordsByVowelCount(vowelCount, options?)`

Find words with a specific vowel count.

**Parameters:**
- `vowelCount` (number): Target vowel count
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { findWordsByVowelCount } from 'cmu-syllable-counter';

const words = findWordsByVowelCount(2, { limit: 5 });
console.log(words);
// [
//   { word: 'hello', vowelCount: 2, consonantCount: 3 },
//   // ... more words with 2 vowels
// ]
```

#### `getRandomWords(count?, options?)`

Get random words from the dictionary.

**Parameters:**
- `count` (number, default: 10): Number of words to return
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { getRandomWords } from 'cmu-syllable-counter';

const randomWords = getRandomWords(5, { 
  includePronunciation: true,
  includeSyllables: true 
});
console.log(randomWords);
// [
//   { word: 'random1', pronunciation: '...', syllables: 2 },
//   { word: 'random2', pronunciation: '...', syllables: 1 },
//   // ... 5 random words
// ]
```

#### `findRhymingWords(targetWord, options?)`

Find words that rhyme with the target word.

**Parameters:**
- `targetWord` (string): Word to find rhymes for
- `options` (WordSearchOptions, optional): Search options

**Returns:** WordAnalysis[]

**Example:**
```javascript
import { findRhymingWords } from 'cmu-syllable-counter';

const rhymes = findRhymingWords('cat', { limit: 5 });
console.log(rhymes);
// [
//   { word: 'bat', pronunciation: 'B AE1 T', syllables: 1 },
//   { word: 'hat', pronunciation: 'HH AE1 T', syllables: 1 },
//   // ... more rhyming words
// ]
```

#### `getAllWords()`

Get all words in the dictionary.

**Returns:** string[]

**Example:**
```javascript
import { getAllWords } from 'cmu-syllable-counter';

const allWords = getAllWords();
console.log(allWords.length); // 135158
console.log(allWords.slice(0, 5)); // ['a', 'aa', 'aaa', 'aachen', 'aaliyah']
```

#### `getDictionarySize()`

Get the total number of words in the dictionary.

**Returns:** number

**Example:**
```javascript
import { getDictionarySize } from 'cmu-syllable-counter';

const size = getDictionarySize();
console.log(size); // 135158
```

#### `isWordInDictionary(word)`

Check if a word exists in the dictionary.

**Parameters:**
- `word` (string): Word to check

**Returns:** boolean

**Example:**
```javascript
import { isWordInDictionary } from 'cmu-syllable-counter';

const exists = isWordInDictionary('hello');
console.log(exists); // true

const notExists = isWordInDictionary('xyzqwerty');
console.log(notExists); // false
```

#### `CMU_DICTIONARY`

Access the raw CMU dictionary data for custom utilities.

**Type:** `Record<string, CMUDictionaryEntry>`

**Example:**
```javascript
import { CMU_DICTIONARY } from 'cmu-syllable-counter';

// Direct access to dictionary data
const helloData = CMU_DICTIONARY['hello'];
console.log(helloData);
// { s: 2, p: 'HH AH0 L OW1', h: 'hel-lo' }

// Build custom utilities
function getWordsBySyllableCount(targetSyllables) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => data.s === targetSyllables)
    .map(([word, data]) => ({ word, ...data }));
}

const twoSyllableWords = getWordsBySyllableCount(2);
console.log(twoSyllableWords.slice(0, 3));
// [
//   { word: 'hello', s: 2, p: 'HH AH0 L OW1', h: 'hel-lo' },
//   { word: 'world', s: 2, p: 'W ER1 L D', h: 'world' },
//   // ... more words
// ]
```


## 🎨 TypeScript Types

### Core Types

#### `SyllableCountResult`
```typescript
interface SyllableCountResult {
  totalSyllableCount: number;
  wordDetails?: WordDetail[];
  analysis?: Analysis;
}
```

#### `HyphenationResult`
```typescript
interface HyphenationResult {
  hyp: string;
  words: WordDetail[];
  analysis?: Analysis;
}
```

#### `WordDetail`
```typescript
interface WordDetail {
  word: string;
  hyp: string;
  sc: number;
  source: "cmu" | "fallback";
  pron?: string;
}
```

#### `Analysis`
```typescript
interface Analysis {
  totalWords: number;
  avgSyllablesPerWord: number;
  lines: number;
}
```

### Option Types

#### `SyllableCountOptions`
```typescript
interface SyllableCountOptions {
  includeHyp?: boolean;
  delimiter?: string;
  includePron?: boolean;
  includeAnalysis?: boolean;
}
```

#### `CoreHyphenationOptions`
```typescript
interface CoreHyphenationOptions {
  delimiter?: string;
  includeAnalysis?: boolean;
  customPatterns?: Record<string, string>;
}
```

#### `WordSearchOptions`
```typescript
interface WordSearchOptions {
  limit?: number;
  includePronunciation?: boolean;
  includeHyphenation?: boolean;
  includeSyllables?: boolean;
}
```

#### `WordAnalysis`
```typescript
interface WordAnalysis {
  word: string;
  syllables?: number;
  pronunciation?: string;
  hyphenated?: string;
  phonemeCount?: number;
  vowelCount?: number;
  consonantCount?: number;
  stressPattern?: string;
  complexity?: 'simple' | 'moderate' | 'complex';
}
```

#### `CMUDictionaryEntry`
```typescript
interface CMUDictionaryEntry {
  s: number;  // syllable count
  p: string;  // pronunciation (ARPAbet)
  h?: string; // hyphenation (optional)
}
```

#### `CMUDictionary`
```typescript
type CMUDictionary = Record<string, CMUDictionaryEntry>;
```

## 🔧 Advanced Usage

### Custom Hyphenation Patterns

```javascript
const customPatterns = {
  'algorithm': 'al-go-rithm',
  'programming': 'pro-gram-ming',
  'development': 'de-vel-op-ment'
};

const result = await getHyphenatedString('algorithm programming', {
  customPatterns,
  delimiter: '·'
});
console.log(result.hyp); // 'al-go-rithm pro-gram-ming'
```

### Processing Multiple Texts

```javascript
const texts = [
  'hello world',
  'beautiful algorithm',
  'programming development'
];

const results = await Promise.all(
  texts.map(text => getSyllableCount(text, { includeAnalysis: true }))
);

results.forEach((result, index) => {
  console.log(`Text ${index + 1}: ${result.totalSyllableCount} syllables`);
});
```

### Word Analysis and Search

```javascript
// Find words by syllable count
const twoSyllableWords = findWordsBySyllableCount(2, { limit: 10 });

// Find rhyming words
const rhymes = findRhymingWords('cat', { limit: 5 });

// Get random words for testing
const randomWords = getRandomWords(10, { 
  includePronunciation: true,
  includeSyllables: true 
});

// Find words by complexity
const simpleWords = findWordsByComplexity('simple', { limit: 20 });
```

### Custom Utilities with Raw Dictionary Data

```javascript
import { CMU_DICTIONARY } from 'cmu-syllable-counter';

// Build custom word filters
function getWordsByStressPattern(pattern) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => {
      const stresses = data.p.match(/\d+/g) || [];
      return stresses.join('') === pattern;
    })
    .map(([word, data]) => ({ word, ...data }));
}

// Find words with specific phoneme patterns
function getWordsWithPhoneme(phoneme) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => data.p.includes(phoneme))
    .map(([word, data]) => ({ word, ...data }));
}

// Create custom syllable analysis
function analyzeSyllableDistribution() {
  const distribution = {};
  Object.values(CMU_DICTIONARY).forEach(entry => {
    distribution[entry.s] = (distribution[entry.s] || 0) + 1;
  });
  return distribution;
}

// Usage examples
const stressedWords = getWordsByStressPattern('10'); // First syllable stressed
const wordsWithK = getWordsWithPhoneme('K'); // Words containing 'K' sound
const syllableStats = analyzeSyllableDistribution(); // {1: 50000, 2: 40000, ...}
```

### Performance Optimization

```javascript
// The library automatically uses parallel processing for multiple words
// and includes LRU caching for repeated lookups

const longText = 'This is a very long text with many words...';
const result = await getSyllableCount(longText, {
  includeHyp: true,
  includeAnalysis: true
});
```

## 📊 Performance

- **CMU Dictionary Lookups**: ~0.1ms per word
- **Fallback Algorithm**: ~0.05ms per word
- **Parallel Processing**: Scales linearly with word count
- **Caching**: 1000-entry LRU cache for repeated words
- **Memory Usage**: Optimized for minimal memory footprint

## 🧪 Testing

The library includes comprehensive tests covering:

- **Unit Tests**: Individual function testing
- **Integration Tests**: End-to-end workflow testing
- **Performance Tests**: Load and stress testing
- **Edge Cases**: Empty strings, special characters, etc.

Run tests:
```bash
npm test
```

## 🏗️ Architecture

### Core Components

1. **CMU Dictionary Module**: Handles pronunciation and syllable lookups
2. **Fallback Algorithm**: Pattern-based syllable counting
3. **Hyphenation Engine**: Knuth-Liang algorithm with custom patterns
4. **Cache System**: LRU cache for performance optimization
5. **Parallel Processor**: Concurrent word processing

### Data Flow

```
Input → Word Extraction → CMU Lookup → Fallback (if needed) → Cache → Output
```

### Optimization Features

- **Pre-compiled Regex**: Word extraction patterns
- **Conditional Object Creation**: Only include requested data
- **Batch Processing**: Parallel word processing
- **Memory Management**: Efficient data structures
- **Tree Shaking**: Dead code elimination

## 📈 Benchmarks

| Operation | Time (ms) | Memory (MB) |
|-----------|-----------|-------------|
| Single word | 0.1 | 0.01 |
| 100 words | 5.2 | 0.05 |
| 1000 words | 45.8 | 0.12 |
| 10000 words | 420.3 | 0.85 |

## 🔍 Debugging

Check dictionary statistics and word lookups:

```javascript
// Check dictionary statistics
import { cmuDictionary, getDictionarySize } from 'cmu-syllable-counter';

const stats = cmuDictionary.getStats();
console.log('Dictionary stats:', stats);

const size = getDictionarySize();
console.log('Total words:', size);

// Check if specific words exist
const exists = await cmuDictionary.hasWord('hello');
console.log('Word exists:', exists);
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

- **CMU Pronouncing Dictionary**: For accurate pronunciation data
- **Knuth-Liang Algorithm**: For hyphenation patterns
- **Node.js Test Runner**: For testing infrastructure

## 📞 Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/rajans-codes/cmu-syllable-counter).

---

**Built with ❤️ for accurate syllable counting and word analysis**