@zip.js/zip.js 2.8.53 → 2.8.55

package/index.d.cts

@@ -190,6 +190,32 @@ declare class TransformStreamLike {
   writable: WritableStream;
 }
 
+/**
+ * Represents a generic class compressing data, e.g. the native `CompressionStream` class.
+ */
+declare class CompressionStreamLike extends TransformStreamLike {
+  /**
+   * Creates the stream
+   *
+   * @param format The compression format.
+   * @param options The options.
+   */
+  constructor(format: string, options?: CompressionStreamOptions);
+}
+
+/**
+ * Represents a generic class decompressing data, e.g. the native `DecompressionStream` class.
+ */
+declare class DecompressionStreamLike extends TransformStreamLike {
+  /**
+   * Creates the stream
+   *
+   * @param format The decompression format.
+   * @param options The options.
+   */
+  constructor(format: string, options?: DecompressionStreamOptions);
+}
+
 /**
  * Configures zip.js
  *
@@ -237,27 +263,20 @@ export interface CodecDefinition {
   format: string;
   /**
    * The URL of a module exporting the `CompressionStream` and/or `DecompressionStream` classes of
-   * the codec. Relative URLs are resolved against `Configuration#baseURI`; passing an absolute URL
-   * (e.g. via `import.meta.resolve()`) is recommended.
+   * the codec. Relative URLs are resolved against {@link Configuration#baseURI}; passing an absolute
+   * URL (e.g. via `import.meta.resolve()`) is recommended.
    */
   codecURI?: string;
   /**
-   * The stream implementation used to compress data, constructed with
-   * `(format, { level, chunkSize, compressionMethod })`.
+   * The stream implementation used to compress data, constructed with `(format, options)`, see
+   * {@link CompressionStreamOptions}.
    */
-  CompressionStream?: typeof TransformStreamLike;
+  CompressionStream?: typeof CompressionStreamLike;
   /**
-   * The stream implementation used to decompress data, constructed with
-   * `(format, { chunkSize, compressionMethod, rawBitFlag, uncompressedSize })`.
-   *
-   * `compressionMethod` allows codecs registered for multiple methods with the same format to
-   * distinguish them (e.g. Reduce, methods 2 to 5). `rawBitFlag` exposes the general purpose bit
-   * flag of the entry, which some methods need to decode the data (e.g. the dictionary size and
-   * number of trees of Implode, or the end-of-stream marker presence of LZMA). `uncompressedSize`
-   * allows size-driven decoders (e.g. Shrink, Reduce, Implode, LZMA without end-of-stream marker)
-   * to stop at the exact output size instead of decoding trailing padding bits.
+   * The stream implementation used to decompress data, constructed with `(format, options)`, see
+   * {@link DecompressionStreamOptions}.
    */
-  DecompressionStream?: typeof TransformStreamLike;
+  DecompressionStream?: typeof DecompressionStreamLike;
   /**
    * The minimum "version needed to extract" value written in zip entry headers (e.g. `63` for
    * Zstandard).
@@ -265,6 +284,72 @@ export interface CodecDefinition {
   versionNeeded?: number;
 }
 
+/**
+ * Represents the options passed as the second argument to the constructor of the classes
+ * compressing data, i.e. {@link CodecDefinition#CompressionStream},
+ * {@link Configuration#CompressionStream} and {@link Configuration#CompressionStreamFallback}.
+ */
+export interface CompressionStreamOptions {
+  /**
+   * The compression level, see {@link ZipWriterConstructorOptions#level}.
+   */
+  level?: number;
+  /**
+   * The size of the chunks in bytes, see {@link Configuration#chunkSize}.
+   */
+  chunkSize?: number;
+  /**
+   * The compression method of the entry. It allows codecs registered for several methods sharing
+   * the same format to distinguish them (e.g. Reduce, methods 2 to 5).
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  compressionMethod?: number;
+}
+
+/**
+ * Represents the options passed as the second argument to the constructor of the classes
+ * decompressing data, i.e. {@link CodecDefinition#DecompressionStream},
+ * {@link Configuration#DecompressionStream} and {@link Configuration#DecompressionStreamFallback}.
+ */
+export interface DecompressionStreamOptions {
+  /**
+   * The size of the chunks in bytes, see {@link Configuration#chunkSize}.
+   */
+  chunkSize?: number;
+  /**
+   * `true` when the data is compressed with the Deflate64 method, the format passed as the first
+   * argument being `"deflate64-raw"` instead of `"deflate-raw"`.
+   *
+   * It is only set for the classes decompressing the deflate methods, i.e.
+   * {@link Configuration#DecompressionStream} and {@link Configuration#DecompressionStreamFallback}.
+   */
+  deflate64?: boolean;
+  /**
+   * The compression method of the entry. It allows codecs registered for several methods sharing
+   * the same format to distinguish them (e.g. Reduce, methods 2 to 5).
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  compressionMethod?: number;
+  /**
+   * The general purpose bit flag of the entry, which some methods need to decode the data (e.g. the
+   * dictionary size and the number of trees of Implode, or the presence of the end-of-stream marker
+   * of LZMA).
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  rawBitFlag?: number;
+  /**
+   * The uncompressed size of the entry declared in its header, undefined when the size is unknown.
+   * It allows size-driven decoders (e.g. Shrink, Reduce, Implode, LZMA without end-of-stream
+   * marker) to stop at the exact output size instead of decoding trailing padding bits.
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  uncompressedSize?: number;
+}
+
 /**
  * Represents the configuration passed to {@link configure}.
  */
@@ -272,6 +357,8 @@ export interface Configuration extends WorkerConfiguration {
   /**
    * The maximum number of web workers used to compress/decompress data simultaneously.
    *
+   * It must be an integer greater than 0, see {@link ERR_INVALID_MAX_WORKERS}.
+   *
    * @defaultValue `navigator.hardwareConcurrency`, or 2 when the environment does not provide it
    */
   maxWorkers?: number;
@@ -297,6 +384,13 @@ export interface Configuration extends WorkerConfiguration {
    * @defaultValue 5000
    */
   workerStartupTimeout?: number;
+  /**
+   * The base URL against which the relative URIs are resolved, i.e. {@link Configuration#workerURI},
+   * {@link Configuration#wasmURI} and {@link CodecDefinition#codecURI}.
+   *
+   * @defaultValue the URL of the module of zip.js
+   */
+  baseURI?: string;
   /**
    * The URI of the web worker.
    *
@@ -311,6 +405,9 @@ export interface Configuration extends WorkerConfiguration {
    * });
    * ```
    *
+   * The worker is created as a module worker, unless the URI is a Data URI or a Blob URI, in which case it is created as a classic
+   * worker. See {@link Configuration#createWorker} for an example of classic worker script installing a polyfill of the Streams API.
+   *
    * @defaultValue "./core/web-worker-wasm.js", or "./core/web-worker-native.js" for the builds using the native implementations
    */
   workerURI?: string;
@@ -325,6 +422,21 @@ export interface Configuration extends WorkerConfiguration {
    *   createWorker: () => new Worker(new URL("./zip-worker.js", import.meta.url), { type: "module" })
    * });
    * ```
+   *
+   * It is also the way to run the web workers on engines where `TransformStream` is missing from the scope of the workers, e.g. Firefox
+   * before version 102. There, the worker script of zip.js throws when it is evaluated and the data is silently compressed/decompressed
+   * in the main scope instead. A polyfill imported by the page does not help, because the worker reads the globals of the Streams API
+   * from its own scope, so it has to be installed by the worker itself before the worker script of zip.js runs. These engines predate
+   * the support of module workers, hence the classic worker script below:
+   * ```
+   * // zip-worker-with-polyfill.js
+   * importScripts("./web-streams-polyfill.js", "./zip-web-worker.js");
+   * ```
+   * ```
+   * configure({
+   *   createWorker: () => new Worker("./zip-worker-with-polyfill.js")
+   * });
+   * ```
    */
   createWorker?: () => Worker;
   /**
@@ -345,6 +457,9 @@ export interface Configuration extends WorkerConfiguration {
   /**
    * The size of the chunks in bytes during data compression/decompression.
    *
+   * Values lower than 64 are raised to 64, and a value that is not an integer greater than 0 is replaced with the default
+   * value.
+   *
    * @defaultValue 65536
    */
   chunkSize?: number;
@@ -353,33 +468,33 @@ export interface Configuration extends WorkerConfiguration {
    *
    * @defaultValue the global `CompressionStream`, or `false` when the environment does not provide it
    */
-  CompressionStream?: typeof TransformStreamLike;
+  CompressionStream?: typeof CompressionStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `true`.
    *
    * @defaultValue the global `DecompressionStream`, or `false` when the environment does not provide it
    */
-  DecompressionStream?: typeof TransformStreamLike;
+  DecompressionStream?: typeof DecompressionStreamLike;
   /**
    * The stream implementation used to compress data when `useCompressionStream` is set to `false`.
    *
    * @defaultValue the implementation embedded in the entry point that was imported, e.g. the WebAssembly one
    */
-  CompressionStreamFallback?: typeof TransformStreamLike;
+  CompressionStreamFallback?: typeof CompressionStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `false`.
    *
    * @defaultValue the implementation embedded in the entry point that was imported, e.g. the WebAssembly one
    */
-  DecompressionStreamFallback?: typeof TransformStreamLike;
+  DecompressionStreamFallback?: typeof DecompressionStreamLike;
   /**
    * @deprecated Use {@link Configuration#CompressionStreamFallback} instead.
    */
-  CompressionStreamZlib?: typeof TransformStreamLike;
+  CompressionStreamZlib?: typeof CompressionStreamLike;
   /**
    * @deprecated Use {@link Configuration#DecompressionStreamFallback} instead.
    */
-  DecompressionStreamZlib?: typeof TransformStreamLike;
+  DecompressionStreamZlib?: typeof DecompressionStreamLike;
 }
 
 /**
@@ -471,22 +586,17 @@ export function initWorker(options?: {
   /**
    * The stream implementation used to compress data when `useCompressionStream` is set to `false` or when `CompressionStream` is unsupported.
    */
-  CompressionStreamFallback?: typeof TransformStreamLike;
+  CompressionStreamFallback?: typeof CompressionStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `false` or when `DecompressionStream` is unsupported.
    */
-  DecompressionStreamFallback?: typeof TransformStreamLike;
+  DecompressionStreamFallback?: typeof DecompressionStreamLike;
   /**
    * The function called before resolving the stream implementations, e.g. to load a WebAssembly module.
    */
   init?(config: Configuration): Promise<unknown> | unknown;
 }): void;
 
-/**
- * Represents a class implementing `CompressionStream` or `DecompressionStream` interfaces.
- */
-declare class CodecStream extends TransformStream {}
-
 /**
  * Returns the MIME type corresponding to a filename extension.
  *
@@ -699,6 +809,8 @@ export interface CreateReadableOptions {
   /**
    * The size in bytes of the chunks emitted by the default implementation (the `chunkSize` value
    * of the global configuration by default).
+   *
+   * It is normalized like {@link Configuration#chunkSize}.
    */
   chunkSize?: number;
 }
@@ -743,6 +855,10 @@ type URLString = string;
  * Represents a {@link Reader} instance used to fetch data from a URL.
  */
 export class HttpReader extends Reader<URLString> {
+  /**
+   * The URL of the data, as passed to the constructor.
+   */
+  url: URLString | URL;
   /**
    * Creates the {@link HttpReader} instance
    *
@@ -859,6 +975,12 @@ export interface WritableWriter {
    * The `WritableStream` instance.
    */
   writable: WritableStream;
+  /**
+   * 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.
+   */
+  size?: number;
   /**
    * The maximum size of split data when creating a {@link ZipWriter} instance or when calling {@link FileEntry#getData} with a generator of {@link WritableWriter} instances.
    */
@@ -895,6 +1017,10 @@ export class Writer<Type> implements Initializable, WritableWriter {
    * The `WritableStream` instance.
    */
   writable: WritableStream;
+  /**
+   * The number of bytes written into the instance.
+   */
+  size: number;
   /**
    * Initializes the instance asynchronously
    *
@@ -920,13 +1046,35 @@ export class Writer<Type> implements Initializable, WritableWriter {
 /**
  * Represents a {@link Writer} instance used to retrieve the written data as a `string`.
  */
-export class TextWriter extends Writer<string> {
+export class TextWriter implements Initializable, WritableWriter {
+  /**
+   * The `WritableStream` instance.
+   */
+  writable: WritableStream;
+  /**
+   * The number of bytes written into the instance.
+   */
+  size: number;
+  /**
+   * The encoding of the text returned by {@link TextWriter#getData}.
+   */
+  encoding?: string;
+  /**
+   * Initializes the instance asynchronously
+   */
+  init(): Promise<void>;
   /**
    * Creates the {@link TextWriter} instance
    *
    * @param encoding The encoding of the text.
    */
   constructor(encoding?: string);
+  /**
+   * Retrieves all the written data
+   *
+   * @returns A promise resolving to the written data.
+   */
+  getData(): Promise<string>;
 }
 
 /**
@@ -937,6 +1085,15 @@ export class BlobWriter implements Initializable, WritableWriter {
    * The `WritableStream` instance.
    */
   writable: WritableStream;
+  /**
+   * The number of bytes written into the instance.
+   */
+  size: number;
+  /**
+   * The MIME type of the content, i.e. the type of the `Blob` instance returned by
+   * {@link BlobWriter#getData}.
+   */
+  contentType?: string;
   /**
    * Initializes the instance asynchronously
    */
@@ -959,6 +1116,11 @@ export class BlobWriter implements Initializable, WritableWriter {
  * Represents a {@link Writer} instance used to retrieve the written data as a Data URI `string` encoded in Base64.
  */
 export class Data64URIWriter extends Writer<string> {
+  /**
+   * The MIME type of the content, i.e. the type declared by the Data URI returned by
+   * {@link Data64URIWriter#getData}.
+   */
+  contentType?: string;
   /**
    * Creates the {@link Data64URIWriter} instance
    *
@@ -975,6 +1137,10 @@ export class SplitDataWriter implements Initializable, WritableWriter {
    * The `WritableStream` instance.
    */
   writable: WritableStream;
+  /**
+   * The number of bytes written into the instance.
+   */
+  size: number;
   /**
    * The number of the disk being written.
    */
@@ -1029,6 +1195,11 @@ export class Uint8ArrayWriter extends Writer<Uint8Array<ArrayBuffer>> {
 /**
  * Represents an instance used to create an unzipped stream.
  *
+ * @remarks
+ * The input is entirely read into a `Blob` before the first entry is emitted, because a zip file stores its
+ * central directory at the end. This class is a convenience wrapper around {@link ZipReader} for stream
+ * sources, it does not extract entries while the data is still arriving.
+ *
  * @example
  * This example will take a zip file, decompress it and then save its files and directories to disk.
  * ```
@@ -1119,6 +1290,13 @@ export class ZipReader<Type> {
   );
   /**
    * The global comment of the zip file.
+   *
+   * @remarks
+   * Unlike {@link EntryMetaData#comment}, it is exposed as raw bytes because the zip format defines no
+   * way to record its encoding: section 4.4.26 of the zip specification says nothing about it, and the
+   * end of central directory record has neither a general purpose bit flag nor an extra field, so the
+   * language encoding flag (see Appendix D - Language Encoding (EFS)) cannot apply to it. Decode it with
+   * the encoding agreed with the producer of the zip file.
    */
   comment: Uint8Array;
   /**
@@ -1131,9 +1309,13 @@ export class ZipReader<Type> {
   appendedData?: Uint8Array;
   /**
    * The data of the digital signature record of the central directory (see
-   * {@link ZipWriterCloseOptions#signCentralDirectory}), if the zip file contains one. zip.js does not verify
-   * signatures; use {@link ZipReader#directoryOffset} and {@link ZipReader#directoryLength} to read the signed
-   * central directory data and verify it.
+   * {@link ZipWriterCloseOptions#signCentralDirectory}), if the zip file contains one.
+   *
+   * @remarks
+   * zip.js does not verify signatures. The signed data is the central directory records, read at
+   * {@link ZipReader#directoryOffset}, and it never includes the digital signature record itself. Some writers
+   * (e.g. SecureZIP) store that record inside {@link ZipReader#directoryLength}, so verifying the whole declared
+   * range would always fail.
    */
   digitalSignature?: Uint8Array;
   /**
@@ -1141,7 +1323,9 @@ export class ZipReader<Type> {
    */
   directoryOffset?: number;
   /**
-   * The length in bytes of the central directory as declared in the end of central directory record.
+   * The length in bytes of the central directory as declared in the end of central directory record. Some
+   * writers (e.g. SecureZIP) include the digital signature record in that length, so subtract
+   * `6 + digitalSignature.length` from it when the record is stored inside the declared range.
    */
   directoryLength?: number;
   /**
@@ -1864,13 +2048,24 @@ export interface LocalDirectory {
   extraFieldUSDZ?: EntryExtraField;
 }
 /**
- * Represents an error raised while processing an entry, decorated with entry context.
+ * Represents an error raised while processing an archive or one of its entries, decorated with context.
  */
 export interface EntryError extends Error {
   /**
    * `true` if the zip file is corrupted because the entry data could not be written entirely.
    */
   corruptedEntry?: boolean;
+  /**
+   * The entry whose data overlaps the data of the entry being read, set on the
+   * {@link ERR_OVERLAPPING_ENTRY} error raised by {@link ZipReaderOptions#checkOverlappingEntry}.
+   * It is the only way to identify the other entry of the pair.
+   */
+  overlappingEntry?: Entry;
+  /**
+   * The ambiguity that was detected, set on the {@link ERR_AMBIGUOUS_ARCHIVE} error raised by
+   * {@link GetEntriesOptions#strictness}. See {@link ERR_AMBIGUOUS_ARCHIVE} for the values it takes.
+   */
+  reason?: string;
   /**
    * The id of the related {@link ZipEntry} (filesystem API).
    */
@@ -2418,6 +2613,10 @@ export class ZipWriter<Type> {
    * 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.
+   *
    * @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.
    */
@@ -2466,6 +2665,10 @@ export class ZipWriter<Type> {
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zip file
    *
+   * @remarks
+   * 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}.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2494,6 +2697,13 @@ export interface ZipWriterAddDataOptions
   executable?: boolean;
   /**
    * The comment of the entry.
+   *
+   * @remarks
+   * It is a string, unlike the global comment passed to {@link ZipWriter#close}, because the encoding of
+   * the comment of an entry is recorded in the header by the general purpose bit 11 (see Appendix D -
+   * Language Encoding (EFS)), set by {@link ZipWriterConstructorOptions#useUnicodeFileNames}. Passing raw
+   * bytes here throws {@link ERR_INVALID_ENTRY_COMMENT_TYPE} instead of writing their textual
+   * representation.
    */
   comment?: string;
   /**
@@ -2651,6 +2861,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * The last modification date.
    *
+   * @remarks
+   * This option and the two below must be `Date` instances: a timestamp expressed in milliseconds, e.g.
+   * {@link File#lastModified}, and an invalid `Date` are both rejected with {@link ERR_INVALID_DATE}. An
+   * invalid `Date` used to be written as an entry carrying no timestamp at all.
+   *
    * @defaultValue The current date.
    */
   lastModDate?: Date;
@@ -2747,7 +2962,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * 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.
+   * {@link ZipWriterConstructorOptions#unixMode} or {@link ZipWriterAddDataOptions#executable}, turns it back off, and setting
+   * {@link ZipWriterConstructorOptions#msdosAttributesRaw} or {@link ZipWriterConstructorOptions#msdosAttributes}
+   * turns it on, overriding an explicit `false`.
    *
    * @defaultValue false
    */
@@ -2824,10 +3041,28 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * When provided, the low 8-bit MS-DOS attributes to write into external file attributes.
    * Must be an integer between 0 and 255.
+   *
+   * @remarks
+   * Setting this option or {@link ZipWriterConstructorOptions#msdosAttributes} selects the MS-DOS platform for
+   * the entry exactly as {@link ZipWriterConstructorOptions#msDosCompatible} does, and overrides that option
+   * when it is explicitly set to `false`. {@link EntryMetaData#versionMadeBy} then loses its Unix upper byte
+   * and no Unix mode is written, so the `0o100644` of a file entry and the `0o040755` of a folder entry are
+   * lost. What counts is that the option is provided, not its value: `0` and `{}` trigger it too.
+   *
+   * Setting any Unix metadata option, i.e. {@link ZipWriterConstructorOptions#uid},
+   * {@link ZipWriterConstructorOptions#gid}, {@link ZipWriterConstructorOptions#unixMode},
+   * {@link ZipWriterConstructorOptions#unixExtraFieldType} or {@link ZipWriterAddDataOptions#executable},
+   * takes precedence and keeps the Unix attributes, with the MS-DOS attributes written into the low byte.
+   * {@link ZipWriterConstructorOptions#externalFileAttributes} is preserved as well, although the entry still
+   * declares the MS-DOS platform.
    */
   msdosAttributesRaw?: number;
   /**
    * When provided, MS-DOS attribute flags (boolean object) to write into external file attributes low byte.
+   *
+   * @remarks
+   * See {@link ZipWriterConstructorOptions#msdosAttributesRaw} for the platform this option selects and for
+   * the Unix metadata it leaves out of the entry.
    */
   msdosAttributes?: {
     readOnly?: boolean;
@@ -2855,9 +3090,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * `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
+   * The data is never compressed, so the {@link ZipWriterConstructorOptions#level} option does not apply and is
+   * ignored. The {@link ZipWriterAddDataOptions#compressionMethod} option selects no codec either, it declares
+   * how the data is already compressed and is written as-is in the entry headers. It must be set, otherwise an
+   * {@link ERR_UNDEFINED_COMPRESSION_METHOD} error is thrown. 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
@@ -2944,7 +3181,7 @@ export interface EntryOnprogressOptions {
 /**
  * Represents an entry in a zip file (Filesystem API).
  */
-declare class ZipEntry {
+export class ZipEntry {
   /**
    * The relative filename of the entry.
    */
@@ -2973,6 +3210,15 @@ declare class ZipEntry {
    * The children of the entry.
    */
   children: ZipEntry[];
+  /**
+   * The options applied to the entry when the zip file is exported.
+   *
+   * @remarks
+   * These are the options passed when the entry was added to the filesystem, updated by
+   * {@link ZipEntry#setOptions}. An entry imported from a zip file has none until
+   * {@link ZipEntry#setOptions} is called.
+   */
+  readonly options?: ZipWriterAddDataOptions;
   /**
    * Clones the entry
    *
@@ -3010,6 +3256,24 @@ declare class ZipEntry {
    * @param name The new name of the entry.
    */
   rename(name: string): void;
+  /**
+   * Sets the options applied to the entry when the zip file is exported
+   *
+   * @remarks
+   * The options are merged into {@link ZipEntry#options}, and an option set to `undefined` is removed
+   * from it instead of being stored. They take precedence over the options passed to
+   * `{@link ZipDirectoryEntry}#export*()` and over the metadata of the entry they were imported from,
+   * exactly like the options passed when adding an entry to the filesystem.
+   *
+   * The options describing the data of an entry exported as-is, e.g.
+   * {@link ZipWriterConstructorOptions#compressionMethod} and
+   * {@link ZipWriterAddDataOptions#uncompressedSize}, are ignored: they are always the ones of the
+   * original entry. The {@link ZipWriterAddDataOptions#directory} option and the progress callbacks
+   * are ignored as well. Invalid option values are reported when the zip file is exported.
+   *
+   * @param options The options.
+   */
+  setOptions(options: ZipWriterAddDataOptions): void;
 }
 
 /**
@@ -3163,7 +3427,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    * before the children of its subdirectories, like the result of `readdir(path, { recursive: true })` in
    * Node.js. This is also the order in which `{@link ZipDirectoryEntry}#export*()` writes them.
    *
-   * Unlike {@link FS#entries}, the directory itself is not included and removed entries leave no empty slot.
+   * Unlike {@link ZipFS#entries}, the directory itself is not included and removed entries leave no empty slot.
    *
    * @param options The options.
    * @returns The array of {@link ZipEntry} instances.
@@ -3377,6 +3641,11 @@ export class ZipDirectoryEntry extends ZipEntry {
    * the same `"a/b.txt"` entry. Filenames are normalized and validated beforehand, see
    * {@link GetEntriesOptions#normalizeFilename} and {@link GetEntriesOptions#filenameValidation}.
    *
+   * The directories created that way are navigable like any other entry but are not written back when the
+   * tree is exported: only the directories carried by the source zip file and the ones created with
+   * {@link ZipDirectoryEntry#addDirectory} are written. A zip file storing no directory entry therefore
+   * round-trips to a zip file storing no directory entry, instead of gaining one entry per path component.
+   *
    * 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
@@ -3513,7 +3782,7 @@ export interface ZipDirectoryEntryImportHttpOptions
     HttpOptions {}
 
 /**
- * Represents the options passed to {@link ZipDirectoryEntry#getChildren} and {@link FS#getChildren}.
+ * Represents the options passed to {@link ZipDirectoryEntry#getChildren} and {@link ZipFS#getChildren}.
  */
 export interface ZipDirectoryEntryGetChildrenOptions {
   /**
@@ -3557,6 +3826,13 @@ export interface ZipDirectoryEntryGetChildrenOptions {
  * {@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.
+ *
+ * An entry added without a {@link ZipWriterAddDataOptions#lastModDate} option is dated with the moment
+ * it was added, so exporting an unchanged tree twice produces the same bytes. That date is the weakest
+ * one: it is replaced by the date of the entry the tree was imported from, which is itself replaced by
+ * the {@link ZipWriterConstructorOptions#lastModDate} option passed here, which pins every date of the
+ * exported zip file. Only a {@link ZipWriterAddDataOptions#lastModDate} option passed when the entry
+ * was added takes precedence over all of them.
  */
 export interface ZipDirectoryEntryExportOptions
   extends ZipWriterConstructorOptions,
@@ -3620,12 +3896,14 @@ export interface ZipDirectoryEntryExportOptions
    * 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.
+   *
+   * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
    */
   readerOptions?: ZipReaderConstructorOptions;
 }
 
 /**
- * Represents the options passed to {@link ZipDirectoryEntry#exportFileSystemHandle} and {@link FS#exportFileSystemHandle}.
+ * Represents the options passed to {@link ZipDirectoryEntry#exportFileSystemHandle} and {@link ZipFS#exportFileSystemHandle}.
  *
  * @remarks
  * The {@link ZipReaderOptions#preventClose} option is ignored: the export owns the writable of each
@@ -3651,6 +3929,8 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
    * 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.
+   *
+   * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
    */
   readerOptions?: ZipReaderConstructorOptions;
 }
@@ -3664,16 +3944,16 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
  * const TEXT_CONTENT = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.";
  * const FILENAME = "lorem.txt";
  * const BLOB = new Blob([TEXT_CONTENT], { type: zip.getMimeType(FILENAME) });
- * let zipFs = new zip.fs.FS();
+ * let zipFs = new zip.ZipFS();
  * zipFs.addBlob("lorem.txt", BLOB);
  * const zippedBlob = await zipFs.exportBlob();
- * zipFs = new zip.fs.FS();
+ * zipFs = new zip.ZipFS();
  * await zipFs.importBlob(zippedBlob);
  * const firstEntry = zipFs.children[0];
  * const unzippedBlob = await firstEntry.getBlob(zip.getMimeType(firstEntry.name));
  * ```
  */
-export interface FS
+export interface ZipFS
   extends Pick<
     ZipDirectoryEntry,
     | "getChildByName"
@@ -3705,7 +3985,7 @@ export interface FS
     | "checkPassword"
   > {}
 
-export class FS {
+export class ZipFS {
   /**
    * The root directory.
    */
@@ -3747,20 +4027,35 @@ export class FS {
   getById(id: number): ZipEntry | undefined;
 }
 
+/**
+ * The type of the filesystem.
+ *
+ * @deprecated Use {@link ZipFS} instead.
+ */
+export type FS = ZipFS;
+
 /**
  * The Filesystem API.
+ *
+ * @deprecated Use the {@link ZipFS}, {@link ZipDirectoryEntry} and {@link ZipFileEntry} exports instead.
  */
 export const fs: {
   /**
    * The Filesystem constructor.
+   *
+   * @deprecated Use {@link ZipFS} instead.
    */
-  FS: typeof FS;
+  FS: typeof ZipFS;
   /**
    * The {@link ZipDirectoryEntry} constructor.
+   *
+   * @deprecated Use the {@link ZipDirectoryEntry} export instead.
    */
   ZipDirectoryEntry: typeof ZipDirectoryEntry;
   /**
    * The {@link ZipFileEntry} constructor.
+   *
+   * @deprecated Use the {@link ZipFileEntry} export instead.
    */
   ZipFileEntry: typeof ZipFileEntry;
 };
@@ -3889,14 +4184,59 @@ export const ERR_INVALID_ENTRY_NAME: string;
  * Invalid entry comment error
  */
 export const ERR_INVALID_ENTRY_COMMENT: string;
+/**
+ * Invalid entry comment type error
+ */
+export const ERR_INVALID_ENTRY_COMMENT_TYPE: string;
+/**
+ * Invalid date error
+ */
+export const ERR_INVALID_DATE: string;
+/**
+ * Invalid function option error
+ *
+ * @remarks
+ * Thrown when an option expecting a function is given a value of another type: {@link ZipWriterConstructorOptions#encodeText},
+ * {@link GetEntriesOptions#decodeText}, {@link ZipWriterConstructorOptions#createTempStream},
+ * {@link ZipWriterCloseOptions#signCentralDirectory} and {@link GetEntriesOptions#decryptCentralDirectory}. It is also
+ * thrown by {@link configure} for {@link Configuration#createWorker}, {@link Configuration#CompressionStream},
+ * {@link Configuration#DecompressionStream}, {@link Configuration#CompressionStreamFallback} and
+ * {@link Configuration#DecompressionStreamFallback}. A falsy value keeps meaning "use the default".
+ */
+export const ERR_INVALID_FUNCTION_OPTION: string;
+/**
+ * Invalid signal error
+ *
+ * @remarks
+ * Thrown when the `signal` option is not an `AbortSignal`. Any object exposing `addEventListener()` and a boolean `aborted`
+ * property is accepted, so a signal coming from another realm keeps working.
+ */
+export const ERR_INVALID_SIGNAL: string;
+/**
+ * Invalid maxWorkers error
+ *
+ * @remarks
+ * Thrown by {@link configure} when {@link Configuration#maxWorkers} is not an integer greater than 0. A value lower than 1
+ * used to deadlock {@link ZipWriter#add} for ever, since no entry could start and none could release the next one. Pass
+ * {@link Configuration#useWebWorkers} set to `false` to compress and decompress data in the main thread instead.
+ */
+export const ERR_INVALID_MAX_WORKERS: string;
 /**
  * Invalid version error
  */
 export const ERR_INVALID_VERSION: string;
+/**
+ * Invalid extra field error
+ */
+export const ERR_INVALID_EXTRAFIELD: string;
 /**
  * Invalid extra field type error
  */
 export const ERR_INVALID_EXTRAFIELD_TYPE: string;
+/**
+ * Invalid extra field data type error
+ */
+export const ERR_INVALID_EXTRAFIELD_DATA_TYPE: string;
 /**
  * Invalid extra field data error
  */
@@ -3923,12 +4263,29 @@ export const ERR_UNSUPPORTED_FORMAT: string;
 export const ERR_SPLIT_ZIP_FILE: string;
 /**
  * Overlapping entry error
+ *
+ * @remarks Thrown by {@link FileEntry#getData} when {@link ZipReaderOptions#checkOverlappingEntry} is set and the
+ * data of the entry overlaps the data of an entry already read. The thrown error carries the other entry in its
+ * `overlappingEntry` property.
  */
 export const ERR_OVERLAPPING_ENTRY: string;
+/**
+ * Entry data out of bounds error
+ *
+ * @remarks Thrown by {@link FileEntry#getData} when the declared extent of the entry data (i.e. its offset plus its compressed size) ends past the end of the zip file.
+ */
+export const ERR_ENTRY_DATA_OUT_OF_BOUNDS: string;
 /**
  * Ambiguous archive error
  *
- * @remarks The thrown error carries a `reason` property describing the ambiguity: `"appended data"`, `"prepended data"`, `"trailing central directory data"`, `"mismatched zip64 end of central directory record"`, or `"duplicate filename"`.
+ * @remarks The thrown error carries a `reason` property describing the ambiguity: `"appended data"`,
+ * `"prepended data"`, `"trailing central directory data"`, `"multiple end of central directory records"`,
+ * `"mismatched zip64 end of central directory record"`, `"duplicate filename"`, or, when
+ * {@link ZipReaderOptions#checkLocalDirectory} compares the local header of an entry with its central
+ * directory record, `"mismatched local file header (filename)"`,
+ * `"mismatched local file header (general purpose bit flag)"`,
+ * `"mismatched local file header (compression method)"` or
+ * `"mismatched local file header (crc32 or sizes)"`.
  */
 export const ERR_AMBIGUOUS_ARCHIVE: string;
 /**
@@ -3966,6 +4323,10 @@ export const ERR_ITERATOR_COMPLETED_TOO_SOON: string;
  * Undefined uncompressed size error
  */
 export const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string;
+/**
+ * Undefined compression method error
+ */
+export const ERR_UNDEFINED_COMPRESSION_METHOD: string;
 export const ERR_UNDETERMINED_SIZE: string;
 /**
  * Undefined reader error
@@ -4023,7 +4384,9 @@ export const ERR_INVALID_LEVEL: string;
  * Invalid password error (thrown when the `password` option is not a string, or the `rawPassword` option is not a `Uint8Array`)
  *
  * @remarks A value of another type would silently produce an unencrypted archive, and a `rawPassword` passed as a string
- * would produce an archive that cannot be opened with the equivalent {@link ZipWriterConstructorOptions#password}.
+ * would produce an archive that cannot be opened with the equivalent {@link ZipWriterConstructorOptions#password}. The
+ * reader applies the same check, where a value of another type used to fail with the unrelated {@link ERR_ENCRYPTED} or
+ * {@link ERR_INVALID_PASSWORD}.
  */
 export const ERR_INVALID_PASSWORD_TYPE: string;
 /**
@@ -4036,6 +4399,16 @@ export const ERR_INVALID_PASSWORD_TYPE: string;
  * or set the {@link ZipWriterAddDataOptions#uncompressedSize} option of each entry holding compressed data.
  */
 export const ERR_INVALID_PASS_THROUGH: string;
+/**
+ * Invalid readerOptions error (thrown by `{@link ZipDirectoryEntry}#export*()`,
+ * {@link ZipDirectoryEntry#getExportedSize} and {@link ZipDirectoryEntry#exportFileSystemHandle} when the
+ * {@link ZipDirectoryEntryExportOptions#readerOptions} option is neither an object nor unset)
+ *
+ * @remarks A value of another type was silently ignored: a password passed as a string instead of an object failed
+ * with the unrelated {@link ERR_ENCRYPTED}, while the other options were dropped without any error. Note that an
+ * unknown property of a `readerOptions` object is still ignored, as everywhere else in the API.
+ */
+export const ERR_INVALID_READER_OPTIONS: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */