@zip.js/zip.js 2.8.58 → 2.8.59

package/index.d.cts

@@ -1341,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
    *
@@ -1369,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*`.
  */
@@ -2420,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.
@@ -2693,7 +2798,8 @@ export class ZipWriter<Type> {
    * @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.
@@ -2779,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`.
    */
@@ -4560,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;

package/index.d.ts

@@ -1341,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
    *
@@ -1369,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*`.
  */
@@ -2420,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.
@@ -2693,7 +2798,8 @@ export class ZipWriter<Type> {
    * @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.
@@ -2779,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`.
    */
@@ -4560,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;