Skip to content

src/core/zip.js ​

text
Reading .zip archives in the browser (and Node 18+) without a library and without inflating them whole.

The central directory at the end of the archive lists every entry with its compression method, CRC-32, sizes and
the offset of its local header (APPNOTE.TXT 6.3.10, with the ZIP64 records for archives over 4 GB or 65,535
entries). An entry becomes a File that is a *slice of the archive's Blob* and costs no memory until it is read:
  stored (method 0)     the slice itself;
  deflated (method 8)   the slice of raw DEFLATE data between a 10-byte gzip header and an 8-byte trailer made from the
                        directory's CRC-32 and size, i.e. a valid .gz member, which the FITS reader (and
                        DecompressionStream('gzip'), which checks the CRC) already decode. Nothing is re-compressed.
So a zip of 2,000 frames costs one read of its directory, and each frame is inflated only when the pipeline reads
it, one at a time (in the worker). Such Files survive postMessage to a worker. A zip inside a zip is opened the same
way (inflated first when it is itself deflated). Not supported: encryption, methods other than 0 and 8 (deflate64,
bzip2, LZMA, zstd), archives split over several disks; those entries are listed with the reason.
Checked in test/zip.test.mjs against archives written by Python's zipfile (test/make_zip_reference.py) and EXOTIC's
sample-data zip.

Import: import { … } from './src/core/zip.js' — no DOM, runs in Node and the browser.

isZip ​

js
function isZip(buf)

True when the bytes start like a zip (a local header "PK\3\4", or the end record of an empty archive).

ZIP_NAME ​

js
const ZIP_NAME

True when a file name ends in .zip.

readZip ​

js
function async readZip(src)

Read the central directory of a zip (a Blob / File, or bytes).

  • returns { entries: [{ path, name, dir, method, encrypted, crc, csize, size, localOffset, supported, why }], comment, zip64 }

entryFile ​

js
function async entryFile(zip, en, prefix = '')

The entry as a File (lazy: a slice of the archive). Stored entries are the bytes themselves; deflated ones are the raw DEFLATE data wrapped as a gzip member (header + data + CRC-32 + size), so anything that reads .gz reads them. The File carries relPath (the path inside the zip, prefixed by prefix), zipMethod and unpackedSize.

inflateEntry ​

js
function async inflateEntry(zip, en)

The decompressed bytes of an entry (Uint8Array): for small entries and nested archives.

zipFiles ​

js
function async zipFiles(src, opts = {})

Every file of a zip, as lazy Files (see entryFile), folders flattened into relPath; zips inside it are opened in turn (to depth levels). filter(path) chooses entries (default: all); hidden macOS entries (__MACOSX/, ._name, .DS_Store) are skipped.

  • returns { files: [File], skipped: [{ path, why }], entries: number of entries read, nested: number of inner zips }

expandZips ​

js
function async expandZips(files, opts = {})

Expand any .zip among files (Files or Blobs with a name) into their contents; other files pass through.

crc32 ​

js
function crc32(u8)

CRC-32 (IEEE 802.3, as zip and gzip use).

makeZip ​

js
function makeZip(files)

A zip of small files, stored without compression (for the page's per-transit CSVs): files [{ name, data: string | Uint8Array }]. Returns a Blob (application/zip). UTF-8 names (flag bit 11).

MIT licensed · Kyle A. Pearson