zlib.js ======= [![Build Status](https://travis-ci.org/imaya/zlib.js.png?branch=master)](https://travis-ci.org/imaya/zlib.js) [English version](./README.en.md) zlib.js は ZLIB(RFC1950), DEFLATE(RFC1951), GZIP(RFC1952), PKZIP の JavaScript 実装です。 使い方 ------ zlib.js は必要な機能ごとに分割されています。 bin ディレクトリから必要なものを利用してください。 - zlib_and_gzip.min.js: ZLIB + GZIP + (Raw) * rawdeflate.js: Raw Deflate * raw.js: Raw Inflate + zlib.min.js: ZLIB Inflate + Deflate * inflate.min.js: ZLIB Inflate * deflate.min.js: ZLIB Deflate * inflate_stream.min.js: ZLIB Inflate (stream mode) + (GZIP) * gzip.min.js: GZIP * gunzip.min.js: GUNZIP + (PKZIP) * zip.min.js ZIP * unzip.min.js UNZIP - node-zlib.js: (ZLIB + GZIP for node.js) ### 圧縮 (Compress) #### Raw Deflate ```js // plain = Array. or Uint8Array var deflate = new Zlib.RawDeflate(plain); var compressed = deflate.compress(); ``` #### Raw Deflate Option ZLIB Option を参照してください。 #### ZLIB ```js // plain = Array. or Uint8Array var deflate = new Zlib.Deflate(plain); var compressed = deflate.compress(); ``` ##### ZLIB Option Zlib.Deflate の第二引数にオブジェクトを渡す事で圧縮オプションを指定する事が出来ます。 ```js { compressionType: Zlib.Deflate.CompressionType, // 圧縮タイプ lazy: number // lazy matching の閾値 } ``` Zlib.Deflate.CompressionType は NONE(無圧縮), FIXED(固定ハフマン符号), DYNAMIC(動的ハフマン符号) から選択する事ができます。 default は DYNAMIC です。 lazy は Lazy Matching の閾値を指定します。 Lazy Matching とは、LZSS のマッチ長が閾値より低かった場合、次の Byte から LZSS の最長一致を試み、マッチ長の長い方を選択する手法です。 #### GZIP GZIP の実装は現在不完全ですが、ただの圧縮コンテナとして使用する場合には特に問題はありません。 zlib.js を用いて作成された GZIP の OS は、自動的に UNKNOWN に設定されます。 ```js // plain = Array. or Uint8Array var gzip = new Zlib.Gzip(plain); var compressed = gzip.compress(); ``` ##### GZIP Option ```js { deflateOptions: Object, // deflate option (ZLIB Option 参照) flags: { fname: boolean, // ファイル名を使用するか comment: boolean, // コメントを使用するか fhcrc: boolean // FHCRC を使用するか }, filename: string, // flags.fname が true のときに書き込むファイル名 comment: string // flags.comment が true のときに書き込むコメント } ``` #### PKZIP PKZIP では複数のファイルを扱うため、他のものとは少し使い方が異なります。 ```js var zip = new Zlib.Zip(); // plainData1 zip.addFile(plainData1, { filename: stringToByteArray('foo.txt') }); zip.addFile(plainData2, { filename: stringToByteArray('bar.txt') }); zip.addFile(plainData3, { filename: stringToByteArray('baz.txt') }); var compressed = zip.compress(); function stringToByteArray(str) { var array = new (window.Uint8Array !== void 0 ? Uint8Array : Array)(str.length); var i; var il; for (i = 0, il = str.length; i < il; ++i) { array[i] = str.charCodeAt(i) & 0xff; } return array; } ``` ##### PKZIP Option filename, comment, extraField は Typed Array が使用可能な場合は必ず Uint8Array を使用してください。 ```js { filename: (Array.|Uint8Array), // ファイル名 comment: (Array.|Uint8Array), // コメント extraField: (Array.|Uint8Array), // その他の領域 compress: boolean, // addFile メソッドを呼んだときに圧縮するか (通常は compress メソッドの呼び出し時に圧縮) compressionMethod: Zlib.Zip.CompressionMethod, // STORE or DEFLATE os: Zlib.Zip.OperatingSystem, // MSDOS or UNIX or MACINTOSH deflateOption: Object // see: ZLIB Option } ``` ### 伸張 (Decompress) 圧縮されたデータの伸張は、基本的に各コンストラクタに圧縮されたデータを渡し、 それの decompress メソッドを呼ぶ事で伸張処理を開始する事が出来ます。 #### Raw Deflate ```js // compressed = Array. or Uint8Array var inflate = new Zlib.RawInflate(compressed); var plain = inflate.decompress(); ``` #### Raw Deflate Option ZLIB Option を参照してください。 #### ZLIB ```js // compressed = Array. or Uint8Array var inflate = new Zlib.Inflate(compressed); var plain = inflate.decompress(); ``` ##### ZLIB Option Zlib.Inflate の第二引数にオブジェクトを渡す事で伸張オプションを指定する事ができます。 ```js { 'index': number, // 入力バッファの開始位置 'bufferSize': number, // 出力バッファの初期サイズ 'bufferType': Zlib.Inflate.BufferType, // バッファの管理方法 'resize': boolean, // 出力バッファのリサイズ 'verify': boolean // 伸張結果の検証を行うか } ``` Zlib.Inflate.BufferType は ADAPTIVE(default) か BLOCK を選択する事ができます。 - ADAPTIVE はバッファを伸張後のサイズを予測して一気に拡張しますが、データによっては余分にメモリを使用しすぎる事があります。 - BLOCK では BufferSize ずつ拡張していきますが、動作はあまり速くありません。 resize オプションは Typed Array 利用可能時 decompress メソッドで返却する値の ArrayBuffer を Uint8Array の長さまで縮小させます。 default は false です。 verify オプションは Adler-32 Checksum の検証を行うかを指定します。 default は false です。 #### GZIP ```js // compressed = Array. or Uint8Array var gunzip = new Zlib.Gunzip(compressed); var plain = gunzip.decompress(); ``` Gunzip のオプションは現在ありません。 #### PKZIP PKZIP の構築と同様に複数ファイルを扱うため、他のものとは少し使い方が異なります。 ```js // compressed = Array. or Uint8Array var unzip = new Zlib.Unzip(compressed); var filenames = unzip.getFilenames(); var plain = unzip.decompress(filenames[0]); ``` Unzip のオプションは現在ありません。 ### Node.js Node.js で使用する場合はユニットテストを参照してください。 ## Debug zlib.js では JavaScript ファイルを minify された形で提供していますが、開発中やデバッグ時に minify する前の状態が知りたい事があります。 そういった時のために SourceMaps ファイルや Pretty Print されたファイルも提供しています。 ### Source Map Source Map を使いたい場合はファイル名に `dev` のついたバージョンを使います。 例えば Source Map を有効にした Inflate を使いたい場合は以下になります。 - inflate.min.js // リリースバージョン - inflate.dev.min.js // 開発バージョン（これを使う） ### Pretty Print SourceMaps とは異なりますが、minify の変数名の短縮のみ避けられれば良いという場合には、 Closure Compiler で読みやすくしたファイルを利用することも可能です。 `zlib.pretty.js` というファイル名で全ての実装がはいっていますので、minify されたものをこのファイルに置き換えるだけで使用できます。 How to build ------------ ビルドは Grunt と Closure Compiler を使用して行います。 ### 必要な環境 - Grunt - Python ### ビルド Grunt を使ってビルドを行います。 ``` $ grunt [target] ``` #### ビルドターゲット target | ファイル名 | 含まれる実装 ---------------|-----------------------|------------- deps | deps.js | 依存関係の解決 deflate | deflate.min.js | ZLIB Deflate inflate | inflate.min.js | ZLIB Inflate inflate_stream | inlfate_stream.min.js | ZLIB Inlate (stream) zlib | zlib.min.js | ZLIB Deflate + Inflate gzip | gzip.min.js | GZIP Compression gunzip | gunzip.min.js | GZIP Decompression zlib_and_gzip | zlib_and_gzip.min.js | ZLIB + GZIP node | node-zlib.js | ZLIB + GZIP for node.js zip | zip.min.js | PKZIP Compression unzip | unzip.min.js | PKZIP Decompression all | * | default target テスト ------ ブラウザでは Karma, Node.js では mocha を使ってテストを行います。 ``` $ npm test ``` ### ブラウザのみのテスト ``` $ npm run test-karma ``` ### Node.js のみのテスト ``` $ npm run test-mocha ``` Issue ----- 現在プリセット辞書を用いた圧縮形式には対応していません。 プリセット辞書は通常の圧縮では利用されないため、影響は少ないと思います。 ライセンス ----------- Copyright © 2012 imaya. Licensed under the MIT License.