@toondepauw/node-zstd

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

Table of Contents

• 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

License

MIT © 2023 - current Toon De Pauw