rules/api.md
GitHubnode:zlib ZIP API reference
Everything here was added in v26.8.0 and is at Stability 1.0 (Early development), unless a row says otherwise.
The docs are pinned at nodejs/node ab476eccd03. Behavior was checked on v26.13.0 and on main
(v28.0.0-pre).
Choosing a class
| Need | Use |
|---|---|
| An archive on disk, with lazy random access or in-place edits | ZipFile.open(path[, { writable }]) |
| An archive already held in memory (an upload or a fetch body) | new ZipBuffer(bytes) |
| Iterate the entries of a buffer once, without an index | ZipEntry.read(bytes) |
| Build a new archive from data | ZipEntry.create* + createZipArchive(entries) |
| Build a new archive from files on disk | zipFiles([[src, name], ...]) |
ZipEntry
Static constructors:
await ZipEntry.create(name, data[, opts])andZipEntry.createSync(...).datais a Buffer, TypedArray, DataView, or ArrayBuffer. A name ending in/makes a directory, and its data must be empty (otherwise it throwsERR_INVALID_ARG_VALUE).optsare:comment,mode(default0o644, or0o755for directories),modified(a Date, default now), andmethod('deflate'(default),'store'or'zstd'). If deflating would not make the data smaller, the entry is stored instead. A stored entry keeps a zero-copy view ofdata.ZipEntry.createStream(name, asyncIterable[, opts]). The data is compressed during serialization, sosize,crc32andcompressedSizeare only known afterwards. A name ending in/throws. Before serialization,content*()throwsERR_INVALID_STATE. AfterzipFile.addEntry()the entry is promoted to a file-backed entry and becomes readable. AftercreateZipArchive()it is spent. It supportsSymbol.disposeandSymbol.asyncDispose, which destroy an unconsumed source.ZipEntry.createSymlink(name, target[, opts])makes a stored entry withisSymlink === true(mode0o777).ZipEntry.read(bytes)returns an iterator ofZipEntry, each a zero-copy view.
Properties: name (verbatim, see rules/security.md), nameBuffer, comment, size,
compressedSize, compressed, method (0 store, 8 deflate, 93 zstd), crc32,
flags, mode (the low 12 bits, or 0 for archives not made on Unix), modified (a Date),
isFile, isDirectory, and isSymlink.
Reading:
| Method | Cap | Verify | Notes |
|---|---|---|---|
content([{ verify = true, maxSize }]) returns Promise<Buffer> |
maxSize, default getMaxZipContentSize() (256 MiB) |
CRC is checked before it returns | The result is a fresh copy |
contentSync([opts]) |
same | same | Blocks the event loop |
contentIterator([{ verify, maxSize }]) returns AsyncIterator<Buffer> |
none unless maxSize is passed |
CRC is checked after the last chunk | Bounded memory. A file-backed entry reads lazily from disk |
rawContent([{ maxSize }]) returns a Promise of the stored bytes |
maxSize, default 256 MiB |
no | v27+ only. On v26.x rawContent is a getter, see rules/versions.md |
rawContentSync(), rawContentIterator() |
v27.0.0-alpha.0.0.0 |
Errors: ERR_ZIP_ENTRY_TOO_LARGE (the declared size is over maxSize), ERR_ZIP_ENTRY_CORRUPT
(a CRC or size mismatch), and ERR_INVALID_STATE (an unserialized streaming entry, or its ZipFile is closed).
ZipFile (on disk)
await ZipFile.open(path, { writable: false })andZipFile.openSync(...)read only the tail and the central directory. A missing file rejects withENOENT; ZipFile never creates a file. A central directory that is too large throwsERR_ZIP_ARCHIVE_TOO_LARGE.- Lookups:
size,has(name),keys(),commentandwritable.get(name)returns aPromise<ZipEntry>andgetSync(name)aZipEntry; both create lazy file-backed entries, and a missing name givesERR_ZIP_ENTRY_NOT_FOUND.entries()andvalues()yield Promises.entriesSync(),valuesSync()andforEachSync()yield resolved entries. The object is iterable (for (const [name, promise] of zip)). await zip.stream(name[, { verify, maxSize }])resolves to astream.Readable. It has no default cap.- Edits (they need
{ writable: true }, otherwiseERR_ZIP_NOT_WRITABLE):add(name, data[, opts])andaddSync.addEntry(entry)andaddEntrySync(the sync form cannot take a pending streaming entry). The new data goes where the old central directory started, and the directory is rewritten after it. An existing entry with the same name is replaced.delete(name)anddeleteSyncreturn whether the entry existed. They only rewrite the directory.- The file is modified when the returned promise settles. A sync method called while an
async edit is pending throws
ERR_INVALID_STATE.
compact([comment])returns aReadableof a fresh archive without dead space.compactSync()returns a Buffer. Neither modifies the open file: write the result to a new path and rename it.close()andcloseSync().Symbol.asyncDisposeandSymbol.disposeare present (observed, not documented) and close the file, soawait using zip = await ZipFile.open(...)works. Entries used after close throwERR_INVALID_STATE(observed; the docs say EBADF-style errors).
ZipBuffer (in memory)
new ZipBuffer(bytes)parses the central directory. It throwsERR_ZIP_INVALID_ARCHIVEorERR_ZIP_UNSUPPORTED_FEATURE. The bytes are not copied: do not mutate or reuse them while the ZipBuffer or any of its entries is alive (passBuffer.from(src)if they might change).get(name)(throwsERR_ZIP_ENTRY_NOT_FOUND),has,keys,values,entries,forEach,sizeandcomment. It is iterable as[name, entry].writableis alwaystrue.add/addSync/addEntryreplace by name, anddelete(name)andclear()remove entries. None of them touches the source bytes.await toBuffer([comment | { comment, baseOffset }])andtoBufferSync()serialize a fresh archive, switching to Zip64 automatically.
Building archives
createZipArchive(iterableOrAsyncIterable[, comment | { comment, baseOffset }])returns astream.Readable, which is also an async iterable of Buffers (await r.toArray()works). The stream owns the entries. If it is destroyed early (for example because apipeline()failed), it disposes the remaining entries. Duplicate names are written twice. A comment over 65,535 bytes throwsERR_ZIP_ARCHIVE_TOO_LARGE.createZipArchiveSync(iterable[, opts])returns an iterator of Buffers (Buffer.concat([...it])). A streaming entry throws when its turn comes.zipFiles(pairs[, comment | { followSymlinks = true, comment, baseOffset }])returns aReadable.pairsis any iterable of[sourcePath, entryName], such as an array, a Map, orObject.entries(). It records the Unix mode and mtime. A directory becomes a directory entry (the trailing/is added) and is not recursed into. Files are streamed. WithfollowSymlinks: false, symlinks are stored as link entries.baseOffsetshifts the recorded offsets so that an archive written after N bytes of other content (a self-extracting stub, for example) is still valid.
Global cap
getMaxZipContentSize() returns the default of 268435456. setMaxZipContentSize(n) is process-wide and
applies only to content()/contentSync(). Streaming reads ignore it.
zlib.crc32c(data[, value]) (v27.0.0-alpha.0.0.0)
This is CRC-32C (Castagnoli, as used by iSCSI, ext4 and SCTP). It differs from zlib.crc32 (v22.2.0, v20.15.0),
which is the checksum ZIP uses. Chain calls by passing the previous result as value:
crc32c('world', crc32c('hello')) === crc32c('helloworld').