ID@agntn/compressionsv0.0.0
Unpack it. Don't guess it.
A blob starts with 1f 8b and somebody asks what's inside. This opens it. gzip, zlib, raw deflate, bzip2, xz and .lzma, zstd, brotli, lz4 and Unix compress, every checksum checked on the way out. Written from the RFCs and the format specs, no zlib binding underneath. One call in TypeScript, the terminal and your agent. Nothing leaves the machine.
- Formats
- 7
- in 11 containers
- Written too
- 5
- 6 with a checksum, 4 agent tools
- Network calls
- 0
- every value computed in place
$ pnpm add @agntn/compressionsgzip
LZ77 and Huffman, raw or wrapped in zlib or gzip. Still everywhere.
Stream
- Size
- 51 → 35 bytes
- Ratio
- 69% · reads back
- Checksum
- CRC-32
- Written by
- this page
- Files
- .gz .tgz
Same call, every format
Pick a format, hand it bytes, get bytes back. Then do it backwards. This file walks through 11 containers and none of it is a recording. Your browser runs every line with the same TypeScript the package ships. zstd and brotli come from their own CLIs, since this package reads them and doesn't write them. The rest it writes right here.
- compress(name, input) and decompress(name, bytes). That's the API on day one
- gzip and zlib are deflate with a container. xz is lzma with one. One family, one option
- Every checksum gets checked on the way out, and a wrong one is an error, not a shrug
Round trip
import { compress, decompress, identify } from "@agntn/compressions";// gzip, RFC 1952const bytes = compress("deflate", "hello world! hello world! hello world! hello world!", { container: "gzip" });// 35 bytes: 1f8b080000000000 ...const { bytes: out, details } = decompress("deflate", bytes, { container: "gzip" });// details { os: 255, members: 1 }new TextDecoder().decode(out); // "hello world! hello world! hello world! hello world!"identify(bytes)[0];// "deflate", container "gzip"A guess that shows its work
Somebody hands you a blob that starts with 28 b5 2f fd and asks what it is. A model squints and says gzip, probably. identify actually tries every container whose start fits, decompresses it for real and ranks what worked. Each score comes with its reasons, so you can disagree with it. And when nothing fits? It says so, and tells you when the bytes look like a ZIP it doesn't open.
- A magic number with a matching checksum beats everything
- Raw deflate and brotli have no magic. They count only when they eat every byte
- peel takes the layers off one by one, gzip inside xz inside zstd
deflate · gzip, it is
Starts with its magic number, checksum matches, decodes to the last byte, decompresses to readable text, comes out longer than it went in.
- deflate · gzip"hello world! hello world! hello world!…100
- no other reading
- no other reading
Seven formats, eleven containers
Prefix codes after LZ77, where deflate, zstd and brotli live. A range coder that learns every bit, which is LZMA. Block sorting, which is bzip2 being bzip2. LZ4, which codes nothing at all and wins on speed. And the dictionary of Unix compress, older than most of the internet. Six containers check themselves on the way out. Every one written from its RFC or spec, with no zlib, no liblzma and no WASM underneath, grouped five ways below.
Importimport { formats, create } from "@agntn/compressions"
Prefix codes
Range coding
Block sorting
Byte aligned
Dictionary codes
Four tools, one executor
Ask a model to gunzip something and it describes gzip to you. Give it compressions_decompress and it opens the thing. compressions mcp, the Pi and OMP extensions and @agntn/compressions/ai all call the same executors. This page runs them too, so the dialog shows exactly what a model reads for "hello world!…".
- compressions_compress, compressions_decompress, compressions_identify, compressions_info
- A misspelled argument is an error. An option of another format is named, not swallowed
- Long output comes in windows, and a bomb stops at 64 MiB
gzip
The bytes come out of the executor, not out of the model's imagination. Readable text comes back as text, anything else as hex.
- bytes
- 51 as utf8
- value
- hello world! hello world! hello world! hello world!
- carried
- os 255, members 1
Your own format is one call
Need run-length coding because some puzzle printed counts and bytes? Write the two functions, register the result, and the registry treats it like a built-in. Options get checked, the output limit holds, and partial works on your format the same way it works on gzip. No plugin manifest, no base class to fight.
- defineCompression takes the metadata and two functions. The checks come free
- register(format) and compress, decompress and the tools see it
- out.fail() gives a broken stream the same error, partial reads included
import { compress, decompress, defineCompression, register } from "@agntn/compressions";const rle = defineCompression({ info: { name: "rle", label, description, containers, compress: true, options: [] }, compress(bytes) { /* a length and a byte per run */ }, decompress(data, out) { /* out.copyByte(byte, length) per pair */ },});register(rle);compress("rle", "aaaabbb"); // Uint8Array [4, 97, 3, 98]decompress("rle", compress("rle", "aaaabbb")).bytes; // the bytes of "aaaabbb"Start with one command
One install gets you the library, the compressions CLI and the MCP server. Name a format, hand it bytes, done. Got a blob and no idea what made it? That's what identify is for, and peel takes every layer off.
- PinPre-1.0, so pin exact versions.
- Not auditedFine for puzzles, CTFs and tooling. Not for untrusted bytes at scale.
- OfflineNothing to fetch, no native binding, runs in the browser too.
First call
$ pnpm add @agntn/compressionsimport { compress, decompress, identify } from "@agntn/compressions";const gz = compress("deflate", "gm", { container: "gzip", name: "gm.txt" }); // 29 bytes, 1f8b08...decompress("deflate", gz, { container: "gzip" }).details.name; // "gm.txt"identify(compress("lzma", "gm", { container: "xz" }))[0]; // lzma xz, 100