0.2.4 • Published 5 months ago
@httpx/compress v0.2.4
@httpx/compress
Simple compression helpers that works on node, browsers, edge and Cloudflare workers.
Install
$ npm install @httpx/compress
$ yarn add @httpx/compress
$ pnpm add @httpx/compress
Features
- 👉 Compress and decompress strings or Uint8Array.
- 🦄 Support base64 encoding for strings (and base64-urlsafe).
- 📐 Lightweight (starts at ~600B)
- 🛡️ Tested on node 18-22, browser, cloudflare workers and runtime/edge.
- 🙏 Works cross-realms (browser, 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! 🦆');
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, {
// Option are optional, use base64 by default.
// Supported values: 'base64', '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 v3.0.9 /home/sebastien/github/httpx/packages/compress
✓ bench/compress-string.bench.ts > Compressor 3243ms
name hz min max mean p75 p99 p995 p999 rme samples
· Compressor('gzip').toEncodedString/base64 (original size: 10 MB) 18.6250 52.1838 56.8048 53.6914 55.7546 56.8048 56.8048 56.8048 ±2.48% 10 slowest
· Compressor('gzip').toEncodedString/base64_urlsafe (original size: 10 MB) 19.2092 51.2096 52.5271 52.0585 52.3733 52.5271 52.5271 52.5271 ±0.55% 10
· Compressor('deflate').toEncodedString/base64 (original size: 10 MB) 20.1292 48.7729 50.6601 49.6790 50.2382 50.6601 50.6601 50.6601 ±0.89% 11
· Compressor('deflate').toEncodedString/base64-url_safe (original size: 10 MB) 20.1714 48.7836 50.4266 49.5751 49.8648 50.4266 50.4266 50.4266 ±0.63% 11 fastest
✓ bench/decompress-string.bench.ts > Decompressor 1845ms
name hz min max mean p75 p99 p995 p999 rme samples
· Decompressor('gzip').fromEncodedString (compressed size: 40.5 kB / total: 10 MB) 13.4591 69.0043 80.8933 74.2992 76.1238 80.8933 80.8933 80.8933 ±4.73% 7
· Decompressor('deflate').fromEncodedString (compressed size: 40.5 kB / total: 10 MB) 13.9292 66.5701 83.4795 71.7914 73.4803 83.4795 83.4795 83.4795 ±7.41% 7 fastest
✓ bench/decompress-uint8array.bench.ts > Decompressor 1402ms
name hz min max mean p75 p99 p995 p999 rme samples
· Decompressor('gzip').fromUint8Array (compressed size: 30.4 kB / total: 10 MB) 30.3619 25.7162 45.3852 32.9360 36.7200 45.3852 45.3852 45.3852 ±9.66% 16
· Decompressor('deflate').fromUint8Array (compressed size: 30.4 kB / total: 10 MB) 36.5280 22.1687 34.0941 27.3763 30.9489 34.0941 34.0941 34.0941 ±6.79% 19 fastest
✓ bench/compress-uint8array.bench.ts > Compressor 1626ms
name hz min max mean p75 p99 p995 p999 rme samples
· Compressor('gzip').toUint8Array (original size: 10 MB) 18.1687 51.2364 64.0366 55.0396 56.1935 64.0366 64.0366 64.0366 ±5.70% 10
· Compressor('deflate').toUint8Array (original size: 10 MB) 19.8917 48.6506 54.0161 50.2723 50.4489 54.0161 54.0161 54.0161 ±2.19% 10 fastest
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.05x faster than Compressor('gzip').toEncodedString/base64_urlsafe (original size: 10 MB)
1.08x faster than Compressor('gzip').toEncodedString/base64 (original size: 10 MB)
Compressor('deflate').toUint8Array (original size: 10 MB) - bench/compress-uint8array.bench.ts > Compressor
1.09x 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.03x 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.20x 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 } | ~ 562B |
import { Decompressor } | ~ 423B |
import { Decompressor, Compressor } | ~ 662B |
For CJS usage (not recommended) track the size on bundlephobia.
Compatibility
Level | CI | Description |
---|---|---|
Node | ✅ | CI for 18.x, 20.x & 22.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 |
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.