but-unzip

library0.1.10jsnpmunverified

Tiny unzip library (<1KB) for Node.js and browsers, current version 0.1.10. Released sporadically, no fixed cadence. Differentiator: minimal size, synchronous entry iteration, automatic use of built-in decompression APIs (zlib in Node, DecompressionStream in modern browsers). Optionally supports pako as fallback for older environments. No streaming, no ZIP64 support. Ships TypeScript definitions.

storage

npm install but-unzip

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUT-UNZIP

but-unzip

storagejavascriptv0.1.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

iter

✓ import { iter } from 'but-unzip'

✗ const { iter } = require('but-unzip')

ESM-only package; no CommonJS version. The `iter` function returns a synchronous generator of zip entries.

unzip

✓ import { unzip } from 'but-unzip'

✗ import unzip from 'but-unzip'

`unzip` is a named export, not default. It returns an array of entries without using a generator.

inflateRaw

✓ import { inflateRaw as platformInflateRaw } from 'but-unzip'

✗ import { inflateRaw } from 'but-unzip'

This is the platform inflateRaw fallback (might be undefined). Intended to be combined with pako fallback in a conditional. Not a standalone function.

Reads a zip file synchronously, iterates entries, and decompresses each entry's data asynchronously.

import { iter } from 'but-unzip'; import * as fs from 'fs'; const zipBytes = fs.readFileSync('archive.zip'); for (const entry of iter(zipBytes)) { console.log('File:', entry.name, '(compressed:', entry.compressedSize, 'bytes)'); const data = await entry.read(); // Uint8Array or Promise<Uint8Array> // process data... }

Debug

Known issues

gotchaZIP64 is not supported. Files >4GB or archives with ZIP64 extensions will fail.

fix

Do not use but-unzip with ZIP64 archives. Consider a full-featured alternative like adm-zip or yauzl.

affects: >=0.0.0

gotchaEntry `.read()` may return a synchronous `Uint8Array` in Node (if using zlib) or a `Promise<Uint8Array>` in browsers (using DecompressionStream). Code must handle both.

fix

Always `await` the return value of `.read()` to be safe in all environments.

affects: >=0.0.0

gotchaThe package is ESM-only and cannot be required via CommonJS `require()`. Attempting to do so throws a runtime error.

fix

Use `import` syntax or a dynamic import. If your project uses CommonJS, consider using a bundler or switching to ESM.

affects: >=0.0.0

gotchaThe `inflateRaw` export is not a standalone decompression function; it's either undefined (no platform support) or a function. It's intended as a fallback target for pako.

fix

Use `import { unzip, inflateRaw as platformInflateRaw } from 'but-unzip';` and supply an alternative like `pako.inflateRaw` if `platformInflateRaw` is null.

affects: >=0.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use ESM imports in a CommonJS script without a bundler or proper package.json configuration.

fix

Use dynamic import: `const { iter } = await import('but-unzip');` or add `"type": "module"` to package.json.

TypeError: entry.read is not a function

Using the iterator result incorrectly; `entry` might be undefined (e.g., empty archive) or `read` was called on a non-entry object.

fix

Ensure you iterate correctly: `for (const entry of iter(bytes)) { await entry.read(); }`.

Error: Unsupported compression method: 1

The archive uses a compression method other than stored (0) or deflated (8), such as bzip2 or LZMA.

fix

Use a different library that supports the compression method, or re-compress the archive with deflate.

Upgrade

Version history

0.1.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/samthor/but-unzip#readme ↗

packagebut-unzip ↗

homepagehttps://github.com/samthor/but-unzip#readme ↗