zstd-napi

zstd-napi

zstd-napi is a TypeScript binding to the native Zstandard compression library, using the Node-API addon interface.

A strong emphasis has been placed on reliability and performance. It has been used for years in at least one production envionment where it is invoked more than a million times per second.

Getting Started

To install, just run npm install zstd-napi (or the equivalent for your choice of package manager). By default, this will download a pre-built native module suitable for your platform from the corresponding GitHub release. If a prebuild isn't available, it will try to build the module from source, which should work as long as you have a C++ compiler installed.

Once installed, usage is as simple as:

import * as zstd from 'zstd-napi';
zstd.compress(Buffer.from('your data here'));

See the API documentation for more details!

Features

The library exposes all of the functionality present in the stable Zstandard API, including dictionary compression, multithreading, advanced compression parameters, and more.

Most of this functionality is available through a high-level API, which is the recommended way to use the library for nearly all applications. Both streaming and single-pass interfaces are available.

The high-level API is built on top of the low-level API, which is exposed as zstd-napi/binding. This is a wrapper around the raw Zstandard API designed to be as thin as possible while preventing JavaScript code from doing anything memory-unsafe. Notably, buffer management is left to the caller. It may be useful as a building block for another library developer, or for applications with specialized use-cases. Most users will be happier using the high-level API.

Currently, there's no support for the (unstable) Zstandard "experimental" API, but at least partial support is planned for the future. If there's functionality you'd like to use, please file an issue and let me know!

Support Policy

Node.js

All live Node.js verisons are supported on a first-class basis. Per the release cycle, this includes the Current version, the Active LTS version, and one or more Maintenance versions. In addition, one previous LTS version is supported on a best-effort basis. As of the latest zstd-napi release, this means:

Node.js Version	Support
21 (Current)	✅
20 (Active LTS)	✅
18 (Maint. LTS)	✅
16	best-effort

Other versions may work, but they aren't regularly tested and may break at any time.

Platform

All of the native code in this project is fairly portable, so in principle zstd-napi should work on any platform supported by both Node.js and Zstandard.

Prebuilds are provided for all platforms with Tier 1 support in Node.js. This includes GNU/Linux armv7, arm64, and x64, macOS arm64 and x64, and Windows x64 and x86. GNU/Linux prebuilds are linked against Glibc 2.28, which is the same version required by official Node.js 18+ builds.

Please file an issue if this library doesn't work on your platform!

Zstandard

zstd-napi's native component statically links Zstandard, currently version 1.5.6. Newer versions will be pulled in as they are released.

Security Updates

This project will make every effort to promptly release fixes for discovered security vulnerabilties. Whenever possible, patches will be released for previous release branches to allow affected users to easily upgrade without other breaking changes.

Changelog

[0.0.8] - 2024-04-07

Added

• API documentation.
• High-level compress and decompress convenience functions.
• Low-level bindings for ZSTD_defaultCLevel and ZSTD_getDictID_fromCDict.
• Prebuilds for GNU/Linux on arm64 and armv7, Windows on ia32.
• New targetCBlockSize compression parameter, stabilized in Zstandard 1.5.6.
• Releases now include SLSA Build L3 provenance attestations.

Changed

• Build GNU/Linux prebuilds on Debian 10 (Glibc 2.28).
• Class type definitions for the low-level bindings now have brands to prevent interchanging e.g. CDict and DDict.
• Upgrade node-addon-api to 7.x.
• Upgrade Zstandard to 1.5.6.

Removed

• Prebuilds for Node-API 6.
• Support for Node-API < 8.
• Support for GNU/Linux with Glibc < 2.28.
• Support for TypeScript < 4.3.

Fixed

• Bindings use type tags (added in Node-API 8) to prevent passing an invalid native object type as a parameter.
• Types no longer require esModuleInterop to be enabled.