@zip.js/zip.js 2.8.52 → 2.8.53

package/index.d.cts

@@ -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;
   /**
@@ -724,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[]
@@ -783,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;
   /**
@@ -1221,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;
@@ -1362,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"
    */
@@ -1377,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.
    *
@@ -1503,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),
@@ -1539,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.
  */
@@ -1584,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.
    */
@@ -1609,7 +1818,7 @@ export interface LocalDirectory {
   /**
    * The Zip64 extra field.
    */
-  extraFieldZip64?: EntryExtraField;
+  extraFieldZip64?: EntryExtraFieldZip64;
   /**
    * The AES extra field.
    */
@@ -1617,16 +1826,18 @@ export interface LocalDirectory {
   /**
    * The NTFS extra field.
    */
-  extraFieldNTFS?: EntryExtraField;
+  extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
    * 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 New Unix extra field (0x7875), storing variable-length uid/gid in both headers.
+   * 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).
    */
@@ -1638,7 +1849,7 @@ export interface LocalDirectory {
   /**
    * The extended timestamp extra field.
    */
-  extraFieldExtendedTimestamp?: EntryExtraField;
+  extraFieldExtendedTimestamp?: EntryExtraFieldExtendedTimestamp;
   /**
    * The Unicode path extra field.
    */
@@ -1722,6 +1933,10 @@ export interface EntryMetaData {
    *
    * 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;
   /**
@@ -1753,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;
   /**
@@ -1850,9 +2069,12 @@ export interface EntryMetaData {
    *
    * 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; the ids are then available in
+   * 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;
   /**
@@ -1934,7 +2156,7 @@ export interface EntryMetaData {
   /**
    * The Zip64 extra field.
    */
-  extraFieldZip64?: EntryExtraField;
+  extraFieldZip64?: EntryExtraFieldZip64;
   /**
    * The AES extra field.
    */
@@ -1942,16 +2164,18 @@ export interface EntryMetaData {
   /**
    * The NTFS extra field.
    */
-  extraFieldNTFS?: EntryExtraField;
+  extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
    * 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 New Unix extra field (0x7875), storing variable-length uid/gid in both headers.
+   * 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).
    */
@@ -1963,7 +2187,7 @@ export interface EntryMetaData {
   /**
    * The extended timestamp extra field.
    */
-  extraFieldExtendedTimestamp?: EntryExtraField;
+  extraFieldExtendedTimestamp?: EntryExtraFieldExtendedTimestamp;
   /**
    * The Unicode path extra field.
    */
@@ -2435,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;
   /**
@@ -2443,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;
   /**
@@ -2478,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;
   /**
@@ -2510,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;
@@ -2543,8 +2782,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * `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.
    *
-   * When the value carries no file type, the type of the entry is added: `S_IFDIR` (`0o040000`)
-   * for a folder entry, `S_IFREG` (`0o100000`) otherwise. Set
+   * 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.
    */
@@ -3513,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;
 };
@@ -3643,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
  */