|
|
@@ -16,12 +16,8 @@ High performance (de)compression in an 8kB package
|
|
|
## Usage
|
|
|
|
|
|
Install `fflate`:
|
|
|
-```console
|
|
|
-npm install --save fflate
|
|
|
-```
|
|
|
-or
|
|
|
-```console
|
|
|
-yarn add fflate
|
|
|
+```sh
|
|
|
+npm install --save fflate # or yarn add fflate, or pnpm add fflate
|
|
|
```
|
|
|
|
|
|
Import:
|
|
|
@@ -31,7 +27,7 @@ import * as fflate from 'fflate';
|
|
|
// So, if you just need gzip support:
|
|
|
import { gzip, gunzip } from 'fflate';
|
|
|
```
|
|
|
-Or `require` (if your environment doesn't support ES Modules):
|
|
|
+If your environment doesn't support ES Modules (e.g. Node.js):
|
|
|
```js
|
|
|
const fflate = require('fflate');
|
|
|
```
|
|
|
@@ -39,14 +35,17 @@ const fflate = require('fflate');
|
|
|
And use:
|
|
|
```js
|
|
|
// This is an ArrayBuffer of data
|
|
|
-const massiveFileBuf = await fetch('/getAMassiveFile').then(
|
|
|
+const massiveFileBuf = await fetch('/aMassiveFile').then(
|
|
|
res => res.arrayBuffer()
|
|
|
);
|
|
|
// To use fflate, you need a Uint8Array
|
|
|
const massiveFile = new Uint8Array(massiveFileBuf);
|
|
|
-// Note that the Node.js Buffer works just fine as well:
|
|
|
+// Note that Node.js Buffers work just fine as well:
|
|
|
// const massiveFile = require('fs').readFileSync('aMassiveFile.txt');
|
|
|
|
|
|
+// Higher level means lower performance but better compression
|
|
|
+// The level ranges from 0 (no compression) to 9 (max compression)
|
|
|
+// The default level is 6
|
|
|
const notSoMassive = fflate.zlib(massiveFile, { level: 9 });
|
|
|
const massiveAgain = fflate.unzlib(notSoMassive);
|
|
|
```
|
|
|
@@ -55,7 +54,7 @@ const massiveAgain = fflate.unzlib(notSoMassive);
|
|
|
const compressed = new Uint8Array(
|
|
|
await fetch('/unknownFormatCompressedFile').then(res => res.arrayBuffer())
|
|
|
);
|
|
|
-// Again, Node.js buffers work too. For example, the above could instead be:
|
|
|
+// Again, Node.js Buffers work too. For example, the above could instead be:
|
|
|
// Buffer.from('H4sIAAAAAAAA//NIzcnJVyjPL8pJUQQAlRmFGwwAAAA=', 'base64');
|
|
|
|
|
|
const decompressed = fflate.decompress(compressed);
|
|
|
@@ -65,8 +64,10 @@ Using strings is easy with `TextEncoder` and `TextDecoder`:
|
|
|
```js
|
|
|
const enc = new TextEncoder(), dec = new TextDecoder();
|
|
|
const buf = enc.encode('Hello world!');
|
|
|
+
|
|
|
// The default compression method is gzip
|
|
|
-// See the docs for more info on the mem option
|
|
|
+// Increasing mem increases may increase performance at the cost of memory
|
|
|
+// The mem ranges from 0 to 12, where 4 is the default
|
|
|
const compressed = fflate.compress(buf, { level: 6, mem: 8 });
|
|
|
|
|
|
// When you need to decompress:
|
|
|
@@ -96,13 +97,11 @@ const decompressed = fflate.decompress(stringToCompressedData(compressedString))
|
|
|
See the [documentation](https://github.com/101arrowz/fflate/blob/master/docs/README.md) for more detailed information about the API.
|
|
|
|
|
|
## What makes `fflate` so fast?
|
|
|
-There are many reasons one might need a compression/decompression library; for example, if a user is uploading a massive file (say a 50 MB PDF) to your server, instead of uploading directly, it's usually faster to compress the file before uploading. Or if you want to generate a ZIP file to download to your user's computer, you also may need to compress it.
|
|
|
-
|
|
|
-For these reasons (and many more) many JavaScript compression/decompression libraries exist. However, the most popular one, [`pako`](https://npmjs.com/package/pako), is merely a clone of Zlib rewritten nearly line-for-line in JavaScript. Although it is by no means badly written, `pako` doesn't recognize the many differences between JavaScript and C, and therefore is suboptimal. Moreover, even when minified, the library is 40 kB; it may not seem like much, but for anyone concerned with optimizing bundle size (especially library authors), it's more weight than necessary.
|
|
|
+Many JavaScript compression/decompression libraries exist. However, the most popular one, [`pako`](https://npmjs.com/package/pako), is merely a clone of Zlib rewritten nearly line-for-line in JavaScript. Although it is by no means poorly made, `pako` doesn't recognize the many differences between JavaScript and C, and therefore is suboptimal for performance. Moreover, even when minified, the library is 45 kB; it may not seem like much, but for anyone concerned with optimizing bundle size (especially library authors), it's more weight than necessary.
|
|
|
|
|
|
Note that there exist some small libraries like [`tiny-inflate`](https://npmjs.com/package/tiny-inflate) for solely decompression, and with a minified size of 3 kB, it can be appealing; however, its performance is extremely lackluster, up to 100x slower than `pako` for some larger files in my tests.
|
|
|
|
|
|
-[`UZIP.js`](https://github.com/photopea/UZIP.js) is both faster (by up to 40%) and smaller (15 kB minified) than `pako`, and it contains a variety of innovations that make it excellent for both performance and compression ratio. However, the developer made a variety of tiny mistakes and inefficient design choices that make it imperfect. Moreover, it does not support GZIP or Zlib data directly; one must remove the headers manually to use `UZIP.js`.
|
|
|
+[`UZIP.js`](https://github.com/photopea/UZIP.js) is both faster (by up to 40%) and smaller (14 kB minified) than `pako`, and it contains a variety of innovations that make it excellent for both performance and compression ratio. However, the developer made a variety of tiny mistakes and inefficient design choices that make it imperfect. Moreover, it does not support GZIP or Zlib data directly; one must remove the headers manually to use `UZIP.js`.
|
|
|
|
|
|
So what makes `fflate` different? It takes the brilliant innovations of `UZIP.js` and optimizes them while adding direct support for GZIP and Zlib data. And unlike all of the above libraries, it uses ES Modules to allow for partial builds, meaning that it can rival even `tiny-inflate` in size while maintaining excellent performance. The end result is a library that, in total, weighs 8kB minified for the entire build (3kB for decompression only and 5kB for compression only), is about 15% faster than `UZIP.js` or up to 60% faster than `pako`, and achieves the same or better compression ratio than the rest.
|
|
|
|
Arjun Barrett