Registry / serialization / zstd-napi

zstd-napi

JSON →
library0.0.12jsnpmunverified

This package, `zstd-napi`, provides high-performance TypeScript bindings to the native Zstandard (zstd) compression library, utilizing the Node-API (N-API) for native addon interfacing. As of its latest stable version, `0.0.12`, the library emphasizes reliability and performance, having been proven in production environments with invocation rates exceeding a million times per second. While a specific release cadence isn't explicitly stated, the frequent minor version bumps (0.0.3 to 0.0.12 in recent history) suggest active development. Key differentiators include comprehensive exposure of the stable Zstandard API, supporting advanced features like dictionary compression and multithreading, and offering both high-level and low-level APIs. It ships with pre-built binaries for common platforms and provides robust Node.js version support, including current and active LTS releases, making it a reliable choice for high-throughput compression tasks in Node.js applications.

npm install zstd-napi
INSTALL
IMPORT
SIG · ZSTD-NAPI
Z
zstd-napi
serializationjavascriptv0.0.12
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

zstd
import * as zstd from 'zstd-napi';
const zstd = require('zstd-napi');
Primary import for the high-level API in modern TypeScript/ESM projects.
{ compress, decompress }
import { compress, decompress } from 'zstd-napi';
Named imports for specific functions from the high-level API.
binding
import * as binding from 'zstd-napi/binding';
const binding = require('zstd-napi/binding');
Import for the low-level API, generally for advanced or specialized use cases where buffer management is handled by the caller.

Demonstrates basic Zstandard compression and decompression using `zstd-napi`'s high-level API, including writing and reading compressed data to a temporary file, and showing how to apply a specific compression level.

import * as zstd from 'zstd-napi'; import { readFileSync, writeFileSync } from 'fs'; import { join } from 'path'; import { tmpdir } from 'os'; async function runCompressionExample() { const originalData = Buffer.from('This is a test string that will be compressed using Zstandard. It is relatively short but should demonstrate the basic functionality of the zstd-napi library.', 'utf8'); console.log(`Original data length: ${originalData.length} bytes`); try { // High-level compress API const compressedData = zstd.compress(originalData); console.log(`Compressed data length: ${compressedData.length} bytes`); // High-level decompress API const decompressedData = zstd.decompress(compressedData); console.log(`Decompressed data length: ${decompressedData.length} bytes`); if (decompressedData.equals(originalData)) { console.log('Decompression successful: Data matches original.'); } else { console.error('Decompression failed: Data mismatch!'); } // Example with compression level (default is 3) const compressedDataLevel10 = zstd.compress(originalData, 10); console.log(`Compressed data (level 10) length: ${compressedDataLevel10.length} bytes`); // Demonstrate writing/reading to a file const tempFilePath = join(tmpdir(), `test_data.zst`); writeFileSync(tempFilePath, compressedData); console.log(`Compressed data written to: ${tempFilePath}`); const readCompressedData = readFileSync(tempFilePath); const reDecompressedData = zstd.decompress(readCompressedData); if (reDecompressedData.equals(originalData)) { console.log('File-based decompression successful.'); } else { console.error('File-based decompression failed: Data mismatch!'); } } catch (error) { console.error('An error occurred during compression/decompression:', error); } } runCompressionExample();
Debug
Known issues
gotchaInstallation of `zstd-napi` may require a C++ compiler on the system if pre-built native binaries are not available for the target platform or Node.js version. This can be a common hurdle in environments without standard development tools.
fix
Ensure you have a C++ compiler (like GCC or Clang) and Python 3.x installed and configured for `node-gyp` to build from source. On Windows, this typically involves installing Visual Studio Build Tools.
affects: >=0.0.1
gotchaWhile `zstd-napi` aims for broad Node.js support, explicitly unsupported or older Node.js versions (e.g., versions outside of Current, Active LTS, and Maintenance LTS) are only supported on a best-effort basis and may experience unexpected breakage or lack of pre-built binaries.
fix
Refer to the official Node.js release schedule and the `zstd-napi` support policy to use a compatible and supported Node.js version. Upgrade Node.js if encountering issues related to ABI compatibility.
affects: >=0.0.1
gotchaThe low-level API exposed via `zstd-napi/binding` provides direct wrappers around the raw Zstandard API and leaves buffer management to the caller. Incorrect usage of this API can lead to memory-unsafe operations in JavaScript code.
fix
For most applications, use the high-level API imported directly from `zstd-napi`. Only utilize the low-level API if you fully understand its implications and require fine-grained control over memory and Zstandard parameters.
affects: >=0.0.1
Errors
Common errors & fixes
Error: The module '...zstd-napi.node' was compiled against a different Node.js version
The native module was built for a different Node.js ABI (Application Binary Interface) version than the one currently running.
fix
Run `npm rebuild zstd-napi` to recompile the native module against your current Node.js version, or ensure you are using a Node.js version for which a pre-built binary is available.
Error: Cannot find module 'zstd-napi' or its corresponding type declarations.
The `zstd-napi` package or its native binding failed to install correctly, or TypeScript cannot locate its type definitions.
fix
Ensure `npm install zstd-napi` completed successfully. If building from source, verify your C++ compiler setup. For TypeScript, check your `tsconfig.json` for correct `moduleResolution` and `typeRoots` settings, though types are generally shipped with the package.
node-gyp rebuild failed with exit code X
The `node-gyp` utility, which compiles native Node.js addons, encountered an error during the build process, typically due to missing or misconfigured C++ development tools.
fix
Install the necessary C++ build tools for your operating system. On Windows, use `npm install --global windows-build-tools`. On macOS, install Xcode Command Line Tools. On Linux, install `build-essential` or equivalent packages.
Upgrade
Version history
0.0.12latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
52 hits · last 30 days
node
42
OpenAI (training)
2
Resources
zstd-napi — npm install zstd-napi · libregistry