text-binary-converter

Convert text to binary string and back (UTF-8). Supports full Unicode. Zero dependencies. TypeScript-first.

Features

• Encodes any JavaScript string (ASCII, Cyrillic, CJK, emoji) to binary using UTF-8
• Three output formats: spaced, no-spaces, 8-bit-groups
• Decodes binary back to the original string with full UTF-8 validation
• binaryToText ignores non-binary characters (spaces, pipes, newlines) automatically
• Written in TypeScript — ships with full type declarations
• Zero runtime dependencies — pure UTF-8 implementation, no Buffer, no TextEncoder
• Works in Node.js, Deno, Bun, and modern browsers
• ESM + CommonJS dual build

Install

npm install text-binary-converter
# or
pnpm add text-binary-converter
# or
yarn add text-binary-converter

Usage

import { textToBinary, binaryToText } from 'text-binary-converter'

// Encode
textToBinary('Hi')                    // '01001000 01101001'
textToBinary('Hi', 'no-spaces')       // '0100100001101001'
textToBinary('Hi', '8-bit-groups')    // '01001000|01101001'

// Multi-byte Unicode works too
textToBinary('Привет')                // valid UTF-8 binary
textToBinary('🌍')                    // 4-byte UTF-8 sequence

// Decode
binaryToText('01001000 01101001')     // 'Hi'
binaryToText('0100100001101001')      // 'Hi' — no-spaces format
binaryToText('01001000|01101001')     // 'Hi' — separators are ignored
binaryToText('  01001000 01101001\n') // 'Hi' — whitespace is ignored

// Round-trip
const bin = textToBinary('Hello, World! 🌍')
binaryToText(bin) // 'Hello, World! 🌍'

CommonJS (require) is also supported:

const { textToBinary, binaryToText } = require('text-binary-converter')

const bin = textToBinary('Hello')
console.log(bin)               // '01001000 01100101 01101100 01101100 01101111'
console.log(binaryToText(bin)) // 'Hello'

API

textToBinary(text: string, format?: BinaryFormat): string

Encodes a string to its UTF-8 binary representation.

| Parameter | Type | Default | Description | |---|---|---|---| | text | string | — | Input string (any Unicode is supported) | | format | BinaryFormat | 'spaced' | Output format (see table below) |

BinaryFormat options:

| Value | Example output | Description | |---|---|---| | 'spaced' | '01001000 01101001' | Bytes separated by spaces | | 'no-spaces' | '0100100001101001' | Continuous bit string, no separators | | '8-bit-groups' | '01001000\|01101001' | Bytes separated by \| |

Returns '' for empty or non-string input.

binaryToText(binary: string): string

Decodes a binary string back to text, interpreting bytes as UTF-8.

| Detail | Behaviour | |---|---| | Non-binary chars | All characters except 0 and 1 are stripped before decoding | | Formats accepted | spaced, no-spaces, 8-bit-groups, or any custom separator | | Empty input | Returns '' | | Invalid length | Throws Error if cleaned length is not a multiple of 8 | | No binary digits | Throws Error if no 0/1 characters are found | | Invalid UTF-8 | Throws Error if the byte sequence is not valid UTF-8 |

Error handling

import { binaryToText } from 'text-binary-converter'

try {
  binaryToText('010') // not a multiple of 8
} catch (e) {
  console.error((e as Error).message)
  // 'Binary string length (3) is not a multiple of 8'
}

try {
  binaryToText('   ') // no binary digits
} catch (e) {
  console.error((e as Error).message)
  // 'No valid binary digits found'
}

Use cases

• Education — demonstrate binary representation and UTF-8 encoding
• Debugging — log binary form of strings for low-level analysis
• Visualization — animate or highlight individual bits in UI
• Data encoding — simple text-based binary representation when compactness is not required

Development

git clone https://github.com/maksimgrushevsky/text-binary-converter.git
cd text-binary-converter
npm install

npm run build         # compile to dist/
npm test              # run tests once
npm run test:watch    # run tests in watch mode
npm run typecheck     # TypeScript type-check only

License

MIT