Zstandard (zstd) Compression Node-API Bindings

Common errors

• Error: The module '...zstd-napi.node' was compiled against a different Node.js version

  cause 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.

  cause 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

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install zstd-napi npm
• yarn add zstd-napi yarn
• pnpm add zstd-napi pnpm

Imports

• zstd
  wrong:

  const zstd = require('zstd-napi');

  correct:

  import * as zstd from '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
  wrong:

  const binding = require('zstd-napi/binding');

  correct:

  import * as binding from 'zstd-napi/binding';

  Import for the low-level API, generally for advanced or specialized use cases where buffer management is handled by the caller.

Quickstart

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();