# zstd-codec

> Zstandard codec powered by Emscripten

Latest version **0.1.5** (published 2024-07-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install zstd-codec
pnpm add zstd-codec
yarn add zstd-codec
bun add zstd-codec
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2024-07-27 |
| First published | 2017-12-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 208 |
| Author | yoshihitoh |
| Maintainers | yoshihitoh |

## Links

- npm: https://www.npmjs.com/package/zstd-codec
- Repository: https://github.com/yoshihitoh/zstd-codec
- Homepage: https://github.com/yoshihitoh/zstd-codec#readme
- Issues: https://github.com/yoshihitoh/zstd-codec/issues
- npm.io page: https://npm.io/package/zstd-codec

## Recent versions

- 0.1.5 (latest) — 2024-07-27
- 0.1.4 — 2022-01-28
- 0.1.3 — 2022-01-27
- 0.1.2 — 2019-12-23
- 0.1.1 — 2018-10-08
- 0.1.0 — 2018-10-08
- 0.0.9 — 2018-03-27
- 0.0.8 — 2018-03-11
- 0.0.7 — 2018-01-29
- 0.0.6 — 2018-01-22
- 0.0.5 — 2018-01-21
- 0.0.4 — 2018-01-03
- 0.0.3 — 2017-12-31
- 0.0.2 — 2017-12-31
- 0.0.1 — 2017-12-31

## README

# zstd-codec
[Zstandard](http://facebook.github.io/zstd/) codec for Node.js and Web, powered by Emscripten.

## Languages
- [English](README.md)

## Description
zstd-codec is a binding of [Zstandard](http://facebook.github.io/zstd/) for Node.js and Browsers,
includes JavaScript port of [Zstandard](http://facebook.github.io/zstd/) compiled with [Emscripten](http://kripken.github.io/emscripten-site/index.html).

## Installation
npm
```bash
npm install zstd-codec
```

yarn
```bash
yarn add zstd-codec
```

## Usage

require module, and instantiate api objects.

```javascript
const ZstdCodec = require('zstd-codec').ZstdCodec;
ZstdCodec.run(zstd => {
    const simple = new zstd.Simple();
    const streaming = new zstd.Streaming();
});
```

- Use Simple API for small data
- Use Streaming API for large data

### Simple API
- Using Zstandard's Simple API
    - `ZSTD_compress` for compress
    - `ZSTD_decompress` for decompress
- Store whole input/output bytes into Emscripten's heap
    - Available Emscripten's heap size is 16MiB
    - (input.length + output.length) should be less than 12MiB

#### compress(content_bytes, compression_level)
- `content_bytes`:  data to compress, must be `Uint8Array`.
- `compression_level`: (optional) compression level, default value is `3`

```javascript
// prepare data to compress
const data = ...;

// compress
const level = 5;
const compressed = simple.compress(data, level);

// handle compressed data
do_something(compressed);
```

#### decompress(compressed_bytes)
- `compressed_bytes`: data to decompress, must be `Uint8Array`.

```javascript
// prepare compressed data
const compressed = ...;

// decompress
const data = simple.decompress(compressed);

// handle decompressed data
do_something(data);
```

### Streaming APIs
- Using Zstandard's Streaming API
    - `ZSTD_xxxxCStream` APIs for compress
    - `ZSTD_xxxxDStream` APIs for decompress
- Store partial input/output bytes into Emscripten's heap

```javascript
const streaming = new ZstdCodec.Streaming();
```

You can use custom `Iterable` object on `compressChunks` / `decompressChunks`.

#### compress(content_bytes, compression_level)
- `content_bytes`: data to compress, must be 'Uint8Array'
- `compression_level`: (optional) compression level, default value is `3`

```javascript
const compressed = streaming.compress(data); // use default compression_level 3
```

#### compressChunks(chunks, size_hint, compression_level)
- `chunks`: data chunks to compress, must be `Iterable` of `Uint8Array`
- `size_hint`: (optional) size hint to store compressed data (to improve performance)
- `compression_level`: (optional) compression level, default value is `3`

```javascript
const chunks = [dataPart1, dataPart2, dataPart3, ...];
const size_hint = chunks.map((ar) => ar.length).reduce((p, c) => p + c);
const compressed = streaming.compressChunks(chunks, size_hint); // use default compression_level 3
```


#### decompress(compressed_bytes, size_hint)
- `compressed_bytes`: data to decompress, must be `Uint8Array`.
- `size_hint`: (optional) size hint to store decompressed data (to improve performance)

```javascript
const data = streaming.decompress(data); // can omit size_hint
```

#### decompressChunks(chunks, size_hint)
- `chunks`: data chunks to compress, must be `Iterable` of `Uint8Array`
- `size_hint`: (optional) size hint to store compressed data (to improve performance)

```javascript
const chunks = [dataPart1, dataPart2, dataPart3, ...];
const size_hint = 2 * 1024 * 1024; // 2MiB
const data = streaming.decompressChunks(chunks, size_hint);
```

### Dictionary API

```javascript
const ZstdCodec = require('zstd-codec').ZstdCodec;
ZstdCodec.run(zstd => {
    const simple = new zstd.Simple();

    // compress using trained dictionary
    const cdict = new zstd.Dict.Compression(dict_bytes, compression_level);
    const compressed = simple.compressUsingDict(data, cdict);

    // decompress using trained dictionary
    const ddict = new zstd.Dict.Decompression(dict_bytes);
    const data = simple.decompressUsingDict(compressed, ddict);
});

```

## Migrate from `v0.0.x` to `v0.1.x`

### API changed
please use callback style module instantiation.

```javascript
// v0.0.x
const zstd = require('zstd-codec').ZstdCodec;
const simple = new zstd.Simple();

// v0.1.x
const ZstdCodec = require('zstd-codec').ZstdCodec;
ZstdCodec.run(zstd => {
    const simple = new zstd.Simple();
});
```

NOTE: I wanted to use `Promise` instead of callback, but does not work :(
Need to survey why promise does not work, but it will take a lot of times.

### Class name changed

- ZstdCompressionDict => zsdt.Dict.Compression
- ZstdDecompressionDict => zsdt.Dict.Decompression

## Example

### Browser
See the [document](https://github.com/yoshihitoh/zstd-codec/blob/develop/js/example/README.md).

### Node.js
TODO: add an example for Node.js.

## TODO
- add CI (Travis CI or Circle CI?)
- improve APIs
- write  this document
- add how to build zstd with Emsxcripten
- add how to test
- performance test
- add more tests

---
_Source: https://npm.io/package/zstd-codec · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._