pako 0.2.8 API documentation

Fork me on GitHub

# pako - zlib port to javascript, very fast!

Why pako is cool:

- Almost as fast in modern JS engines as C implementation (see benchmarks).
- Works in browsers, you can browserify any separate component.
- Chunking support for big blobs.
- Results are binary equal to well known zlib (now v1.2.8 ported).

This project was done to understand how fast JS can be and is it necessary to develop native C modules for CPU-intensive tasks. Enjoy the result!

Famous projects, using pako:

- browserify (via browserify-zlib)
- JSZip
- mincer
- JS-Git and Tedit by @creatronix

Benchmarks:

    node v0.10.26, 1mb sample:

       deflate-dankogai x 4.73 ops/sec ±0.82% (15 runs sampled)
       deflate-gildas x 4.58 ops/sec ±2.33% (15 runs sampled)
       deflate-imaya x 3.22 ops/sec ±3.95% (12 runs sampled)
     ! deflate-pako x 6.99 ops/sec ±0.51% (21 runs sampled)
       deflate-pako-string x 5.89 ops/sec ±0.77% (18 runs sampled)
       deflate-pako-untyped x 4.39 ops/sec ±1.58% (14 runs sampled)
     * deflate-zlib x 14.71 ops/sec ±4.23% (59 runs sampled)
       inflate-dankogai x 32.16 ops/sec ±0.13% (56 runs sampled)
       inflate-imaya x 30.35 ops/sec ±0.92% (53 runs sampled)
     ! inflate-pako x 69.89 ops/sec ±1.46% (71 runs sampled)
       inflate-pako-string x 19.22 ops/sec ±1.86% (49 runs sampled)
       inflate-pako-untyped x 17.19 ops/sec ±0.85% (32 runs sampled)
     * inflate-zlib x 70.03 ops/sec ±1.64% (81 runs sampled)

    node v0.11.12, 1mb sample:

       deflate-dankogai x 5.60 ops/sec ±0.49% (17 runs sampled)
       deflate-gildas x 5.06 ops/sec ±6.00% (16 runs sampled)
       deflate-imaya x 3.52 ops/sec ±3.71% (13 runs sampled)
     ! deflate-pako x 11.52 ops/sec ±0.22% (32 runs sampled)
       deflate-pako-string x 9.53 ops/sec ±1.12% (27 runs sampled)
       deflate-pako-untyped x 5.44 ops/sec ±0.72% (17 runs sampled)
     * deflate-zlib x 14.05 ops/sec ±3.34% (63 runs sampled)
       inflate-dankogai x 42.19 ops/sec ±0.09% (56 runs sampled)
       inflate-imaya x 79.68 ops/sec ±1.07% (68 runs sampled)
     ! inflate-pako x 97.52 ops/sec ±0.83% (80 runs sampled)
       inflate-pako-string x 45.19 ops/sec ±1.69% (57 runs sampled)
       inflate-pako-untyped x 24.35 ops/sec ±2.59% (40 runs sampled)
     * inflate-zlib x 60.32 ops/sec ±1.36% (69 runs sampled)

zlib's test is partialy afferted by marshling (that make sense for inflate only). You can change deflate level to 0 in benchmark source, to investigate details. For deflate level 6 results can be considered as correct.

Install:

node.js:

    npm install pako

browser:

    bower install pako

## Example & API

Full docs - http://nodeca.github.io/pako/

    var pako = require('pako');

    // Deflate
    //
    var input = new Uint8Array();
    //... fill input data here
    var output = pako.deflate(input);

    // Inflate (simple wrapper can throw exception on broken stream)
    //
    var compressed = new Uint8Array();
    //... fill data to uncompress here
    try {
      var result = pako.inflate(compressed);
    } catch (err) {
      console.log(err);
    }

    //
    // Alternate interface for chunking & without exceptions
    //

    var inflator = new pako.Inflate();

    inflator.push(chunk1, false);
    inflator.push(chunk2, false);
    ...
    inflator.push(chunkN, true); // true -> last chunk

    if (inflator.err) {
      console.log(inflator.msg);
    }

    var output = inflator.result;

Sometime you can wish to work with strings. For example, to send big objects as json to server. Pako detects input data type. You can force output to be string with option `{ to: 'string' }`.

    var pako = require('pako');

    var test = { my: 'super', puper: [456, 567], awesome: 'pako' };

    var binaryString = pako.deflate(JSON.stringify(test), { to: 'string' });

    //
    // Here you can do base64 encode, make xhr requests and so on.
    //

    var restored = JSON.parse(pako.inflate(binaryString, { to: 'string' }));

## Notes

Pako does not contain some specific zlib functions:

- deflate - methods `deflateCopy`, `deflateBound`, `deflateParams`, `deflatePending`, `deflatePrime`, `deflateSetDictionary`, `deflateTune`.
- inflate - `inflateGetDictionary`, `inflateCopy`, `inflateMark`, `inflatePrime`, `inflateSetDictionary`, `inflateSync`, `inflateSyncPoint`, `inflateUndermine`.

## Authors

- Andrey Tupitsin @anrd83
- Vitaly Puzrin @puzrin

Personal thanks to:

- Vyacheslav Egorov (@mraleph) for his awesome tutoruals about optimising JS code for v8, IRHydra tool and his advices.
- David Duponchel (@dduponchel) for help with testing.

## License

MIT

class

## Deflate

View source

### Description

Generic JS-style wrapper for zlib calls. If you don't need streaming behaviour - use more simple functions: deflate, deflateRaw and gzip.

### Constructor

- new Deflate

### Class properties

- err
- msg
- result

### Instance methods

- onData
- onEnd
- push

constructor

## Deflate.new

View source

- - new Deflate(options)

- - options
  - - Object

  - zlib deflate options.

Creates new deflator instance with specified params. Throws exception on bad params. Supported options:

- `level`
- `windowBits`
- `memLevel`
- `strategy`

http://zlib.net/manual.html#Advanced for more information on these.

Additional options, for internal needs:

- `chunkSize` - size of generated data chunks (16K by default)
- `raw` (Boolean) - do raw deflate
- `gzip` (Boolean) - create gzip wrapper
- `to` (String) - if equal to 'string', then result will be "binary string" (each char code [0..255])
- `header` (Object) - custom header for gzip
  - `text` (Boolean) - true if compressed data believed to be text
  - `time` (Number) - modification time, unix timestamp
  - `os` (Number) - operation system code
  - `extra` (Array) - array of bytes with extra data (max 65536)
  - `name` (String) - file name (binary string)
  - `comment` (String) - comment (binary string)
  - `hcrc` (Boolean) - true if header crc should be added

##### Example:

    var pako = require('pako')
      , chunk1 = Uint8Array([1,2,3,4,5,6,7,8,9])
      , chunk2 = Uint8Array([10,11,12,13,14,15,16,17,18,19]);

    var deflate = new pako.Deflate({ level: 3});

    deflate.push(chunk1, false);
    deflate.push(chunk2, true);  // true -> last chunk

    if (deflate.err) { throw new Error(deflate.err); }

    console.log(deflate.result);

class property

## Deflate.err

View source

- - Deflate.err
  - - Number

Error code after deflate finished. 0 (Z_OK) on success. You will not need it in real life, because deflate errors are possible only on wrong options or bad `onData` / `onEnd` custom handlers.

class property

## Deflate.msg

View source

- - Deflate.msg
  - - String

Error message, if Deflate.err != 0

class property

## Deflate.result

View source

- - Deflate.result
  - - Uint8Array
    - Array

Compressed result, generated by default Deflate#onData and Deflate#onEnd handlers. Filled after you push last chunk (call Deflate#push with `Z_FINISH` / `true` param) or if you push a chunk with explicit flush (call Deflate#push with `Z_SYNC_FLUSH` param).

instance method

## Deflate#onData

View source

- - Deflate#onData(chunk)
  - - Void

- - chunk
  - - Uint8Array
    - Array
    - String

  - ouput data. Type of array depends on js engine support. When string output requested, each chunk will be string.

By default, stores data blocks in `chunks[]` property and glue those in `onEnd`. Override this handler, if you need another behaviour.

instance method

## Deflate#onEnd

View source

- - Deflate#onEnd(status)
  - - Void

- - status
  - - Number

  - deflate status. 0 (Z_OK) on success, other if not.

Called once after you tell deflate that the input stream is complete (Z_FINISH) or should be flushed (Z_SYNC_FLUSH) or if an error happened. By default - join collected chunks, free memory and fill `results` / `err` properties.

instance method

## Deflate#push

View source

- - Deflate#push(data[, mode])
  - - Boolean

- - data
  - - Uint8Array
    - Array
    - ArrayBuffer
    - String

  - input data. Strings will be converted to utf8 byte sequence.

- - mode
  - - Number
    - Boolean

  - 0..6 for corresponding Z_NO_FLUSH..Z_TREE modes. See constants. Skipped or `false` means Z_NO_FLUSH, `true` meansh Z_FINISH.

Sends input data to deflate pipe, generating Deflate#onData calls with new compressed chunks. Returns `true` on success. The last data block must have mode Z_FINISH (or `true`). That will flush internal pending buffers and call Deflate#onEnd. For interim explicit flushes (without ending the stream) you can use mode Z_SYNC_FLUSH, keeping the compression context.

On fail call Deflate#onEnd with error code and return false.

We strongly recommend to use `Uint8Array` on input for best speed (output array format is detected automatically). Also, don't skip last param and always use the same type in your code (boolean or number). That will improve JS speed.

For regular `Array`-s make sure all elements are [0..255].

##### Example

    push(chunk, false); // push one of data chunks
    ...
    push(chunk, true);  // push last chunk

method

## deflate

View source

- - deflate(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to compress.

- - options
  - - Object

  - zlib deflate options.

Compress `data` with deflate alrorythm and `options`.

Supported options are:

- level
- windowBits
- memLevel
- strategy

http://zlib.net/manual.html#Advanced for more information on these.

Sugar (options):

- `raw` (Boolean) - say that we work with raw stream, if you don't wish to specify negative windowBits implicitly.
- `to` (String) - if equal to 'string', then result will be "binary string" (each char code [0..255])

##### Example:

    var pako = require('pako')
      , data = Uint8Array([1,2,3,4,5,6,7,8,9]);

    console.log(pako.deflate(data));

method

## deflateRaw

View source

- - deflateRaw(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to compress.

- - options
  - - Object

  - zlib deflate options.

The same as deflate, but creates raw data, without wrapper (header and adler32 crc).

method

## gzip

View source

- - gzip(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to compress.

- - options
  - - Object

  - zlib deflate options.

The same as deflate, but create gzip wrapper instead of deflate one.

class

## Inflate

View source

### Description

Generic JS-style wrapper for zlib calls. If you don't need streaming behaviour - use more simple functions: inflate and inflateRaw.

### Constructor

- new Inflate

### Class properties

- err
- msg
- result

### Instance methods

- onData
- onEnd
- push

constructor

## Inflate.new

View source

- - new Inflate(options)

- - options
  - - Object

  - zlib inflate options.

Creates new inflator instance with specified params. Throws exception on bad params. Supported options:

- `windowBits`

http://zlib.net/manual.html#Advanced for more information on these.

Additional options, for internal needs:

- `chunkSize` - size of generated data chunks (16K by default)
- `raw` (Boolean) - do raw inflate
- `to` (String) - if equal to 'string', then result will be converted from utf8 to utf16 (javascript) string. When string output requested, chunk length can differ from `chunkSize`, depending on content.

By default, when no options set, autodetect deflate/gzip data format via wrapper header.

##### Example:

    var pako = require('pako')
      , chunk1 = Uint8Array([1,2,3,4,5,6,7,8,9])
      , chunk2 = Uint8Array([10,11,12,13,14,15,16,17,18,19]);

    var inflate = new pako.Inflate({ level: 3});

    inflate.push(chunk1, false);
    inflate.push(chunk2, true);  // true -> last chunk

    if (inflate.err) { throw new Error(inflate.err); }

    console.log(inflate.result);

class property

## Inflate.err

View source

- - Inflate.err
  - - Number

Error code after inflate finished. 0 (Z_OK) on success. Should be checked if broken data possible.

class property

## Inflate.msg

View source

- - Inflate.msg
  - - String

Error message, if Inflate.err != 0

class property

## Inflate.result

View source

- - Inflate.result
  - - Uint8Array
    - Array
    - String

Uncompressed result, generated by default Inflate#onData and Inflate#onEnd handlers. Filled after you push last chunk (call Inflate#push with `Z_FINISH` / `true` param) or if you push a chunk with explicit flush (call Inflate#push with `Z_SYNC_FLUSH` param).

instance method

## Inflate#onData

View source

- - Inflate#onData(chunk)
  - - Void

- - chunk
  - - Uint8Array
    - Array
    - String

  - ouput data. Type of array depends on js engine support. When string output requested, each chunk will be string.

By default, stores data blocks in `chunks[]` property and glue those in `onEnd`. Override this handler, if you need another behaviour.

instance method

## Inflate#onEnd

View source

- - Inflate#onEnd(status)
  - - Void

- - status
  - - Number

  - inflate status. 0 (Z_OK) on success, other if not.

Called either after you tell inflate that the input stream is complete (Z_FINISH) or should be flushed (Z_SYNC_FLUSH) or if an error happened. By default - join collected chunks, free memory and fill `results` / `err` properties.

instance method

## Inflate#push

View source

- - Inflate#push(data[, mode])
  - - Boolean

- - data
  - - Uint8Array
    - Array
    - ArrayBuffer
    - String

  - input data

- - mode
  - - Number
    - Boolean

  - 0..6 for corresponding Z_NO_FLUSH..Z_TREE modes. See constants. Skipped or `false` means Z_NO_FLUSH, `true` meansh Z_FINISH.

Sends input data to inflate pipe, generating Inflate#onData calls with new output chunks. Returns `true` on success. The last data block must have mode Z_FINISH (or `true`). That will flush internal pending buffers and call Inflate#onEnd. For interim explicit flushes (without ending the stream) you can use mode Z_SYNC_FLUSH, keeping the decompression context.

On fail call Inflate#onEnd with error code and return false.

We strongly recommend to use `Uint8Array` on input for best speed (output format is detected automatically). Also, don't skip last param and always use the same type in your code (boolean or number). That will improve JS speed.

For regular `Array`-s make sure all elements are [0..255].

##### Example

    push(chunk, false); // push one of data chunks
    ...
    push(chunk, true);  // push last chunk

method

## inflate

View source

- - inflate(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to decompress.

- - options
  - - Object

  - zlib inflate options.

Decompress `data` with inflate/ungzip and `options`. Autodetect format via wrapper header by default. That's why we don't provide separate `ungzip` method.

Supported options are:

- windowBits

http://zlib.net/manual.html#Advanced for more information.

Sugar (options):

- `raw` (Boolean) - say that we work with raw stream, if you don't wish to specify negative windowBits implicitly.
- `to` (String) - if equal to 'string', then result will be converted from utf8 to utf16 (javascript) string. When string output requested, chunk length can differ from `chunkSize`, depending on content.

##### Example:

    var pako = require('pako')
      , input = pako.deflate([1,2,3,4,5,6,7,8,9])
      , output;

    try {
      output = pako.inflate(input);
    } catch (err)
      console.log(err);
    }

method

## inflateRaw

View source

- - inflateRaw(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to decompress.

- - options
  - - Object

  - zlib inflate options.

The same as inflate, but creates raw data, without wrapper (header and adler32 crc).

method

## ungzip

View source

- - ungzip(data[, options])
  - - Uint8Array
    - Array
    - String

- - data
  - - Uint8Array
    - Array
    - String

  - input data to decompress.

- - options
  - - Object

  - zlib inflate options.

Just shortcut to inflate, because it autodetects format by header.content. Done for convenience.