Fork me on GitHub

pako - zlib port to javascript, very fast!

Build Status NPM version

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:

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

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

Class properties

Instance methods

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

Class properties

Instance methods

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.