simple-zstd 2.0.0-0 → 2.0.0

package/README.md

@@ -1,183 +1,730 @@
 # simple-zstd
 
 [![Build Status](https://travis-ci.org/Stieneee/simple-zstd.svg?branch=master)](https://travis-ci.org/Stieneee/simple-zstd)
-[![Package Size Size](https://badgen.net/badge/packagephobia/install/simple-zstd)](https://packagephobia.now.sh/result?p=simple-zstd)
 [![License](https://badgen.net/badge/license/MIT/blue)](https://choosealicense.com/licenses/mit/)
 
-Node.js interface to system installed zstandard (zstd).
+Node.js interface to system-installed Zstandard (zstd) with TypeScript support.
 
-## "Simple"-ZSTD
+## Overview
 
-The package name is inspired by another simple-git which is a wrapper around the git binary installed on the system.
-In summary this package, like simple-git, attempts to provide a lightwieght wrapper around the system installed ZSTD binary.
-This provides a more stable package in comparison to a package that builds against a library at the cost of having to manage child process.
+simple-zstd is a lightweight wrapper around the system-installed zstd binary, inspired by simple-git's approach of wrapping system binaries rather than building against native libraries. This provides a more stable and portable solution at the cost of requiring zstd to be installed on the system.
 
-A few additional features have made there way into version 2 including a class that will attempt to pre-start child processes before they are need for the most latenacy concerned applications.
+### Features
 
-Regardless of whether you are performing a compression or decompression or using a stream or buffer interface this package will spawn an instance of zstd to handle the action.
-When the action is completed the child process will be killed.
-A dicitionary parameter on all functions supports both buffer and path definintons.
-If you provide the dictionary as a buffer this package will create a tmp file using the tmp (tmp-promise) package.
+- **TypeScript Support**: Full TypeScript definitions and modern ES modules
+- **Multiple Interfaces**: Static functions, buffer methods, and class-based API with process pooling
+- **Promise-Based**: All operations return promises for modern async/await patterns
+- **Stream & Buffer**: Support for both streaming and buffer-based compression/decompression
+- **Smart Decompression**: Automatic detection and passthrough of non-compressed data
+- **Dictionary Support**: Use compression dictionaries via Buffer or file path
+- **Process Pooling**: Pre-spawn child processes for latency-sensitive applications
+- **Node.js 18+**: Built on modern Node.js features
 
-All functions return a promise.
-This promise will return the stream or a buffer depending on the function type called.
+## Requirements
 
-Finally the decompression methods provide a "maybe" functionality.
-If a buffer or stream is passed that is not a zstd compressed byte stream the byte stream is not altered.
+- **Node.js**: >= 18.0.0
+- **zstd**: Must be installed and available on system PATH
 
-## Dependencies
+## Installation
 
-ZSTD must be installed on the system.
-It will work in both Linux and Windows environments assuming the zstd(.exe) can be found on the path.
+### Install zstd
 
-Example:
+**Ubuntu/Debian:**
 
-`sudo apt install zstd`
+```bash
+sudo apt install zstd
+```
 
-## Installation
+**macOS:**
+
+```bash
+brew install zstd
+```
+
+**Windows:**
+
+```bash
+choco install zstd
+# or download from: https://github.com/facebook/zstd/releases
+```
+
+### Install simple-zstd
+
+```bash
+npm install simple-zstd
+```
+
+## API Reference
+
+### Types
+
+```typescript
+import { Duplex } from "node:stream";
+import { SpawnOptions } from "node:child_process";
+import { DuplexOptions } from "node:stream";
+
+interface ZSTDOpts {
+  dictionary?: Buffer | { path: string }; // Compression dictionary
+  zstdOptions?: string[]; // CLI args to pass to zstd (e.g., ['--ultra'])
+  spawnOptions?: SpawnOptions; // Node.js child_process spawn options
+  streamOptions?: DuplexOptions; // Node.js stream options
+}
+
+interface PoolOpts {
+  compressQueueSize?: number; // Number of pre-spawned compression processes
+  decompressQueueSize?: number; // Number of pre-spawned decompression processes
+  compressQueue?: {
+    compLevel?: number;
+    dictionary?: Buffer | { path: string };
+    zstdOptions?: string[];
+    spawnOptions?: SpawnOptions;
+    streamOptions?: DuplexOptions;
+  };
+  decompressQueue?: {
+    dictionary?: Buffer | { path: string };
+    zstdOptions?: string[];
+    spawnOptions?: SpawnOptions;
+    streamOptions?: DuplexOptions;
+  };
+}
+```
+
+### Static Functions
+
+```typescript
+// Compression
+compress(compLevel: number, opts?: ZSTDOpts): Promise<Duplex>
+compressBuffer(buffer: Buffer, compLevel: number, opts?: ZSTDOpts): Promise<Buffer>
+
+// Decompression (with automatic passthrough for non-compressed data)
+decompress(opts?: ZSTDOpts): Promise<Duplex>
+decompressBuffer(buffer: Buffer, opts?: ZSTDOpts): Promise<Buffer>
+```
+
+### Class: SimpleZSTD
 
-`npm i simple-zstd`
+The `SimpleZSTD` class provides process pooling for better performance when performing many compression/decompression operations.
+
+```typescript
+class SimpleZSTD {
+  // Static factory method (recommended)
+  static create(poolOptions?: PoolOpts): Promise<SimpleZSTD>;
+
+  // Instance methods
+  compress(compLevel?: number): Promise<Duplex>;
+  compressBuffer(buffer: Buffer, compLevel?: number): Promise<Buffer>;
+  decompress(): Promise<Duplex>;
+  decompressBuffer(buffer: Buffer): Promise<Buffer>;
+  destroy(): void;
+
+  // Statistics
+  get queueStats(): {
+    compress: { hits: number; misses: number };
+    decompress: { hits: number; misses: number };
+  };
+}
+```
+
+**Note:** Use the static `create()` method instead of the constructor. The constructor is private to ensure proper async initialization.
 
 ## Usage
 
-The static functions provide the most basic interface for usage
+### Example 1: Stream Interface (TypeScript)
 
-```javascript
-const {compress, decompress, compressBuffer, decompressBuffer} = require('../index');
+```typescript
+import fs from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { compress, decompress } from "simple-zstd";
 
-compLevel = 3; // ZSTD Compression Level
-spawnOptions = {} // node:child_process spawnOptions object - adjust the spwan options of the ZSTD process
-streamOptions = {} // node:stream streamOptions - adjust the stream options 
-zstdOptions = [] // Array of Options to pass to the zstd process e.g. ['--ultra']
-dictionary = Buffer || {path} // Supply an optional dictionary buffer or path to dictionary file
+async function copyFile() {
+  const c = await compress(3); // Compression level 3
+  const d = await decompress();
+
+  await pipeline(
+    fs.createReadStream("example.txt"),
+    c,
+    d,
+    fs.createWriteStream("example_copy.txt")
+  );
 
-// Static Functions
-function compress(compLevel, spawnOptions, streamOptions, zstdOptions, dictionary) // returns a promise that resolves to a stream
-function compressBuffer(buffer, compLevel, spawnOptions, streamOptions, zstdOptions, dictionary) // returns a promise that resolves to a buffer
-function decompress(spawnOptions, streamOptions, zstdOptions, dictionary) // returns a promise that resolves to a stream
-function decompressBuffer(buffer, spawnOptions, streamOptions, zstdOptions, dictionary) // returns a promise that resolves to a buffer
+  console.log("File compressed and decompressed!");
+}
+
+copyFile().catch(console.error);
 ```
 
-The SimpleZSTD class allows an the settings to be preset for a pool of child process.
-The function names are the same on the class however the options can not be changed from the class constructor.
+### Example 2: Buffer Interface (TypeScript)
 
-### Example - Stream Interface
+```typescript
+import { compressBuffer, decompressBuffer } from "simple-zstd";
 
-This simple example reads a file, compressed, decopressed and writes the file as a copy.
-Running this example will spawn two instances of zstd as child processes.
+async function processBuffer() {
+  const buffer = Buffer.from("this is a test");
+
+  // Compress with level 3
+  const compressed = await compressBuffer(buffer, 3);
+  console.log(
+    `Original: ${buffer.length} bytes, Compressed: ${compressed.length} bytes`
+  );
+
+  // Decompress
+  const decompressed = await decompressBuffer(compressed);
+  console.log(decompressed.toString()); // "this is a test"
+}
+
+processBuffer().catch(console.error);
+```
+
+### Example 3: CommonJS Usage
 
 ```javascript
-const fs = require('fs');
-const { pipeline } = require('node:stream');
-const {compress, decompress} = require('simple-zstd');
+const fs = require("fs");
+const { pipeline } = require("node:stream/promises");
+const { compress, decompress } = require("simple-zstd");
 
 async function copyFile() {
   const c = await compress(3);
   const d = await decompress();
 
   await pipeline(
-    fs.createReadStream('example.txt'),
+    fs.createReadStream("example.txt"),
     c,
     d,
-    fs.createWriteStream('example_copy.txt'),
-    () => {
-      console.log('The file has been compressed and decompressed to example_copy.txt')
-    }
+    fs.createWriteStream("example_copy.txt")
   );
+
+  console.log("File compressed and decompressed!");
 }
 
-copyFile();
+copyFile().catch(console.error);
+```
 
+### Example 4: Class Interface with Process Pooling
+
+The `SimpleZSTD` class pre-spawns zstd processes for lower latency. This is ideal for high-throughput scenarios.
+
+```typescript
+import fs from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { SimpleZSTD } from "simple-zstd";
+
+async function processMultipleFiles() {
+  // Create instance with process pools using static factory method
+  const zstd = await SimpleZSTD.create({
+    compressQueueSize: 2, // Pre-spawn 2 compression processes
+    decompressQueueSize: 2, // Pre-spawn 2 decompression processes
+    compressQueue: {
+      compLevel: 3, // Default compression level for pool
+    },
+  });
+
+  try {
+    // Process first file with pool default (level 3)
+    const c1 = await zstd.compress();
+    const d1 = await zstd.decompress();
+
+    await pipeline(
+      fs.createReadStream("file1.txt"),
+      c1,
+      d1,
+      fs.createWriteStream("file1_copy.txt")
+    );
+
+    console.log("File 1 processed!");
+
+    // Process second file with custom compression level (bypasses pool)
+    const c2 = await zstd.compress(19); // Override with level 19
+    const d2 = await zstd.decompress();
+
+    await pipeline(
+      fs.createReadStream("file2.txt"),
+      c2,
+      d2,
+      fs.createWriteStream("file2_copy.txt")
+    );
+
+    console.log("File 2 processed!");
+
+    // Check pool statistics
+    console.log("Pool stats:", zstd.queueStats);
+    // Example output: { compress: { hits: 1, misses: 1 }, decompress: { hits: 2, misses: 0 } }
+    // Note: compress shows 1 miss because we used custom level for file2
+  } finally {
+    // Clean up all child processes
+    zstd.destroy();
+  }
+}
+
+processMultipleFiles().catch(console.error);
 ```
 
-### Example - Buffer Interface
+### Example 5: Using Compression Dictionaries
 
-This example demonstrates the use of the buffer interface
+```typescript
+import fs from "node:fs";
+import { compressBuffer, decompressBuffer, SimpleZSTD } from "simple-zstd";
 
-```javascript
-const {compressBuffer, decompressBufer} = require('simple-zstd');
+// Static functions with dictionaries
+async function useDictionaryStatic() {
+  const dictionary = fs.readFileSync("my-dictionary.zstd");
+  const data = Buffer.from("Sample text to compress");
 
-async function printString() {
-  const buffer = Buffer.from('this is a test');
+  // Compress with dictionary
+  const compressed = await compressBuffer(data, 3, { dictionary });
 
-  const compressed = await compressBuffer(buffer, 3);
-  const decompressed = await decompressBuffer(compressed);
+  // Decompress with same dictionary
+  const decompressed = await decompressBuffer(compressed, { dictionary });
+
+  console.log(decompressed.toString()); // "Sample text to compress"
+}
 
-  console.log(decompressed.toString()); // this is a test
+// Class with dictionaries (supports Buffer or file path)
+async function useDictionaryClass() {
+  const dictionary = fs.readFileSync("my-dictionary.zstd");
+
+  const zstd = await SimpleZSTD.create({
+    compressQueue: {
+      compLevel: 3,
+      dictionary, // Can be Buffer or { path: '/path/to/dict' }
+    },
+    decompressQueue: {
+      dictionary, // Same dictionary for decompression
+    },
+  });
+
+  try {
+    const data = Buffer.from("Sample text to compress");
+    const compressed = await zstd.compressBuffer(data);
+    const decompressed = await zstd.decompressBuffer(compressed);
+    console.log(decompressed.toString()); // "Sample text to compress"
+  } finally {
+    zstd.destroy();
+  }
 }
 
-printString();
+useDictionaryStatic().catch(console.error);
 ```
 
-### Example - Class Interface
+**Dictionary Caching:** When using dictionary Buffers with static functions, simple-zstd automatically caches the temporary dictionary files using SHA-256 hashing. This means:
+- ✅ Multiple calls with the **same dictionary Buffer** reuse the same temp file
+- ✅ No performance penalty for repeated operations with dictionaries
+- ✅ Automatic cleanup when the dictionary is no longer in use
+- ✅ **Fixes exponential slowdown** when compressing thousands of items with dictionaries
 
-This example demonstrates the use of the class interface.
-Once a class instance is created it can be used to with either the stream or buffer interface.
-Options can not be changed once the class is instantiated.
-This due to the fact that the class will start to spawn child processes with settings passed to the constructor.
-Calling ```destroy()``` will kill all child processes.
+```typescript
+const dict = fs.readFileSync('my-dict.zstd');
 
-```javascript
-const fs = require('fs');
-const { pipeline } = require('node:stream');
-const { SimpleZSTD } = require('simple-zstd');
-
-poolOptions = {
-    compressQueue: { 
-      targetSize: 1 // this determines how many instances of zstd are spawned into the qeueue. leaving it empty will result child processes to bring spawned as needed.
-      compLevel, 
-      spawnOptions, 
-      streamOptions, 
-      zstdOptions
-    }, 
-    decompressQueue: { 
-      targetSize: 1 // there is a queue for both compression and decompression
-      spawnOptions, 
-      streamOptions, 
-      zstdOptions
-    }, 
+// These 1000 operations will only create ONE temp file total
+for (let i = 0; i < 1000; i++) {
+  await compressBuffer(data[i], 3, { dictionary: dict });
 }
+// Temp file is automatically cleaned up when no longer referenced
+```
 
-async function copyFile() {
-  const i = new SimpleZSTD(poolOptions, dictionary); // poolOptions set options for the compressions and decompressiong porcess pools. dictionary is optional and set for both pools.
+### Example 6: Smart Decompression (Auto-detect)
 
-  const c = await i.compress(3); // this will pull a instance from the queue
-  const d = await i.decompress();
+The decompression functions automatically detect if data is zstd-compressed and pass through uncompressed data unchanged.
 
-  pipeline(
-    fs.createReadStream('example.txt'),
-    c,
-    d,
-    brake(200000),
-    fs.createWriteStream('example_copy.txt'),
-    () => {
-      console.log('The file has been compressed and decompressed to example_copy.txt')
-    }
-  );
+```typescript
+import { decompressBuffer } from "simple-zstd";
+
+async function smartDecompress() {
+  const plainText = Buffer.from("not compressed");
+  const result = await decompressBuffer(plainText);
+
+  // Non-compressed data passes through unchanged
+  console.log(result.toString()); // "not compressed"
 }
 
-copyFile();
+smartDecompress().catch(console.error);
 ```
 
-## zstdOptions
+## Advanced Options
 
-This interface allows you to pass any command line option to the zstd process.
-  
-```javascript
-const c2 = await compress(22, {}, {}, ['--ultra']);
+### Custom zstd Options
+
+Pass any command-line option to the zstd process via `zstdOptions`:
+
+```typescript
+import { compress } from "simple-zstd";
+
+// Use ultra compression (level 22)
+const stream = await compress(22, {
+  zstdOptions: ["--ultra"],
+});
+
+// Multiple options
+const stream2 = await compress(19, {
+  zstdOptions: ["--ultra", "--long"],
+});
+```
+
+### Spawn Options
+
+Control the child process spawn behavior:
+
+```typescript
+import { compress } from "simple-zstd";
+
+const stream = await compress(3, {
+  spawnOptions: {
+    cwd: "/custom/working/directory",
+    env: { ...process.env, CUSTOM_VAR: "value" },
+  },
+});
+```
+
+### Stream Options
+
+Customize the Duplex stream behavior:
+
+```typescript
+import { compress } from "simple-zstd";
+
+const stream = await compress(3, {
+  streamOptions: {
+    highWaterMark: 64 * 1024, // 64KB buffer
+  },
+});
+```
+
+### Stream Events
+
+All compression and decompression streams emit the following events:
+
+```typescript
+import { compress } from "simple-zstd";
+
+const stream = await compress(3);
+
+// Standard Duplex stream events
+stream.on("data", (chunk: Buffer) => {
+  console.log("Received chunk:", chunk.length, "bytes");
+});
+
+stream.on("end", () => {
+  console.log("Stream finished");
+});
+
+stream.on("error", (err: Error) => {
+  console.error("Stream error:", err);
+});
+
+// zstd-specific events
+stream.on("stderr", (message: string) => {
+  // zstd process stderr output
+  console.warn("zstd stderr:", message);
+});
+
+stream.on("exit", (code: number, signal: NodeJS.Signals | null) => {
+  // zstd process exit event
+  console.log("zstd process exited with code:", code);
+});
 ```
 
-## Debug
+**Event Reference:**
+
+- `data` - Emitted when compressed/decompressed data is available
+- `end` - Emitted when the stream has finished processing
+- `error` - Emitted on stream errors or if zstd exits with non-zero code
+- `stderr` - Emitted when the zstd process writes to stderr (warnings, debug info)
+- `exit` - Emitted when the underlying zstd process exits
 
-The package supports the debug package.
-Setting the DEBUD Environment variable will cause the debug messages to be printed to the console.
-This will presents debug information for both zstd spawns and the child process queue.
+## Debugging
+
+Enable debug output using the `DEBUG` environment variable:
 
 ```bash
-DEBUG=SimpleZSTD,SimpleZSTDQueue node example.js
+# Debug simple-zstd operations
+DEBUG=SimpleZSTD node app.js
+
+# Debug process queue
+DEBUG=SimpleZSTDQueue node app.js
 
+# Debug both
+DEBUG=SimpleZSTD,SimpleZSTDQueue node app.js
 ```
 
+## Migrating to v2
+
+Version 2.0 is a complete rewrite with TypeScript support and a modernized API. Here's what you need to know:
+
+### Breaking Changes
+
+#### 1. Node.js Version Requirement
+
+**v1:** No explicit requirement
+**v2:** Requires Node.js >= 18.0.0
+
+```bash
+# Check your Node version
+node --version  # Should be v18.0.0 or higher
+```
+
+#### 2. Function Names Changed
+
+| v1 Function             | v2 Function                                  |
+| ----------------------- | -------------------------------------------- |
+| `ZSTDCompress(level)`   | `compress(level, opts?)`                     |
+| `ZSTDDecompress()`      | `decompress(opts?)`                          |
+| `ZSTDDecompressMaybe()` | `decompress(opts?)` _(built-in auto-detect)_ |
+
+**v1 Code:**
+
+```javascript
+const { ZSTDCompress, ZSTDDecompress } = require("simple-zstd");
+
+const compressStream = ZSTDCompress(3);
+const decompressStream = ZSTDDecompress();
+```
+
+**v2 Code:**
+
+```javascript
+const { compress, decompress } = require("simple-zstd");
+
+const compressStream = await compress(3);
+const decompressStream = await decompress();
+```
+
+#### 3. All Functions Now Return Promises
+
+**v1:** Functions returned streams synchronously
+**v2:** Functions return `Promise<Duplex>` and must be awaited
+
+**v1 Code:**
+
+```javascript
+fs.createReadStream("file.txt")
+  .pipe(ZSTDCompress(3))
+  .pipe(ZSTDDecompress())
+  .pipe(fs.createWriteStream("output.txt"));
+```
+
+**v2 Code:**
+
+```javascript
+const c = await compress(3);
+const d = await decompress();
+
+await pipeline(
+  fs.createReadStream("file.txt"),
+  c,
+  d,
+  fs.createWriteStream("output.txt")
+);
+```
+
+#### 4. "Maybe" Functionality Now Built-in
+
+**v1:** Had separate `ZSTDDecompressMaybe()` function
+**v2:** All decompression functions auto-detect and pass through non-compressed data
+
+**v1 Code:**
+
+```javascript
+const { ZSTDDecompressMaybe } = require("simple-zstd");
+
+stream.pipe(ZSTDDecompressMaybe()).pipe(output);
+```
+
+**v2 Code:**
+
+```javascript
+const { decompress } = require("simple-zstd");
+
+const d = await decompress(); // Automatically detects compressed data
+pipeline(stream, d, output);
+```
+
+#### 5. Options Structure Changed
+
+**v1:** Limited options as separate parameters
+**v2:** Unified options object with TypeScript types
+
+**v1 Code:**
+
+```javascript
+// v1 had limited customization
+ZSTDCompress(3, streamOptions);
+```
+
+**v2 Code:**
+
+```javascript
+await compress(3, {
+  dictionary: Buffer.from("..."),
+  zstdOptions: ["--ultra"],
+  spawnOptions: { cwd: "/tmp" },
+  streamOptions: { highWaterMark: 64 * 1024 },
+});
+```
+
+### New Features in v2
+
+#### TypeScript Support
+
+```typescript
+import { compress, decompress, SimpleZSTD } from "simple-zstd";
+import type { ZSTDOpts, PoolOpts } from "simple-zstd";
+```
+
+#### Buffer Interface
+
+New convenience methods for working with buffers directly:
+
+```typescript
+import { compressBuffer, decompressBuffer } from "simple-zstd";
+
+const compressed = await compressBuffer(Buffer.from("data"), 3);
+const decompressed = await decompressBuffer(compressed);
+```
+
+#### Process Pooling with SimpleZSTD Class
+
+Pre-spawn processes for better performance with async factory method:
+
+```typescript
+import { SimpleZSTD } from "simple-zstd";
+
+const zstd = await SimpleZSTD.create({
+  compressQueueSize: 2,
+  decompressQueueSize: 2,
+  compressQueue: {
+    compLevel: 3,
+    dictionary: Buffer.from("..."), // Optional
+  },
+});
+
+// Use pooled processes
+const stream = await zstd.compress();
+
+// Or override compression level for specific operations
+const stream2 = await zstd.compress(19);
+
+// Clean up when done
+zstd.destroy();
+```
+
+#### Dictionary Support
+
+Full support for compression dictionaries:
+
+```typescript
+const dictionary = fs.readFileSync("dict.zstd");
+
+await compress(3, { dictionary });
+await compressBuffer(data, 3, { dictionary });
+```
+
+### Migration Examples
+
+#### Simple Stream Compression
+
+**v1:**
+
+```javascript
+const { ZSTDCompress, ZSTDDecompress } = require("simple-zstd");
+
+fs.createReadStream("input.txt")
+  .pipe(ZSTDCompress(3))
+  .pipe(fs.createWriteStream("output.zst"));
+```
+
+**v2:**
+
+```javascript
+const { compress } = require("simple-zstd");
+const { pipeline } = require("node:stream/promises");
+
+const c = await compress(3);
+await pipeline(
+  fs.createReadStream("input.txt"),
+  c,
+  fs.createWriteStream("output.zst")
+);
+```
+
+#### Error Handling
+
+**v1:**
+
+```javascript
+ZSTDCompress(3).on("error", (err) => console.error(err));
+```
+
+**v2:**
+
+```javascript
+try {
+  const c = await compress(3);
+  c.on("error", (err) => console.error(err));
+} catch (err) {
+  console.error("Failed to create stream:", err);
+}
+```
+
+#### With Custom Options
+
+**v1:**
+
+```javascript
+// Limited options in v1
+const stream = ZSTDCompress(3, { highWaterMark: 64 * 1024 });
+```
+
+**v2:**
+
+```javascript
+const stream = await compress(3, {
+  streamOptions: { highWaterMark: 64 * 1024 },
+  zstdOptions: ["--ultra"],
+});
+```
+
+### Upgrade Checklist
+
+- [ ] Update Node.js to >= 18.0.0
+- [ ] Replace `ZSTDCompress` with `compress`
+- [ ] Replace `ZSTDDecompress` with `decompress`
+- [ ] Replace `ZSTDDecompressMaybe` with `decompress` (same function)
+- [ ] Add `await` to all compression/decompression calls
+- [ ] Update imports to use new function names
+- [ ] Consider using buffer methods (`compressBuffer`/`decompressBuffer`) for simpler use cases
+- [ ] Consider using `SimpleZSTD` class for high-throughput scenarios
+- [ ] Update error handling for async/await pattern
+- [ ] Update tests to handle promises
+
+## Performance Benchmarks
+
+This package has been benchmarked against other zstd packages.
+At this time is appears to be the fastest package for processing large files.
+
+[Benchmark Tests](https://github.com/Stieneee/node-compression-test)
+
+## Performance Considerations
+
+This package spawns a child process for each compression or decompression operation. While this provides excellent performance for large files, child process creation overhead can become a bottleneck when processing many small files rapidly.
+
+**Solution:** Use the `SimpleZSTD` class with process pooling for high-throughput scenarios:
+
+```typescript
+const zstd = await SimpleZSTD.create({
+  compressQueueSize: 4, // Pre-spawn 4 compression processes
+  decompressQueueSize: 4, // Pre-spawn 4 decompression processes
+});
+
+// Reuse pooled processes for multiple operations
+for (const file of files) {
+  const stream = await zstd.compress();
+  // ... process file ...
+}
+
+zstd.destroy(); // Clean up when done
+```
+
+Process pooling significantly reduces latency by reusing existing child processes instead of spawning new ones for each operation.
+
 ## Contributing
 
 Pull requests are welcome.
@@ -186,7 +733,7 @@ Pull requests are welcome.
 
 MIT License
 
-Copyright (c) 2022 Tyler Stiene
+Copyright (c) 2025 Tyler Stiene
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal