A compact, URL-safe, Base64-like encoding for arbitrary-length bit sequences. Weird64 adds sentinel bits before grouping data into six-bit characters, so it can recover the exact number of input bits, including trailing zeroes.
Important
Weird64 is not RFC 4648 Base64 and is not a cryptographic primitive. Do not use it for encryption, authentication, hashing, or security-sensitive obfuscation.
Conventional Base64 encodes bytes. Weird64 is intended for data that is naturally expressed as a sequence of bits and might not end on an eight-bit boundary.
- Exact round trips for arbitrary-length bit arrays
- URL-safe default alphabet with no
=padding - Boolean-array, binary-string, and
BlobAPIs - Custom alphabets with strict validation
- ESM, CommonJS, and TypeScript declarations
- No silent recovery from malformed input
If your data already consists of bytes, standard Base64 or base64url is usually the interoperable choice.
pnpm add weird64npm install weird64yarn add weird64Named exports are recommended:
import {
decodeBinaryString,
decodeBooleans,
encodeBinaryString,
encodeBooleans,
} from 'weird64';
const encodedBits = encodeBooleans([true, false, true]);
console.log(encodedBits); // "s"
console.log(decodeBooleans(encodedBits)); // [true, false, true]
const encodedBinary = encodeBinaryString('101010');
console.log(encodedBinary); // "rG"
console.log(decodeBinaryString(encodedBinary)); // "101010"A default namespace-style export is also available:
import weird64 from 'weird64';
const encoded = weird64.encodeBinaryString('00101001010');
console.log(encoded); // "bAW"encodeBlob uses the standard Blob.arrayBuffer() API. No FileReader
argument is required.
import { decodeBlob, encodeBlob } from 'weird64';
const input = new Blob(['Hello, Weird64!'], { type: 'text/plain' });
const encoded = await encodeBlob(input);
const output = await decodeBlob(encoded, input.type);
console.log(await output.text()); // "Hello, Weird64!"A custom alphabet must contain exactly 64 unique Unicode characters. Use the same alphabet for encoding and decoding.
import { decodeBooleans, encodeBooleans } from 'weird64';
const alphabet =
'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ+/';
const encoded = encodeBooleans([true, false, true], alphabet);
const decoded = decodeBooleans(encoded, alphabet);The encoder:
- Adds a
1sentinel before and after the payload. - Adds between zero and five trailing
0bits to reach a six-bit boundary. - Maps each six-bit group to one character in the selected alphabet.
For [1, 0, 1], the framed bits are 1 101 1, padded to 110110, and mapped
to s in the default alphabet.
The sentinels preserve the length of one encoded value. They do not make a concatenation of multiple Weird64 values self-delimiting; use an external container or delimiter for records.
The format is currently pre-1.0. Compatibility vectors are tested, and any intentional format change will be documented in the changelog.
The API reference is generated by TypeDoc directly from the TypeScript source.
- Node.js 18.18 or newer
- Modern browsers with
Blob.arrayBuffer() - ESM and CommonJS consumers
Blob encoding currently creates an in-memory bit string. For large binary payloads, prefer a byte-oriented standard encoding or process independently framed chunks in your application.
pnpm install
pnpm verifypnpm verify runs formatting and lint checks, TypeScript 6 type checking,
tests with coverage thresholds, package export validation, and both VitePress
and TypeDoc documentation builds.
See CONTRIBUTING.md before opening a pull request. By participating, you agree to follow the Code of Conduct. Please report vulnerabilities through the process in SECURITY.md.
Weird64 follows Semantic Versioning. While the project is below 1.0, minor releases may contain breaking API or format changes; these will be called out in CHANGELOG.md.
MIT © ZIIO AI