Optionalchecktrue to throw an ERR_AMBIGUOUS_ARCHIVE error when calling FileEntry#getData if the local
file header of the entry disagrees with its central directory record in a way that could make other tools
(e.g. streaming readers based on local file headers) interpret the entry differently. This detects mismatched
filenames, general purpose bit flags (encryption, data descriptor and language encoding flags), compression
methods, CRC-32 checksums and sizes. The extra fields are not compared because the zip specification allows
them to differ.
This is the boolean form of ZipReaderOptions#strictness: true means "strict" and false means
any value but "strict". When both options are set, the value passed to FileEntry#getData takes
precedence over the value passed to the constructor of ZipReader, and strictness takes precedence
over checkAmbiguity when both are set at the same level. false downgrades an inherited "strict" value
to "balanced" and leaves an inherited "tolerant" value unchanged.
Optionalchecktrue to verify the authentication code of entries encrypted with AES. The verification detects encrypted
data tampered or corrupted after the encryption.
Optionalchecktrue to verify the CRC-32 checksum of the entry against the value stored in the zip file. The verification
is run on the decompressed data and covers the whole read pipeline. It also applies to entries encrypted with
AES in AE-1 format. It is skipped for entries in AE-2 format because they store a zeroed CRC-32 value.
Optionalchecktrue to reject the entry with an ERR_AMBIGUOUS_ARCHIVE error when its local file header
disagrees with its central directory record while calling FileEntry#getData, false to deposit
the differences on EntryMetaData#warnings instead. This is the entry-level half of
ZipReaderOptions#checkAmbiguity, exposed on its own so it can be enabled without the archive-level
checks and disabled without giving up the rest of ZipReaderOptions#strictness. It is the only way to
validate the local file headers of a self-extracting archive, since
GetEntriesOptions#checkAmbiguity rejects prepended data outright.
true compares the filename as well, like ZipReaderOptions#strictness set to "strict"; false
compares everything except the filename, like "tolerant". Set
ZipReaderOptions#checkLocalFilename to control the filename comparison on its own. An explicit
value takes precedence over the strictness default at every level.
true when ZipReaderOptions#strictness is "strict" or "balanced", false when
it is "tolerant".
Optionalchecktrue to compare the filename of the local file header with the one of the central directory record when
calling FileEntry#getData, false to leave the filename out of that comparison.
Comparing the filename costs one extra read per entry whenever the local file header carries no extra
field, which is why it is left out below ZipReaderOptions#strictness set to "strict". This option
selects what is compared without changing whether a difference throws or warns, which
ZipReaderOptions#checkLocalDirectory decides. It is therefore the only way to obtain
WARNING_MISMATCHED_LOCAL_FILE_HEADER_FILENAME as a warning, with
{ checkLocalFilename: true, checkLocalDirectory: false }, and the only way to keep every other check of
"strict" without paying the extra read, with { checkLocalFilename: false, strictness: "strict" }.
the value of ZipReaderOptions#checkLocalDirectory when it is set, otherwise true
when ZipReaderOptions#strictness is "strict" and false when it is "balanced" or
"tolerant".
Optionalchecktrue to throw an ERR_OVERLAPPING_ENTRY error when calling FileEntry#getData if the entry
overlaps with another entry on which FileEntry#getData has already been called (with the option
checkOverlappingEntry or checkOverlappingEntryOnly set to true).
Optionalchecktrue to throw an ERR_OVERLAPPING_ENTRY error when calling FileEntry#getData if the entry
overlaps with another entry on which FileEntry#getData has already been called (with the option
checkOverlappingEntry or checkOverlappingEntryOnly set to true) without trying to read the content of the
entry.
Optionalchecktrue to check only if the password is valid.
Optionalchecktrue to throw an ERR_HTTP_RESOURCE_CHANGED error when the ETag, Last-Modified or total size headers
returned by a range request differ from the ones returned by the first range request, i.e. when the resource has
been modified while being read. Headers missing from the responses are ignored, note that Access-Control-Expose-Headers
must include them when the resource is fetched cross-origin.
Optionalchecktrue to check the CRC-32 checksum of the entry.
Use ZipReaderOptions#checkCrc32 instead.
Optionalcombinetrue to read the end of the archive with the same request that gives its size, and to serve the later reads
landing in that range from the response instead of requesting them again, make sure beforehand that the server
supports a suffix range request.
The request asks for the last 65,557 bytes, which is how far back the reader scans for the end of central directory record, so it fetches nothing the reader was not going to read anyway. An archive shorter than that is fetched whole, and reading it then costs a single request.
OptionalcommentThe encoding of the comment of the entry.
The option is ignored when the general purpose bit 11 is set in the header of the entry, and valid UTF-8 is detected when the option is not set, see GetEntriesOptions#filenameEncoding.
OptionaldecodeThe function called for decoding the filename and the comment of the entry.
The raw text value.
The encoding of the text.
The type of the decoded text, "filename" or "comment".
The decoded text value or undefined if the raw text value should be decoded by zip.js.
OptionaldecryptThe function called for decrypting the central directory when it is encrypted (see the Strong Encryption Specification in the ZIP format specification). Without this function, reading such an archive throws an ERR_ENCRYPTED_CENTRAL_DIRECTORY error. zip.js provides the encrypted data and the related metadata but does not implement the decryption itself.
The raw data stored in place of the central directory, i.e. the decryption header followed by the encrypted (and possibly compressed) central directory, as stored in the zip file.
OptionalencryptionInfo: DirectoryEncryptionInfo
The encryption metadata read from the Zip64 end of central directory record, or
undefined if the zip file does not contain a version 2 record.
The decrypted and decompressed central directory records.
OptionalduplicatesThe policy applied when two entries of the imported zip file claim the same node of the tree
The tree indexes the entries by path, whereas a zip file stores a flat list of filenames, so two
entries can claim one node: they can hold the same filename, hold filenames differing only by the
path components ignored when building the tree (e.g. "a/b.txt" and "./a/b.txt"), or one can be
a file and the other a directory holding it (e.g. "a" and "a/b.txt").
"throw" refuses the zip file with an ERR_DUPLICATE_IMPORTED_ENTRY error, whose cause
property holds the EntryMetaData instance of the entry that could not be imported. The
filesystem is left unchanged, i.e. the entries imported before the error are removed and the
content held before the import is restored.
"keep-first" ignores the entry claiming a node already taken, and "keep-last" replaces the
entry holding the node, which is the behavior of most zip tools. The entries that do not collide
are imported in both cases.
When both entries are directory records, "keep-last" replaces the record held by the node and keeps
the entries already imported below it, which belong to the node rather than to either record. A
directory record claiming a node created implicitly by the entries below it is not a collision, it is
the record that node was missing.
A file claiming a node already holding a directory is the one collision that also drops entries that
did not collide: "keep-last" replaces the directory with the file, and the entries below it go with
it, since a file node cannot hold them. "keep-first" keeps the directory and its entries and ignores
the file instead, so the two policies are mirrors of each other for that shape.
Optionalextracttrue to extract the appended data into ZipReader#appendedData.
Optionalextracttrue to extract the prepended data into ZipReader#prependedData.
OptionalfilenameThe encoding of the filename of the entry.
The option is ignored when the general purpose bit 11 is set in the header of the entry: such a
filename is always decoded as UTF-8. It is only read when the bit is not set. When the option is not
set either, a filename holding bytes outside ASCII is decoded as UTF-8 if they form valid UTF-8, since
many writers store UTF-8 without setting the bit (macOS Archive Utility, ditto, the macOS build of
Info-ZIP zip, Java 6), and as IBM Code Page 437 otherwise. Set the option to decode such filenames
as another legacy encoding instead.
OptionalfilenameHow strictly the filename of each entry should be validated. A rejected name throws an
ERR_UNSAFE_FILENAME error carrying the offending name in its filename property.
"strict": reject the names rejected by "balanced", plus the names that do not map cleanly to a file
path, i.e. empty names, names containing a "." path component or an empty one (e.g. "a//b.txt"), and
names containing a NUL character."balanced": reject names that would escape the directory they are extracted into, i.e. names containing
a ".." path component delimited by slashes or by backslashes (e.g. "..\\file.txt", which a Windows host
resolves as a parent directory), and absolute names, i.e. names starting with "/", with a drive letter
(e.g. "C:/file.txt") or with a backslash (root-relative and UNC paths on Windows)."tolerant": never reject a name.A backslash is otherwise not interpreted as a path separator: it is a valid filename character on UNIX systems, and it also occurs as the trail byte of legitimate double-byte filenames (e.g. CP932) decoded with another charset.
Names are validated, never rewritten, so the filename reported for an entry always matches its central directory record.
The value of GetEntriesOptions#strictness.
Optionalforcetrue to always use Range headers when fetching data.
OptionalheadersThe HTTP headers.
OptionalmaxThe maximum number of bytes tolerated after the zip structure before the archive is rejected. Defaults to
0 when GetEntriesOptions#strictness is "strict", 65535 when it is "balanced", and Infinity
when it is "tolerant".
An explicit value takes precedence over the strictness default at every level, so it can loosen "strict"
or reintroduce a rejection under "tolerant". It also bounds how far back the end of central directory
record is searched for, so a value smaller than the amount of data actually appended surfaces an
ERR_EOCDR_NOT_FOUND error when the record lies beyond the searched region and an
ERR_AMBIGUOUS_ARCHIVE error otherwise.
OptionalmaximumThe maximum size in bytes of the range requests sent to read the data of an entry. The data is read with as many range requests as necessary, each response body being streamed, so that the size of a request never depends on the size of the entry.
Because response bodies are streamed with backpressure, this value does not bound how much data
is buffered in memory; it bounds the byte span, and therefore the lifetime, of each individual
range request. Smaller windows keep each request short-lived, which avoids the idle or duration
timeouts enforced by servers, CDNs and proxies when a slow consumer holds a connection open, and
avoids relying on the server honoring very large ranges. Set it to Infinity to disable windowing
and read each entry with a single range request covering its whole remaining length.
OptionalnormalizeThe function called for normalizing the filename of each entry, e.g. to repair the names rejected by GetEntriesOptions#filenameValidation.
It is called with the decoded filename, after GetEntriesOptions#decodeText and before the name is
validated, so a name it fails to repair is still rejected. The returned name becomes the name of the entry:
it is used to detect directory entries by their trailing "/", and to detect duplicate filenames when
GetEntriesOptions#checkAmbiguity is set, so two names normalized into the same name are reported as
an ERR_AMBIGUOUS_ARCHIVE error instead of silently shadowing each other. The raw filename remains
available in EntryMetaData#rawFilename.
The decoded filename.
The normalized filename or undefined to keep the decoded filename.
Optionalpasstrue to import the entries of the zip file as-is, without decompressing and decrypting them
Only a boolean, where ZipReaderOptions#passThrough also takes "compressed": the
filesystem copies each entry through a writer, which has nowhere to put content that is still
compressed. "compressed" throws an ERR_UNSUPPORTED_PASS_THROUGH_VALUE error.
OptionalpasswordThe password used to decrypt the content of the entry.
Optionalpreventtrue to prevent closing of WritableWriter#writable when calling FileEntry#getData.
It only applies to the writable owned by the caller. It is ignored by the Writer instances returning the written data, such as BlobWriter or TextWriter, whose writable is created internally and must be closed for Writer#getData to resolve.
Optionalpreventtrue to prevent using HEAD HTTP request in order the get the size of the content.
false to explicitly use HEAD, this is useful in case of CORS where Access-Control-Expose-Headers: Content-Range is not returned by the server.
Leaving it unset is not the same as setting it to false when HttpOptions#useRangeHeader or
HttpOptions#forceRangeRequests is set: the size is then read from a ranged GET request instead, and
only an explicit false restores the HEAD request.
false, and true when HttpOptions#useRangeHeader or HttpOptions#forceRangeRequests is set
OptionalrawThe password used to encrypt the content of the entry (raw).
OptionalsignalThe AbortSignal instance used to cancel the decompression.
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.
OptionalstrictnessHow tolerant the reader should be when the local file header of an entry disagrees with its central directory record.
"strict": compare the filename, the general purpose bit flag, the compression method, the CRC-32
checksum and the sizes, and throw an ERR_AMBIGUOUS_ARCHIVE error on any difference."balanced": compare everything except the filename, and throw on any difference."tolerant": compare everything except the filename, and deposit the differences on
EntryMetaData#warnings instead of throwing.Every field except the filename is read from the local file header anyway, to locate the entry data, so
the comparison "balanced" performs reads no additional bytes. Comparing the filename reads the filename
bytes as well, which costs one extra read per entry whenever the local file header carries no extra field
— the common case in practice, and the reason the filename is left out below "strict". Use
ZipReaderOptions#checkLocalDirectory to request or suppress the whole comparison explicitly, and
ZipReaderOptions#checkLocalFilename to include or exclude the filename on its own.
Optionaltransfertrue to transfer stream ownership to web workers.
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 use Range headers when fetching data from servers returning Accept-Ranges headers.
Optionalusetrue to use web workers to compress/decompress data in non-blocking background processes.
Optionalusetrue to rely XMLHttpRequest instead of fetch to fetch data.
OptionalfetchThe function used to fetch the data. It takes precedence over HttpRangeOptions#useXHR
when set. The returned object must expose the status, statusText and headers properties,
and the arrayBuffer() method of the Response class.
Optionalinit: RequestInit
Represents the options passed to ZipDirectoryEntry#importHttpContent.