@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!')

License

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