function

zlib.createZipArchive

entries: Iterable<ZipEntry, any, any> | AsyncIterable<ZipEntry, any, any>,
options?: string | CreateZipArchiveOptions

Serializes entries into a ZIP archive, switching to Zip64 structures automatically once the entry count, or any offset or size, exceeds what the classic 32-/16-bit ZIP fields can hold. The returned Readable is also an AsyncIterable of the same Buffer chunks it streams.

Entries are written in iteration order and nothing deduplicates names: an iterable that yields two entries with the same name produces an archive containing both, and most extraction tools keep the one that appears later. ZipBuffer and ZipFile add() methods replace entries by name instead.

The entries are owned by the returned stream: each is consumed as the archive is produced and must not be reused afterwards. This matters for streaming entries (from zlib.ZipEntry.createStream()), which hold an underlying source such as a file read stream. If the returned stream is destroyed before it is fully consumed - for example, the destination of a pipeline() fails - it disposes the entry it was serializing and every entry still queued behind it, destroying their sources so no descriptor leaks. Consume the stream to the end, or destroy it (directly, through a failed pipeline(), or with await using), to guarantee this cleanup; a stream that is neither consumed nor destroyed cannot release anything. A ZipEntry that is never handed to an archive can be released directly with Symbol.dispose / Symbol.asyncDispose.

Throws an ERR_ZIP_ARCHIVE_TOO_LARGE error if the archive comment exceeds 65,535 bytes when encoded as UTF-8.

Passing options.baseOffset produces an archive that is valid immediately when placed after other content in the same file, without relying on a reader's self-extracting-archive detection to compensate for the shift.

@param entries

Iterable | AsyncIterable of ZipEntry.

@param options

An archive comment, as a shorthand for { comment: options }.

@returns

A byte stream of the serialized archive.

Referenced types

class ZipEntry

A single file or directory inside a ZIP archive. Instances are produced by ZipBuffer and ZipFile, or created directly for writing with ZipEntry.create()/ZipEntry.createStream().

create() and content() each have a *Sync counterpart (the streaming contentIterator() does not). As with the synchronous node:fs APIs, these block the Node.js event loop and further JavaScript execution until the operation (including any deflate/inflate pass) completes; use them only where synchronous execution is appropriate (for example, short-lived scripts or startup code), not in code that must stay responsive.

  • readonly comment: string
  • readonly compressed: boolean

    true if the entry's content is stored in compressed form (any compression method, currently deflate or Zstandard); false if it is stored uncompressed.

  • readonly compressedSize: number
  • readonly crc32: number
  • readonly flags: number

    The entry's raw general-purpose bit flag.

  • readonly isDirectory: boolean

    true if the entry is a directory (its name ends with /).

  • readonly isFile: boolean

    true if the entry is a regular file - that is, neither a directory nor a symbolic link.

  • readonly method: number

    The entry's raw compression method: 0 for stored, 8 for deflate, 93 for Zstandard.

  • readonly mode: number

    The entry's Unix mode permission bits, including the setuid, setgid, and sticky bits (the low 12 bits, 0o7777), or 0 if the archive was not written on a Unix-like system. The file-type bits are not included here; use zipEntry.isDirectory / zipEntry.isSymlink for the type.

  • readonly modified: Date

    The entry's last-modification time. When the archive carries a higher-fidelity timestamp in an extra field - an NTFS (0x000a), Info-ZIP extended (0x5455), or Info-ZIP Unix (0x5855) field, as most modern tools write - that absolute (UTC) time is used; otherwise the coarse, local-time MS-DOS date/time field (2-second resolution) is used.

    Some tools store their high-fidelity timestamp only in the local file header, so on a file-backed entry (one returned by zipFile.get()) the first read of this property may perform a small synchronous positioned disk read to resolve that header. If that read fails, the value silently falls back to the central-directory data.

  • readonly name: string

    The entry's name, decoded from the central directory, which is treated as authoritative - a local file header that disagrees is ignored, so a mismatched-header ("ZIP-confusion") archive cannot make name disagree with what is read. The bytes are decoded from a valid Info-ZIP Unicode Path extra field (0x7075) when one is present; otherwise as UTF-8 when the language-encoding flag (general-purpose bit 11) is set or the bytes are valid UTF-8 (plenty of tools wrote UTF-8 names without ever setting the flag); and as CP437 - the historical default - only when they are not. See zipEntry.nameBuffer for the raw bytes.

    The name is returned verbatim: it is never normalized, and a name containing .., a leading /, a drive letter, or backslashes is neither rewritten nor rejected. A ZipFile/ZipBuffer never writes to disk, so guarding against path traversal ("Zip Slip") when extracting is the caller's responsibility.

  • readonly nameBuffer: Buffer

    The entry's raw name bytes, before any character decoding. Useful when the archive's names are in an encoding other than UTF-8 or CP437 and the caller wants to decode them itself.

  • readonly rawContent: null | Buffer<ArrayBufferLike>

    The entry's raw (still compressed, if applicable) content when it is held in memory, or null when there is no in-memory buffer to expose - for an entry created with zlib.ZipEntry.createStream(), or a file-backed entry returned by zipFile.get(), whose bytes are read from disk on demand rather than retained. Use zipEntry.content() or zipEntry.contentIterator() to read a file-backed entry.

  • readonly size: number

    The entry's uncompressed size, in bytes.

  • [Symbol.asyncDispose](): Promise<void>;
  • options?: ZipEntryContentOptions
    ): Promise<NonSharedBuffer>;

    Throws an ERR_ZIP_ENTRY_TOO_LARGE error if the entry's declared size exceeds maxSize, an ERR_ZIP_ENTRY_CORRUPT error if the content fails CRC-32 verification or does not match its declared size, and an ERR_INVALID_STATE error for a streaming entry (zlib.ZipEntry.createStream()) whose content is not yet available (see that method for when a streaming entry becomes readable).

    @returns

    Promise fulfilled with a Buffer containing the entry's decompressed content. The buffer is a fresh copy that shares no memory with the archive or with data the entry was created from.

  • options?: ZipEntryContentIterOptions
    ): AsyncIterator<Buffer<ArrayBufferLike>>;

    Unlike zipEntry.content(), this does not buffer the whole member in memory. For a file-backed entry (one returned by zipFile.get()) the compressed bytes are read from disk as the iterator is consumed and nothing is retained; the entry is valid only while its ZipFile is open.

    Because streaming is the bounded-memory path for arbitrarily large members, it is not capped by zlib.getMaxZipContentSize() the way zipEntry.content() is - that default guards a single large allocation, which streaming never makes. Output is still bounded per chunk to the declared uncompressed size; pass maxSize to impose an explicit ceiling.

    For an in-memory entry stored without compression, the yielded chunks are zero-copy views of the entry's retained content (see zipEntry.rawContent); do not mutate them.

    The yielded chunks are provisional until the iterator completes. CRC-32 verification (and the final declared-size check) can only run once every byte has been read, so a corrupt or truncated entry is reported by the iterator throwing after the last chunk, not before the first. Each chunk is still bounded so the total never exceeds the declared size or maxSize, but a consumer that must not act on unverified bytes should buffer them (or use zipEntry.content(), which verifies before returning anything) rather than processing chunks as they arrive.

    @returns

    AsyncIterator of Buffer chunks of the entry's decompressed content.

  • options?: ZipEntryContentOptions
    ): NonSharedBuffer;

    The synchronous version of zipEntry.content().

    @param options

    See zipEntry.content().

    @returns

    The entry's decompressed content.

  • static create(
    filename: string,
    data: ZipInputType,
    options?: ZipEntryCreateOptions
    ): Promise<ZipEntry>;

    Compresses data (unless method is 'store', or compression would not reduce its size) and computes its CRC-32.

    When the entry ends up stored uncompressed (because method is 'store', or because compression would not reduce the size), the entry retains a zero-copy view of data rather than a copy, and its CRC-32 has already been recorded. Do not mutate data after creating the entry; pass a copy if it might change.

    The MS-DOS date/time fields ZIP uses for modified have 2-second resolution and no time zone. When modified does not fall on a whole 2-second boundary, an Info-ZIP extended-timestamp extra field is written as well, recording the whole (UTC) second so the time round-trips more precisely (see zipEntry.modified). This applies to every entry-creation path.

    @param filename

    The entry's name within the archive. A trailing / marks a directory entry.

    @param data

    The entry's complete, uncompressed content. Must be empty when filename names a directory.

  • static createStream(
    filename: string,
    source: AsyncIterable<Uint8Array<ArrayBufferLike>>,
    options?: ZipEntryCreateStreamOptions

    Creates an entry whose content is compressed on the fly as it is serialized by zlib.createZipArchive(), without buffering source in memory. Its size, compressedSize, and crc32 only become available once serialization has finished. There is no synchronous counterpart: streaming entries only make sense with an asynchronous, incrementally-produced source.

    source is drained exactly once, during serialization. Until that happens the entry has no readable content, so zipEntry.content(), zipEntry.contentSync(), and zipEntry.contentIterator() throw ERR_INVALID_STATE. If the entry is serialized by adding it to a writable ZipFile with zipFile.addEntry() (or addEntrySync()), it is then promoted in place to a file-backed entry pointing at the copy just written, so it becomes readable (and can be serialized again) for as long as that ZipFile stays open. Serializing it any other way (for example directly through zlib.createZipArchive()) leaves it spent and unreadable.

    Because source may hold an operating-system resource (a file read stream, say), a streaming entry is disposable: its Symbol.dispose and Symbol.asyncDispose methods destroy source if it has not been consumed. An entry passed to an archive is disposed by that archive (see zlib.createZipArchive()); dispose an entry directly only when it was built but never handed to one. Disposal is a no-op for non-streaming entries - in particular a file-backed entry never closes the ZipFile descriptor it borrows.

    @param filename

    The entry's name within the archive. Must not end in /.

    @param source

    Yields the entry's uncompressed content as Uint8Array chunks.

  • static createSync(
    filename: string,
    data: ZipInputType,
    options?: ZipEntryCreateOptions

    The synchronous version of zlib.ZipEntry.create().

    @param filename

    The entry's name within the archive. A trailing / marks a directory entry.

    @param data

    The entry's complete, uncompressed content. Must be empty when filename names a directory.

    @param options

    See zlib.ZipEntry.create().

  • static read(
    buffer: ZipInputType
    ): Iterator<ZipEntry>;

    Parses every entry out of buffer directly, without indexing it into a ZipBuffer. Like ZipBuffer, the yielded entries hold zero-copy views of buffer rather than copies of their content, so the same rule applies: do not mutate or reuse buffer while any of them is still in use.

    @param buffer

    A complete ZIP archive.

    @returns

    Iterator of ZipEntry.

interface CreateZipArchiveOptions

  • baseOffset?: number

    Shifts every local/central header offset the archive records by this many bytes.

  • comment?: string

    An archive comment.