Typescript Encoder and Decoder for Heatshrink

Introduction

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.

Installation and Basic Usage

npm install heatshrink-compression-ts

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.

Next Steps

• See example usage run immediately on Runkit.

• Try out the libary yourself on Runkit.

API Documentation

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