Skip to content

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

License

Notifications You must be signed in to change notification settings

toondepauw/node-zstd

Repository files navigation

@toondepauw/node-zstd

CI workflow latest-release Zstandard license

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

Table of Contents

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

About

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

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published