Optionalbufferedtrue to write entry data in a buffer before appending it to the zip file.
bufferedWrite is automatically set to true when compressing more than one entry in parallel.
OptionalcentralThe extra field of the entry written only in the central directory record.
OptionalcommentThe comment of the entry.
It is a string, unlike the global comment passed to ZipWriter#close, because the encoding of the comment of an entry is recorded in the header by the general purpose bit 11 (see Appendix D - Language Encoding (EFS)), set by ZipWriterConstructorOptions#useUnicodeFileNames. Passing raw bytes here throws ERR_INVALID_ENTRY_COMMENT_TYPE instead of writing their textual representation.
OptionalcompressionThe compression method (e.g. 8 for DEFLATE, 0 for STORE).
Optionalcrc32The CRC-32 checksum of the content. This option is ignored if the ZipWriterConstructorOptions#passThrough option is unset
or false, and it is the caller's to supply otherwise, since the checksum cannot be computed from data which is not decompressed.
When the entry is AES-encrypted, this option is only stored when the encryption stage is passed through too, i.e. when
ZipWriterConstructorOptions#passThrough is set to true and the data is copied verbatim from an archive which already
published the checksum (see ZipWriterConstructorOptions#encrypted). The entry is then marked as AE-1. When the option is
set to "compressed" the writer performs the encryption itself, so storing the checksum of the content would disclose what that
encryption hides: the option is ignored, the entry is marked as AE-2 and the checksum fields are set to 0. See the remarks of
ZipWriterConstructorOptions#password.
OptionalcreateAn async factory function that returns a TransformStream-like object ({ writable, readable }) used as a temporary buffer when entries are written in parallel.
When provided, this replaces the default in-memory TransformStream buffer, allowing data to be stored externally (e.g. filesystem, OPFS, network).
The writable side receives compressed entry data. The readable side is consumed when the entry is replayed into the final zip stream.
The optional dispose method is called once the entry has been processed (on success, error, or abort) so a resource-backed buffer can release its resource.
See createOPFSTempStream for a ready-made OPFS-backed implementation, createSyncAccessHandleTempStream for a faster worker-only variant, and createBlobTempStream for a Blob-backed one.
The readable side is consumed only once the writable side has been closed, since the local
header written before it holds the size and the CRC-32 of the entry. The object must therefore be able to
hold a whole entry, either by buffering it like the default
new TransformStream(undefined, undefined, { highWaterMark: Infinity }) does, or by draining it like the
three implementations above do. A factory returning new TransformStream() deadlocks instead, its default
queuing strategy holding a single chunk.
OptionalcreationThe creation date.
This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.
Unlike ZipWriterConstructorOptions#lastModDate, it has no default: the date is written only when the option is set, so that the entries do not carry a meaningless creation time.
Optionaldatatrue to add a data descriptor.
When set to false, the ZipWriterConstructorOptions#bufferedWrite option will automatically be
set to true. It will be automatically set to false when it is undefined and the
ZipWriterConstructorOptions#bufferedWrite option is set to true, or when the entry is a folder
or an empty entry stored without compression or encryption, since the header can then carry the sizes and
the CRC-32 directly. It will be automatically set to true when the
ZipWriterConstructorOptions#zipCrypto option is set to true, except for such a folder or empty
entry, which holds no encrypted data and therefore needs no descriptor either. Otherwise, the default
value is true.
Optionaldatatrue to add the signature of the data descriptor.
Optionaldirectorytrue if the entry is a directory.
Optionalencryptedtrue to write encrypted data when passThrough is set to true.
OptionalencryptionThe encryption strength (AES):
OptionalentryThe entry the data comes from, e.g. one returned by ZipReader#getEntries, used as a source of default values for the options describing it.
Copying an entry from one zip file into another needs about ten options forwarded, and forwarding a subset of them corrupts the copy silently rather than throwing: the writer cannot tell that EntryMetaData#compressionMethod describes data it is about to store verbatim. This option hands it the entry instead, and the options describing that entry are read from it.
EntryMetaData#externalFileAttributes, EntryMetaData#versionMadeBy, EntryMetaData#comment, EntryMetaData#lastModDate, EntryMetaData#creationDate, EntryMetaData#lastAccessDate, EntryMetaData#internalFileAttributes, DirectoryEntry#directory, EntryMetaData#uid, EntryMetaData#gid and the extra fields of the entry which zip.js does not interpret itself are always read from it.
ZipWriterAddDataOptions#uncompressedSize, ZipWriterAddDataOptions#crc32,
EntryMetaData#compressionMethod, ZipWriterConstructorOptions#dataDescriptor and
ZipWriterConstructorOptions#rawLastModDate are read from it as well when the
ZipWriterConstructorOptions#passThrough option is set, since the data is then stored as it is read.
ZipWriterConstructorOptions#encrypted, ZipWriterConstructorOptions#zipCrypto and
ZipWriterConstructorOptions#encryptionStrength are only read from it when that option is set to true, i.e. when the
encryption stage is passed through too: with "compressed" the writer performs the encryption itself and the scheme is the
caller's to choose, so carrying the scheme of the source over would rekey an entry into the very scheme it was read from.
Every value read from the entry is a default against the options of the same ZipWriter#add call: an option written next to it wins. Against the options the ZipWriter was constructed with the precedence is the other way round, since the values read from the entry are merged into the options of the call, so a date pinned on the writer does not normalize a copied entry. Note that ZipDirectoryEntry#exportZip resolves the same conflict the opposite way, an export option overriding the metadata of an imported entry. The filename is not one of these values, it stays the first argument of ZipWriter#add, so an entry can be copied under another name.
ZipWriterConstructorOptions#encrypted is one of the values read from the entry, so copying an encrypted entry with
passThrough set to true takes the branch documented on that option: the ciphertext is written as-is and keeps the
password it was encrypted with, while a ZipWriterConstructorOptions#password in scope encrypts the other entries
only. Re-keying an entry is what passThrough set to "compressed" is for, since the encryption stage runs there.
A value which is not an object throws an ERR_INVALID_ENTRY error, and changing the
ZipWriterConstructorOptions#lastModDate of an entry encrypted with ZipCrypto throws an
ERR_ZIP_CRYPTO_LAST_MOD_DATE error when the encryption stage is passed through as well, i.e. when
ZipWriterConstructorOptions#passThrough is true rather than "compressed". Under "compressed" the
entry is encrypted again, or not encrypted at all, so the date is free to change. See the remarks of that option.
Optionalexecutabletrue if the entry is an executable file.
Optionalextendedtrue to store extended timestamp extra fields.
When set to false, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds, dates being truncated to the whole second and odd seconds rounded up to the next even second.
Some zip-based formats forbid any extra field on a specific entry, which the default value of this
option would write. OpenDocument requires its mimetype entry to come first, to be stored without compression
and to carry no extra field, so a conformant ODF package needs both this option set to false and
ZipWriterConstructorOptions#level set to 0 on that entry. EPUB asks for the same pair: OCF states
that the mimetype file must not be compressed or encrypted and that there must not be an extra field in its
ZIP header, which is what pins the byte offset of application/epub+zip so a reader can sniff the format
without parsing the archive, and epubcheck reports an extra field there as an error.
OptionalexternalThe external file attribute.
When set explicitly, the value is written verbatim (including 0), unless unixMode, setuid, setgid
or sticky is also set, in which case these options override the upper 16 bits while the lower 16 bits
are preserved. When omitted, the value is derived from the other options (e.g. the MS-DOS directory
attribute for folder entries, Unix default permissions when msDosCompatible is false).
OptionalextraThe extra field of the entry, written in the local file header and the central directory.
OptionalgidThe Unix group id to write in the Unix extra field or as part of the external attributes.
OptionalinternalThe internal file attribute.
Optionalkeeptrue to keep the order of the entry physically in the zip file.
The entries are then written one after another, but concurrent calls to ZipWriter#add still compress concurrently: one entry is written directly into the zip file while the others are buffered until it is their turn, i.e. ZipWriterConstructorOptions#bufferedWrite is set automatically for them.
OptionallastThe last access date.
This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.
Unlike ZipWriterConstructorOptions#lastModDate, it has no default: the date is written only when the option is set, so that the entries do not carry a meaningless access time.
OptionallastThe last modification date.
This option and the two below must be Date instances: a timestamp expressed in milliseconds, e.g.
File#lastModified, and an invalid Date are both rejected with ERR_INVALID_DATE. An
invalid Date used to be written as an entry carrying no timestamp at all.
OptionallevelThe level of compression.
The minimum value is 0 and means that no compression is applied. The maximum value is 9.
The native API CompressionStream does not support compression levels. Any value other than 6,
its de facto level, disables useCompressionStream and compresses the data with the embedded
implementation instead. Note that the compressed data produced at a given level can still vary
between platforms. Set useCompressionStream to false to get deterministic output across
platforms.
When no deflate implementation is available at all, i.e. the environment provides no usable
CompressionStream and the embedded implementation cannot be loaded, the entry is stored
instead of being compressed rather than failing. The fallback is reported twice: the
EntryMetaData#compressionMethod of the entry returned by ZipWriter#add is 0,
and WARNING_COMPRESSION_UNAVAILABLE is deposited on ZipWriter#warnings.
When the ZipWriterConstructorOptions#passThrough option passes the compression stage through, nothing is compressed and this option declares the level bits of the general purpose bit flag instead, see the remarks of that option.
OptionallocalThe extra field of the entry written only in the local file header.
OptionalmsdosWhen provided, MS-DOS attribute flags (boolean object) to write into external file attributes low byte.
See ZipWriterConstructorOptions#msdosAttributesRaw for the platform this option selects and for the Unix metadata it leaves out of the entry.
OptionalmsdosWhen provided, the low 8-bit MS-DOS attributes to write into external file attributes. Must be an integer between 0 and 255.
Setting this option or ZipWriterConstructorOptions#msdosAttributes selects the MS-DOS platform for
the entry exactly as ZipWriterConstructorOptions#msDosCompatible does, and overrides that option
when it is explicitly set to false. EntryMetaData#versionMadeBy then loses its Unix upper byte
and no Unix mode is written, so the 0o100644 of a file entry and the 0o040755 of a folder entry are
lost. What counts is that the option is provided, not its value: 0 and {} trigger it too.
Setting any Unix metadata option, i.e. ZipWriterConstructorOptions#uid, ZipWriterConstructorOptions#gid, ZipWriterConstructorOptions#unixMode, ZipWriterConstructorOptions#unixExtraFieldType or ZipWriterAddDataOptions#executable, takes precedence and keeps the Unix attributes, with the MS-DOS attributes written into the low byte. ZipWriterConstructorOptions#externalFileAttributes is preserved as well, although the entry still declares the MS-DOS platform.
Optionalmstrue to write EntryMetaData#externalFileAttributes in MS-DOS format for folder entries.
It also selects the MS-DOS platform for ZipWriterConstructorOptions#versionMadeBy and leaves the Unix
attributes out of the entries. Setting any Unix metadata option, e.g.
ZipWriterConstructorOptions#unixMode or ZipWriterAddDataOptions#executable, turns it back off, and setting
ZipWriterConstructorOptions#msdosAttributesRaw or ZipWriterConstructorOptions#msdosAttributes
turns it on, overriding an explicit false.
MS-DOS era extractors, e.g. PKUNZIP 2.04g, only honor the directory attribute of entries declaring the MS-DOS platform. Without this option, they extract folder entries as zero-length files, which can then prevent extracting the files stored below the folders.
Optionalntfstrue to always store the NTFS extra field, false to never store it.
By default, the NTFS extra field is stored only when it preserves information the extended timestamp extra field cannot represent: a last modification date outside its supported range, or explicit ZipWriterConstructorOptions#lastAccessDate or ZipWriterConstructorOptions#creationDate values.
This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.
OptionaloffsetThe offset of the first entry in the zip file.
When the option is undefined, the offset is the number of bytes already written into the
destination, read from its size property, see WritableWriter#size. A size property
set on a WritableStream instance passed directly to the ZipWriter constructor is
also read, for backward compatibility. When the option is set, the bytes between the size of
the destination and the offset are assumed to exist in the final zip file without being
written, e.g. when writing one part of a zip file assembled by the caller.
The option is only read when the ZipWriter is created, e.g. by ZipDirectoryEntry#exportZip; a value passed to ZipWriter#add is ignored.
Optionalpasstrue to write the data as-is without compressing it and without crypting it, "compressed" to encrypt it
without compressing it.
The data is never compressed, so the ZipWriterConstructorOptions#level option selects no codec, and neither does the ZipWriterAddDataOptions#compressionMethod option: both describe how the data is already compressed and are written as-is in the entry headers, the method in its own field and the level in the level bits of the general purpose bit flag. The method must be set, otherwise an ERR_UNDEFINED_COMPRESSION_METHOD error is thrown; the level is optional and leaves those bits unset. The ZipWriterAddDataOptions#crc32 option must be set as well, otherwise an ERR_UNDEFINED_CRC32 error is thrown, unless the entry is written as AES in AE-2 format, which stores no checksum.
The level is read from the options of the entry only. A level set on the options of the writer applies to the entries the writer compresses itself and is not inherited here, since it would describe data the writer never produced. A stored entry carries no level bits either way, they describe a deflate stream.
The entries with no content, e.g. the directories, ignore this option entirely. Setting the ZipWriterConstructorOptions#password or the
ZipWriterConstructorOptions#rawPassword option throws an
ERR_UNSUPPORTED_ENCRYPTION_PASS_THROUGH error, unless the
ZipWriterConstructorOptions#encrypted option is set to true to declare that the data is already
encrypted. In that case the password encrypts the other entries only, and the data written as-is keeps the
password it was encrypted with, which is not verified.
The codecs run in a fixed order, the data is compressed and then encrypted, so this option selects how many
of these two stages are skipped rather than which one. "compressed" declares that the data is already
compressed but not yet encrypted, so the compression stage is skipped and the encryption stage runs: it
encrypts an entry without recompressing it, which is what the true value cannot express and why it rejects
a password. The ZipWriterAddDataOptions#uncompressedSize and
ZipWriterAddDataOptions#compressionMethod options are still the caller's to declare, since neither
can be derived from data which is not decompressed.
The CRC32 of the entry cannot be computed either, so the ZipWriterAddDataOptions#crc32 option is
the caller's to declare as well. It is written as-is for an entry which is not AES-encrypted, i.e. for a
plain or a ZipCrypto entry, both of which store the checksum in clear anyway. It is dropped for an
AES-encrypted entry, which is marked AE-2 with the checksum fields set to 0: the encryption stage runs
here, so this is a new encryption, and a stored plaintext checksum would let an attacker verify guessed
content without knowing the password. Only the true value may mark an entry AE-1, and only because the
data is then copied verbatim from an archive which already published that checksum.
A value which is neither a boolean, "compressed" nor unset throws an ERR_INVALID_PASS_THROUGH_VALUE
error. The filesystem API copies entries verbatim and only accepts a boolean, see
ERR_UNSUPPORTED_PASS_THROUGH_VALUE.
When the data was encrypted with ZipCrypto, the verification byte stored in the encrypted data depends on the last modification date of the source entry if the data descriptor is used. The ZipWriterConstructorOptions#dataDescriptor and ZipWriterConstructorOptions#rawLastModDate values of the source entry must then be forwarded, otherwise reading the copied entry fails with an ERR_INVALID_PASSWORD error. The filesystem API forwards them when exporting entries and throws an ERR_ZIP_CRYPTO_LAST_MOD_DATE error if the date is overridden.
OptionalpasswordThe password used to encrypt the content of the entry.
When a password is set and the ZipWriterConstructorOptions#zipCrypto option is not set to true, the
entry is encrypted in AES AE-2 format: the CRC-32 checksum of the content is stored as 0 so that the zip
file reveals no information about the encrypted content. A stored checksum would allow an attacker to verify
guessed content without knowing the password. The integrity of the data is guaranteed by the authentication
code instead.
Optionalpreventtrue to prevent closing of WritableWriter#writable.
OptionalrawThe last modification date, as its raw 32-bit MS-DOS date and time value.
The value is written verbatim into the local and central directory headers and takes precedence over ZipWriterConstructorOptions#lastModDate, which still fills the extended timestamp and NTFS extra fields. The filesystem API sets it when exporting entries with ZipReaderOptions#passThrough set in ZipDirectoryEntryExportOptions#readerOptions, so that the entries copied as-is keep the exact date and time of the source zip file.
OptionalrawThe password used to encrypt the content of the entry (raw).
Optionalsetgidtrue to set the setgid bit when writing the Unix mode.
Optionalsetuidtrue to set the setuid bit when writing the Unix mode.
OptionalsignalThe AbortSignal instance used to cancel the compression.
A signal already aborted when the operation starts rejects it with ERR_ABORTED as the
reason of the AbortError, or with signal.reason when it is set, without relying on the
signal option of pipeTo that the oldest supported engines ignore.
OptionalsignatureThe signature (CRC32 checksum) of the content. This option is ignored if the ZipWriterConstructorOptions#passThrough option
is unset or false.
Use ZipWriterAddDataOptions#crc32 instead.
Optionalstickytrue to set the sticky bit when writing the Unix mode.
Optionalsupportfalse to never write disk numbers in zip64 data.
Optionaltransfertrue to transfer stream ownership to web workers.
OptionaluidThe Unix owner id to write in the Unix extra field or as part of the external attributes.
OptionaluncompressedThe uncompressed size of the entry. This option is ignored if the ZipWriterConstructorOptions#passThrough option is unset
or false. It is required when it is set to true or to "compressed", since the size cannot be derived from data which is not
decompressed.
OptionalunixWhich Unix extra field format to write when creating entries that include Unix metadata.
When ZipFS exports imported entries, their uid/gid are re-emitted as "infozip" regardless of the field type found in the imported zip file, unless this option is set explicitly.
OptionalunixThe Unix mode (st_mode bits) to use when writing external attributes.
The value includes the Unix file type, so it is also how a symbolic link is written: pass
0o120777 and use the path of the link target as the content of the entry. Extractors that
support symbolic links, e.g. Info-ZIP unzip, then restore the entry as a link.
A folder entry is always written with S_IFDIR (0o040000), replacing any file type carried by the
value, so the same mode can be set once on the writer and reused for every entry. Any other entry keeps
the file type it is given, and is written with S_IFREG (0o100000) when the value carries none. Set
ZipWriterConstructorOptions#externalFileAttributes instead to write a mode with no
file type.
Optionalusdztrueto produce zip files compatible with the USDZ specification: the data of the entries is aligned on 64-byte
boundaries and stored uncompressed unless the ZipWriterConstructorOptions#level or
ZipWriterAddDataOptions#compressionMethod options are set explicitly. Setting the
ZipWriterConstructorOptions#password option throws an ERR_UNSUPPORTED_ENCRYPTION_USDZ error.
Writing into a split zip file throws an ERR_UNSUPPORTED_SPLIT_USDZ error, since the 64-byte alignment
of an entry is invalidated when the disk it is written into rolls over.
These constraints apply to the entries written with ZipWriter#add only. The entries copied with ZipWriter#appendZip keep the layout of the source zip file and are not checked, so appending a zip file that does not comply with the USDZ specification, or appending it when the size of the output is not a multiple of 64 bytes, silently produces a non-compliant file.
The option is only read when the ZipWriter is created; a value passed to ZipWriter#add is ignored.
Optionalusetrue to use the native API CompressionStream/DecompressionStream to compress/decompress data.
When compressing, the native API is only used when level is undefined or equal to 6, see ZipWriterConstructorOptions#level.
Optionalusetrue to mark the file names as UTF-8 setting the general purpose bit 11 in the header (see Appendix D -
Language Encoding (EFS)), false to mark the names as compliant with the original IBM Code Page 437.
By default the flag is derived from the content: it is set when the encoded name or the encoded comment of the entry holds a byte outside printable ASCII, and cleared otherwise. Printable ASCII is spelled identically in UTF-8 and in Code Page 437, so the flag carries no information there, and every other writer decides it the same way. A control character is not printable ASCII: Code Page 437 maps the bytes 0x01 to 0x1f and the byte 0x7f to the IBM graphic characters rather than to the control characters themselves, so a name or a comment holding one of them keeps the flag and stays readable. The comment is part of the test because the flag announces its encoding too, so deriving from the name alone would mislabel an ASCII name carrying a comment written in another language.
Note that setting this option only sets the flag, it does not ensure that the file names are in the
correct encoding: when it is set to false, the names are still encoded in UTF-8 unless the
ZipWriterConstructorOptions#encodeText option is also set to encode them in the intended code page.
Setting it to false alone therefore produces an archive whose file names are mislabeled, holding UTF-8
bytes announced as Code Page 437: the names holding characters outside of ASCII are decoded incorrectly
by the readers honoring the flag, including ZipReader unless
GetEntriesOptions#filenameEncoding is set to "utf-8".
Optionalusetrue to use web workers to compress/decompress data in non-blocking background processes.
OptionalversionThe "Version" field, i.e. the minimum version needed to extract the entry.
OptionalversionThe "Version made by" field, whose upper byte is the platform and lower byte the version of the specification.
The platform is not taken from the value passed here. It is forced to Unix (3) when the entry carries Unix
metadata, i.e. when ZipWriterConstructorOptions#uid, ZipWriterConstructorOptions#gid,
ZipWriterConstructorOptions#unixMode or ZipWriterConstructorOptions#unixExtraFieldType is set,
since Unix mode bits stored under another platform are ignored by the extractors. It is forced to MS-DOS (0)
when ZipWriterConstructorOptions#msdosAttributes or
ZipWriterConstructorOptions#msdosAttributesRaw is set. Only the lower byte of the value survives in
both cases.
768, i.e. 3 << 8, or 20 when ZipWriterConstructorOptions#msDosCompatible is set to true
Optionalzip64true to use Zip64 to store the entry.
zip64 is automatically set to true when necessary (e.g. compressed data larger than 4GB or with unknown size).
An entry of unknown size is stored with Zip64 in its local header, because the size of the data descriptor must be
chosen before writing the data. Its central directory record drops Zip64 when the actual sizes fit in 32 bits.
Optionalziptrue to use the ZipCrypto algorithm to encrypt the content of the entry. Setting it to true will also
set the ZipWriterConstructorOptions#dataDescriptor to true.
It is not recommended to set zipCrypto to true because the ZipCrypto encryption can be easily broken.
OptionalencodeThe function called for encoding the filename and the comment of the entry.
zip.js encodes them in UTF-8 when the option is not set, so it must be set to write them in another
code page, together with ZipWriterConstructorOptions#useUnicodeFileNames set to false to
announce them as Code Page 437 instead of UTF-8.
The text to encode.
The type of the encoded text, "filename" or "comment".
The encoded text or undefined if the text should be encoded by zip.js.
OptionalonendThe function called when ending compression/decompression.
The total number of bytes (computed).
An empty promise or undefined.
OptionalonprogressThe function called during compression/decompression.
The current progress in bytes.
The total number of bytes.
An empty promise or undefined.
OptionalonstartThe function called when starting compression/decompression.
The total number of bytes.
An empty promise or undefined.
Represents the options passed to ZipWriter#add.