unzipit

The ZIP standard does not guarantee Unicode. If a zip file uses a different encoding for filenames, unzip() might fail to create a valid string key in the entries object. In these cases, use unzipRaw() to get an array of entries and access the entry.nameBytes property to decode the filename manually using your preferred encoding (e.g., TextDecoder).

// Using unzipRaw to handle non-UTF-8 names
const { entries } = await unzipRaw(blob);
for (const entry of entries) {
  // Decode using a specific encoding like windows-1252
  const decodedName = new TextDecoder('windows-1252').decode(entry.nameBytes);
  console.log('Decoded filename:', decodedName);
}

To avoid downloading an entire zip file before processing, use HTTPRangeReader if your server supports HTTP range requests. This allows unzipit to read only the central directory at the end of the file and then fetch specific entry data on demand via range requests.

import { unzip, HTTPRangeReader } from 'unzipit';

async function readFiles(url) {
  const reader = new HTTPRangeReader(url);
  const { zip, entries } = await unzip(reader);
  // Entries are now available, and their data will be fetched via range requests as needed
  const stream = await entries['some/huge/file.bin'].stream();
}

To unzip a file using the main thread, import unzip and pass a URL or a compatible data object (like Blob, ArrayBuffer, SharedArrayBuffer, TypedArray, or a custom Reader). The unzip function returns an object containing entries, where each entry allows you to retrieve its data as an ArrayBuffer or a Blob (with an optional MIME type).

import {unzip} from 'unzipit';

async function readFiles(url) {
  const {entries} = await unzip(url);

  // print all entries and their sizes
  for (const [name, entry] of Object.entries(entries)) {
    console.log(name, entry.size);
  }

  // read an entry as an ArrayBuffer
  const arrayBuffer = await entries['path/to/file'].arrayBuffer();

  // read an entry as a blob and tag it with mime type 'image/png'
  const blob = await entries['path/to/otherFile'].blob('image/png');
}

You can use unzipit via npm/bundlers, by including the distributed files directly, or via CDN.

Via ESM Import (Local File):

import * as unzipit from `./unzipit.module.js`;

Via Script Tag (Local File):

<script src="unzipit.min.js"></script>

Via CDN:

import * as unzipit from 'https://unpkg.com/unzipit@2.0.1/dist/unzipit.module.js';
// or
<script src="https://unpkg.com/unzipit@2.0.1/dist/unzipit.js"></script>

To improve performance, you can offload decompression to web workers. You must first call setOptions with the workerURL pointing to the unzipit-worker.module.js file before calling unzip.

import {unzip, setOptions} from 'unzipit';

setOptions({workerURL: 'path/to/unzipit-worker.module.js'});

async function readFiles(url) {
  const {entries} = await unzip(url);
  // ...
}

In Node.js, you cannot pass a URL directly. You must either pass an ArrayBuffer, SharedArrayBuffer, TypedArray, or implement a custom Reader object.

Using an ArrayBuffer:

const unzipit = require('unzipit');
const fsPromises = require('fs').promises;

async function readFiles(filename) {
  const buf = await fsPromises.readFile(filename);
  const {zip, entries} = await unzipit.unzip(new Uint8Array(buf));
  // ...
}

Using Workers in Node.js: To use workers in Node, use require.resolve to provide the worker path and call unzipit.cleanup() to allow the process to exit.

const unzipit = require('unzipit');

unzipit.setOptions({workerURL: require.resolve('unzipit/dist/unzipit-worker.js')});

// ... use unzip ...

// Call this to shut down workers and allow Node to exit
unzipit.cleanup();

When running or inspecting live browser tests, you can disable timeouts by appending ?timeout=0 to the URL. This is useful for debugging long-running or complex test cases in the browser environment.

http://localhost:8080/tests/?timeout=0

You can maximize throughput by extracting multiple entries simultaneously using Promise.all. This is particularly effective when using workers.

import {unzip, setOptions} from 'unzipit';

setOptions({workerURL: 'path/to/unzipit-worker.module.js'});

async function readFiles(url) {
  const {entries} = await unzipit.unzip(url);
  const names = Object.keys(entries);
  const blobs = await Promise.all(Object.values(entries).map(e => e.blob()));

  // names and blobs are now parallel arrays so do whatever you want.
  const blobsByName = Object.fromEntries(names.map((name, i) => [name, blobs[i]]));
}

If you have enabled workers, call cleanup() to shut them down. This is particularly important in Node.js environments to allow the process to exit gracefully, as the process will wait for workers to terminate.

import { cleanup } from 'unzipit';

// Call when the application is shutting down
cleanup();