@oloko64/metaphone-ptbr-node

A modernized, TypeScript-first implementation of the Metaphone algorithm specifically tailored for Brazilian Portuguese.

This project is a modern fork of the original bipbop/metaphone-ptbr, which has been unmaintained for several years. This version is designed to work seamlessly with modern Node.js versions, provides full TypeScript support, and is optimized for performance.

Why this version?

• Modern Node.js Support: Compatible with Node.js 18+ and ESM.
• TypeScript Native: Built with TypeScript for excellent IDE support and type safety.
• Improved Performance: Optimized character processing and normalization.
• Maintained: Actively updated to ensure compatibility with modern environments.

Installation

npm install @oloko64/metaphone-ptbr-node

Or using yarn:

yarn add @oloko64/metaphone-ptbr-node

Usage

Basic Usage (ESM)

import { metaphone } from '@oloko64/metaphone-ptbr-node';

console.log(metaphone('Caminhão')); // Output: KM3
console.log(metaphone('Ação'));     // Output: AK
console.log(metaphone('Filho'));    // Output: F1

With Custom Rules

You can provide additional replacement rules (phases) as a second argument:

import { metaphone } from '@oloko64/metaphone-ptbr-node';

const customRules = [
  [/UNIDADE/g, 'UN'],
  [/DEPARTAMENTO/g, 'DEP']
];

console.log(metaphone('UNIDADE DEPARTAMENTO', customRules));

API

metaphone(text: string, additionalPhases?: [RegExp | string, string][], limit?: number): string | null

• text: The input string to be processed.
• additionalPhases: (Optional) An array of tuple rules to apply before the metaphone calculation.
• limit: (Optional) Maximum string length for processing (default: 255).
• Returns: A phonetic string representation or null if the input is invalid or too long.

Development

1. Install dependencies:

   npm install

2. Run tests:

   npm test

3. Build the project:

   npm run build

License

This project is licensed under the MIT License.

Credits

Based on the original implementation by BipBop.