{"id":16284,"library":"zstd-napi","title":"Zstandard (zstd) Compression Node-API Bindings","description":"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.","status":"active","version":"0.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/drakedevel/zstd-napi","tags":["javascript","binding","compression","native","zstandard","zstd","Node-API","N-API","typescript"],"install":[{"cmd":"npm install zstd-napi","lang":"bash","label":"npm"},{"cmd":"yarn add zstd-napi","lang":"bash","label":"yarn"},{"cmd":"pnpm add zstd-napi","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary import for the high-level API in modern TypeScript/ESM projects.","wrong":"const zstd = require('zstd-napi');","symbol":"zstd","correct":"import * as zstd from 'zstd-napi';"},{"note":"Named imports for specific functions from the high-level API.","symbol":"{ compress, decompress }","correct":"import { compress, decompress } from 'zstd-napi';"},{"note":"Import for the low-level API, generally for advanced or specialized use cases where buffer management is handled by the caller.","wrong":"const binding = require('zstd-napi/binding');","symbol":"binding","correct":"import * as binding from 'zstd-napi/binding';"}],"quickstart":{"code":"import * as zstd from 'zstd-napi';\nimport { readFileSync, writeFileSync } from 'fs';\nimport { join } from 'path';\nimport { tmpdir } from 'os';\n\nasync function runCompressionExample() {\n  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');\n  console.log(`Original data length: ${originalData.length} bytes`);\n\n  try {\n    // High-level compress API\n    const compressedData = zstd.compress(originalData);\n    console.log(`Compressed data length: ${compressedData.length} bytes`);\n\n    // High-level decompress API\n    const decompressedData = zstd.decompress(compressedData);\n    console.log(`Decompressed data length: ${decompressedData.length} bytes`);\n\n    if (decompressedData.equals(originalData)) {\n      console.log('Decompression successful: Data matches original.');\n    } else {\n      console.error('Decompression failed: Data mismatch!');\n    }\n\n    // Example with compression level (default is 3)\n    const compressedDataLevel10 = zstd.compress(originalData, 10);\n    console.log(`Compressed data (level 10) length: ${compressedDataLevel10.length} bytes`);\n    \n    // Demonstrate writing/reading to a file\n    const tempFilePath = join(tmpdir(), `test_data.zst`);\n    writeFileSync(tempFilePath, compressedData);\n    console.log(`Compressed data written to: ${tempFilePath}`);\n\n    const readCompressedData = readFileSync(tempFilePath);\n    const reDecompressedData = zstd.decompress(readCompressedData);\n    if (reDecompressedData.equals(originalData)) {\n        console.log('File-based decompression successful.');\n    } else {\n        console.error('File-based decompression failed: Data mismatch!');\n    }\n\n  } catch (error) {\n    console.error('An error occurred during compression/decompression:', error);\n  }\n}\n\nrunCompressionExample();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Installation 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The native module was built for a different Node.js ABI (Application Binary Interface) version than the one currently running.","error":"Error: The module '...zstd-napi.node' was compiled against a different Node.js version"},{"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.","cause":"The `zstd-napi` package or its native binding failed to install correctly, or TypeScript cannot locate its type definitions.","error":"Error: Cannot find module 'zstd-napi' or its corresponding type declarations."},{"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.","cause":"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.","error":"node-gyp rebuild failed with exit code X"}],"ecosystem":"npm"}