Node.js addon for native Zstandard encoding and decoding with support for dictionaries.
npm install @toondepauw/node-zstd!CI workflow
Node.js addon for native Zstandard encoding and decoding with support for dictionaries.
- Installation
- Support matrix
- API
- Running Tests
- Releasing
- License
With npm:
``
npm install @toondepauw/node-zstd
With yarn:
`
yarn add @toondepauw/node-zstd
| | node14 | node16 | node18 | node20 |
| ---------------- | ------ | ------ | ------ | ------ |
| Linux arm64 gnu | ✓ | ✓ | ✓ | ✓ |
| Linux arm64 musl | ✓ | ✓ | ✓ | ✓ |
| Linux x64 gnu | ✓ | ✓ | ✓ | ✓ |
| Linux x64 musl | ✓ | ✓ | ✓ | ✓ |
| macOS arm64 | ✓ | ✓ | ✓ | ✓ |
| macOS x64 | ✓ | ✓ | ✓ | ✓ |
| Windows x64 | ✓ | ✓ | ✓ | ✓ |
| FreeBSD x64 | ✓ | ✓ | ✓ | ✓ |
`ts`
export class Decoder {
constructor(dictionary?: Buffer | undefined | null);
decode(data: Buffer): Promise
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. |
`ts`
export class Encoder {
constructor(level: number, dictionary?: Buffer | undefined | null);
encode(data: Buffer): Promise
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. |Buffer
| dictionary | | Optional | Contents of dictionary file. |
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.
`ts
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);
})();
`
`ts
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);
`
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.
`ts
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);
`
npm test
CI will automatically publish when it detects a new release after:
`
npm version [major | minor | patch | ...]
git push --follow-tags origin main