The Zstandard WASM library, provides a simplified wrapper around the Zstandard c++ library.

See Zstandard for more details.

import { Zstd } from "@hpcc-js/wasm-zstd";

const zstd = await Zstd.load();

//  Generate some "data"
const data = new Uint8Array(Array.from({ length: 100000 }, (_, i) => i % 256));

const compressed_data = zstd.compress(data);
const decompressed_data = zstd.decompress(compressed_data);

WARNING

Zstd.load() returns a process-wide singleton. Streaming compression and decompression mutate shared codec state and must be serialized by the caller. Do not interleave concurrent streaming operations on the same instance.

Methods

load()

static load(): Promise<Zstd>

Compiles and instantiates the raw wasm.

INFO

In general WebAssembly compilation is disallowed on the main thread if the buffer size is larger than 4KB, hence forcing load to be asynchronous;

Returns

Promise<Zstd>

A promise to an instance of the Zstd class.

---

unload()

static unload(): void

Unloades the compiled wasm instance.

Returns

void

---

dispose()

dispose(): void

Unloads the compiled wasm instance, equivalent to Zstd.unload. Disposing an instance that has already been unloaded is a no-op.

Returns

void

---

[dispose]()

[dispose](): void

Returns

void

---

version()

version(): string

Returns

string

The Zstd c++ version

---

reset()

reset(): void

Resets both compression and decompression state (legacy API). Prefer resetCompression / resetDecompression so the two contexts are not reset accidentally together.

Returns

void

---

resetCompression()

resetCompression(compressionLevel?): void

Resets compression state and optionally sets the compression level.

Parameters

compressionLevel?

number

When omitted, the current level is kept.

Returns

void

---

resetDecompression()

resetDecompression(): void

Resets decompression state before a new streaming decode.

Returns

void

---

setCompressionLevel()

setCompressionLevel(level): void

Sets the compression level for streaming compression.

Parameters

level

number

Compression level (use minCLevel() to maxCLevel())

Returns

void

---

compress()

compress(data, compressionLevel?): Uint8Array

Parameters

data

Uint8Array

Data to be compressed

compressionLevel?

number = ...

Compression v Speed tradeoff, when omitted it will default to zstd.defaultCLevel() which is currently 3.

Returns

Uint8Array

Compressed data.

TIP

A note on compressionLevel: The library supports regular compression levels from 1 up o 22. Levels >= 20, should be used with caution, as they require more memory. The library also offers negative compression levels, which extend the range of speed vs. ratio preferences. The lower the level, the faster the speed (at the cost of compression).

---

compressChunk()

compressChunk(data): Uint8Array

Compresses a chunk of data in streaming mode. Call resetCompression before the first chunk, then compressChunk for each chunk, and finally compressEnd. Intermediate calls may return an empty array when Zstandard buffers input.

Parameters

data

Uint8Array

Chunk of data to be compressed

Returns

Uint8Array

Compressed chunk data produced for this input (may be empty)

---

compressEnd()

compressEnd(): Uint8Array

Finishes the streaming compression and returns any remaining compressed data.

Returns

Uint8Array

Final compressed data

---

decompress()

decompress(compressedData): Uint8Array

Parameters

compressedData

Uint8Array

Data to be decompressed

Returns

Uint8Array

Uncompressed data.

---

decompressChunk()

decompressChunk(compressedData): Uint8Array

Decompresses a chunk of data in streaming mode. Call resetDecompression before the first chunk, then decompressChunk for each chunk, and finally decompressEnd. Intermediate calls may return an empty array. Callers must not guess an output size.

Parameters

compressedData

Uint8Array

Chunk of compressed data

Returns

Uint8Array

Decompressed chunk data produced for this input (may be empty)

---

decompressEnd()

decompressEnd(): void

Verifies that streaming decompression completed a full frame and was not truncated. Empty intermediate output is not treated as completion; call this after the final chunk.

Returns

void

---

defaultCLevel()

defaultCLevel(): number

Returns

number

Default compression level (see notes above above).

---

minCLevel()

minCLevel(): number

Returns

number

---

maxCLevel()

maxCLevel(): number

Returns

number