|
| 1 | +# Z'PIPE! |
| 2 | + |
| 3 | +zpipe is **not** a pipe. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +>The famous pipe. How people reproached me for it! And yet, could you stuff my pipe? No, it's just a representation, is it not? So if I had written on my picture "This is a pipe," I'd have been lying! |
| 8 | +
|
| 9 | +## About |
| 10 | + |
| 11 | +zpipe exposes an interface to the [DEFLATE](http://www.ietf.org/rfc/rfc1951.txt) algorithm of the [ZLib](http://zlib.net/) compression library, it has been cross-compiled to JavaScript with [Emscripten](https://github.com/kripken/emscripten). |
| 12 | + |
| 13 | +## Motivation |
| 14 | + |
| 15 | +* Currently no compression API exposed in browsers |
| 16 | +* Help users suffering from poor upload bandwidth |
| 17 | + |
| 18 | +## Usage |
| 19 | + |
| 20 | +Regular `<script>` include ... |
| 21 | + |
| 22 | +``` html |
| 23 | +<script type="text/javascript" src="zpipe.min.js"></script> |
| 24 | + |
| 25 | +<script> |
| 26 | + var deflated = zpipe.deflate("the balloon"); |
| 27 | +
|
| 28 | + var inflated = zpipe.inflate(deflated); // "the balloon" |
| 29 | +</script> |
| 30 | +``` |
| 31 | + |
| 32 | +With require() ... |
| 33 | + |
| 34 | +``` js |
| 35 | +var zpipe = require("zpipe"); |
| 36 | + |
| 37 | +var deflated = zpipe.deflate("the balloon"); |
| 38 | + |
| 39 | +var inflated = zpipe.inflate(deflated); // "the balloon" |
| 40 | +``` |
| 41 | +## Browser support |
| 42 | + |
| 43 | +zpipe is supported in the following browsers: |
| 44 | + |
| 45 | +* Internet Explorer 7+ (**Note**: Use [zpipe-native](https://github.com/richardassar/zpipe-native/)) |
| 46 | +* Google Chrome |
| 47 | +* Mozilla Firefox |
| 48 | +* Opera |
| 49 | +* Safari |
| 50 | + |
| 51 | +## Installation |
| 52 | + |
| 53 | +Install the package with **npm** |
| 54 | + |
| 55 | + $ npm install zpipe |
| 56 | + |
| 57 | +and bundle it with **Browserify**. |
| 58 | + |
| 59 | + $ browserify example.js -o bundle.js |
| 60 | + |
| 61 | +Alternatively just add it to your **Ender** bundle. |
| 62 | + |
| 63 | + $ ender add zpipe |
| 64 | + |
| 65 | +## But it's so big! |
| 66 | + |
| 67 | +Ok 201 KB for `zpipe.min.js` is big, however it comes in at **57.6 KB** gzipped. This is acceptable. |
| 68 | + |
| 69 | +## Tests |
| 70 | + |
| 71 | +Test against node zlib bindings: |
| 72 | + |
| 73 | + $ make test |
| 74 | + |
| 75 | +Run the test in the browser by pointing your browser to `test/test.html` and `test/test-native.html`. |
| 76 | + |
| 77 | +## Character encoding |
| 78 | + |
| 79 | +zpipe operates on octet strings only, multi-byte characters will have their high byte masked. If you want to handle multi-byte characters then you must convert your strings to UTF-8 prior to calling `deflate()` and then convert them back after calling `inflate()` |
| 80 | + |
| 81 | +You could use [utf8](https://github.com/ryanmcgrath/node-utf8) or [jshashes](https://github.com/h2non/jsHashes)' `Helpers.utf8Encode()` function for this, for example. |
| 82 | + |
| 83 | +## TODO |
| 84 | + |
| 85 | +* Support stream compression through workers |
| 86 | +* Benchmarks |
0 commit comments