{"id":12281,"library":"unicode-confusables","title":"Unicode Confusables Utility","description":"The `unicode-confusables` utility provides functions to detect and resolve visually confusing Unicode characters in strings, adhering to the security guidelines outlined in Unicode Technical Standard #39 (UTS39). It leverages the `confusables.txt` data file to identify characters that can be easily mistaken for others, including homoglyphs and zero-width characters. Currently at version 0.1.1, the library's release cadence is tied to updates in the UTS39 standard and `confusables.txt` data. Its primary differentiators include direct adherence to the official Unicode standard, the ability to not only detect but also rectify confused characters, and support for a wide range of scripts, including non-Latin languages. It also provides a mechanism to update its underlying data set, making it crucial for applications requiring robust input validation and security against 'homograph attacks' or similar visual spoofing.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install unicode-confusables","lang":"bash","label":"npm"},{"cmd":"yarn add unicode-confusables","lang":"bash","label":"yarn"},{"cmd":"pnpm add unicode-confusables","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is supported, ESM `import` is preferred for modern applications. For CJS, use object destructuring as shown in `wrong` example.","wrong":"const isConfusing = require('unicode-confusables').isConfusing;","symbol":"isConfusing","correct":"import { isConfusing } from 'unicode-confusables';"},{"note":"This is a named export, not a default export. Incorrectly importing it as a default will result in a TypeError.","wrong":"import confusables from 'unicode-confusables';","symbol":"confusables","correct":"import { confusables } from 'unicode-confusables';"},{"note":"The README shows CommonJS `require` usage. For modern TypeScript/ESM projects, the `import` syntax is standard. The library ships with TypeScript types.","wrong":"const { rectifyConfusion } = require('unicode-confusables');","symbol":"rectifyConfusion","correct":"import { rectifyConfusion } from 'unicode-confusables';"}],"quickstart":{"code":"import { isConfusing, confusables, rectifyConfusion } from 'unicode-confusables';\n\nasync function demonstrateConfusables() {\n  const confusingString = 'fоо'; // 'o' here is a Cyrillic 'о' (U+043E)\n  const regularString = 'foo';\n\n  console.log(`Is '${confusingString}' confusing? ${isConfusing(confusingString)}`);\n  console.log(`Is '${regularString}' confusing? ${isConfusing(regularString)}`);\n\n  console.log(`Confusables for '${confusingString}':`, confusables(confusingString));\n  console.log(`Rectified '${confusingString}': '${rectifyConfusion(confusingString)}'`);\n\n  const zeroWidthString = 'vitalik\\u200b'; // vitalik with a zero-width space (U+200B)\n  console.log(`Is '${zeroWidthString}' confusing (with zero-width char)? ${isConfusing(zeroWidthString)}`);\n  console.log(`Confusables for '${zeroWidthString}':`, confusables(zeroWidthString));\n\n  const mixedCaseHomoglyph = 'mI01'; // common homoglyphs for m, I, 0, 1\n  console.log(`Confusables for '${mixedCaseHomoglyph}':`, confusables(mixedCaseHomoglyph));\n}\n\ndemonstrateConfusables();","lang":"typescript","description":"Demonstrates how to check if a string contains confusing Unicode characters, identify the specific confusables, and rectify them. It also shows detection of zero-width characters and homoglyphs."},"warnings":[{"fix":"Pin the exact version in `package.json` (e.g., `\"unicode-confusables\": \"0.1.1\"`) and review updates manually.","message":"As a 0.x.x version, the API is not yet stable and breaking changes may be introduced in minor or patch versions without a major version increment. It is advisable to pin exact versions or frequently review release notes.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Integrate `npm run update` into your CI/CD pipeline or a regular maintenance script to ensure the data is current.","message":"The underlying `confusables.txt` data, sourced from unicode.org, can be updated. If your application relies on the latest data for security, you must periodically run `npm run update` to fetch and parse a fresh copy.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Supplement this library with other security measures appropriate for your application's threat model, and educate users about potential risks beyond UTS39.","message":"This library's definition of 'confusing' is strictly based on Unicode UTS39. It does not cover all possible visual spoofing methods (e.g., domain squatting, visual similarities not listed in UTS39, or culturally specific visual attacks).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"For performance-sensitive applications, consider caching results for common strings or rate-limiting checks. Profile your application to identify bottlenecks.","message":"Processing very long strings or making frequent calls to `confusables` or `isConfusing` in a performance-critical loop can be computationally intensive, as it involves character-by-character analysis and lookups.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports: `import { isConfusing } from 'unicode-confusables';`","cause":"This typically occurs when trying to use named exports with a default import syntax in an ESM environment after TypeScript transpilation.","error":"TypeError: (0, unicode_confusables_1.isConfusing) is not a function"},{"fix":"Use object destructuring for CommonJS `require`: `const { isConfusing } = require('unicode-confusables');`","cause":"This happens when attempting to call `isConfusing` on the entire module object, rather than destructuring the named export, particularly in CommonJS.","error":"TypeError: isConfusing is not a function"},{"fix":"Run `npm install unicode-confusables` or `yarn add unicode-confusables` to install the package. Verify the import path is exactly `'unicode-confusables'`.","cause":"The package has not been installed, or there's a typo in the import path.","error":"Module not found: Error: Can't resolve 'unicode-confusables'"}],"ecosystem":"npm"}