{"_id":"@cristiansantana/phonetics","_rev":"2-84f166e26aa847290d7f4bfd1ab16854","name":"@cristiansantana/phonetics","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@cristiansantana/phonetics","version":"1.0.0","keywords":["search","fuzzy","phonetics","soundex","metaphone","phonetic","pronounceable","similarity","text","string","typescript","library","utility"],"author":{"name":"Cristián Santana","email":"hola@cristiansantana.cl"},"license":"ISC","_id":"@cristiansantana/phonetics@1.0.0","maintainers":[{"name":"cristiansantana","email":"hola@cristiansantana.cl"}],"homepage":"https://github.com/cristiansantana/chile-rut#readme","bugs":{"url":"https://github.com/cristiansantana/chile-rut/issues"},"dist":{"shasum":"0d71e0f89f34e018369b662b0fd7da098f7f1611","tarball":"https://registry.npmjs.org/@cristiansantana/phonetics/-/phonetics-1.0.0.tgz","fileCount":22,"integrity":"sha512-K5ZAXYE/KtMMu0mRzqkO56lFdhWk0YfB9hArLfyGiMvluoZRORh02WLUzkfdaoVVMT3Y9ymPLja12Qzz0afP0w==","signatures":[{"sig":"MEUCIBUrQJHJ6LIpKvOgwiMOMKujDq6LPJIJQOb6zI5uSzTeAiEAti+zyeH7RGWux0HMnrzfw5pX9OKWhbfYRfzf01ewVa4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45052},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"06218dfcecdb11e7b75e1247309cb4b3049fbfb4","scripts":{"test":"jest","build":"tsup","format-check":"prettier \"**/*.{js,ts,json}\" --check --config .prettierrc.json","format-write":"prettier \"**/*.{js,ts,json}\" --write --config .prettierrc.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"cristiansantana","email":"hola@cristiansantana.cl"},"repository":{"url":"git+https://github.com/cristiansantana/chile-rut.git","type":"git"},"_npmVersion":"11.2.0","description":"TypeScript library for generating phonetic keys from text strings to improve sound-based fuzzy search","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","tsup":"^8.5.0","ts-jest":"^29.4.1","ts-node":"^10.9.2","prettier":"^3.6.2","typescript":"^5.9.2","@types/jest":"^30.0.0"},"_npmOperationalInternal":{"tmp":"tmp/phonetics_1.0.0_1754915240866_0.08232234537456273","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cristiansantana/phonetics","version":"1.0.1","type":"module","description":"TypeScript library for generating phonetic keys from text strings to improve sound-based fuzzy search","main":"dist/index.js","types":"dist/index.d.ts","author":{"name":"Cristián Santana","email":"hola@cristiansantana.cl"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/cristiansantana/phonetics.git"},"publishConfig":{"access":"public"},"keywords":["search","fuzzy","phonetics","soundex","metaphone","phonetic","pronounceable","similarity","text","string","typescript","library","utility"],"scripts":{"build":"tsup","format-check":"prettier \"**/*.{js,ts,json}\" --check --config .prettierrc.json","format-write":"prettier \"**/*.{js,ts,json}\" --write --config .prettierrc.json","prepublishOnly":"npm run build","test":"jest"},"devDependencies":{"@types/jest":"^30.0.0","jest":"^30.0.5","prettier":"^3.6.2","ts-jest":"^29.4.1","ts-node":"^10.9.2","tsup":"^8.5.0","typescript":"^5.9.2"},"_id":"@cristiansantana/phonetics@1.0.1","gitHead":"87fd2c953fb093dcacd97e554d7ca4bf5fa5576d","bugs":{"url":"https://github.com/cristiansantana/phonetics/issues"},"homepage":"https://github.com/cristiansantana/phonetics#readme","_nodeVersion":"22.14.0","_npmVersion":"11.2.0","dist":{"integrity":"sha512-LhXZKKNJVOrjThtR4Rhg4nRfMkiFk6oa7mwDQOWx4xuyPhVEq7fL5ZtuZWWr/PeHoMee2EFLydo6ZJZ+TekjpQ==","shasum":"24a2c97f8dcdd2dd2f0dfaeee18b8fb10062730d","tarball":"https://registry.npmjs.org/@cristiansantana/phonetics/-/phonetics-1.0.1.tgz","fileCount":22,"unpackedSize":45052,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFfjncWboGEuabvRRR7f6Nj9//7rZQKB/7BQGw5Ln30KAiEAmQeqEy/bo+2ZIOD4ZcDmjm2UZpGARhIqdpjN8q5dNUc="}]},"_npmUser":{"name":"cristiansantana","email":"hola@cristiansantana.cl"},"directories":{},"maintainers":[{"name":"cristiansantana","email":"hola@cristiansantana.cl"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/phonetics_1.0.1_1754915480412_0.6170289331382797"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-11T12:27:20.789Z","modified":"2025-08-11T12:31:20.741Z","1.0.0":"2025-08-11T12:27:21.035Z","1.0.1":"2025-08-11T12:31:20.586Z"},"bugs":{"url":"https://github.com/cristiansantana/phonetics/issues"},"author":{"name":"Cristián Santana","email":"hola@cristiansantana.cl"},"license":"ISC","homepage":"https://github.com/cristiansantana/phonetics#readme","keywords":["search","fuzzy","phonetics","soundex","metaphone","phonetic","pronounceable","similarity","text","string","typescript","library","utility"],"repository":{"type":"git","url":"git+https://github.com/cristiansantana/phonetics.git"},"description":"TypeScript library for generating phonetic keys from text strings to improve sound-based fuzzy search","maintainers":[{"name":"cristiansantana","email":"hola@cristiansantana.cl"}],"readme":"# Phonetics\n\n![Build status](https://github.com/cristiansantana/phonetics/actions/workflows/build.yml/badge.svg)\n\nTypeScript library for generating **phonetic keys from text strings** to improve **sound-based fuzzy matching/searching**.  \nIncludes utilities to compare phrases word-by-word using phonetic similarity.\n\n- Supported languages: **Spanish (`es`)**, **English (`en`)**, **French (`fr`)**, **Italian (`it`)**.\n- Designed for **typo-tolerant search** based on how words sound.\n\n## Installation\n\n```bash\n# with npm\nnpm install @cristiansantana/phonetics\n\n# with pnpm\npnpm add @cristiansantana/phonetics\n\n# with yarn\nyarn add @cristiansantana/phonetics\n```\n\n## Requirements\n\n- Node.js 18+ (20+ recommended)\n- TypeScript 5+ (if using TS)\n\n## Importing\n\nESM (recommended):\n\n```ts\nimport { phoneticKey, comparePhonetic } from \"@cristiansantana/phonetics\";\n```\n\nCommonJS:\n\n```js\nconst { phoneticKey, comparePhonetic } = require(\"@cristiansantana/phonetics\");\n```\n\n## Quick usage\n\n```ts\nimport { phoneticKey, comparePhonetic } from \"@cristiansantana/phonetics\";\n\n// Generate a phonetic key for a word\nconst k1 = phoneticKey(\"nueva\", \"es\"); // will match 'nueba'\nconst k2 = phoneticKey(\"phone\", \"en\"); // will match 'fone'\n\n// Compare full sentences (total mode, bag-of-words)\nconst s1 = comparePhonetic(\n  \"Nueva cerveza helada\",\n  \"Nueba servesa elada\",\n  \"es\",\n  \"total\"\n);\n// s1 -> 100.00\n\n// Containment: Is A contained in B?\nconst s2 = comparePhonetic(\n  \"cerveza helada\",\n  \"nueva cerveza helada artesanal\",\n  \"es\",\n  \"a-in-b\"\n);\n// s2 -> 100.00\n\n// Respecting word order\nconst s3 = comparePhonetic(\n  \"rojo verde azul\",\n  \"verde rojo azul\",\n  \"es\",\n  \"total\",\n  true\n);\n// s3 < 100.00 (penalizes different order)\n```\n\n## API\n\n### `phoneticKey(text: string, lang: ISO639_1): string`\n\nGenerates a **normalized phonetic key** for `text`, useful for indexing and comparing by sound.\n\n- `text`: word or text (internally tokenized but returns a normalized string).\n- `lang`: ISO 639-1 language code: `'es' | 'en' | 'fr' | 'it'`.\n- Returns: a string containing the phonetic key.\n\n**Examples**\n\n```ts\nphoneticKey(\"llave\", \"es\") === phoneticKey(\"yave\", \"es\"); // true\nphoneticKey(\"colour\", \"en\") === phoneticKey(\"color\", \"en\"); // true\nphoneticKey(\"beaux\", \"fr\") === phoneticKey(\"beau\", \"fr\"); // true\nphoneticKey(\"acqua\", \"it\") === phoneticKey(\"ackwa\", \"it\"); // true\n```\n\n---\n\n### `comparePhonetic(a: string, b: string, lang: ISO639_1, mode?: CompareMode, orderMatters?: boolean): number`\n\nCompares two strings **per word** using phonetic keys.  \nReturns a **float between 0 and 100** with **two decimal precision**.\n\n#### Parameters\n\n- `a`: First string to compare.\n- `b`: Second string to compare.\n- `lang`: ISO 639-1 language code: `'es' | 'en' | 'fr' | 'it'`.\n- `mode` (optional, default `'total'`):\n  - `'total'`: symmetric Jaccard over multisets `(intersection / union) × 100`\n  - `'a-in-b'`: coverage of A in B `(intersection / |A|) × 100`\n  - `'b-in-a'`: coverage of B in A `(intersection / |B|) × 100`\n- `orderMatters` (optional, default `false`): if `true`, compares words positionally instead of as a bag of words.\n\n#### Returns\n\n`number` — a float in the range **0..100**.\n\n**Examples**\n\n```ts\ncomparePhonetic(\"red green blue\", \"green red blue\", \"es\", \"total\", false);\n// -> 100.00 (same words, order ignored)\n\ncomparePhonetic(\"red green blue\", \"green red blue\", \"es\", \"total\", true);\n// -> less than 100.00 (order matters)\n```\n\n---\n\n## Error handling\n\nIf an unsupported language code is provided, both `phoneticKey` and `comparePhonetic` will throw an error:\n\n```ts\nphoneticKey(\"hola\", \"pt\" as any);\n// Error: Unsupported language: pt\n```\n","readmeFilename":"README.md"}