unicode-text-obfuscator

A small, zero-dependency Node.js utility that replaces eligible ASCII characters with visually similar Unicode characters.

Use it for Unicode handling tests, demo data, and playful text effects. It is not encryption and must not be used to protect secrets or disguise unsafe content.

Installation

Install it in a project:

npm install unicode-text-obfuscator

Install the command globally:

npm install --global unicode-text-obfuscator

You can also run it without a global installation:

npx unicode-text-obfuscator "Hello world"

JavaScript API

CommonJS

const {
  obfuscate,
  deobfuscate,
  getAvailableProfiles,
} = require('unicode-text-obfuscator');

const transformed = obfuscate('Hello world 123', {
  fraction: 0.6,
  preserveDigits: true,
  profile: 'strict',
});

console.log(transformed);
console.log(deobfuscate(transformed));
console.log(getAvailableProfiles());

ES modules

import packageApi from 'unicode-text-obfuscator';

const { obfuscate, deobfuscate } = packageApi;

console.log(obfuscate('Hello world'));
console.log(deobfuscate('Hеllо wоrld'));

obfuscate(text, options)

obfuscate('Hello world', {
  fraction: 0.5,
  preserveDigits: false,
  profile: 'loose',
});

Options:

| Option | Type | Default | Description | | --- | --- | --- | --- | | fraction | number | 1 | Replacement probability from 0 to 1 | | preserveDigits | boolean | false | Keep ASCII digits unchanged | | profile | string | loose | Use strict, loose, or fullwidth | | random | () => number | Math.random | Injectable random source for tests or deterministic behavior |

Invalid fractions and profile names throw an error instead of being silently corrected.

Mapping profiles

• strict: a smaller set of strong visual matches
• loose: the broader mapping used by the original package
• fullwidth: converts non-space printable ASCII characters to fullwidth forms

obfuscate('Hello 123!', { profile: 'fullwidth' });
// Ｈｅｌｌｏ １２３！

Deterministic output

Provide a random function when you need repeatable output:

const alwaysFirst = () => 0;

console.log(obfuscate('Hello', {
  random: alwaysFirst,
}));

For production-quality seeded randomness, pass a seeded PRNG function from your own application.

deobfuscate(text)

deobfuscate converts characters generated by this package back to ASCII when their mapping is unambiguous.

deobfuscate('Hеllо');
// Hello

Unknown Unicode characters are preserved. This function is not a general-purpose implementation of the Unicode confusables algorithm.

Command-line usage

text-obfuscator [options] [text]

Examples:

text-obfuscator "Hello world"
text-obfuscator --fraction 0.5 "Hello world"
text-obfuscator --profile strict "Hello world"
text-obfuscator "User 123" --preserve-digits
text-obfuscator --deobfuscate "Hеllо"
echo "Hello world" | text-obfuscator --profile fullwidth

Options:

-d, --deobfuscate       Convert known generated lookalikes back to ASCII
-f, --fraction <number> Replacement probability from 0 to 1
-p, --profile <name>    strict, loose, or fullwidth
    --preserve-digits   Keep ASCII digits unchanged
-h, --help              Show help
-v, --version           Show the installed version

Use -- before text that starts with a hyphen:

text-obfuscator -- "--example"

Limitations and safety

• Visual similarity depends on the font and rendering environment.
• The resulting text is different at the Unicode and byte levels.
• Search, validation, moderation, and accessibility systems may treat the transformed text differently.
• This package is not encryption, anonymization, or security software.
• Do not use it to impersonate identifiers, domains, usernames, or trusted content.

Development

Requires Node.js 18.3 or newer.

npm install
npm run check
npm test
npm link
text-obfuscator --help

The test suite uses Node's built-in test runner, so the package remains dependency-free.

See CONTRIBUTING.md for contribution guidelines and SECURITY.md for security reporting.

Releasing

This project follows semantic versioning in major.minor.patch order. The files in this release already use version 1.1.0.

npm run check
npm test
npm publish --dry-run

git add .
git commit -m "release: v1.1.0"
git tag v1.1.0
git push origin main --follow-tags

npm publish

The prepublishOnly script checks syntax and runs the complete test suite before npm publishing.

License

MIT