Getting started

Install

npm

npm install @derodero24/comprs

pnpm

pnpm add @derodero24/comprs

yarn

yarn add @derodero24/comprs

bun

bun add @derodero24/comprs

deno

deno add npm:@derodero24/comprs

comprs needs Node.js 22 or later. The package manager installs one prebuilt native binary for your platform as an optional dependency (see Platforms); browsers get the WebAssembly build, which ships in the package.

Compress and decompress

The unified API, @derodero24/comprs/next, has one function per direction for every format, with an options object:

import { compress, compressSync, decompress, decompressSync } from '@derodero24/comprs/next';

const data = new TextEncoder().encode('Hello, comprs!');

// The plain names are async, as in node:zlib: in Node.js, they run on the libuv thread pool.
const zstd = await compress(data, { format: 'zstd', level: 19 });
const restored = await decompress(zstd); // detects the format

// The *Sync variants run on the calling thread.
const gzip = compressSync(data, { format: 'gzip', gzipHeader: { filename: 'hello.txt' } });
decompressSync(gzip, { format: 'gzip', maxOutputSize: 1024 * 1024 });

Every result is a plain Uint8Array. The formats are 'zstd', 'gzip', 'deflate' (zlib), 'deflate-raw', 'brotli' and 'lz4'; the unified API guide has every option.

The package root, @derodero24/comprs, has a function for each format and variant instead, such as zstdCompress(data, level) and gzipDecompressAsync(data), which return a Node.js Buffer in the native addon. Both APIs are supported and produce the same bytes at the same settings; see the classic API.

Stream

Pipe a stream of bytes through a CompressionStream or a DecompressionStream, which work like the standard classes in every format:

import { CompressionStream, DecompressionStream } from '@derodero24/comprs/next';

const compressed = file.stream().pipeThrough(new CompressionStream('zstd', { level: 9 }));
const response = new Response(compressed, { headers: { 'Content-Encoding': 'zstd' } });

const body = request.body!.pipeThrough(
  new DecompressionStream('auto', { maxOutputSize: 10 * 1024 * 1024 }),
);

Node.js streams have their own stream.Transform factories; see Streaming.

Handle errors

The errors that comprs raises have a stable code:

const bytes = new Uint8Array(await request.arrayBuffer());
try {
  await decompress(bytes, { maxOutputSize: 10 * 1024 * 1024 });
} catch (error) {
  // 413 for a body that decompresses to more than 10 MiB, 400 for corrupt data and the like
  const status =
    error instanceof Error && 'code' in error && error.code === 'ERR_COMPRS_SIZE_LIMIT' ? 413 : 400;
}

See Errors and limits for every code.

Deno and Bun

Both load the native addon, as Node.js does:

// Deno
import { compress } from 'npm:@derodero24/comprs/next';

// Bun, as in Node.js
import { compress } from '@derodero24/comprs/next';

Deno needs permission to load it: run with --allow-ffi --allow-read --allow-env, or --allow-all. Without --allow-ffi, the import fails with a misleading Cannot find native binding error, which blames a bug in npm. Deno also needs a local node_modules directory, which holds the platform package with the binary: set "nodeModulesDir": "auto" in deno.json, or install the package into a local node_modules with npm.

Browsers

Bundlers that target browsers pick the WebAssembly build through the browser condition of the package’s exports. The same imports work, with no initialization call:

import { compressSync } from '@derodero24/comprs/next';

const gzip = compressSync(new TextEncoder().encode('Hello from the browser!'), { format: 'gzip' });

Some bundlers need a setting for the WebAssembly binary or for top-level await; see Browsers.