Package Exports

@toondepauw/node-zstd
@toondepauw/node-zstd/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@toondepauw/node-zstd) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@toondepauw/node-zstd

Node.js addon for native Zstandard encoding and decoding with support for dictionaries.

Installation
Support matrix
API
Running Tests
Releasing
License

Installation

With npm:

npm install @toondepauw/node-zstd

With yarn:

yarn add @toondepauw/node-zstd

Support matrix

	node14	node16	node18	node20
Linux arm64 gnu	✓	✓	✓	✓
Linux arm64 musl	✓	✓	✓	✓
Linux x64 gnu	✓	✓	✓	✓
Linux x64 musl	✓	✓	✓	✓
macOS arm64	✓	✓	✓	✓
macOS x64	✓	✓	✓	✓
Windows x64	✓	✓	✓	✓
FreeBSD x64	✓	✓	✓	✓

API

Decoder

export class Decoder {
  constructor(dictionary?: Buffer | undefined | null);
  decode(data: Buffer): Promise<Buffer>;
  decodeSync(data: Buffer): Buffer;
}

These options can be provided as arguments to the decoder constructor.

Option	Type	Requirement	Description
dictionary	`Buffer`	Optional	Contents of dictionary file.

Encoder

export class Encoder {
  constructor(level: number, dictionary?: Buffer | undefined | null);
  encode(data: Buffer): Promise<Buffer>;
  encodeSync(data: Buffer): Buffer;
}

These options can be provided as arguments to the encoder constructor.

Option	Type	Requirement	Description
level	`number`	Required	Zstd compression level. Can range between -7 (fastest) and 22 (slowest, best compression ratio). Level 3 is a good default.
dictionary	`Buffer`	Optional	Contents of dictionary file.

Usage

This package provides both an asynchronous and synchronous API. In most cases the asynchronous one is preferred as it is non-blocking. If blocking I/O is not a concern the synchronous API has a slight performance benefit.

Async

import { Encoder, Decoder } from "@toondepauw/node-zstd";

const COMPRESSION_LEVEL = 3;

const encoder = new Encoder(COMPRESSION_LEVEL);
const decoder = new Decoder();

(async () => {
  const buff = Buffer.from("Hello, world!");
  const encoded = await encoder.encode(buff);
  const decoded = await decoder.decode(encoded);
})();

Sync

import { Encoder, Decoder } from "@toondepauw/node-zstd";

const COMPRESSION_LEVEL = 3;

const encoder = new Encoder(COMPRESSION_LEVEL);
const decoder = new Decoder();

const buff = Buffer.from("Hello, world!");
const encoded = encoder.encodeSync(buff);
const decoded = decoder.decodeSync(encoded);

Dictionary

A dictionary provides a better compression ratio and improved compression speed for small files, but requires the dictionary to be present during both encoding and decoding.

import { readFileSync } from "fs";
import { Encoder, Decoder } from "@toondepauw/node-zstd";

const COMPRESSION_LEVEL = 3;
const dictionary = readFileSync("./dictionary");

// Same dictionary should be used for both encoding and decoding.
const encoder = new Encoder(COMPRESSION_LEVEL, dictionary);
const decoder = new Decoder(dictionary);

Running Tests

npm test

Releasing

CI will automatically publish when it detects a new release after:

npm version [major | minor | patch | ...]
git push --follow-tags origin main