invisible-strings

Invisible Strings

Convert regular text into invisible, zero-width Unicode characters and back again.

What is this?

Invisible Strings is a lightweight TypeScript library that allows you to convert normal text into strings composed of invisible Unicode characters. These "invisible strings" can be embedded in other text without being visible to readers, but they can be programmatically decoded back to the original text.

Installation

# Using npm
npm install invisible-strings

# Using yarn
yarn add invisible-strings

# Using pnpm
pnpm add invisible-strings

Usage

Basic Usage

import is from 'invisible-strings';

// Create a new instance with a default character mapping
const { toInvisible, fromInvisible } = is();

// Convert a string to invisible characters
const hiddenMessage = toInvisible('Hello World');
console.log('Hidden message:', hiddenMessage); // Outputs invisible characters

// Convert the invisible string back to normal text
const visibleMessage = fromInvisible(hiddenMessage);
console.log('Visible message:', visibleMessage); // Outputs: "Hello World"

Using Tagged Template Literals

The library also provides tagged template literals for more elegant usage:

import is from 'invisible-strings';

const { visible, invisible } = is();

// Convert to invisible using template literal
const hiddenText = invisible`This text will be invisible`;

// Convert back to normal text
const normalText = visible`${hiddenText}`;
console.log(normalText); // Outputs: "This text will be invisible"

Custom Dictionary

You can also provide your own dictionary for more control:

import is, { getDictionary } from 'invisible-strings';

// Get a randomized dictionary
const customDictionary = getDictionary();

// Create a new instance with the custom dictionary
const { toInvisible, fromInvisible } = is(customDictionary);

// Use the same dictionary to encode and decode
const hiddenMessage = toInvisible('Secret message');
const visibleMessage = fromInvisible(hiddenMessage);

Alternatively, you can use the helpers directly from the main export:

import is from 'invisible-strings';

// Access helper functions
const customDictionary = is.helpers.getDictionary();
const reverseDictionary = is.helpers.getReverseDictionary(customDictionary);

// Create a new instance with the custom dictionary
const { toInvisible, fromInvisible } = is(customDictionary);

API Reference

Main Export

The default export is a function that returns an object with the following methods:

is(initialDictionary?: Dictionary) => {
  dictionary: Dictionary;
  toInvisible: (input: string) => string;
  fromInvisible: (input: string) => string;
  invisible: (strings: TemplateStringsArray, ...values: string[]) => string;
  visible: (strings: TemplateStringsArray, ...values: string[]) => string;
}

Helper Functions

The library provides several helper functions that can be accessed through the main export's helpers property:

import is from 'invisible-strings';

// Access helpers
const { getDictionary, getReverseDictionary, toInvisible, fromInvisible, shuffleArray } = is.helpers;

These helper functions include:

• getDictionary() - Creates a new randomized character mapping dictionary
• getReverseDictionary(dictionary) - Reverses a character mapping dictionary
• toInvisible(dictionary, input) - Converts a string to invisible characters using the provided dictionary
• fromInvisible(reverseDictionary, input) - Converts invisible characters back to a normal string
• shuffleArray(array) - Utility function to shuffle an array

For detailed information about these helpers and how they work, please see the CONTRIBUTING.md file.

How It Works

Invisible Strings works by:

• Converting each character in your text to its Unicode character code
• Mapping each digit of the character code to a specific invisible Unicode character
• Joining these invisible characters with an invisible delimiter
• For decoding, the process is reversed

The library uses various zero-width and other invisible Unicode characters to encode your text. These characters include:

• Zero Width Space
• Zero Width Non-Joiner
• Zero Width Joiner
• Various Unicode whitespace and control characters

Use Cases

• Watermarking text content
• Embedding hidden metadata in plain text
• Creating invisible identifiers
• Steganography in text

Browser Compatibility

This library uses standard JavaScript and Unicode characters, making it compatible with all modern browsers.

Contributing

Contributions are welcome! Please see our CONTRIBUTING.md for details on how to contribute, the project structure, and the helper functions implementation details.

License

MIT © Yoann Moinet