@httpx/compress
v0.3.10
Published
Compression utilities
Readme
@httpx/compress
Lightweight compression helpers based on widely available Compression Streams API. Works in node, bun, edge, cloudflare and browsers. Provides support for string encoding (base64 and base64-urlsafe).
Install
$ npm install @httpx/compress
$ yarn add @httpx/compress
$ pnpm add @httpx/compressFeatures
- 👉 Compress and decompress strings or Uint8Array.
- 🦄 Support base64 encoding for strings (and base64-urlsafe).
- 📐 Lightweight (starts at ~570B)
- 🛡️ Tested on node 20-25, browser, bun, cloudflare workers and runtime/edge.
- 🙏 Works cross-realms (workers, browser, bun, edge, node, cloudflare...)
- 🗝️ Available in ESM and CJS formats.
Documentation
👉 Official website or GitHub Readme
Quickstart
import { Compressor, Decompressor } from '@httpx/compress';
const compressor = new Compressor('gzip');
const gzippedStr = await compressor.toEncodedString('Hello, World! 🦆', {
encoding: 'base64', // optional, 'base64' by default
});
const decompressor = new Decompressor('gzip');
const originalStr = await decompressor.fromEncodedString(gzippedStr);Api
Compressor
| Method | Description |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| toUint8Array() | Compress a string or a Uint8Array to a binary Uint8Array. |
| toEncodedString() | Compress a string or a Uint8Array to a encoded string. |
Decompressor
| Method | Description |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| fromUint8Array() | Decompresses a compressed Uint8Array to its original binary form. |
| fromEncodedString() | Compress a string or a Uint8Array to a encoded string. |
Usage
Compressor
toUint8Array
import { Compressor } from '@httpx/compress';
const compressor = new Compressor('gzip'); // or 'deflate'
const longString = 'Hello, World! 🦆'.repeat(500_000);
const compressedUInt8 = await compressor.toUint8Array(longString);toEncodedString
import { Compressor } from '@httpx/compress';
const compressor = new Compressor('gzip'); // or 'deflate'
const longString = 'Hello, World! 🦆'.repeat(500_000);
const compressedString = await compressor.toEncodedString(longString, {
// Optional.
// Supported values: 'base64' (default), 'base64_urlsafe'
encoding: 'base64',
});Decompressor
fromUint8Array
import { Decompressor } from '@httpx/compress';
const decompressor = new Decompressor('gzip'); // or 'deflate'
const decompressedUInt8 = await decompressor.fromUint8Array(compressedUInt8);fromEncodedString
import { Decompressor } from '@httpx/compress';
const decompressor = new Decompressor('gzip'); // or 'deflate'
const decompressedString = await decompressor.fromEncodedString(compressedString);Benchmarks
Performance is continuously monitored thanks to codspeed.io.
RUN v4.0.10 /home/sebastien/github/httpx/packages/compress
✓ bench/compress-string.bench.ts > Compressor 2909ms
name hz min max mean p75 p99 p995 p999 rme samples
· Compressor('gzip').toEncodedString/base64 (original size: 10 MB) 23.7417 36.5044 50.2012 42.1200 45.6970 50.2012 50.2012 50.2012 ±6.49% 13
· Compressor('gzip').toEncodedString/base64_urlsafe (original size: 10 MB) 25.0138 36.3645 48.4145 39.9780 42.7624 48.4145 48.4145 48.4145 ±5.97% 13
· Compressor('deflate').toEncodedString/base64 (original size: 10 MB) 25.7052 32.4704 44.4953 38.9026 41.5483 44.4953 44.4953 44.4953 ±5.58% 13
· Compressor('deflate').toEncodedString/base64-url_safe (original size: 10 MB) 25.7872 36.2869 43.8019 38.7790 39.3598 43.8019 43.8019 43.8019 ±3.70% 13
✓ bench/decompress-string.bench.ts > Decompressor 1770ms
name hz min max mean p75 p99 p995 p999 rme samples
· Decompressor('gzip').fromEncodedString (compressed size: 40.5 kB / total: 10 MB) 13.8849 63.9173 77.2744 72.0209 75.4232 77.2744 77.2744 77.2744 ±5.92% 7
· Decompressor('deflate').fromEncodedString (compressed size: 40.5 kB / total: 10 MB) 15.9822 58.0578 68.1414 62.5697 63.3899 68.1414 68.1414 68.1414 ±4.40% 8
✓ bench/decompress-uint8array.bench.ts > Decompressor 1424ms
name hz min max mean p75 p99 p995 p999 rme samples
· Decompressor('gzip').fromUint8Array (compressed size: 30.4 kB / total: 10 MB) 25.3188 34.7045 44.3954 39.4964 41.7273 44.3954 44.3954 44.3954 ±4.61% 13
· Decompressor('deflate').fromUint8Array (compressed size: 30.4 kB / total: 10 MB) 27.8963 32.0022 40.0406 35.8470 37.3682 40.0406 40.0406 40.0406 ±3.88% 14
✓ bench/compress-uint8array.bench.ts > Compressor 1453ms
name hz min max mean p75 p99 p995 p999 rme samples
· Compressor('gzip').toUint8Array (original size: 10 MB) 25.4082 33.8772 45.0735 39.3574 41.9890 45.0735 45.0735 45.0735 ±5.10% 13
· Compressor('deflate').toUint8Array (original size: 10 MB) 26.7354 33.5035 42.0188 37.4037 40.4936 42.0188 42.0188 42.0188 ±4.43% 14
BENCH Summary
Compressor('deflate').toEncodedString/base64-url_safe (original size: 10 MB) - bench/compress-string.bench.ts > Compressor
1.00x faster than Compressor('deflate').toEncodedString/base64 (original size: 10 MB)
1.03x faster than Compressor('gzip').toEncodedString/base64_urlsafe (original size: 10 MB)
1.09x faster than Compressor('gzip').toEncodedString/base64 (original size: 10 MB)
Compressor('deflate').toUint8Array (original size: 10 MB) - bench/compress-uint8array.bench.ts > Compressor
1.05x faster than Compressor('gzip').toUint8Array (original size: 10 MB)
Decompressor('deflate').fromEncodedString (compressed size: 40.5 kB / total: 10 MB) - bench/decompress-string.bench.ts > Decompressor
1.15x faster than Decompressor('gzip').fromEncodedString (compressed size: 40.5 kB / total: 10 MB)
Decompressor('deflate').fromUint8Array (compressed size: 30.4 kB / total: 10 MB) - bench/decompress-uint8array.bench.ts > Decompressor
1.10x faster than Decompressor('gzip').fromUint8Array (compressed size: 30.4 kB / total: 10 MB)See benchmark file for details.
Bundle size
Bundle size is tracked by a size-limit configuration
| Scenario (esm) | Size (compressed) |
|---------------------------------------|------------------:|
| import { Compressor } | ~ 568B |
| import { Decompressor } | ~ 450B |
| import { Decompressor, Compressor } | ~ 697B |
For CJS usage (not recommended) track the size on bundlephobia.
Compatibility
| Level | CI | Description |
|--------------|-----|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Node | ✅ | CI for 20.x, 22.x, 24.x & 25.x. |
| Browser | ✅ | Tested with latest chrome (vitest/playwright) |
| Browserslist | ✅ | > 95% on 01/2025. defaults, chrome >= 96, firefox >= 105, edge >= 113, safari >= 15, ios >= 15, opera >= 103, not dead |
| Bun | ✅ | Tested with latest (at time of writing >= 1.3.3) |
| Edge | ✅ | Ensured on CI with @vercel/edge-runtime. |
| Cloudflare | ✅ | Ensured with @cloudflare/vitest-pool-workers (see wrangler.toml |
| Typescript | ✅ | TS 5.4 + / are-the-type-wrong checks on CI. |
| ES2022 | ✅ | Dist files checked with es-check |
| Performance | ✅ | Monitored with codspeed.io |
For older browsers: most frontend frameworks can transpile the library (ie: nextjs...)
Contributors
Contributions are welcome. Have a look to the CONTRIBUTING document.
Sponsors
If my OSS work brightens your day, let's take it to new heights together! Sponsor, coffee, or star – any gesture of support fuels my passion to improve. Thanks for being awesome! 🙏❤️
Special thanks to
License
MIT © Sébastien Vanvelthem and contributors.