src/core/zip.js
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
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
const ZIP_NAMETrue when a file name ends in .zip.
readZip
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
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
function async inflateEntry(zip, en)The decompressed bytes of an entry (Uint8Array): for small entries and nested archives.
zipFiles
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
function async expandZips(files, opts = {})Expand any .zip among files (Files or Blobs with a name) into their contents; other files pass through.
crc32
function crc32(u8)CRC-32 (IEEE 802.3, as zip and gzip use).
makeZip
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).