Typescript Encoder and Decoder for Heatshrink


$3

Forked from iotile/heatshrink-ts

Thank you @Tim Burke

Heatshrink is a compression library that can be used in very low resource microcontroller devices. It is based on LZSS encoding, which
looks for repeated strings of characters and replaces them with references to a previous occurence rather than repeating them.

You can read more details at the repository for the original C implementation of heatshrink.

~~This typescript package only implements the heatshrink decoding process so it can decode compressed data that it receives from
a device using the heatshrink library. It is written in typescript and distributed on NPM for easy installation and usage.~~

Now there is encoder too.

$3

``shell
npm install heatshrink-compression-ts
`
`typescript
import { HeatshrinkDecoder } from "heatshrink-compression-ts";
import { HeatshrinkEncoder } from "heatshrink-compression-ts";

const WINDOW_BITS = 8;
const LOOKAHEAD_BITS = 4;
const INPUT_BUFFER_LENGTH = 64;

const txt = new TextEncoder().encode('test test');
let encodedInput = new HeatshrinkEncoder(WINDOW_BITS, LOOKAHEAD_BITS).compress(txt);

let decoder = new HeatshrinkDecoder(WINDOW_BITS, LOOKAHEAD_BITS, INPUT_BUFFER_LENGTH);
decoder.process(encodedInput);

let output = decoder.getOutput();

let outputString = new TextDecoder().decode(output);
console.log("Decoded output: " + outputString);
``

There are 2 key parameters that need to match between the encoder and decoder:

- The window size (WINDOW_BITS), which is a number between 4 and 15, inclusive
that sets how large of a sliding window is used to look for repeated strings.
It is internally considered as a power of 2, so the value 8 would be 2**8 or
256 bytes for the sliding window.

- The lookahead size (LOOKAHEAD_BITS), which is a number between 2 and 15, always
strictly smaller than the window size. This sets how long of a repeated pattern
the encoder can see and therefore compress. According to the heatshrink
documentation, a good size is WINDOW_BITS / 2.

Important: Neither of these two parameters are transferred with heatshrink compressed
data but they are required to decode it properly. You must magically know the
right values for the encoder that was used to produce your encoded data or the
decoding process will not produce the correct output.

The input buffer length can be whatever you want but a larger input buffer is
a little more time efficient. 64 bytes is a reasonable value. This parameter
will probably go away in the future since it is not so meaningful in a
non-embedded context.

$3

- See example usage run
immediately on Runkit.

- Try out the libary yourself on Runkit.

$3

API Documentation can be found at: https://iotile.github.io/heatshrink-ts/