@zip.js/zip.js 2.8.58 → 2.8.60

package/index.d.cts

@@ -216,6 +216,12 @@ declare class DecompressionStreamLike extends TransformStreamLike {
   constructor(format: string, options?: DecompressionStreamOptions);
 }
 
+/**
+ * The version of zip.js (e.g. `"2.8.59"`), i.e. the `version` declared in the `package.json` file
+ * of the library.
+ */
+export const VERSION: string;
+
 /**
  * Configures zip.js
  *
@@ -247,6 +253,61 @@ export function registerCodec(codec: CodecDefinition): void;
  */
 export function unregisterCodec(compressionMethod: number): void;
 
+/**
+ * Returns the definitions of the codecs registered with {@link registerCodec}, in registration
+ * order. The returned objects are snapshots: modifying them does not alter the registered codecs.
+ *
+ * @remarks
+ * The `CompressionStream` and `DecompressionStream` classes of a codec registered with
+ * {@link CodecDefinition#codecURI} only appear once the module has been imported, i.e. after the
+ * first entry using the codec has been read or written.
+ *
+ * @returns The codec definitions.
+ */
+export function getRegisteredCodecs(): CodecDefinition[];
+
+/**
+ * Returns the compression methods supported in the current environment and configuration: the
+ * built-in methods followed by the codecs registered with {@link registerCodec}, in registration
+ * order.
+ *
+ * @remarks
+ * The support of the built-in methods is resolved against the compression streams available when
+ * the function is called, i.e. the classes set with {@link configure} and the implementations
+ * embedded in the build. A caller can test whether an entry is readable by looking up
+ * {@link EntryMetaData#compressionMethod} in the result and checking
+ * {@link EntryMetaData#encrypted}; `FileEntry#getData` remains the authority.
+ *
+ * @returns The supported compression methods.
+ */
+export function getSupportedCompressionMethods(): SupportedCompressionMethod[];
+
+/**
+ * Represents the support of a compression method, see {@link getSupportedCompressionMethods}.
+ */
+export interface SupportedCompressionMethod {
+  /**
+   * The compression method stored in zip entry headers (e.g. `8` for Deflate).
+   */
+  compressionMethod: number;
+  /**
+   * `true` if entries can be compressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  compression?: boolean;
+  /**
+   * `true` if entries can be decompressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  decompression?: boolean;
+  /**
+   * `true` if the method comes from a codec registered with {@link registerCodec}.
+   */
+  registered: boolean;
+}
+
 /**
  * Represents a codec definition passed to {@link registerCodec}.
  */
@@ -310,6 +371,13 @@ export interface CompressionStreamOptions {
    * It is only set for the codecs registered with {@link registerCodec}.
    */
   compressionMethod?: number;
+  /**
+   * The uncompressed size of the entry, undefined when the size is unknown.
+   * It allows codecs such as Zstandard to include the content size in the compressed frame.
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  uncompressedSize?: number;
 }
 
 /**
@@ -757,6 +825,48 @@ export interface ReadableReader {
  *   }
  * }
  * ```
+ *
+ * @example
+ * Reading a file on the filesystem with random access does not always require a custom {@link Reader}:
+ * on runtimes exposing files as lazily-read `Blob` instances, the `Blob` returned by
+ * `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun can be passed directly to
+ * {@link ZipReader}. Deno has no equivalent API yet, see https://github.com/denoland/deno/issues/32316.
+ * The class below reads a
+ * `Deno.FsFile` with random access instead of buffering it entirely in memory. The `seek()` and `read()`
+ * calls are serialized in a queue because zip.js can read multiple byte ranges concurrently:
+ * ```
+ * class FsFileReader extends Reader {
+ *
+ *   constructor(file) {
+ *     super();
+ *     this.file = file;
+ *     this.queue = Promise.resolve();
+ *   }
+ *
+ *   async init() {
+ *     super.init();
+ *     this.size = (await this.file.stat()).size;
+ *   }
+ *
+ *   readUint8Array(offset, length) {
+ *     const result = this.queue.then(async () => {
+ *       await this.file.seek(offset, Deno.SeekMode.Start);
+ *       const data = new Uint8Array(length);
+ *       let bytesRead = 0;
+ *       while (bytesRead < length) {
+ *         const count = await this.file.read(data.subarray(bytesRead));
+ *         if (count === null) {
+ *           return data.subarray(0, bytesRead);
+ *         }
+ *         bytesRead += count;
+ *       }
+ *       return data;
+ *     });
+ *     this.queue = result.catch(() => undefined);
+ *     return result;
+ *   }
+ * }
+ * ```
  */
 export class Reader<Type> implements Initializable, ReadableReader {
   /**
@@ -1286,7 +1396,9 @@ export class ZipReader<Type> {
    * 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.
+   * that reads the requested byte ranges directly, or a lazily-read `Blob` instance when the runtime
+   * provides one, e.g. `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun. See
+   * {@link Reader} for an example reading a `Deno.FsFile` with random access.
    *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
@@ -1341,6 +1453,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 +1506,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 +2609,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 +2910,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 +2997,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`.
    */
@@ -3179,6 +3401,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * 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.
    *
+   * The option is only read when the {@link ZipWriter} is created; a value passed to
+   * {@link ZipWriter#add} is ignored.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3211,6 +3436,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   encrypted?: boolean;
   /**
    * The offset of the first entry in the zip file.
+   *
+   * @remarks
+   * When the option is undefined, the offset is the number of bytes already written into the
+   * destination, read from its `size` property, see {@link WritableWriter#size}. A `size` property
+   * set on a `WritableStream` instance passed directly to the {@link ZipWriter} constructor is
+   * also read, for backward compatibility. When the option is set, the bytes between the size of
+   * the destination and the offset are assumed to exist in the final zip file without being
+   * written, e.g. when writing one part of a zip file assembled by the caller.
+   *
+   * The option is only read when the {@link ZipWriter} is created, e.g. by
+   * {@link ZipDirectoryEntry#exportZip}; a value passed to {@link ZipWriter#add} is ignored.
    */
   offset?: number;
   /**
@@ -3727,6 +3963,10 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @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.
+   *
+   * The stream is buffered entirely in memory, because reading a zip file requires random access. To import
+   * a large file without buffering it, use {@link ZipDirectoryEntry#importZip} with a seekable input, see
+   * the {@link ZipReader} constructor remarks and the {@link Reader} examples.
    */
   importReadable(
     readable: ReadableStream,
@@ -3753,6 +3993,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    * {@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.
+   *
+   * Like the {@link ZipReader} constructor, a `ReadableStream` input is buffered entirely in memory, see
+   * its remarks and the {@link Reader} examples for reading large seekable resources with random access.
    */
   importZip(
     reader:
@@ -4560,3 +4803,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;