https://github.com/binhtran432k/varbyte-printable
A library for encoding variable-length bytes into a compact, printable, and JSON/JavaScript-safe string format.
https://github.com/binhtran432k/varbyte-printable
binary-to-text bun compression data-serialization encoding oxc typescript
Last synced: 4 months ago
JSON representation
A library for encoding variable-length bytes into a compact, printable, and JSON/JavaScript-safe string format.
- Host: GitHub
- URL: https://github.com/binhtran432k/varbyte-printable
- Owner: binhtran432k
- License: mit
- Created: 2025-01-27T05:34:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-30T06:50:14.000Z (about 1 year ago)
- Last Synced: 2025-10-10T20:16:40.864Z (4 months ago)
- Topics: binary-to-text, bun, compression, data-serialization, encoding, oxc, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/varbyte-printable
- Size: 30.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# varbyte-printable
[](https://www.npmjs.com/package/varbyte-printable)
[](https://www.npmjs.com/package/varbyte-printable)
[](https://github.com/binhtran432k/varbyte-printable/actions/workflows/ci.yml)
[](https://github.com/binhtran432k/varbyte-printable/actions/workflows/cd.yml)
A library for encoding variable-length bytes into a compact, printable, and
JSON/JavaScript-safe string format.
- [About](#about)
- [Features](#features)
- [Installation](#installation)
- [How It Works](#how-it-works)
- [Usage](#usage)
- [Development](#development)
- [References](#references)
## About
`varbyte-printable` is a lightweight library that encodes arrays of bytes into
a **compact, printable** format while ensuring compatibility with **JSON and
JavaScript-safe strings**.
The encoding algorithm is inspired by **Lezer** by [Marijn
Haverbeke](https://github.com/lezer-parser), borrowing key logic to achieve
efficient compression.
This project is built using:
- **Bun** for fast development and bundling.
- **oxc-transform** for isolated TypeScript declaration generation.
## Features
- **Compact Encoding**: Reduces byte array size.
- **Printable Output**: Ensures all characters are JSON-safe.
- **JavaScript-Friendly**: Compatible with JavaScript strings.
## Installation
You can install `varbyte-printable` using:
```sh
bun add varbyte-printable
# or using npm
npm install varbyte-printable
```
## How It Works
The encoding algorithm converts numbers into groups of printable ASCII characters:
- `0xFFFF`, often used as a placeholder, is encoded as `'~'`.
- Characters from `' '` (32) to `'}'` (125), excluding `'"'` (34) and `'\\'`
(92), represent values from **0 to 91**.
- The **first bit** in each encoded character indicates whether it is the final
digit in the number.
- This leaves **46 additional values**, which are significant in the encoding.
- The digits in a number are ordered from **high to low significance**.
## Usage
### Encoding & Decoding Example
```ts
import {
encodeVarbytePrintable,
decodeVarbytePrintable,
} from "varbyte-printable";
const bytes = new Uint16Array([72, 101, 108, 1080, 111]);
const encoded = encodeVarbytePrintable(bytes);
console.log(encoded); // T!j#X#`8f#c
const decoded = decodeVarbytePrintable(Uint16Array, encoded);
console.log(decoded); // Uint16Array(5) [72, 101, 108, 1080, 111]
```
## Development
To build the project locally:
```sh
git clone https://github.com/binhtran432k/varbyte-printable.git
cd varbyte-printable
bun install
bun gen
```
To run test:
```sh
bun test
```
## References
- [Lezer by Marijn Haverbeke](https://github.com/lezer-parser) - Algorithm inspiration.
- [Bun](https://bun.sh/) - Build and runtime support.
- [oxc-transform](https://github.com/oxc-project/oxc) - TypeScript
transformation tool.