# lz4-asm

> A JavaScript binding of LZ4 for the browser.

Latest version **0.4.2** (published 2020-06-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install lz4-asm
pnpm add lz4-asm
yarn add lz4-asm
bun add lz4-asm
```

Provides the command `lz4-asm`.

## 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.4.2 |
| Published | 2020-06-14 |
| First published | 2015-12-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 561.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ukyo |
| Maintainers | ukyo |
| Keywords | lz4 |

## Links

- npm: https://www.npmjs.com/package/lz4-asm
- npm.io page: https://npm.io/package/lz4-asm

## Dependencies (1)

- [yargs](https://npm.io/package/yargs.md) ^3.32.0

## Recent versions

- 0.4.2 (latest) — 2020-06-14
- 0.4.0 — 2020-06-14
- 0.3.3 — 2016-02-15
- 0.3.2 — 2016-02-08
- 0.3.1 — 2016-02-02
- 0.3.0 — 2016-02-02
- 0.2.0 — 2015-12-14

## README

# lz4.js

LZ4 WASM, ASM.js and CLI for browser and Node with almost native performance.
This package includes WASM, ASM.js module and variant that can be used in CLI.

## Install and Use

html

```html
<script src="node_modules/lz4/dist/lz4wasm.js"></script>

OR

<script src="node_modules/lz4/dist/lz4asm.js"></script>

```

### npm

```
npm install lz4-asm
```

### npm global

```
npm install lz4-asm -g
lz4-asm -h
```

### WASM Module modes

### Asynchronouse module mode ( default )

By default module will be exposed as UMD module. In browsers will be defined as `window.lz4init`
Since WASM modules can't be easily loaded synchronously in browsers some setup for initialization have to be proceed:
- `lz4init()` call will trigger asyncronous loading of `.wasm` file and return instance of lz4module
- `lz4module` accessible right after lz4init call, but the only safe method to ensure that `.wasm` file loading finished - wait for lz4module.ready Promise
- `lz4module.ready` Promise will return fully loaded lz4module instance that can be named `lz4`
- From usage perspective not really useful to work directly with `wasm` module, there is predefined `lz4.lz4js` property that contains all useful methods and helpers.

In short all this flow can be described with next code example:
```javascript
  const lz4module = lz4init();
  lz4module.ready.then((lz4) => {
    const lz4js = lz4.lz4js;
  })
```

Or even shorter with async/await and Object destructuring
```javascript
  const { lz4js } = await lz4init().ready;
```

### Synchronouse module mode

First of all to compile sources in synchronous module mode - set `-s WASM_ASYNC_COMPILATION=0` option in `gulp/emscripten.js` file for `DEV_ARGS` variable.

Then in node env it can be accessed easily `const lz4 = lz4init();` that's it.
BUT! There is a big issue in browsers because WASM modules are restricted for synchronous load in  main thread.
There are two ways to load it, both require to pass argument into init function `lz4init({ wasmBinary: wasmModuleAsArrayBuffer });` where wasmModuleAsArrayBuffer - preloaded file as ArrayBuffer in Uint8Array view representation:
1. Manually load/preload module through XHR/fetch, etc. then transform to arrayBuffer and call 
```javascript
fetch('PATH_TO_WASM_FILE')
  .then(response => response.arrayBuffer())
  .then(wasmModuleAsArrayBuffer => lz4init({ wasmBinary: wasmModuleAsArrayBuffer }))
  .catch(err => {
    throw new Error('Failed to load WASM module');
  })
```
1. Another variant - to encode `.wasm` module as base64, include in bundle, on runtime decode base64 to arrayBuffer and init
```javascript
function _base64ToArrayBuffer(base64) {
    const binary_string = window.atob(base64);
    const binary_length = binary_string.length;
    const bytes = new Uint8Array(binary_length);
    for (var i = 0; i < binary_length; i++) {
        bytes[i] = binary_string.charCodeAt(i);
    }
    return bytes.buffer;
}

const wasmModuleAsArrayBuffer = _base64ToArrayBuffer(wasmAsBase64);
const lz4 = lz4init({ wasmBinary: wasmModuleAsArrayBuffer });
```

### ASM.js Module modes

Both `async` (default) and `sync` modes available for ASM.js module but with one important difference.
For `sync` variant there **NO NEED for any extra setup**. Set `-s WASM_ASYNC_COMPILATION=0` option in `gulp/emscripten.js` and simply use as:
```javascript
const lz4 = lz4init();
```

It is much easier operate with ASM.js variant is sync mode, but for some cases it operate slower than WASM variant. You can see difference in tests if target different variants in top `require` statement.

## API

### static values

- `lz4.BLOCK_MAX_SIZE['64KB']`
- `lz4.BLOCK_MAX_SIZE['256KB']`
- `lz4.BLOCK_MAX_SIZE['1MB']`
- `lz4.BLOCK_MAX_SIZE['4MB']`

### lz4.compress(source, options)

compress to a lz4 buffer.

- source `Uint8Array | Buffer`
- options
  - frameInfo
    - blockSizeID: `Number [4-7]` or as alias `lz4.BLOCK_MAX_SIZE["4MB"]`. Available sizes: `{ "64KB": 4, "256KB": 5, "1MB": 6, "4MB" 7 }`
    - blockMode: `Number [0-1]. Default: 0`, 0: blocks linked, 1: blocks independent
    - contentChecksumFlag: `Number [0-1]. Default: 0`, 0: Checksum not available. 1: frame terminated with 32-bit checksum of decompressed data
    - dictID: `Number [0-1]. Default: 0`, Dictionary ID, sent by compressor to help decoder select correct dictionary; 0: no dictID provided
    - blockChecksumFlag: `Number [0-1]. Default: 0`, 1: each block followed by a checksum of block's compressed data; 0: disabled
  - preferences
    - compressionLevel: `Number [0-16]. Default: 0`, 0: faster but low compression, 16: slower but best compression
    - autoFlush: `Number [0-1]. Default: 1`, 1: always flush, reduces usage of internal buffers. 0 - flush disabled
    - favorDecSpeed: `Number [0-1]. Default: 1`, 1: parser favors decompression speed vs compression ratio. Only works for high compression modes
- return `Uint8Array | Buffer`

More about options you can find at LZ4 frame description: https://github.com/lz4/lz4/blob/master/doc/lz4_Frame_format.md

### lz4.decompress(source)

decompress a lz4 buffer.

- source `Uint8Array | Buffer`
- return `Uint8Array | Buffer`

### lz4.createCompressStream(options)

create a nodejs transform stream.

- options
  - frameInfo
    - blockSizeID: `Number [4-7]` or as alias `lz4.BLOCK_MAX_SIZE["4MB"]`. Available sizes: `{ "64KB": 4, "256KB": 5, "1MB": 6, "4MB" 7 }`
    - blockMode: `Number [0-1]. Default: 0`, 0: blocks linked, 1: blocks independent
    - contentChecksumFlag: `Number [0-1]. Default: 0`, 0: Checksum not available. 1: frame terminated with 32-bit checksum of decompressed data
    - dictID: `Number [0-1]. Default: 0`, Dictionary ID, sent by compressor to help decoder select correct dictionary; 0: no dictID provided
    - blockChecksumFlag: `Number [0-1]. Default: 0`, 1: each block followed by a checksum of block's compressed data; 0: disabled
  - preferences
    - compressionLevel: `Number [0-16]. Default: 0`, 0: faster but low compression, 16: slower but best compression
    - autoFlush: `Number [0-1]. Default: 1`, 1: always flush, reduces usage of internal buffers. 0 - flush disabled
    - favorDecSpeed: `Number [0-1]. Default: 1`, 1: parser favors decompression speed vs compression ratio. Only works for high compression modes

More about options you can find at LZ4 frame description: https://github.com/lz4/lz4/blob/master/doc/lz4_Frame_format.md

### lz4.createDecompressStream()

create a nodejs transform stream.

## Development

### Require

- latest emscripten
- nodejs 10+

### Init

Clone the repo.

```
git clone https://github.com/ukyo/lz4.js.git
```

Install the dev dependencies.

```
cd path/to/lz4.js
npm install
```

Download the original LZ4 repo and compile for development.

```
npx gulp init
```

### Write code

Watch for code updates and run tests.

```
npx gulp watchDev
```

Run development tests

### Release

Release build.

```
npx gulp release
```

### List of available gulp commands
```
buildLib
cleanTest
cleanRelease
compileDev
compileAsmRelease
compileWasmRelease
concatDev
concatAsmRelease
concatWasmRelease
debugTests
fetchLib
rollup
runTests
watchDev

initTask
release
releaseAsm
releaseWasm
testDev
```

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