nysiis/README.md

NYSIIS phonetic encoding algorithm.

## nysiis

The `nysiis` package provides a JavaScript implementation of the [New York State Identification and Intelligence System](https://en.wikipedia.org/wiki/New_York_State_Identification_and_Intelligence_System) (NYSIIS) phonetic encoding algorithm. NYSIIS encodes names based on pronunciation, which is helpful in name-matching and searching applications.

### Install

```sh
npm i nysiis

# or

yarn add nysiis
```

### How to Use

```javascript
import Nysiis from 'nysiis';

// Create an instance with specific language rules
const nysiis = new Nysiis({
  languageRules: ["english", "igbo", "yoruba", "hindi", "urdu"],
  maxLength: 6,
  strict: true,
});

// Function to demonstrate encoding
function demonstrateEncoding(name: string, description: string = "") {
  try {
    const encoded = nysiis.encode(name);
    console.log(
      `${
        description ? `[${description}] ` : ""
      }Original: "${name}" → Encoded: "${encoded}"`
    );
  } catch (err: unknown) {
    if (err instanceof Error) {
      console.error(`Error encoding "${name}":`, err.message);
    } else {
      console.error(`Error encoding "${name}":`, String(err));
    }
  }
}

// English names
console.log("\n=== English Names ===");
demonstrateEncoding("Watkins", "English");
demonstrateEncoding("Robert Johnson", "English");
demonstrateEncoding("Samantha Williams", "English");

// Yoruba names
console.log("\n=== Yoruba Names ===");
demonstrateEncoding("Olanrewaju", "Yoruba");
demonstrateEncoding("Adebayo", "Yoruba");
demonstrateEncoding("Oluwaseun", "Yoruba");

// Igbo names
console.log("\n=== Igbo Names ===");
demonstrateEncoding("Obinwanne", "Igbo");
demonstrateEncoding("Kpakpando", "Igbo");
demonstrateEncoding("Nwachukwu", "Igbo");

// Hindi names
console.log("\n=== Hindi Names ===");
demonstrateEncoding("Bharat", "Hindi");
demonstrateEncoding("Dhawan", "Hindi");
demonstrateEncoding("Thakur", "Hindi");

// Urdu names
console.log("\n=== Urdu Names ===");
demonstrateEncoding("Sheikh", "Urdu");
demonstrateEncoding("Khan", "Urdu");
demonstrateEncoding("Chaudhry", "Urdu");

// Available languages
console.log("\n=== Available Languages ===");
console.log("Supported languages:", nysiis.getAvailableLanguages());
```

### Reference

```tex
@inproceedings{Rajkovic2007,
  author    = {Petar Rajkovic and Dragan Jankovic},
  title     = {Adaptation and Application of Daitch-Mokotoff Soundex Algorithm on Serbian Names},
  booktitle = {XVII Conference on Applied Mathematics},
  editors   = {D. Herceg and H. Zarin},
  pages     = {193--204},
  year      = {2007},
  publisher = {Department of Mathematics and Informatics, Novi Sad},
  url       = {https://jmp.sh/hukNujCG}
}
```

### Additional References

+ [Commission Implementing Regulation (EU) 2016/480](https://www.legislation.gov.uk/eur/2016/480/contents)
+ [Commission Implementing Regulation (EU) 2023/2381](https://eur-lex.europa.eu/eli/reg_impl/2023/2381/oj)

### License

This project is licensed under the [MIT License](./LICENSE).

### Copyright

(c) 2024 - 2025 [Finbarrs Oketunji](https://finbarrs.eu).