From 35f2f0251f0c5d56286f141551794731791bf2ec Mon Sep 17 00:00:00 2001 From: Vitaly Puzrin Date: Mon, 14 Sep 2015 15:21:23 +0300 Subject: [PATCH] Recreated docs --- .nojekyll | 0 index.html | 1639 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1639 insertions(+) create mode 100644 .nojekyll create mode 100644 index.html diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/index.html b/index.html new file mode 100644 index 0000000..90aa3e9 --- /dev/null +++ b/index.html @@ -0,0 +1,1639 @@ +pako 0.2.8 API documentation
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

+
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.

+
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.

+
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.

+
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.

+
\ No newline at end of file