fflate

High performance (de)compression in an 8kB package

Why fflate?

fflate (short for fast flate) is the fastest, smallest, and most versatile pure JavaScript compression and decompression library in existence, handily beating pako, tiny-inflate, and UZIP.js in performance benchmarks while being multiple times more lightweight. Its compression ratios are often better than even the original Zlib C library. It includes support for DEFLATE, GZIP, and Zlib data. Data compressed by fflate can be decompressed by other tools, and vice versa.

In addition to the base decompression and compression APIs, fflate supports high-speed ZIP file archiving for an extra 3 kB. In fact, the compressor, in synchronous mode, compresses both more quickly and with a higher compression ratio than most compression software (even Info-ZIP, a C program), and in asynchronous mode it can utilize multiple threads to achieve over 3x the performance of virtually any other utility.

	pako	tiny-inflate	UZIP.js	fflate
Decompression performance	1x	Up to 40% slower	Up to 25% faster	Up to 25% faster
Compression performance	1x	N/A	Up to 25% faster	Up to 50% faster
Base bundle size (minified)	45.6kB	3kB (inflate only)	14.2kB	8kB (3kB for inflate only)
Decompression support	✅	✅	✅	✅
Compression support	✅	❌	✅	✅
ZIP support	❌	❌	✅	✅
Streaming support	✅	❌	❌	✅
GZIP support	✅	❌	❌	✅
Supports files up to 4GB	✅	❌	❌	✅
Doesn't hang on error	✅	❌	❌	✅
Dictionary support	✅	❌	❌	✅
Multi-thread/Asynchronous	❌	❌	❌	✅
Streaming ZIP support	❌	❌	❌	✅
Uses ES Modules	❌	❌	❌	✅

Demo

If you'd like to try fflate for yourself without installing it, you can take a look at the browser demo. Since fflate is a pure JavaScript library, it works in both the browser and Node.js (see Browser support for more info).

Usage

Install fflate:

npm i fflate # or yarn add fflate, or pnpm add fflate

Import:

// I will assume that you use the following for the rest of this guide
import * as fflate from 'fflate';

// However, you should import ONLY what you need to minimize bloat.
// So, if you just need GZIP compression support:
import { gzipSync } from 'fflate';
// Woo! You just saved 20 kB off your bundle with one line.

If your environment doesn't support ES Modules (e.g. Node.js):

// Try to avoid this when using fflate in the browser, as it will import
// all of fflate's components, even those that you aren't using.
const fflate = require('fflate');

If you want to load from a CDN in the browser:

<script src="https://unpkg.com/fflate@0.8.3"></script>
<script src="https://cdn.jsdelivr.net/npm/fflate@0.8.3/umd/index.js"></script>



<script type="module">
  import * as fflate from 'https://cdn.skypack.dev/fflate@0.8.3?min';
</script>

If you are using Deno:

// Don't use the ?dts Skypack flag; it isn't necessary for Deno support
// The @deno-types comment adds TypeScript typings

// @deno-types="https://cdn.skypack.dev/fflate@0.8.3/lib/index.d.ts"
import * as fflate from 'https://cdn.skypack.dev/fflate@0.8.3?min';

If your environment doesn't support bundling:

// Again, try to import just what you need

// For the browser:
import * as fflate from 'fflate/esm/browser.js';
// If the standard ESM import fails on Node (i.e. older version):
import * as fflate from 'fflate/esm';

And use:

// This is an ArrayBuffer of data
const massiveFileBuf = await fetch('/aMassiveFile').then(
  res => res.arrayBuffer()
);
// To use fflate, you need a Uint8Array
const massiveFile = new Uint8Array(massiveFileBuf);
// 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.zlibSync(massiveFile, { level: 9 });
const massiveAgain = fflate.unzlibSync(notSoMassive);
const gzipped = fflate.gzipSync(massiveFile, {
  // GZIP-specific: the filename to use when decompressed
  filename: 'aMassiveFile.txt',
  // GZIP-specific: the modification time. Can be a Date, date string,
  // or Unix timestamp
  mtime: '9/1/16 2:00 PM'
});

fflate can autodetect a compressed file's format as well:

const compressed = new Uint8Array(
  await fetch('/GZIPorZLIBorDEFLATE').then(res => res.arrayBuffer())
);
// Above example with Node.js Buffers:
// Buffer.from('H4sIAAAAAAAAE8tIzcnJBwCGphA2BQAAAA==', 'base64');

const decompressed = fflate.decompressSync(compressed);

Using strings is easy with fflate's string conversion API:

const buf = fflate.strToU8('Hello world!');

// The default compression method is gzip
// Increasing mem may increase performance at the cost of memory
// The mem ranges from 0 to 12, where 4 is the default
const compressed = fflate.compressSync(buf, { level: 6, mem: 8 });

// When you need to decompress:
const decompressed = fflate.decompressSync(compressed);
const origText = fflate.strFromU8(decompressed);
console.log(origText); // Hello world!

If you need to use an (albeit inefficient) binary string, you can set the second argument to true.

const buf = fflate.strToU8('Hello world!');

// The second argument, latin1, is a boolean that indicates that the data
// is not Unicode but rather should be encoded and decoded as Latin-1.
// This is useful for creating a string from binary data that isn't
// necessarily valid UTF-8. However, binary strings are incredibly
// inefficient and tend to double file size, so they're not recommended.
const compressedString = fflate.strFromU8(
  fflate.compressSync(buf),
  true
);
const decompressed = fflate.decompressSync(
  fflate.strToU8(compressedString, true)
);
const origText = fflate.strFromU8(decompressed);
console.log(origText); // Hello world!

You can use streams as well to incrementally add data to be compressed or decompressed:

// This example uses synchronous streams, but for the best experience
// you'll definitely want to use asynchronous streams.

let outStr = '';
const gzipStream = new fflate.Gzip({ level: 9 }, (chunk, isLast) => {
  // accumulate in an inefficient binary string (just an example)
  outStr += fflate.strFromU8(chunk, true);
});

// You can also attach the data handler separately if you don't want to
// do so in the constructor.
gzipStream.ondata = (chunk, final) => { ... }

// Since this is synchronous, all errors will be thrown by stream.push()
gzipStream.push(chunk1);
gzipStream.push(chunk2);

...

// You should mark the last chunk by using true in the second argument
// In addition to being necessary for the stream to work properly, this
// will also set the isLast parameter in the handler to true.
gzipStream.push(lastChunk, true);

console.log(outStr); // The compressed binary string is now available

// The options parameter for compression streams is optional; you can
// provide one parameter (the handler) or none at all if you set
// deflateStream.ondata later.
const deflateStream = new fflate.Deflate((chunk, final) => {
  console.log(chunk, final);
});

// If you want to create a stream from strings, use EncodeUTF8
const utfEncode = new fflate.EncodeUTF8((data, final) => {
  // Chaining streams together is done by pushing to the
  // next stream in the handler for the previous stream
  deflateStream.push(data, final);
});

utfEncode.push('Hello'.repeat(1000));
utfEncode.push(' '.repeat(100));
utfEncode.push('world!'.repeat(10), true);

// The deflateStream has logged the compressed data

const inflateStream = new fflate.Inflate();
inflateStream.ondata = (decompressedChunk, final) => { ... };

let stringData = '';

// Streaming UTF-8 decode is available too
const utfDecode = new fflate.DecodeUTF8((data, final) => {
  stringData += data;
});

// Decompress streams auto-detect the compression method, as the
// non-streaming decompress() method does.
const dcmpStrm = new fflate.Decompress((chunk, final) => {
  console.log(chunk, 'was encoded with GZIP, Zlib, or DEFLATE');
  utfDecode.push(chunk, final);
});

dcmpStrm.push(zlibJSONData1);
dcmpStrm.push(zlibJSONData2, true);

// This succeeds; the UTF-8 decoder chained with the unknown compression format
// stream to reach a string as a sink.
console.log(JSON.parse(stringData));

You can create multi-file ZIP archives easily as well. Note that by default, compression is enabled for all files, which is not useful when ZIPping many PNGs, JPEGs, PDFs, etc. because those formats are already compressed. You should either override the level on a per-file basis or globally to avoid wasting resources.

// Note that the asynchronous version (see below) runs in parallel and
// is *much* (up to 3x) faster for larger archives.
const zipped = fflate.zipSync({
  // Directories can be nested structures, as in an actual filesystem
  'dir1': {
    'nested': {
      // You can use Unicode in filenames
      '你好.txt': fflate.strToU8('Hey there!')
    },
    // You can also manually write out a directory path
    'other/tmp.txt': new Uint8Array([97, 98, 99, 100])
  },

  // You can also provide compression options
  'massiveImage.bmp': [aMassiveFile, {
    level: 9,
    mem: 12
  }],
  // PNG is pre-compressed; no need to waste time
  'superTinyFile.png': [aPNGFile, { level: 0 }],

  // Directories take options too
  'exec': [{
    'hello.sh': [fflate.strToU8('echo hello world'), {
      // ZIP only: Set the operating system to Unix
      os: 3,
      // ZIP only: Make this file executable on Unix
      attrs: 0o755 << 16
    }]
  }, {
    // ZIP and GZIP support mtime (defaults to current time)
    mtime: new Date('10/20/2020')
  }]
}, {
  // These options are the defaults for all files, but file-specific
  // options take precedence.
  level: 1,
  // Obfuscate last modified time by default 
  mtime: new Date('1/1/1980')
});

// If you write the zipped data to myzip.zip and unzip, the folder
// structure will be outputted as:

// myzip.zip (original file)
// dir1
// |-> nested
// |   |-> 你好.txt
// |-> other
// |   |-> tmp.txt
// massiveImage.bmp
// superTinyFile.png

// When decompressing, folders are not nested; all filepaths are fully
// written out in the keys. For example, the return value may be:
// { 'nested/directory/structure.txt': Uint8Array(2) [97, 97] }
const decompressed = fflate.unzipSync(zipped, {
  // You may optionally supply a filter for files. By default, all files in a
  // ZIP archive are extracted, but a filter can save resources by telling
  // the library not to decompress certain files
  filter(file) {
    // Don't decompress the massive image or any files larger than 10 MiB
    return file.name != 'massiveImage.bmp' && file.originalSize <= 10_000_000;
  }
});

If you need extremely high performance or custom ZIP compression formats, you can use the highly-extensible ZIP streams. They take streams as both input and output. You can even use custom compression/decompression algorithms from other libraries, as long as they are defined in the ZIP spec (see section 4.4.5). If you'd like more info on using custom compressors, feel free to ask. ```js // ZIP object // Can also specify zip.ondata outside of the constructor const zip = new fflate.Zip((err, dat, final) => { if (!err) { // output of the streams console.log(dat, final); } });

const helloTxt = new fflate.ZipDeflate('hello.txt', { level: 9 });

// Always add streams to ZIP archives before pushing to those streams zip.add(helloTxt);

helloTxt.push(chunk1); // Last chunk helloTxt.push(chunk2, true);

// ZipPassThrough is like ZipDeflate with level 0, but allows for tree shaking const nonStreamingFile = new fflate.ZipPassThrough('test.png'); zip.add(nonStreamingFile); // If you have data already loaded, just .push(data, true) nonStreamingFile.push(pngData, true);

/