typo-tolerance-synonyms/README.md

This package provides an advanced multilingual search engine with phonetic matching and extensive language support, designed to filter input for typographical errors and return refined search results.

# typo-tolerance-synonyms

An advanced search package that provides typo tolerance, automatic synonym detection, phonetic matching, and multi-language support. Perfect for e-commerce sites, content management systems, and search applications.

[![npm version](https://img.shields.io/npm/v/typo-tolerance-synonyms.svg)](https://www.npmjs.com/package/typo-tolerance-synonyms)
[![License](https://img.shields.io/npm/l/typo-tolerance-synonyms.svg)](https://github.com/yourusername/typo-tolerance-synonyms/blob/master/LICENSE)

## Features

- 🔍 Advanced typo tolerance using Levenshtein distance
- 🎯 Automatic synonym detection
- 🔊 Phonetic matching support
- 🌍 Multi-language support
- ⚡ High-performance caching
- 📝 Customizable scoring system
- 🎮 Perfect for e-commerce and product search

## Installation

```bash
npm install typo-tolerance-synonyms
```

## Basic Usage

```javascript
const { TypoTolerantSearch } = require('typo-tolerance-synonyms');

async function searchExample() {
    const search = new TypoTolerantSearch({
        typoTolerance: 2,
        usePhonetic: true,
        languages: ['eng', 'afr'] // English and Afrikaans support
    });

    const results = await search.search('gaming mouse', products);
    console.log(results);
}
```

## Gaming Accessories Example (English & Afrikaans)

```javascript
const { TypoTolerantSearch } = require('typo-tolerance-synonyms');

async function gamingSearchExample() {
    // Initialize the search engine
    const search = new TypoTolerantSearch({
        typoTolerance: 2,
        usePhonetic: true,
        languages: ['eng', 'afr']
    });

    // Sample gaming accessories database
    const products = [
        // English entries
        'Gaming Mouse RGB Wireless',
        'Professional Gaming Keyboard',
        'Gaming Headset with Microphone',
        'RGB Mousepad XL Size',
        'Controller for PC Games',
        // Afrikaans entries
        'Speletjie Muis Draadloos',  // Gaming Mouse Wireless
        'Professionele Sleutelbord',  // Professional Keyboard
        'Kopfoon met Mikrofoon',      // Headphone with Microphone
        'Muismat Groot Grootte',      // Mousepad Large Size
        'Beheerder vir Rekenaarspeletjies' // Controller for Computer Games
    ];

    // Example 1: Search with typo (English)
    const typoSearch = await search.search('gaming mose wireless', products);
    console.log('Typo Search Results:');
    console.log(typoSearch);
    // Output will include:
    // - Gaming Mouse RGB Wireless
    // - Speletjie Muis Draadloos
    // (with relevance scores)

    // Example 2: Search in Afrikaans with typo
    const afrikaansSearch = await search.search('spelietje muiz', products, {
        language: 'afr'
    });
    console.log('Afrikaans Search Results:');
    console.log(afrikaansSearch);
    // Output will include:
    // - Speletjie Muis Draadloos
    // - Gaming Mouse RGB Wireless
    // (with relevance scores)

    // Example 3: Phonetic search
    const phoneticSearch = await search.search('geiming hedset', products);
    console.log('Phonetic Search Results:');
    console.log(phoneticSearch);
    // Will match both English and Afrikaans headset entries
}

gamingSearchExample();
```

## Advanced Configuration

```javascript
const search = new TypoTolerantSearch({
    // Basic settings
    typoTolerance: 2,              // Maximum number of character differences allowed
    caseSensitive: false,          // Case sensitivity
    usePhonetic: true,             // Enable phonetic matching
    
    // Language settings
    languages: ['eng', 'afr'],     // Supported languages
    
    // Scoring weights
    weights: {
        exact: 1.0,                // Exact match weight
        synonym: 0.9,              // Synonym match weight
        phonetic: 0.8,             // Phonetic match weight
        typo: 0.7                  // Typo tolerance weight
    }
});
```

## API Reference

### Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| typoTolerance | number | 2 | Maximum allowed character differences |
| caseSensitive | boolean | false | Enable case-sensitive search |
| usePhonetic | boolean | true | Enable phonetic matching |
| languages | string[] | ['eng'] | Supported languages |
| weights | object | {...} | Scoring weights configuration |

### Methods

#### search(searchText, targetArray[, options])

Performs a search with typo tolerance and synonym support.

```javascript
const results = await search.search('gaming headfones', products, {
    language: 'eng',
    threshold: 0.3
});
```

Parameters:
- `searchText`: String to search for
- `targetArray`: Array of strings to search in
- `options`: Optional configuration object
  - `language`: Force specific language processing
  - `threshold`: Minimum score threshold (0-1)

Returns: Array of matches with scores:
```javascript
[
    {
        text: "Gaming Headset with Microphone",
        score: 0.95,
        language: "eng",
        matches: 2
    },
    // ...more results
]
```

#### getPhoneticCodes(word)

Get phonetic codes for a word using multiple algorithms.

```javascript
const codes = search.getPhoneticCodes('gaming');
// Returns: { metaphone: 'GMNG', doubleMetaphone: ['KMNK', 'KMNK'], soundex: 'G552' }
```

## Language Support

Currently supported languages:
- English (eng)
- Afrikaans (afr)

Each language includes:
- Language-specific synonym detection
- Stopword filtering
- Diacritic handling
- Custom text normalization

## Performance Tips

1. **Caching**: The package automatically caches synonym and phonetic results
2. **Batch Processing**: Process multiple searches in parallel using Promise.all
3. **Language Detection**: Specify language when known for better performance

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE for details

## Support

- Documentation: [Full Documentation](https://github.com/yourusername/typo-tolerance-synonyms/wiki)
- Issues: [GitHub Issues](https://github.com/yourusername/typo-tolerance-synonyms/issues)
- Email: your.email@example.com

## Changelog

### Version 1.0.0
- Initial release with typo tolerance and multi-language support
- English and Afrikaans language support
- Phonetic matching implementation
- Automatic synonym detection