@zip.js/zip.js 2.8.57 → 2.8.59

package/index.d.ts

@@ -983,7 +983,8 @@ export interface WritableWriter {
   /**
    * The number of bytes written into the instance. It is set to 0 before the first write and
    * updated as the data is written, so a writer needing the value (e.g. to compute the offset of a
-   * disk) can read it.
+   * disk) can read it. A value set before the first write is kept and used as the starting offset
+   * instead of being reset to 0.
    */
   size?: number;
   /**
@@ -1280,6 +1281,13 @@ export class ZipReader<Type> {
   /**
    * Creates the instance
    *
+   * @remarks
+   * Reading a zip file requires random access because the central directory located at the end of the
+   * file is read first. A `ReadableStream` instance, or an object providing only a `readable` property
+   * (e.g. a file handle), is therefore buffered entirely in memory when the instance is initialized. To
+   * read a large seekable resource without buffering it, pass a custom {@link Reader} implementation
+   * that reads the requested byte ranges directly.
+   *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
    */
@@ -1333,6 +1341,31 @@ export class ZipReader<Type> {
    * `6 + digitalSignature.length` from it when the record is stored inside the declared range.
    */
   directoryLength?: number;
+  /**
+   * The non-fatal diagnostics deposited while reading the entries, replaced every time
+   * {@link ZipReader#getEntries} or {@link ZipReader#getEntriesGenerator} runs.
+   *
+   * @remarks
+   * A warning reports a characteristic of the zip file observed in data the parse had already read: depositing
+   * one never costs additional I/O, and a well-formed zip file deposits none. Each
+   * {@link ArchiveWarning#reason} value is deposited at most once per call, with
+   * {@link ArchiveWarning#filename} naming the first entry it applies to when it applies to an entry.
+   *
+   * Two kinds of reasons are deposited. Observations are always non-fatal: {@link WARNING_UNSORTED_CENTRAL_DIRECTORY},
+   * {@link WARNING_UNKNOWN_VERSION} (the low byte of the "version needed to extract" field exceeds the highest
+   * known zip specification version; the high byte is ignored because some writers store a host identifier in it),
+   * {@link WARNING_COMPRESSED_PATCHED_DATA} (bit 5 of the general purpose bit flag),
+   * {@link WARNING_MALFORMED_EXTRA_FIELD}, {@link WARNING_UNKNOWN_ZIP64_EXTENSIBLE_DATA} and
+   * {@link WARNING_WRAPPED_ENTRIES_COUNT}. The other reasons are the checks that
+   * `strictness: "strict"` rejects with {@link ERR_AMBIGUOUS_ARCHIVE}: when the effective strictness tolerates
+   * one of them and the evidence is already in hand, the same reason string is deposited as a warning instead —
+   * {@link WARNING_APPENDED_DATA}, {@link WARNING_PREPENDED_DATA}, {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA},
+   * {@link WARNING_DUPLICATE_FILENAME} and {@link WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY}.
+   *
+   * The warnings related to the local file header of an entry are deposited on
+   * {@link EntryMetaData#warnings} when its data is read, not here.
+   */
+  warnings?: ArchiveWarning[];
   /**
    * Returns all the entries in the zip file
    *
@@ -1361,6 +1394,58 @@ export class ZipReader<Type> {
   close(): Promise<void>;
 }
 
+/**
+ * Returns `true` if the data looks like a zip file, i.e. if {@link ZipReader#getEntries} called on the same
+ * data with the same options would locate the archive structure instead of throwing
+ * {@link ERR_EOCDR_NOT_FOUND} or the {@link ERR_AMBIGUOUS_ARCHIVE} error caused by appended data.
+ *
+ * @remarks
+ * The probe runs the same search as {@link ZipReader}: it locates the end of central directory record with
+ * the end-anchored backward scan and verifies that a central directory record is stored where it points,
+ * without parsing the entries. `true` therefore means the data is a plausible zip container, not that every
+ * entry can be read: a truncated or otherwise damaged central directory is only detected by calling
+ * {@link ZipReader#getEntries}. Formats built on zip, e.g. office documents or Java archives, return `true`.
+ *
+ * Like the {@link ZipReader} constructor, a `ReadableStream` or an object providing only a `readable`
+ * property is buffered entirely in memory before probing, which defeats the purpose of a cheap probe; prefer
+ * a seekable {@link Reader} input.
+ *
+ * @param reader The {@link Reader} instance used to read data.
+ * @param options The options.
+ * @returns A promise resolving to `true` if the data looks like a zip file.
+ */
+export function isZipFile(
+  reader:
+    | Reader<unknown>
+    | ReadableReader
+    | ReadableStream
+    | Reader<unknown>[]
+    | ReadableReader[]
+    | ReadableStream[],
+  options?: IsZipFileOptions
+): Promise<boolean>;
+
+/**
+ * Represents the options passed to {@link isZipFile}.
+ */
+export interface IsZipFileOptions {
+  /**
+   * The tolerance of the probe, with the same semantics and default as
+   * {@link ZipReaderConstructorOptions#strictness}: it selects the default amount of tolerated appended data
+   * (0 for `"strict"`, 65536 bytes for `"balanced"`, unlimited for `"tolerant"`) and `"strict"` also returns
+   * `false` when multiple end of central directory records reach the end of the data.
+   *
+   * @defaultValue "balanced"
+   */
+  strictness?: "strict" | "balanced" | "tolerant";
+  /**
+   * The maximum number of bytes tolerated after the end of central directory record, overriding the default
+   * selected by {@link IsZipFileOptions#strictness}, with the same semantics as
+   * {@link ZipReaderConstructorOptions#maxAppendedDataSize}.
+   */
+  maxAppendedDataSize?: number;
+}
+
 /**
  * Represents the options passed to the constructor of {@link ZipReader}, and `{@link ZipDirectory}#import*`.
  */
@@ -1957,6 +2042,12 @@ export interface LocalDirectory {
    * The length of the extra field in bytes.
    */
   extraFieldLength: number;
+  /**
+   * The byte offset of the entry data, i.e. {@link EntryMetaData#offset} plus the size of the local file header,
+   * of the filename and of the extra field. It can be used with {@link Reader#createReadable} to read the stored
+   * data directly, e.g. to serve ranged requests into an entry compressed with the `"store"` method.
+   */
+  dataOffset: number;
   /**
    * The extra field (raw).
    */
@@ -2316,9 +2407,6 @@ export interface EntryMetaData {
    * The upper 16-bit portion of {@link EntryMetaData#externalFileAttributes} when it represents Unix mode bits.
    */
   unixExternalUpper?: number;
-  /**
-   * The number of the disk where the entry data starts.
-   */
   /**
    * The internal file attribute (raw).
    * @deprecated Use {@link EntryMetaData#internalFileAttributes} instead.
@@ -2409,7 +2497,35 @@ export interface EntryMetaData {
    * {@link EntryMetaData#uid} and {@link EntryMetaData#gid}, which are read from the central directory.
    */
   localDirectory?: LocalDirectory;
+  /**
+   * The non-fatal diagnostics deposited while reading the entry data, replaced every time the data is read.
+   *
+   * @remarks
+   * The reasons deposited here relate to the local file header: {@link WARNING_MALFORMED_EXTRA_FIELD} when its
+   * extra field data cannot be fully parsed, and — only when {@link ZipReaderOptions#checkLocalDirectory} is
+   * disabled, e.g. with `strictness: "tolerant"` — the local file header mismatches the enabled check rejects
+   * with {@link ERR_AMBIGUOUS_ARCHIVE}: {@link WARNING_MISMATCHED_LOCAL_FILE_HEADER_BIT_FLAG},
+   * {@link WARNING_MISMATCHED_LOCAL_FILE_HEADER_COMPRESSION_METHOD} and
+   * {@link WARNING_MISMATCHED_LOCAL_FILE_HEADER_CRC32_OR_SIZES}. The archive-level warnings are deposited on
+   * {@link ZipReader#warnings} instead.
+   */
+  warnings?: ArchiveWarning[];
 }
+
+/**
+ * Represents a non-fatal diagnostic deposited on {@link ZipReader#warnings} or {@link EntryMetaData#warnings}.
+ */
+export interface ArchiveWarning {
+  /**
+   * The reason of the warning, one of the exported `WARNING_*` constants.
+   */
+  reason: string;
+  /**
+   * The filename of the first entry the warning applies to, when it applies to an entry.
+   */
+  filename?: string;
+}
+
 export interface DirectoryEntry extends EntryMetaData {
   /**
    * `true` if the entry is a directory.
@@ -2561,6 +2677,11 @@ export class ZipWriterStream {
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zipped file.
    *
+   * @remarks
+   * If an entry could not be written, this method aborts the zipped stream with the error — the
+   * readable side of the stream fails instead of ending — and throws it. The `entryErrors` property
+   * of the thrown error contains the errors of all the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2614,13 +2735,45 @@ export class ZipWriter<Type> {
    */
   readonly hasCorruptedEntries?: boolean;
 
+  /**
+   * Adds the entries of an existing zip file into the current zip. This method can be called at any
+   * time, including between calls to {@link ZipWriter#add} and repeatedly to merge several zip files.
+   *
+   * @remarks
+   * The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
+   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
+   * the disks of the output, which is a single zip file unless the writer is a split zip file writer. The data of
+   * the entries is copied as-is; in particular, the constraints set by {@link ZipWriterConstructorOptions#usdz}
+   * are not applied to the copied entries.
+   *
+   * Pending {@link ZipWriter#add} calls are completed before the data is copied, and add() calls made
+   * while the copy is in progress are written after it. If an entry of the zip file has the same
+   * filename as an entry of the current zip, the method throws with the `ERR_DUPLICATED_NAME` error
+   * message and leaves the current zip unchanged; call {@link ZipWriter#remove} beforehand to resolve
+   * the conflicts.
+   *
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the copy
+   * and throws its error if it was not caught.
+   *
+   * @param reader The {@link Reader} instance used to read the content of the zip file.
+   * @returns A promise resolving when the zip file has been added.
+   */
+  appendZip<ReaderType>(
+    reader:
+      | Reader<ReaderType>
+      | ReadableReader
+      | ReadableStream
+      | Reader<unknown>[]
+      | ReadableReader[]
+      | ReadableStream[]
+  ): Promise<void>;
+
   /**
    * Adds an existing zip file at the beginning of the current zip. This method
    * cannot be called after the first call to {@link ZipWriter#add}.
    *
-   * @remarks The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
-   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
-   * the disks of the output, which is a single zip file unless the writer is a split zip file writer.
+   * @deprecated Use {@link ZipWriter#appendZip} instead, which is equivalent when the zip file is
+   * empty and can also be called after entries have been added.
    *
    * @param reader The {@link Reader} instance used to read the content of the zip file.
    * @returns A promise resolving when the zip file has been added.
@@ -2638,10 +2791,15 @@ export class ZipWriter<Type> {
   /**
    * Adds an entry into the zip file
    *
+   * @remarks
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the entry
+   * and throws its error if it was not caught.
+   *
    * @param filename The filename of the entry. Paths must use forward slashes ("/") as separator,
    * as required by section 4.4.17.1 of the zip specification. The value is stored as-is; in
    * particular, Windows path separators ("\\") are not converted and become part of the filename,
-   * which is interpreted inconsistently by zip tools.
+   * which is interpreted inconsistently by zip tools, and leading or trailing whitespace is
+   * preserved, which Windows filesystems cannot represent at the end of a name.
    * @param reader The  {@link Reader} instance used to read the content of the entry.
    * @param options The options.
    * @returns A promise resolving to an {@link EntryMetaData} instance.
@@ -2674,6 +2832,14 @@ export class ZipWriter<Type> {
    * The global comment is passed as raw bytes and the comment of an entry
    * ({@link ZipWriterAddDataOptions#comment}) as a string on purpose, see {@link ZipReader#comment}.
    *
+   * If {@link ZipWriter#add} or {@link ZipWriter#appendZip} calls failed and their rejection was
+   * never handled — e.g. the returned promise was not awaited — this method throws the first of
+   * these errors instead of finalizing the zip file. The `entryErrors` property of the thrown error
+   * contains all of them. Errors already caught by the caller do not resurface here, so entries can
+   * still be skipped by awaiting {@link ZipWriter#add} and catching the error. Throwing the errors
+   * counts as reporting them: catching the error of this method and calling it again finalizes the
+   * zip file without the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2719,6 +2885,10 @@ export interface ZipWriterAddDataOptions
    * The extra field of the entry written only in the local file header.
    */
   localExtraField?: Map<number, Uint8Array>;
+  /**
+   * The extra field of the entry written only in the central directory record.
+   */
+  centralExtraField?: Map<number, Uint8Array>;
   /**
    * The uncompressed size of the entry. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
    */
@@ -2874,6 +3044,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * @defaultValue The current date.
    */
   lastModDate?: Date;
+  /**
+   * The last modification date, as its raw 32-bit MS-DOS date and time value.
+   *
+   * @remarks
+   * The value is written verbatim into the local and central directory headers and takes precedence over
+   * {@link ZipWriterConstructorOptions#lastModDate}, which still fills the extended timestamp and NTFS extra
+   * fields. The filesystem API sets it when exporting entries with {@link ZipReaderOptions#passThrough} set in
+   * {@link ZipDirectoryEntryExportOptions#readerOptions}, so that the entries copied as-is keep the exact date
+   * and time of the source zip file.
+   */
+  rawLastModDate?: number;
   /**
    * The last access date.
    *
@@ -2920,7 +3101,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   zipCrypto?: boolean;
   /**
-   * The "Version" field.
+   * The "Version" field, i.e. the minimum version needed to extract the entry.
+   *
+   * @defaultValue the minimum version required by the features of the entry: 10 for entries stored without
+   * compression or encryption, 20 for deflated, folder or ZipCrypto-encrypted entries, raised to 45 for Zip64
+   * entries and 51 for AES-encrypted entries.
    */
   version?: number;
   /**
@@ -2942,7 +3127,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * `true` 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.
    *
-   * Note that this does not ensure that the file names are in the correct encoding.
+   * Note that 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
+   * {@link ZipWriterConstructorOptions#encodeText} option is also set to encode them in the intended code page.
    *
    * @defaultValue true
    */
@@ -2973,6 +3160,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#msdosAttributesRaw} or {@link 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.
+   *
    * @defaultValue false
    */
   msDosCompatible?: boolean;
@@ -3093,6 +3284,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterAddDataOptions#compressionMethod} options are set explicitly. Setting the
    * {@link ZipWriterConstructorOptions#password} option throws an {@link ERR_UNSUPPORTED_ENCRYPTION_USDZ} error.
    *
+   * These constraints apply to the entries written with {@link ZipWriter#add} only. The entries copied with
+   * {@link 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.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3110,6 +3306,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@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.
+   *
+   * 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
+   * {@link ZipWriterConstructorOptions#dataDescriptor} and {@link ZipWriterConstructorOptions#rawLastModDate}
+   * values of the source entry must then be forwarded, otherwise reading the copied entry fails with an
+   * {@link ERR_INVALID_PASSWORD} error. The filesystem API forwards them when exporting entries and throws an
+   * {@link ERR_ZIP_CRYPTO_LAST_MOD_DATE} error if the date is overridden.
    */
   passThrough?: boolean;
   /**
@@ -4426,6 +4629,17 @@ export const ERR_INVALID_PASS_THROUGH: string;
  * unknown property of a `readerOptions` object is still ignored, as everywhere else in the API.
  */
 export const ERR_INVALID_READER_OPTIONS: string;
+/**
+ * Locked last modification date error (thrown by `{@link ZipDirectoryEntry}#export*()` and
+ * {@link ZipDirectoryEntry#getExportedSize} when the date of an entry encrypted with ZipCrypto and exported with
+ * {@link ZipReaderOptions#passThrough} set in {@link ZipDirectoryEntryExportOptions#readerOptions} is changed)
+ *
+ * @remarks The ZipCrypto encryption header embeds a password verification byte derived from the time of the
+ * entry: the encrypted data, copied as-is, only decrypts when the time in the rewritten headers still matches.
+ * The error is thrown when the new date would prevent the entry from being decrypted; changes which keep the
+ * verification byte intact, e.g. a change of the day only, are written normally.
+ */
+export const ERR_ZIP_CRYPTO_LAST_MOD_DATE: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */
@@ -4456,3 +4670,76 @@ export const ERR_UNSUPPORTED_CRYPTO_API: string;
  * disallowing workers; set `useWebWorkers` to `false` in {@link configure} to work around it)
  */
 export const ERR_WORKER_STARTUP_TIMEOUT: string;
+/**
+ * Warning reason: the central directory records are not ordered by entry data position (see {@link ZipReader#warnings})
+ */
+export const WARNING_UNSORTED_CENTRAL_DIRECTORY: string;
+/**
+ * Warning reason: the low byte of the "version needed to extract" field of an entry exceeds the highest known
+ * zip specification version (see {@link ZipReader#warnings})
+ */
+export const WARNING_UNKNOWN_VERSION: string;
+/**
+ * Warning reason: an entry has bit 5 of the general purpose bit flag set, i.e. declares compressed patched data
+ * (see {@link ZipReader#warnings})
+ */
+export const WARNING_COMPRESSED_PATCHED_DATA: string;
+/**
+ * Warning reason: the extra field data of a record cannot be fully parsed; the raw bytes stay available in
+ * `rawExtraField` (see {@link ZipReader#warnings} and {@link EntryMetaData#warnings})
+ */
+export const WARNING_MALFORMED_EXTRA_FIELD: string;
+/**
+ * Warning reason: the Zip64 end of central directory record carries extensible data the zip file does not use
+ * (see {@link ZipReader#warnings})
+ */
+export const WARNING_UNKNOWN_ZIP64_EXTENSIBLE_DATA: string;
+/**
+ * Warning reason: the zip file contains more than 65535 entries without Zip64, recovered from the 16-bit entry
+ * count wrapped modulo 65536 (see {@link ZipReader#warnings})
+ */
+export const WARNING_WRAPPED_ENTRIES_COUNT: string;
+/**
+ * Warning reason: data is appended after the end of the zip file (see {@link ZipReader#warnings}); the reason of
+ * {@link ERR_AMBIGUOUS_ARCHIVE} when the appended data exceeds {@link GetEntriesOptions#maxAppendedDataSize}
+ */
+export const WARNING_APPENDED_DATA: string;
+/**
+ * Warning reason: data is prepended before the zip file (see {@link ZipReader#warnings}); the reason of
+ * {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
+ */
+export const WARNING_PREPENDED_DATA: string;
+/**
+ * Warning reason: data lies between the end of the central directory records and the end of central directory
+ * record, either inside the declared central directory length or beyond it (see {@link ZipReader#warnings});
+ * the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
+ */
+export const WARNING_TRAILING_CENTRAL_DIRECTORY_DATA: string;
+/**
+ * Warning reason: several entries share the same filename (see {@link ZipReader#warnings}); the reason of
+ * {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
+ */
+export const WARNING_DUPLICATE_FILENAME: string;
+/**
+ * Warning reason: the end of central directory record and its Zip64 counterpart disagree on a field stored in
+ * both (see {@link ZipReader#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
+ */
+export const WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY: string;
+/**
+ * Warning reason: the general purpose bit flag of the local file header contradicts the central directory
+ * (see {@link EntryMetaData#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
+ * {@link ZipReaderOptions#checkLocalDirectory} is enabled
+ */
+export const WARNING_MISMATCHED_LOCAL_FILE_HEADER_BIT_FLAG: string;
+/**
+ * Warning reason: the compression method of the local file header contradicts the central directory
+ * (see {@link EntryMetaData#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
+ * {@link ZipReaderOptions#checkLocalDirectory} is enabled
+ */
+export const WARNING_MISMATCHED_LOCAL_FILE_HEADER_COMPRESSION_METHOD: string;
+/**
+ * Warning reason: the crc32 or the sizes of the local file header contradict the central directory
+ * (see {@link EntryMetaData#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
+ * {@link ZipReaderOptions#checkLocalDirectory} is enabled
+ */
+export const WARNING_MISMATCHED_LOCAL_FILE_HEADER_CRC32_OR_SIZES: string;