unzipit.js

Common errors

• TypeError: (0 , unzipit__WEBPACK_IMPORTED_MODULE_0__.unzip) is not a function

  cause Incorrect import syntax for named exports, typically attempting a default import for `unzip`.
  fix Use a named import: `import { unzip } from 'unzipit';`.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require` syntax in an ES Module environment (browser, or Node.js project configured for ESM).
  fix Use ES Module `import` statements (e.g., `import { unzip } from 'unzipit'`) or ensure your Node.js project is configured for CommonJS (`"type": "commonjs"` in `package.json`).

• Failed to construct 'Worker': Script at 'path/to/unzipit-worker.module.js' cannot be accessed from origin 'null'.

  cause The `workerURL` provided to `setOptions` points to an inaccessible or improperly served path for the web worker script.
  fix Ensure `workerURL` is a valid, publicly accessible URL relative to your web application's origin, or a data URL. Double-check the path to `unzipit-worker.module.js` in your `dist` folder.

Warnings

• breaking Users migrating from CommonJS (`require`) to ES Modules (`import`) or targeting modern Node.js environments (Node 18+) will experience breaking changes in import syntax.
  Fix: Replace `const unzipit = require('unzipit')` with `import { unzip } from 'unzipit'` or `import * as unzipit from 'unzipit'` for ES Module compatibility. Ensure your project's `package.json` specifies `"type": "module"` or uses `.mjs` file extensions for ESM.
• gotcha When using web workers for parallel processing, the `workerURL` option *must* be correctly set to the path of `unzipit-worker.module.js`.
  Fix: Call `setOptions({workerURL: 'path/to/unzipit-worker.module.js'})` *before* calling `unzip`. The worker script is usually found in the `dist` folder of the `unzipit` package.
• gotcha In Node.js environments, `unzipit` cannot directly fetch from URLs without a custom `Reader` or by pre-loading the ZIP content into an `ArrayBuffer`, `SharedArrayBuffer`, or `TypedArray`.
  Fix: For Node.js, first read the file into a buffer using `fsPromises.readFile()` or use a library like `node-fetch` to get a `Blob` or `ArrayBuffer` from a URL, then pass that data to `unzip`.
• gotcha The `unzip` function returns a `Zip` object with an `entries` property, which is a plain object mapping entry names to `ZipEntry` objects. Directly iterating over `entries` as an array will fail.
  Fix: Use `Object.entries(entries)`, `Object.keys(entries)`, or `Object.values(entries)` to iterate over the entries, as shown in the examples.

Install

• npm install unzipit npm
• yarn add unzipit yarn
• pnpm add unzipit pnpm

Imports

• unzip
  wrong:

  import unzip from 'unzipit';

  correct:

  import { unzip } from 'unzipit';

  `unzip` is the primary named export for initiating the ZIP extraction process. Attempting a default import will fail.
• setOptions
  wrong:

  const { setOptions } = require('unzipit');

  correct:

  import { setOptions } from 'unzipit';

  Used to configure global options like `workerURL`. While `require` might work in some Node setups, ESM is the recommended approach for this library with Node >=18.
• * as unzipit (ESM)
  wrong:

  const unzipit = require('unzipit');

  correct:

  import * as unzipit from 'unzipit';

  Imports all exports under a namespace. `require` is incorrect for browser environments and typically for Node >=18 when using ESM.
• unzipit (CommonJS)

  const unzipit = require('unzipit');

  This CommonJS import pattern is supported for Node.js environments. For browser or modern Node.js ESM projects, use `import` syntax.

Quickstart

Demonstrates basic usage of `unzipit` to fetch a ZIP file from a URL, list its contents, and extract specific entries as text and Blob objects, handling potential errors.

import { unzip } from 'unzipit';

async function processZipFromUrl(zipUrl: string) {
  try {
    // Replace with a real URL for actual testing
    const dataUrl = zipUrl || 'https://greggman.github.io/unzipit/test/zips/archive-with-folder.zip';

    console.log(`Attempting to unzip from: ${dataUrl}`);
    const { entries, zip } = await unzip(dataUrl);

    console.log(`Total entries found: ${Object.keys(entries).length}`);

    // Iterate through all entries and log their names and sizes
    for (const [name, entry] of Object.entries(entries)) {
      console.log(`  Entry: ${name}, Size: ${entry.size} bytes`);
    }

    // Example: Read a specific file (e.g., 'folder/file1.txt' from the example URL)
    const specificEntry = entries['folder/file1.txt'];
    if (specificEntry) {
      console.log(`\nAttempting to read 'folder/file1.txt' as text...`);
      const textContent = await specificEntry.text();
      console.log(`Content of 'folder/file1.txt':\n---\n${textContent.substring(0, 100)}...\n---`); // Log first 100 chars
    } else {
      console.log(`\nEntry 'folder/file1.txt' not found (check URL or entry name).`);
    }

    // Example: Read another entry as a Blob (e.g., if there was an image.png)
    const imageEntry = entries['image.png']; // Replace with an actual image entry if present
    if (imageEntry) {
      console.log(`\nAttempting to read 'image.png' as a Blob...`);
      const imageBlob = await imageEntry.blob('image/png');
      console.log(`'image.png' read as Blob of type: ${imageBlob.type}, size: ${imageBlob.size}`);
      // In a browser, you could create an object URL: URL.createObjectURL(imageBlob);
    } else {
      console.log(`\nEntry 'image.png' not found.`);
    }

  } catch (error) {
    console.error("Error processing zip file:", error);
  }
}

// Call the function with an example URL. Pass an empty string to demonstrate 'not found' messages.
processZipFromUrl('https://greggman.github.io/unzipit/test/zips/archive-with-folder.zip');