@neodon/zstd NPM

@neodon/zstd

This package wraps the zstd command in a stream for either compression or decompression.

NOTE: You must have the zstd command available on your path (TODO: allow specifying the location as a parameter).

Installing the zstd CLI

Here are some quick install commands for zstd on different operating systems:

OS/Distro	Package Manager	Install Command
Alpine	APK	`apk add zstd`
Arch Linux	Pacman	`sudo pacman -S zstd`
CentOS/RHEL	YUM	`sudo yum install -y zstd`
Fedora	DNF	`sudo dnf install -y zstd`
MacOS	Homebrew	`brew install zstd`
MacOS	MacPorts	`sudo port install zstd`
openSUSE	Zypper	`sudo zypper install zstd`
Ubuntu/Debian	APT	`sudo apt-get install -y zstd`
Windows	Chocolatey	`choco install -y zstandard`
Windows	MSYS2	`pacman -S zstandard`
Windows	Scoop	`scoop install zstd`

Usage

Basic Streaming

Here's a simple example showing compression and decompression in a pipeline:

import { createZstdCompress, createZstdDecompress } from '@neodon/zstd'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'

// Example: Compress data, decompress it, and write the result

await pipeline(
  // Create a simple readable stream with some text
  Readable.from('Hello, world!\n'),

  // Compress using zstd
  createZstdCompress(),

  // Immediately decompress to verify the roundtrip
  createZstdDecompress(),

  // Write the result to stderr (could use any writable stream)
  process.stderr,

  // Prevent pipeline from automatically closing the last stream - process.stderr
  { end: false }
)

File Compression

Here's a complete example showing file compression, decompression, and verification:

import { createZstdCompress, createZstdDecompress } from '@neodon/zstd'
import assert from 'node:assert'
import { createReadStream, createWriteStream, readFileSync, writeFileSync } from 'node:fs'
import { pipeline } from 'node:stream/promises'

// Example: Demonstrate compression/decompression with file verification

const inputFile = 'inputFile.json'
const compressedFile = 'compressed.json.zst'
const outputFile = 'decompressed.json'

// Sample data to compress
const inputData = {
  message: 'Hello from zstd!',
  numbers: [1, 2, 3],
  nested: { works: true }
}

// Write initial data
writeFileSync(inputFile, JSON.stringify(inputData, null, 2))

// Compress JSON file to .zst
await pipeline(
  createReadStream(inputFile),
  createZstdCompress(),
  createWriteStream(compressedFile),
)

// Decompress .zst back to JSON
await pipeline(
  createReadStream(compressedFile),
  createZstdDecompress(),
  createWriteStream(outputFile),
)

// Verify the roundtrip was successful
const result = JSON.parse(readFileSync(outputFile, 'utf8'))
assert.deepStrictEqual(result, inputData)
console.log('Compression/decompression successful!')