Unicode Confusables Utility

Common errors

• TypeError: (0, unicode_confusables_1.isConfusing) is not a function

  cause This typically occurs when trying to use named exports with a default import syntax in an ESM environment after TypeScript transpilation.
  fix Ensure you are using named imports: `import { isConfusing } from 'unicode-confusables';`

• TypeError: isConfusing is not a function

  cause This happens when attempting to call `isConfusing` on the entire module object, rather than destructuring the named export, particularly in CommonJS.
  fix Use object destructuring for CommonJS `require`: `const { isConfusing } = require('unicode-confusables');`

• Module not found: Error: Can't resolve 'unicode-confusables'

  cause The package has not been installed, or there's a typo in the import path.
  fix Run `npm install unicode-confusables` or `yarn add unicode-confusables` to install the package. Verify the import path is exactly `'unicode-confusables'`.

Warnings

• breaking 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.
  Fix: Pin the exact version in `package.json` (e.g., `"unicode-confusables": "0.1.1"`) and review updates manually.
• gotcha 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.
  Fix: Integrate `npm run update` into your CI/CD pipeline or a regular maintenance script to ensure the data is current.
• gotcha 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).
  Fix: Supplement this library with other security measures appropriate for your application's threat model, and educate users about potential risks beyond UTS39.
• gotcha 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.
  Fix: For performance-sensitive applications, consider caching results for common strings or rate-limiting checks. Profile your application to identify bottlenecks.

Install

• npm install unicode-confusables npm
• yarn add unicode-confusables yarn
• pnpm add unicode-confusables pnpm

Imports

• isConfusing
  wrong:

  const isConfusing = require('unicode-confusables').isConfusing;

  correct:

  import { isConfusing } from 'unicode-confusables';

  While CommonJS `require` is supported, ESM `import` is preferred for modern applications. For CJS, use object destructuring as shown in `wrong` example.
• confusables
  wrong:

  import confusables from 'unicode-confusables';

  correct:

  import { confusables } from 'unicode-confusables';

  This is a named export, not a default export. Incorrectly importing it as a default will result in a TypeError.
• rectifyConfusion
  wrong:

  const { rectifyConfusion } = require('unicode-confusables');

  correct:

  import { rectifyConfusion } from 'unicode-confusables';

  The README shows CommonJS `require` usage. For modern TypeScript/ESM projects, the `import` syntax is standard. The library ships with TypeScript types.

Quickstart

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.

import { isConfusing, confusables, rectifyConfusion } from 'unicode-confusables';

async function demonstrateConfusables() {
  const confusingString = 'fоо'; // 'o' here is a Cyrillic 'о' (U+043E)
  const regularString = 'foo';

  console.log(`Is '${confusingString}' confusing? ${isConfusing(confusingString)}`);
  console.log(`Is '${regularString}' confusing? ${isConfusing(regularString)}`);

  console.log(`Confusables for '${confusingString}':`, confusables(confusingString));
  console.log(`Rectified '${confusingString}': '${rectifyConfusion(confusingString)}'`);

  const zeroWidthString = 'vitalik\u200b'; // vitalik with a zero-width space (U+200B)
  console.log(`Is '${zeroWidthString}' confusing (with zero-width char)? ${isConfusing(zeroWidthString)}`);
  console.log(`Confusables for '${zeroWidthString}':`, confusables(zeroWidthString));

  const mixedCaseHomoglyph = 'mI01'; // common homoglyphs for m, I, 0, 1
  console.log(`Confusables for '${mixedCaseHomoglyph}':`, confusables(mixedCaseHomoglyph));
}

demonstrateConfusables();