0.2.4 • Published 5 months ago

@httpx/compress v0.2.4

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

@httpx/compress

Simple compression helpers that works on node, browsers, edge and Cloudflare workers. npm changelog codecov bundles node browserslist size downloads license

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

MethodDescription
toUint8Array()Compress a string or a Uint8Array to a binary Uint8Array.
toEncodedString()Compress a string or a Uint8Array to a encoded string.

Decompressor

MethodDescription
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.

CodSpeed Badge

 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

LevelCIDescription
NodeCI for 18.x, 20.x & 22.x.
BrowserTested 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
EdgeEnsured on CI with @vercel/edge-runtime.
CloudflareEnsured with @cloudflare/vitest-pool-workers (see wrangler.toml
TypescriptTS 5.4 + / are-the-type-wrong checks on CI.
ES2022Dist files checked with es-check
PerformanceMonitored 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.

0.2.4

5 months ago

0.2.3

5 months ago

0.2.2

5 months ago

0.2.1

7 months ago

0.2.0

7 months ago

0.1.0

7 months ago

0.0.2

8 months ago