@zip.js/zip.js 2.8.51 → 2.8.53

package/index.d.ts

@@ -272,7 +272,7 @@ export interface Configuration extends WorkerConfiguration {
   /**
    * The maximum number of web workers used to compress/decompress data simultaneously.
    *
-   * @defaultValue `navigator.hardwareConcurrency`
+   * @defaultValue `navigator.hardwareConcurrency`, or 2 when the environment does not provide it
    */
   maxWorkers?: number;
   /**
@@ -311,7 +311,7 @@ export interface Configuration extends WorkerConfiguration {
    * });
    * ```
    *
-   * @defaultValue "./core/web-worker.js"
+   * @defaultValue "./core/web-worker-wasm.js", or "./core/web-worker-native.js" for the builds using the native implementations
    */
   workerURI?: string;
   /**
@@ -351,25 +351,25 @@ export interface Configuration extends WorkerConfiguration {
   /**
    * The stream implementation used to compress data when `useCompressionStream` is set to `true`.
    *
-   * @defaultValue {@link CodecStream}
+   * @defaultValue the global `CompressionStream`, or `false` when the environment does not provide it
    */
   CompressionStream?: typeof TransformStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `true`.
    *
-   * @defaultValue {@link CodecStream}
+   * @defaultValue the global `DecompressionStream`, or `false` when the environment does not provide it
    */
   DecompressionStream?: typeof TransformStreamLike;
   /**
    * The stream implementation used to compress data when `useCompressionStream` is set to `false`.
    *
-   * @defaultValue {@link CodecStream}
+   * @defaultValue the implementation embedded in the entry point that was imported, e.g. the WebAssembly one
    */
   CompressionStreamFallback?: typeof TransformStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `false`.
    *
-   * @defaultValue {@link CodecStream}
+   * @defaultValue the implementation embedded in the entry point that was imported, e.g. the WebAssembly one
    */
   DecompressionStreamFallback?: typeof TransformStreamLike;
   /**
@@ -395,6 +395,8 @@ export interface WorkerConfiguration {
   /**
    * `true` 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 {@link ZipWriterConstructorOptions#level}.
+   *
    * @defaultValue true
    */
   useCompressionStream?: boolean;
@@ -722,7 +724,11 @@ export class Data64URIReader extends Reader<string> {}
 export class Uint8ArrayReader extends Reader<Uint8Array> {}
 
 /**
- * Represents a {@link Reader} instance used to read data provided as an array of {@link ReadableReader} instances (e.g. split zip files).
+ * Represents a {@link Reader} instance used to read data provided as an array of {@link Reader} instances,
+ * {@link ReadableReader} instances or `ReadableStream` instances (e.g. split zip files).
+ *
+ * @remarks Elements that only provide a `ReadableStream` are buffered when the reader is initialized, since
+ * mapping a global offset onto a disk requires the size of every disk.
  */
 export class SplitDataReader extends Reader<
   Reader<unknown>[] | ReadableReader[] | ReadableStream[]
@@ -781,7 +787,11 @@ export interface HttpOptions extends HttpRangeOptions {
    * `true` 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.
    *
-   * @defaultValue false
+   * Leaving it unset is not the same as setting it to `false` when {@link HttpOptions#useRangeHeader} or
+   * {@link HttpOptions#forceRangeRequests} is set: the size is then read from a ranged `GET` request instead, and
+   * only an explicit `false` restores the `HEAD` request.
+   *
+   * @defaultValue false, and `true` when {@link HttpOptions#useRangeHeader} or {@link HttpOptions#forceRangeRequests} is set
    */
   preventHeadRequest?: boolean;
   /**
@@ -1152,6 +1162,12 @@ export class ZipReader<Type> {
   ): AsyncGenerator<Entry, boolean>;
   /**
    * Closes the zip file
+   *
+   * @remarks It cancels the `ReadableStream` instance passed to the constructor when nothing has been read
+   * from it, which is the only resource a {@link ZipReader} instance can hold. It does nothing otherwise: the
+   * stream is already consumed once {@link ZipReader#getEntries} has read the entries into memory, and the
+   * {@link Reader} instances are never closed, they belong to the caller. The entries returned by
+   * {@link ZipReader#getEntries} can therefore still be read after calling it.
    */
   close(): Promise<void>;
 }
@@ -1213,6 +1229,12 @@ export interface GetEntriesOptions {
    * the content of an entry, it also validates the local file header against the central directory record (see
    * {@link ZipReaderOptions#checkAmbiguity}).
    *
+   * This is the boolean form of {@link GetEntriesOptions#strictness}: `true` means `"strict"` and `false` means
+   * any value but `"strict"`. When both options are set, the value passed to {@link ZipReader#getEntries} takes
+   * precedence over the value passed to the constructor of {@link 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.
+   *
    * @defaultValue false
    */
   checkAmbiguity?: boolean;
@@ -1354,9 +1376,18 @@ export interface DirectoryEncryptionInfo {
 export interface ZipReaderOptions {
   /**
    * How tolerant the reader should be when the local file header of an entry disagrees with its central
-   * directory record. `"strict"` throws an {@link ERR_AMBIGUOUS_ARCHIVE} error (equivalent to
-   * {@link ZipReaderOptions#checkAmbiguity} set to `true`); `"balanced"` and `"tolerant"` trust the central
-   * directory record.
+   * directory record. Any difference throws an {@link ERR_AMBIGUOUS_ARCHIVE} error.
+   *
+   * - `"strict"`: compare the filename, the general purpose bit flag, the compression method, the CRC-32
+   * checksum and the sizes.
+   * - `"balanced"`: compare everything except the filename.
+   * - `"tolerant"`: compare nothing and trust the central directory record.
+   *
+   * 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. Use {@link ZipReaderOptions#checkLocalDirectory} to request or suppress the
+   * whole comparison explicitly.
    *
    * @defaultValue "balanced"
    */
@@ -1369,9 +1400,31 @@ export interface ZipReaderOptions {
    * 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 {@link ZipReaderOptions#strictness}: `true` means `"strict"` and `false` means
+   * any value but `"strict"`. When both options are set, the value passed to {@link FileEntry#getData} takes
+   * precedence over the value passed to the constructor of {@link 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.
+   *
    * @defaultValue false
    */
   checkAmbiguity?: boolean;
+  /**
+   * `true` to validate the local file header of the entry against its central directory record when calling
+   * {@link FileEntry#getData}, `false` to skip that validation. This is the entry-level half of
+   * {@link ZipReaderOptions#checkAmbiguity}, exposed on its own so it can be enabled without the archive-level
+   * checks and disabled without giving up the rest of {@link ZipReaderOptions#strictness}. It is the only way to
+   * validate the local file headers of a self-extracting archive, since
+   * {@link GetEntriesOptions#checkAmbiguity} rejects prepended data outright.
+   *
+   * `true` compares the filename as well, like {@link ZipReaderOptions#strictness} set to `"strict"`; `false`
+   * compares nothing, like `"tolerant"`. An explicit value takes precedence over the strictness default at
+   * every level.
+   *
+   * @defaultValue `true` when {@link ZipReaderOptions#strictness} is `"strict"` or `"balanced"`, `false` when
+   * it is `"tolerant"`.
+   */
+  checkLocalDirectory?: boolean;
   /**
    * `true` to check only if the password is valid.
    *
@@ -1435,7 +1488,12 @@ export interface ZipReaderOptions {
    */
   signal?: AbortSignal;
   /**
-   * `true` to prevent closing of {@link Writer#writable} when calling {@link FileEntry#getData}.
+   * `true` to prevent closing of {@link WritableWriter#writable} when calling {@link FileEntry#getData}.
+   *
+   * @remarks
+   * It only applies to the writable owned by the caller. It is ignored by the {@link Writer} instances
+   * returning the written data, such as {@link BlobWriter} or {@link TextWriter}, whose writable is
+   * created internally and must be closed for {@link Writer#getData} to resolve.
    *
    * @defaultValue false
    */
@@ -1490,9 +1548,14 @@ export interface EntryExtraFieldAES extends EntryExtraField {
    */
   vendorId?: number;
   /**
-   * The compression method stored in the AES extra field.
+   * The compression method stored in the header of the entry, i.e. `99` for a WinZip AES entry.
    */
   originalCompressionMethod?: number;
+  /**
+   * The real compression method of the entry, stored in the AES extra field because the header carries `99`
+   * instead. This is the value reported by {@link EntryMetaData#compressionMethod}.
+   */
+  compressionMethod?: number;
 }
 /**
  * Represents a Unix extra field record storing timestamps: the Info-ZIP Unix type 1 extra field (0x5855),
@@ -1526,7 +1589,149 @@ export interface EntryExtraFieldUnicode extends EntryExtraField {
    * `true` if the extra field is consistent with the entry metadata.
    */
   valid?: boolean;
+  /**
+   * The version of the extra field.
+   */
+  version?: number;
+  /**
+   * The filename stored in the extra field, when it is a Unicode path extra field (0x7075).
+   */
+  filename?: string;
+  /**
+   * The comment stored in the extra field, when it is a Unicode comment extra field (0x6375).
+   */
+  comment?: string;
 }
+/**
+ * Represents the Zip64 extra field record of an entry. Each property is only defined when the matching field
+ * of the header was set to its maximum value, i.e. when the real value had to be stored in the extra field.
+ */
+export interface EntryExtraFieldZip64 extends EntryExtraField {
+  /**
+   * The uncompressed size of the entry.
+   */
+  uncompressedSize?: number;
+  /**
+   * The compressed size of the entry.
+   */
+  compressedSize?: number;
+  /**
+   * The offset of the local file header of the entry.
+   */
+  offset?: number;
+  /**
+   * The number of the disk where the entry data starts.
+   */
+  diskNumberStart?: number;
+}
+/**
+ * Represents the NTFS extra field record of an entry (0x000a), storing the dates as Windows `FILETIME` values.
+ */
+export interface EntryExtraFieldNTFS extends EntryExtraField {
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The creation date.
+   */
+  creationDate?: Date;
+  /**
+   * The last modification date (raw), as a Windows `FILETIME` value.
+   */
+  rawLastModDate?: bigint;
+  /**
+   * The last access date (raw), as a Windows `FILETIME` value.
+   */
+  rawLastAccessDate?: bigint;
+  /**
+   * The creation date (raw), as a Windows `FILETIME` value.
+   */
+  rawCreationDate?: bigint;
+}
+/**
+ * Represents the extended timestamp extra field record of an entry (0x5455), storing the dates as 32-bit Unix
+ * times. The central directory record only carries the last modification date, the local file header carries
+ * the dates selected by the flags of the extra field.
+ */
+export interface EntryExtraFieldExtendedTimestamp extends EntryExtraField {
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The creation date.
+   */
+  creationDate?: Date;
+  /**
+   * The last modification date (raw), as a 32-bit Unix time.
+   */
+  rawLastModDate?: number;
+  /**
+   * The last access date (raw), as a 32-bit Unix time.
+   */
+  rawLastAccessDate?: number;
+  /**
+   * The creation date (raw), as a 32-bit Unix time.
+   */
+  rawCreationDate?: number;
+}
+/**
+ * Represents a Unix extra field record storing ownership: the Info-ZIP "new" Unix extra field (0x7875), read
+ * into {@link EntryMetaData#extraFieldInfoZip}, or the Info-ZIP "old" Unix extra field (0x7855), read into
+ * {@link EntryMetaData#extraFieldUnix}.
+ */
+export interface EntryExtraFieldUnix extends EntryExtraField {
+  /**
+   * The version of the extra field, only defined for the Info-ZIP "new" Unix extra field (0x7875).
+   */
+  version?: number;
+  /**
+   * The Unix user id.
+   */
+  uid?: number;
+  /**
+   * The Unix group id.
+   */
+  gid?: number;
+}
+/**
+ * Represents the data descriptor record written after the content of an entry, when
+ * {@link EntryBitFlag#dataDescriptor} is set.
+ */
+export interface LocalDataDescriptor {
+  /**
+   * `true` if the record is preceded by its optional signature.
+   *
+   * The signature is not part of the original format, it is a later convention writers are free to follow. It is
+   * reported as absent when the values following it disagree with the central directory, since the record is then
+   * read as starting at the first byte.
+   */
+  signature: boolean;
+  /**
+   * The CRC-32 checksum stored in the record, which is allowed to differ from {@link EntryMetaData#crc32}.
+   */
+  crc32: number;
+  /**
+   * The compressed size stored in the record, which is allowed to differ from
+   * {@link EntryMetaData#compressedSize}.
+   */
+  compressedSize: number;
+  /**
+   * The uncompressed size stored in the record, which is allowed to differ from
+   * {@link EntryMetaData#uncompressedSize}.
+   */
+  uncompressedSize: number;
+}
+
 /**
  * Represents the local file header fields of an entry, read when getting the entry data.
  */
@@ -1571,6 +1776,23 @@ export interface LocalDirectory {
    * The extra field.
    */
   extraField?: Map<number, EntryExtraField>;
+  /**
+   * The filename of the entry stored in the local file header (raw), which is allowed to differ from
+   * {@link EntryMetaData#rawFilename}.
+   *
+   * Only defined when the local filename has been read, i.e. when the {@link ZipReaderOptions#strictness} option
+   * is set to `"strict"` or when the {@link ZipReaderOptions#checkLocalDirectory} option is set to `true`, since
+   * reading it costs one read the central directory does not need.
+   */
+  rawFilename?: Uint8Array;
+  /**
+   * The data descriptor record written after the content, when the entry has one.
+   *
+   * Only defined when the record has been read, i.e. when the {@link ZipReaderOptions#checkOverlappingEntry} or
+   * the {@link ZipReaderOptions#checkOverlappingEntryOnly} option is set to `true`, since the sizes stored in the
+   * central directory make it unnecessary to read it otherwise.
+   */
+  dataDescriptor?: LocalDataDescriptor;
   /**
    * The CRC-32 checksum of the content.
    */
@@ -1596,7 +1818,7 @@ export interface LocalDirectory {
   /**
    * The Zip64 extra field.
    */
-  extraFieldZip64?: EntryExtraField;
+  extraFieldZip64?: EntryExtraFieldZip64;
   /**
    * The AES extra field.
    */
@@ -1604,15 +1826,18 @@ export interface LocalDirectory {
   /**
    * The NTFS extra field.
    */
-  extraFieldNTFS?: EntryExtraField;
+  extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
-   * The Unix extra field.
+   * The Info-ZIP Unix type 2 extra field (0x7855). Its uid/gid are stored in the local file header only, the
+   * central directory version carries no data and merely flags their presence.
    */
-  extraFieldUnix?: EntryExtraField;
+  extraFieldUnix?: EntryExtraFieldUnix;
   /**
-   * The Info-ZIP Unix extra field.
+   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It is read
+   * whenever the type 2 extra field (0x7855) is absent or carries no ids, which is its usual state in the
+   * central directory.
    */
-  extraFieldInfoZip?: EntryExtraField;
+  extraFieldInfoZip?: EntryExtraFieldUnix;
   /**
    * The Info-ZIP Unix type 1 extra field (0x5855).
    */
@@ -1624,7 +1849,7 @@ export interface LocalDirectory {
   /**
    * The extended timestamp extra field.
    */
-  extraFieldExtendedTimestamp?: EntryExtraField;
+  extraFieldExtendedTimestamp?: EntryExtraFieldExtendedTimestamp;
   /**
    * The Unicode path extra field.
    */
@@ -1694,8 +1919,26 @@ export interface EntryMetaData {
   filenameUTF8: boolean;
   /**
    * `true` if the entry is an executable file
+   *
+   * Always `false` when {@link EntryMetaData#symlink} is `true`: the permissions of a symbolic link
+   * are not meaningful, Unix systems store them as `0o777`.
    */
   executable: boolean;
+  /**
+   * `true` if the entry is a symbolic link, i.e. if the Unix file type stored in
+   * {@link EntryMetaData#externalFileAttributes} is `S_IFLNK` (`0o120000`).
+   *
+   * The target of the link is the content of the entry, stored as a path with no trailing NUL
+   * character. It is read like any other entry, e.g. with `entry.getData(new TextWriter())`.
+   *
+   * The path is not validated: it can be absolute or escape the archive with `..` segments. It must
+   * be checked before being used to resolve a file.
+   *
+   * There is no option to write a symbolic link. Set the file type in
+   * {@link ZipWriterConstructorOptions#unixMode} instead, i.e. pass `0o120777` with the path of the
+   * target as the content of the entry.
+   */
+  symlink: boolean;
   /**
    * `true` if the content of the entry is encrypted.
    */
@@ -1725,15 +1968,19 @@ export interface EntryMetaData {
    */
   creationDate?: Date;
   /**
-   * The last modification date (raw).
+   * The last modification date (raw), as the MS-DOS date and time stored in the header. Unlike
+   * {@link EntryMetaData#lastModDate}, it is not replaced by the value of the NTFS extra field when that field
+   * is present; read {@link EntryMetaData#extraFieldNTFS} for the raw NTFS value.
    */
   rawLastModDate: number | bigint;
   /**
-   * The last access date (raw).
+   * The last access date (raw), as the Windows `FILETIME` value stored in the NTFS extra field. Only defined
+   * when that extra field is present.
    */
   rawLastAccessDate?: number | bigint;
   /**
-   * The creation date (raw).
+   * The creation date (raw), as the Windows `FILETIME` value stored in the NTFS extra field. Only defined when
+   * that extra field is present.
    */
   rawCreationDate?: number | bigint;
   /**
@@ -1819,10 +2066,21 @@ export interface EntryMetaData {
   };
   /**
    * Unix owner id when available.
+   *
+   * The value is read from the central directory. The Info-ZIP Unix extra fields type 1 (0x5855) and type 2
+   * (0x7855) store the ids in the local file header only, so entries carrying just these fields leave the
+   * property undefined until the data has been read, at which point it is filled in from
+   * {@link EntryMetaData#localDirectory}. The Info-ZIP New Unix extra field (0x7875) and the PKWARE Unix
+   * extra field (0x000d) store the ids in both headers and are unaffected.
+   *
+   * @remarks A value read from the central directory is never overwritten by the local file header, since the
+   * type 2 field truncates the ids to 16 bits while the New Unix field does not.
    */
   uid?: number;
   /**
    * Unix group id when available.
+   *
+   * See {@link EntryMetaData#uid} for the fields storing the ids in the local file header only.
    */
   gid?: number;
   /**
@@ -1898,7 +2156,7 @@ export interface EntryMetaData {
   /**
    * The Zip64 extra field.
    */
-  extraFieldZip64?: EntryExtraField;
+  extraFieldZip64?: EntryExtraFieldZip64;
   /**
    * The AES extra field.
    */
@@ -1906,15 +2164,18 @@ export interface EntryMetaData {
   /**
    * The NTFS extra field.
    */
-  extraFieldNTFS?: EntryExtraField;
+  extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
-   * The Unix extra field.
+   * The Info-ZIP Unix type 2 extra field (0x7855). Its uid/gid are stored in the local file header only, the
+   * central directory version carries no data and merely flags their presence.
    */
-  extraFieldUnix?: EntryExtraField;
+  extraFieldUnix?: EntryExtraFieldUnix;
   /**
-   * The Info-ZIP Unix extra field.
+   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It is read
+   * whenever the type 2 extra field (0x7855) is absent or carries no ids, which is its usual state in the
+   * central directory.
    */
-  extraFieldInfoZip?: EntryExtraField;
+  extraFieldInfoZip?: EntryExtraFieldUnix;
   /**
    * The Info-ZIP Unix type 1 extra field (0x5855).
    */
@@ -1926,7 +2187,7 @@ export interface EntryMetaData {
   /**
    * The extended timestamp extra field.
    */
-  extraFieldExtendedTimestamp?: EntryExtraField;
+  extraFieldExtendedTimestamp?: EntryExtraFieldExtendedTimestamp;
   /**
    * The Unicode path extra field.
    */
@@ -1941,6 +2202,11 @@ export interface EntryMetaData {
   extraFieldUSDZ?: EntryExtraField;
   /**
    * The local file header fields, set when the entry data has been read.
+   *
+   * The local file header is the only place where the Info-ZIP Unix extra fields type 1 (0x5855) and type 2
+   * (0x7855) store the uid/gid, so this is where they are read for entries carrying just these fields, e.g.
+   * with `entry.localDirectory.extraFieldUnixType1.uid`. The values are not merged into
+   * {@link EntryMetaData#uid} and {@link EntryMetaData#gid}, which are read from the central directory.
    */
   localDirectory?: LocalDirectory;
 }
@@ -2312,6 +2578,12 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * 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.
+   *
    * @defaultValue 6
    */
   level?: number;
@@ -2331,6 +2603,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * 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 {@link createOPFSTempStream} for a ready-made OPFS-backed implementation, {@link createSyncAccessHandleTempStream} for a faster worker-only variant, and {@link createBlobTempStream} for a `Blob`-backed one.
+   *
+   * @remarks 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.
    */
   createTempStream?: () => TempStream | Promise<TempStream>;
   /**
@@ -2380,7 +2659,8 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * This option is ignored if the {@link ZipWriterConstructorOptions#extendedTimestamp} option is set to `false`.
    *
-   * @defaultValue The current date.
+   * Unlike {@link 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.
    */
   lastAccessDate?: Date;
   /**
@@ -2388,7 +2668,8 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * This option is ignored if the {@link ZipWriterConstructorOptions#extendedTimestamp} option is set to `false`.
    *
-   * @defaultValue The current date.
+   * Unlike {@link 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.
    */
   creationDate?: Date;
   /**
@@ -2423,9 +2704,18 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   version?: number;
   /**
-   * The "Version made by" field.
+   * The "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 {@link ZipWriterConstructorOptions#uid}, {@link ZipWriterConstructorOptions#gid},
+   * {@link ZipWriterConstructorOptions#unixMode} or {@link 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 {@link ZipWriterConstructorOptions#msdosAttributes} or
+   * {@link ZipWriterConstructorOptions#msdosAttributesRaw} is set. Only the lower byte of the value survives in
+   * both cases.
    *
-   * @defaultValue 20
+   * @defaultValue 768, i.e. `3 << 8`, or 20 when {@link ZipWriterConstructorOptions#msDosCompatible} is set to `true`
    */
   versionMadeBy?: number;
   /**
@@ -2455,6 +2745,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * `true` to write {@link EntryMetaData#externalFileAttributes} in MS-DOS format for folder entries.
    *
+   * It also selects the MS-DOS platform for {@link ZipWriterConstructorOptions#versionMadeBy} and leaves the Unix
+   * attributes out of the entries. Setting any Unix metadata option, e.g.
+   * {@link ZipWriterConstructorOptions#unixMode}, turns it back off.
+   *
    * @defaultValue false
    */
   msDosCompatible?: boolean;
@@ -2467,6 +2761,12 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * attribute for folder entries, Unix default permissions when `msDosCompatible` is `false`).
    */
   externalFileAttributes?: number;
+  /**
+   * The external file attribute.
+   *
+   * @deprecated Use {@link ZipWriterConstructorOptions#externalFileAttributes} instead.
+   */
+  externalFileAttribute?: number;
   /**
    * The Unix owner id to write in the Unix extra field or as part of the external attributes.
    */
@@ -2477,6 +2777,16 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   gid?: number;
   /**
    * The 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
+   * {@link ZipWriterConstructorOptions#externalFileAttributes} instead to write a mode with no
+   * file type.
    */
   unixMode?: number;
   /**
@@ -2505,6 +2815,12 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * @defaultValue 0
    */
   internalFileAttributes?: number;
+  /**
+   * The internal file attribute.
+   *
+   * @deprecated Use {@link ZipWriterConstructorOptions#internalFileAttributes} instead.
+   */
+  internalFileAttribute?: number;
   /**
    * When provided, the low 8-bit MS-DOS attributes to write into external file attributes.
    * Must be an integer between 0 and 255.
@@ -2537,6 +2853,16 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   usdz?: boolean;
   /**
    * `true` to write the data as-is without compressing it and without crypting it.
+   *
+   * @remarks
+   * The {@link ZipWriterConstructorOptions#level} and {@link ZipWriterAddDataOptions#compressionMethod} options
+   * do not apply to data written as-is, and the entries with no content, e.g. the directories, ignore this
+   * option entirely. Setting the {@link ZipWriterConstructorOptions#password} or the
+   * {@link ZipWriterConstructorOptions#rawPassword} option throws an
+   * {@link ERR_UNSUPPORTED_ENCRYPTION_PASS_THROUGH} error, unless the
+   * {@link 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.
    */
   passThrough?: boolean;
   /**
@@ -2563,6 +2889,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
 
 /**
  * Represents options passed to {@link FileEntry#getData}, {@link ZipWriter.add} and `{@link ZipDirectory}.export*`.
+ *
+ * @remarks
+ * When passed to `{@link ZipDirectory}.export*`, these functions report the progress of the whole archive instead
+ * of the progress of each entry: {@link EntryDataOnprogressOptions#onstart} and
+ * {@link EntryDataOnprogressOptions#onend} are called once, and the total number of bytes is the sum of the sizes
+ * of all the entries. Use {@link ZipDirectoryEntryExportOptions#onentryprogress} to be notified when each entry
+ * is written.
  */
 export interface EntryDataOnprogressOptions {
   /**
@@ -2630,6 +2963,10 @@ declare class ZipEntry {
   parent?: ZipEntry;
   /**
    * The uncompressed size of the content.
+   *
+   * @remarks It is the size of the raw compressed content when the entry has been imported with the
+   * `passThrough` option set to `true`, since the entry holds the compressed data in that case. The
+   * uncompressed size of the original entry remains available in {@link ZipEntry#data}.
    */
   uncompressedSize: number;
   /**
@@ -2932,6 +3269,10 @@ export class ZipDirectoryEntry extends ZipEntry {
   /**
    * Adds an entry with content provided via a `FileSystemEntry` instance
    *
+   * The options apply to every entry added, including the directories. The
+   * {@link ZipWriterConstructorOptions#lastModDate} option replaces the last modification date of the
+   * files, which is otherwise taken from each `FileSystemEntry` instance.
+   *
    * @param fileSystemEntry The `FileSystemEntry` instance.
    * @param options The options.
    * @returns A promise resolving to an array of {@link ZipFileEntry} or a {@link ZipDirectoryEntry} instances.
@@ -2947,6 +3288,10 @@ export class ZipDirectoryEntry extends ZipEntry {
    * whose {@link EntryError#entryName} is the path of the handle that failed, relative to the parent
    * of `fileSystemHandle`.
    *
+   * The options apply to every entry added, including the directories. The
+   * {@link ZipWriterConstructorOptions#lastModDate} option replaces the last modification date of the
+   * files, which is otherwise taken from each `FileSystemHandle` instance.
+   *
    * @param fileSystemHandle The `fileSystemHandle` instance.
    * @param options The options.
    * @returns A promise resolving to an array of {@link ZipFileEntry} or a {@link ZipDirectoryEntry} instances.
@@ -2960,6 +3305,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param blob The `Blob` instance.
    * @param options  The options.
+   *
+   * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
+   * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
    */
   importBlob(
     blob: Blob,
@@ -2970,6 +3318,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param dataURI The Data URI `string` encoded in Base64.
    * @param options  The options.
+   *
+   * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
+   * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
    */
   importData64URI(
     dataURI: string,
@@ -2980,6 +3331,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param array The `Uint8Array` instance.
    * @param options  The options.
+   *
+   * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
+   * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
    */
   importUint8Array(
     array: Uint8Array,
@@ -2990,6 +3344,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param url The URL.
    * @param options  The options.
+   *
+   * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
+   * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
    */
   importHttpContent(
     url: string,
@@ -3000,21 +3357,30 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param readable The `ReadableStream` instance.
    * @param options  The options.
+   *
+   * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
+   * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
    */
   importReadable(
     readable: ReadableStream,
     options?: ZipReaderConstructorOptions
   ): Promise<[ZipEntry]>;
   /**
-   * Extracts a zip file provided via a custom {@link Reader} instance into the entry
+   * Extracts a zip file provided via a custom {@link Reader} instance or a {@link ZipReader} instance into
+   * the entry
    *
-   * @param reader The {@link Reader} instance.
+   * @param reader The {@link Reader} instance or the {@link ZipReader} instance.
    * @param options  The options.
    *
    * @remarks The filename of each entry is split into path components to build the tree of entries. Empty
    * components and `"."` components are ignored, so `"a//b.txt"`, `"./a/b.txt"` and `"a/./b.txt"` all produce
    * the same `"a/b.txt"` entry. Filenames are normalized and validated beforehand, see
    * {@link GetEntriesOptions#normalizeFilename} and {@link GetEntriesOptions#filenameValidation}.
+   *
+   * Passing a {@link ZipReader} instance is the way to read the data of the zip file itself, e.g. its
+   * {@link ZipReader#prependedData} or its {@link ZipReader#comment} property, since the instance created
+   * otherwise is not exposed. Its options are used as defaults for the options passed here, and it must not
+   * have read its entries yet when it is created over a `ReadableStream` instance, which can only be read once.
    */
   importZip(
     reader:
@@ -3023,7 +3389,8 @@ export class ZipDirectoryEntry extends ZipEntry {
       | ReadableStream
       | Reader<unknown>[]
       | ReadableReader[]
-      | ReadableStream[],
+      | ReadableStream[]
+      | ZipReader<unknown>,
     options?: ZipReaderConstructorOptions
   ): Promise<[ZipEntry]>;
   /**
@@ -3081,7 +3448,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    * Running the same export again is the supported way to recover, since directories are merged and
    * files are overwritten.
    *
-   * @remarks An entry flagged as a symbolic link by its {@link EntryMetaData#externalFileAttributes} is written
+   * @remarks An entry flagged as a symbolic link by {@link EntryMetaData#symlink} is written
    * as a regular file whose content is the path of the link target, because the File System Access API cannot
    * create symbolic links.
    *
@@ -3108,6 +3475,34 @@ export class ZipDirectoryEntry extends ZipEntry {
       | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream>,
     options?: ZipDirectoryEntryExportOptions
   ): Promise<unknown>;
+  /**
+   * Computes the exact size in bytes of the zip file that `export*()` would produce for the entry
+   * and its descendants, without reading or compressing any data.
+   *
+   * Pass the same options object that will be passed to the export method, otherwise the result
+   * will not match. The size is only determinable when every descendant is stored (i.e. `level` is
+   * set to 0) or passed through, and has a known size; {@link ERR_UNDETERMINED_SIZE} is thrown
+   * otherwise. Encryption does not prevent it, the overhead of ZipCrypto and AES being fixed.
+   *
+   * The intended use is setting the `Content-Length` header of a zip file streamed over HTTP.
+   *
+   * @remarks Entries added with {@link ZipDirectoryEntry#addReadable} never have a known size, and
+   * entries added with {@link ZipDirectoryEntry#addHttpContent} only get one once their content has
+   * been read. The returned size assumes a single output file, it does not apply to split zip files.
+   *
+   * {@link ERR_UNDETERMINED_SIZE} is also thrown when the size depends on the order in which the
+   * entries are physically written, which the buffered write path only determines at write time.
+   * This happens when `usdz` is set, since the alignment padding depends on the offset of each
+   * entry, and when the archive exceeds 4GB, since the offsets recorded in the central directory
+   * are then extended to 64 bits. Passing `bufferedWrite: false` makes both determinable again,
+   * as does exporting a directory whose children are all files. It is thrown as well when
+   * `signCentralDirectory` is set, the length of the signature being unknown until it is computed.
+   *
+   * @param options The options.
+   * @returns A promise resolving to the size in bytes.
+   * @throws {@link ERR_UNDETERMINED_SIZE} if the size cannot be determined.
+   */
+  getExportedSize(options?: ZipDirectoryEntryExportOptions): Promise<number>;
 }
 
 /**
@@ -3131,6 +3526,37 @@ export interface ZipDirectoryEntryGetChildrenOptions {
 
 /**
  * Represents the options passed to `{@link ZipDirectoryEntry}#export*()`.
+ *
+ * @remarks
+ * The options set here apply to every entry of the exported zip file, including the entries imported
+ * from a zip file: such an entry keeps the metadata of the entry it was imported from, e.g. its
+ * {@link ZipWriterConstructorOptions#lastModDate} option, only when the option is not set here. The
+ * options passed when adding an entry to the filesystem take precedence over the options set here, and
+ * the options describing the data of the entries exported as-is, e.g.
+ * {@link ZipWriterConstructorOptions#compressionMethod} and
+ * {@link ZipWriterAddDataOptions#uncompressedSize}, are always the ones of the original entries.
+ *
+ * The {@link ZipWriterConstructorOptions#password} option encrypts the exported zip file. It never
+ * decrypts the entries being exported: the password of an entry imported from an encrypted zip file
+ * must be passed in the {@link ZipDirectoryEntryExportOptions#readerOptions} option instead.
+ *
+ * Likewise, the {@link ZipWriterConstructorOptions#passThrough} option describes the data returned
+ * by the Reader instances. Exporting entries imported from a zip file as-is is done with the
+ * {@link ZipReaderOptions#passThrough} option in the
+ * {@link ZipDirectoryEntryExportOptions#readerOptions} option instead. Setting it here throws an
+ * {@link ERR_INVALID_PASS_THROUGH} error, unless the {@link ZipWriterAddDataOptions#uncompressedSize}
+ * option of every entry holding content is known.
+ *
+ * Exporting entries as-is and setting the {@link ZipWriterConstructorOptions#password} option throws an
+ * {@link ERR_UNSUPPORTED_ENCRYPTION_PASS_THROUGH} error, since the data of these entries is copied
+ * verbatim and cannot be encrypted. Entries imported from an encrypted zip file are an exception: they
+ * are exported as-is without error, and keep the password they were encrypted with.
+ *
+ * The {@link ZipWriterConstructorOptions#preventClose} option only applies when the caller owns the
+ * writable, i.e. when a {@link WritableWriter} instance is passed to
+ * {@link ZipDirectoryEntry#exportZip} or {@link ZipDirectoryEntry#exportWritable}. It is ignored by the
+ * other `{@link ZipDirectoryEntry}#export*()` methods, whose Writer instance can only return its data
+ * once its writable is closed.
  */
 export interface ZipDirectoryEntryExportOptions
   extends ZipWriterConstructorOptions,
@@ -3144,13 +3570,66 @@ export interface ZipDirectoryEntryExportOptions
    */
   mimeType?: string;
   /**
-   * The options passed to the Reader instances
+   * The function called each time an entry is written.
+   *
+   * @remarks
+   * This function reports the entries whereas {@link EntryDataOnprogressOptions#onprogress} reports the
+   * bytes. It is called once per entry, after the entry has been written, so `progress` reaches `total`
+   * when the last entry is written.
+   *
+   * When {@link ZipWriterConstructorOptions#bufferedWrite} is enabled, the entries are written
+   * concurrently: `progress` counts the entries written instead of giving the position of the entry in
+   * the zip file.
+   *
+   * @param progress The number of entries written.
+   * @param total The total number of entries.
+   * @param entry The entry written.
+   * @returns An empty promise or `undefined`.
+   */
+  onentryprogress?(
+    progress: number,
+    total: number,
+    entry: EntryMetaData
+  ): Promise<void> | void;
+  /**
+   * The global comment of the zip file, see {@link ZipWriter#close}.
+   *
+   * @remarks
+   * The {@link ZipWriterAddDataOptions#comment} option is the comment of an entry: setting it here
+   * comments every entry of the exported zip file instead of the zip file itself.
+   */
+  globalComment?: Uint8Array;
+  /**
+   * The function called for signing the central directory, see
+   * {@link ZipWriterCloseOptions#signCentralDirectory}.
+   *
+   * @param directory The raw data of the central directory records.
+   * @returns The data of the digital signature record.
+   */
+  signCentralDirectory?(
+    directory: Uint8Array
+  ): Uint8Array | PromiseLike<Uint8Array>;
+  /**
+   * The options passed to the Reader instances.
+   *
+   * @remarks
+   * The {@link ZipReaderOptions#password} option must be set here to export entries imported from an
+   * encrypted zip file, since the {@link ZipDirectoryEntryExportOptions#password} option sets the
+   * password used to encrypt the exported zip file instead.
+   *
+   * The {@link ZipReaderOptions#passThrough} option set here exports the entries imported from a zip
+   * file as-is, without decompressing and decrypting them, exactly as importing them with this option
+   * does. It is ignored by the entries added to the filesystem, which are compressed as usual.
    */
   readerOptions?: ZipReaderConstructorOptions;
 }
 
 /**
  * Represents the options passed to {@link ZipDirectoryEntry#exportFileSystemHandle} and {@link FS#exportFileSystemHandle}.
+ *
+ * @remarks
+ * The {@link ZipReaderOptions#preventClose} option is ignored: the export owns the writable of each
+ * file it creates and must close it for the data to be written.
  */
 export interface ZipDirectoryEntryExportFileSystemHandleOptions
   extends EntryGetDataOptions {
@@ -3165,6 +3644,15 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
    * @defaultValue false
    */
   concurrent?: boolean;
+  /**
+   * The options passed to the Reader instances.
+   *
+   * @remarks
+   * These options override the ones passed at the top level. The {@link ZipReaderOptions#password}
+   * option can be set here or at the top level, unlike {@link ZipDirectoryEntryExportOptions} where
+   * the top-level password encrypts the exported zip file instead.
+   */
+  readerOptions?: ZipReaderConstructorOptions;
 }
 
 /**
@@ -3212,6 +3700,7 @@ export interface FS
     | "exportWritable"
     | "exportFileSystemHandle"
     | "exportZip"
+    | "getExportedSize"
     | "isPasswordProtected"
     | "checkPassword"
   > {}
@@ -3264,20 +3753,14 @@ export class FS {
 export const fs: {
   /**
    * The Filesystem constructor.
-   *
-   * @defaultValue {@link FS}
    */
   FS: typeof FS;
   /**
    * The {@link ZipDirectoryEntry} constructor.
-   *
-   * @defaultValue {@link ZipDirectoryEntry}
    */
   ZipDirectoryEntry: typeof ZipDirectoryEntry;
   /**
    * The {@link ZipFileEntry} constructor.
-   *
-   * @defaultValue {@link ZipFileEntry}
    */
   ZipFileEntry: typeof ZipFileEntry;
 };
@@ -3394,6 +3877,10 @@ export const ERR_DUPLICATED_NAME: string;
  * Invalid comment error
  */
 export const ERR_INVALID_COMMENT: string;
+/**
+ * Invalid comment type error
+ */
+export const ERR_INVALID_COMMENT_TYPE: string;
 /**
  * Invalid entry name error
  */
@@ -3422,6 +3909,10 @@ export const ERR_INVALID_ENCRYPTION_STRENGTH: string;
  * Unsupported encryption in USDZ files error
  */
 export const ERR_UNSUPPORTED_ENCRYPTION_USDZ: string;
+/**
+ * Unsupported encryption in pass-through entries error
+ */
+export const ERR_UNSUPPORTED_ENCRYPTION_PASS_THROUGH: string;
 /**
  * Invalid format error
  */
@@ -3475,8 +3966,13 @@ export const ERR_ITERATOR_COMPLETED_TOO_SOON: string;
  * Undefined uncompressed size error
  */
 export const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string;
+export const ERR_UNDETERMINED_SIZE: string;
 /**
  * Undefined reader error
+ *
+ * @remarks Thrown when adding an entry with the {@link ZipWriterConstructorOptions#passThrough} option set to `true`
+ * and no Reader instance: the headers of such an entry describe its content verbatim and would declare content that
+ * is not there. Directory entries are exempt, they have no content to write as-is.
  */
 export const ERR_UNDEFINED_READER: string;
 /**
@@ -3530,6 +4026,16 @@ export const ERR_INVALID_LEVEL: string;
  * would produce an archive that cannot be opened with the equivalent {@link ZipWriterConstructorOptions#password}.
  */
 export const ERR_INVALID_PASSWORD_TYPE: string;
+/**
+ * Invalid passThrough option error (thrown by `{@link ZipDirectoryEntry}#export*()` and
+ * {@link ZipDirectoryEntry#getExportedSize} when an entry would be written as-is without a known uncompressed size)
+ *
+ * @remarks The {@link ZipWriterConstructorOptions#passThrough} option describes the data returned by the Reader
+ * instances, which the filesystem API creates itself. Use the {@link ZipReaderOptions#passThrough} option in the
+ * {@link ZipDirectoryEntryExportOptions#readerOptions} option to export the entries imported from a zip file as-is,
+ * or set the {@link ZipWriterAddDataOptions#uncompressedSize} option of each entry holding compressed data.
+ */
+export const ERR_INVALID_PASS_THROUGH: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */