@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 zstd

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

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

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
async function main() {
  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!')
}

main().catch(console.error)

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.