@zip.js/zip.js 2.20.0 → 2.22.0

package/index.d.cts

@@ -635,13 +635,6 @@ export interface WorkerConfiguration {
    * @defaultValue true
    */
   useCompressionStream?: boolean;
-  /**
-   * `true` to transfer stream ownership to web workers.
-   *
-   * @deprecated The option is ignored whatever its value: the data always crosses the worker boundary chunk by
-   * chunk, transferring the streams instead was slower on every engine measured.
-   */
-  transferStreams?: boolean;
 }
 
 /**
@@ -1545,8 +1538,9 @@ export class ZipReader<Type> {
    * {@link WARNING_APPENDED_DATA}, {@link WARNING_PREPENDED_DATA}, {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA},
    * {@link WARNING_MISMATCHED_CENTRAL_DIRECTORY_OFFSET}, {@link WARNING_DUPLICATE_FILENAME} and
    * {@link WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY}.
-   * {@link WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY} is the one reason of that group which is never tolerated,
-   * so it is only ever the reason of an error. {@link WARNING_MISSING_ZIP64_EXTRA_FIELD} is deposited when an
+   * {@link WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY} is never deposited as a warning: `"balanced"` rejects it
+   * like `"strict"`, and `"tolerant"` reads the last record and reports the stale one as
+   * {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA}. {@link WARNING_MISSING_ZIP64_EXTRA_FIELD} is deposited when an
    * entry cannot be read because its central directory record lacks a Zip64 extra field, and `"strict"` throws
    * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} for it.
    *
@@ -1889,7 +1883,10 @@ export interface ZipReaderOptions {
    * (e.g. streaming readers based on local file headers) interpret the entry differently. This detects mismatched
    * filenames, general purpose bit flags (encryption, data descriptor and language encoding flags), compression
    * methods, CRC-32 checksums and sizes. The extra fields are not compared because the zip specification allows
-   * them to differ.
+   * them to differ. A local file header whose CRC-32 checksum and sizes are all zero without the data descriptor
+   * flag is tolerated, because some streaming writers leave these fields blank. When the entry has a data
+   * descriptor, its CRC-32 checksum and sizes are compared with the central directory record instead, provided
+   * the descriptor is read, i.e. when {@link ZipReaderOptions#checkOverlappingEntry} is set.
    *
    * This is the boolean form of {@link ZipReaderOptions#strictness}: `true` means `"strict"` and `false` means
    * any value but `"strict"`. When both options are set, the value passed to {@link FileEntry#getData} takes
@@ -2566,11 +2563,13 @@ export interface EntryMetaData {
    */
   lastModDate: Date;
   /**
-   * The last access date.
+   * The last access date, read from the extra fields of the central directory record or, when it holds none, from
+   * the extra fields of the local file header once the data of the entry has been read.
    */
   lastAccessDate?: Date;
   /**
-   * The creation date.
+   * The creation date, read from the extra fields of the central directory record or, when it holds none, from
+   * the extra fields of the local file header once the data of the entry has been read.
    */
   creationDate?: Date;
   /**
@@ -3073,15 +3072,25 @@ export class ZipWriter<Type> {
    * @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 disks of the output, which is a single zip file unless the writer is a split zip file writer. In that case,
+   * the bytes before the first entry (e.g. a self-extracting stub) are copied after the split zip file signature of
+   * the first disk, where no system runs them; use the {@link ZipWriterAppendZipOptions#filter} option to drop them. 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.
+   * are not applied to the copied entries. The comment and the digital signature of the zip file are not copied,
+   * since its central directory is rebuilt: pass them to {@link ZipWriter#close}.
    *
-   * 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
+   * Pending {@link ZipWriter#add} calls are completed before the data is copied. add() calls made while the
+   * `filter` option runs are written before the copied entries, and add() calls made once the copy has started
+   * 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 conflicts. The same error is thrown when two entries of the zip file share a filename, since a
+   * `ZipWriter` holds one entry per filename: use the {@link ZipWriterAppendZipOptions#filter} option to
+   * keep one of them. The entries passed to `filter` are not modified by the copy. An entry whose sizes or
+   * offset are unusable because its Zip64 extra field is missing (see
+   * {@link WARNING_MISSING_ZIP64_EXTRA_FIELD}) cannot be copied: the method throws
+   * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} and leaves the current zip unchanged, unless the
+   * {@link ZipWriterAppendZipOptions#filter} option leaves the entry out.
    *
    * 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.
@@ -3162,10 +3171,11 @@ export class ZipWriter<Type> {
    * Removes an entry from the central directory that will be written for the zip file. The entry
    * data itself cannot be removed because it has already been streamed to the output.
    *
-   * @param entry The entry to remove. This can be an {@link Entry} instance or the filename of the entry.
+   * @param entry The entry to remove. This can be an {@link Entry} instance, the {@link EntryMetaData} returned by
+   * {@link ZipWriter#add} or passed to the `filter` option of {@link ZipWriter#appendZip}, or the filename of the entry.
    * @returns `true` if the entry has been removed, `false` otherwise.
    */
-  remove(entry: Entry | string): boolean;
+  remove(entry: EntryMetaData | string): boolean;
 
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zip file
@@ -3328,20 +3338,52 @@ export interface ZipWriterAppendZipOptions {
   /**
    * Selects the entries of the zip file to copy: the function is called once per entry, in the order of the
    * central directory, and the entry is copied when it returns (or resolves to) `true`. The function can read
-   * the data of the entry with {@link Entry#getData} to decide, the zip file is closed after the last call.
+   * the data of the entry with {@link Entry#getData} to decide: every call completes before any data is copied.
+   *
+   * The second argument is the entry of the current zip which has the same filename, as {@link ZipWriter#add}
+   * or a previous call to {@link ZipWriter#appendZip} left it, or `undefined` when there is none. It is the way to
+   * apply a duplicate filename policy, since keeping both entries throws `ERR_DUPLICATED_NAME`: return
+   * `!existingEntry` to keep the entry of the current zip, call {@link ZipWriter#remove} with `existingEntry` and
+   * return `true` to replace it, or compare `crc32`, `uncompressedSize` or `lastModDate` to decide. An entry
+   * being added concurrently by a pending {@link ZipWriter#add} call is not passed.
    *
    * @remarks
    * When the option is set, the data of the zip file is copied entry by entry and the entries left out leave no
    * bytes behind in the output, unlike {@link ZipWriter#remove}, which drops an entry from the central directory
-   * after its data has been written. The bytes of the zip file outside its entries, e.g. a self-extracting stub
-   * before the first entry, are not copied either. Without the option, the data of the zip file is copied as a
-   * whole. The duplicate filename check applies to the entries kept only, so an entry can be replaced by
-   * leaving it out and adding its replacement with {@link ZipWriter#add}.
+   * after its data has been written. The bytes of the zip file outside the entries kept are not copied either:
+   * a self-extracting stub, the data of entries removed earlier and the padding between entries, so a zip file
+   * aligned with {@link ZipWriterConstructorOptions#usdz} is not aligned any more once filtered. Without the
+   * option, the data of the zip file is copied as a whole. The duplicate filename check applies to the entries
+   * kept only, so an entry can be replaced by leaving it out and adding its replacement with {@link ZipWriter#add}.
+   *
+   * An entry is copied from its local file header to the end of its data or, when it has one, of its data
+   * descriptor, whose layout is read back from the zip file; when no layout matches, the entry is copied up to
+   * the next entry or to the central directory. Before anything is written, each kept entry is checked to start
+   * with a local file header and to end before the next entry or the central directory; otherwise the method
+   * throws {@link ERR_LOCAL_FILE_HEADER_NOT_FOUND} or {@link ERR_OVERLAPPING_ENTRY} and leaves the current zip
+   * unchanged. The same checks apply when the output is a split zip file, whose entries are copied one by one
+   * as well.
    *
    * @param entry The entry read from the zip file.
+   * @param existingEntry The entry of the current zip with the same filename, if any.
    * @returns `true` to copy the entry.
    */
-  filter?: (entry: Entry) => boolean | Promise<boolean>;
+  filter?: (entry: Entry, existingEntry?: EntryMetaData) => boolean | Promise<boolean>;
+  /**
+   * The options of the {@link ZipReader} which reads the zip file.
+   *
+   * @remarks
+   * The zip file is read with the default options otherwise, so a zip file which a `ZipReader` rejects by default
+   * cannot be appended as-is: set {@link ZipReaderConstructorOptions#filenameValidation} or
+   * {@link ZipReaderConstructorOptions#strictness} here to copy the entries of a zip file holding unsafe or
+   * unusual filenames, {@link ZipReaderConstructorOptions#filenameEncoding} to decode the filenames the
+   * duplicate check and the `filter` option see, and {@link ZipReaderConstructorOptions#password} to let
+   * `filter` read the data of encrypted entries with {@link Entry#getData}. The bytes of the entries are copied
+   * as-is whatever the options are.
+   *
+   * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
+   */
+  readerOptions?: ZipReaderConstructorOptions;
 }
 
 export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
@@ -5046,6 +5088,9 @@ export const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
 export const ERR_CENTRAL_DIRECTORY_NOT_FOUND: string;
 /**
  * Local file header not found error
+ *
+ * @remarks Also thrown by {@link ZipWriter#appendZip} when a copied entry does not point at a local file header
+ * (see {@link ZipWriterAppendZipOptions#filter}).
  */
 export const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
 /**
@@ -5059,7 +5104,8 @@ export const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
  * {@link WARNING_MALFORMED_EXTRA_FIELD} on {@link EntryMetaData#warnings}, and an entry without a data descriptor
  * keeps the sentinels as its local sizes, which the local file header check reports as
  * {@link WARNING_MISMATCHED_LOCAL_FILE_HEADER_CRC32_OR_SIZES}, an error or a warning depending on
- * {@link ZipReaderOptions#strictness}.
+ * {@link ZipReaderOptions#strictness}. Also thrown by {@link ZipWriter#appendZip}, before anything is written,
+ * when an entry to copy lacks the field (see {@link WARNING_MISSING_ZIP64_EXTRA_FIELD}).
  */
 export const ERR_EXTRAFIELD_ZIP64_NOT_FOUND: string;
 /**
@@ -5281,13 +5327,16 @@ export const ERR_SPLIT_ZIP_FILE: string;
  *
  * @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.
+ * `overlappingEntry` property. Also thrown by {@link ZipWriter#appendZip} when the data of a copied entry runs
+ * into the next entry or into the central directory (see {@link ZipWriterAppendZipOptions#filter}).
  */
 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.
+ * @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 central directory or past the end of the zip file, whatever
+ * {@link ZipReaderOptions#strictness} and {@link ZipReaderOptions#checkOverlappingEntry} are set to.
  */
 export const ERR_ENTRY_DATA_OUT_OF_BOUNDS: string;
 /**
@@ -5295,7 +5344,8 @@ export const ERR_ENTRY_DATA_OUT_OF_BOUNDS: string;
  *
  * @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
+ * `"mismatched central directory offset"`, `"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)"`,
@@ -5477,7 +5527,8 @@ export const ERR_UNSUPPORTED_PASS_THROUGH_VALUE: 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)
+ * {@link ZipDirectoryEntryExportOptions#readerOptions} option is neither an object nor unset, and by
+ * {@link ZipWriter#appendZip} for {@link ZipWriterAppendZipOptions#readerOptions})
  *
  * @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
@@ -5637,24 +5688,26 @@ export const WARNING_PREPENDED_CENTRAL_DIRECTORY: string;
  */
 export const WARNING_TRAILING_CENTRAL_DIRECTORY_DATA: string;
 /**
- * Warning reason: the end of central directory record stores a central directory offset that points past the
- * central directory actually found before it, so the archive was read from the directory found rather than from
- * the stored offset (see {@link ZipReader#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
+ * Warning reason: the end of central directory record stores a central directory offset that does not point at
+ * the central directory actually found before it, so the archive was read from the directory found rather than
+ * from the stored offset (see {@link ZipReader#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
  * `strictness: "strict"`
  *
  * @remarks
  * Such an archive is typically one written with absolute offsets for a prefix that is no longer there, e.g. a
- * self-extracting archive whose stub was removed. When the local file header of the first entry is found at
- * the same shifted position, the entries are read from the shifted positions; otherwise the offsets stored in
- * the central directory are used as they are.
+ * self-extracting archive whose stub was removed, or one whose end of central directory record was damaged.
+ * When the local file header of the first entry is found at the same shifted position only, the entries are
+ * read from the shifted positions; otherwise the offsets stored in the central directory are used as they are.
+ * A stored offset short of the directory whose entries are found at the shifted positions is diagnosed as
+ * {@link WARNING_PREPENDED_DATA} instead.
  */
 export const WARNING_MISMATCHED_CENTRAL_DIRECTORY_OFFSET: string;
 /**
  * Warning reason: a central directory record holds the Zip64 sentinel in a size, offset or disk number field
  * but carries no Zip64 extra field resolving it (see {@link ZipReader#warnings}). The entry is listed, its
- * sizes and offset are unusable, and reading its data throws {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND}; the
- * other entries are unaffected. Under `strictness: "strict"`, {@link ZipReader#getEntries} throws
- * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} instead.
+ * sizes and offset are unusable, and reading its data or copying it with {@link ZipWriter#appendZip} throws
+ * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND}; the other entries are unaffected. Under `strictness: "strict"`,
+ * {@link ZipReader#getEntries} throws {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} instead.
  */
 export const WARNING_MISSING_ZIP64_EXTRA_FIELD: string;
 /**
@@ -5669,8 +5722,9 @@ export const WARNING_DUPLICATE_FILENAME: string;
 export const WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY: string;
 /**
  * Warning reason: more than one end of central directory record reaches the end of the file, so another reader
- * may select a different one and list different entries; the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
- * {@link ZipReaderOptions#checkAmbiguity} is enabled
+ * may select a different one and list different entries; the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
+ * `strictness: "strict"` and `"balanced"`. It is never deposited as a warning: `"tolerant"` reads the last
+ * record and reports the stale one as {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA}.
  */
 export const WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY: string;
 /**
@@ -5694,7 +5748,8 @@ export const WARNING_MISMATCHED_LOCAL_FILE_HEADER_BIT_FLAG: string;
  */
 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
+ * Warning reason: the crc32 or the sizes of the local file header, or of the data descriptor when it is read
+ * (see {@link ZipReaderOptions#checkOverlappingEntry}), contradict the central directory
  * (see {@link EntryMetaData#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
  * {@link ZipReaderOptions#checkLocalDirectory} is enabled
  */

package/index.d.ts

@@ -635,13 +635,6 @@ export interface WorkerConfiguration {
    * @defaultValue true
    */
   useCompressionStream?: boolean;
-  /**
-   * `true` to transfer stream ownership to web workers.
-   *
-   * @deprecated The option is ignored whatever its value: the data always crosses the worker boundary chunk by
-   * chunk, transferring the streams instead was slower on every engine measured.
-   */
-  transferStreams?: boolean;
 }
 
 /**
@@ -1545,8 +1538,9 @@ export class ZipReader<Type> {
    * {@link WARNING_APPENDED_DATA}, {@link WARNING_PREPENDED_DATA}, {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA},
    * {@link WARNING_MISMATCHED_CENTRAL_DIRECTORY_OFFSET}, {@link WARNING_DUPLICATE_FILENAME} and
    * {@link WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY}.
-   * {@link WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY} is the one reason of that group which is never tolerated,
-   * so it is only ever the reason of an error. {@link WARNING_MISSING_ZIP64_EXTRA_FIELD} is deposited when an
+   * {@link WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY} is never deposited as a warning: `"balanced"` rejects it
+   * like `"strict"`, and `"tolerant"` reads the last record and reports the stale one as
+   * {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA}. {@link WARNING_MISSING_ZIP64_EXTRA_FIELD} is deposited when an
    * entry cannot be read because its central directory record lacks a Zip64 extra field, and `"strict"` throws
    * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} for it.
    *
@@ -1889,7 +1883,10 @@ export interface ZipReaderOptions {
    * (e.g. streaming readers based on local file headers) interpret the entry differently. This detects mismatched
    * filenames, general purpose bit flags (encryption, data descriptor and language encoding flags), compression
    * methods, CRC-32 checksums and sizes. The extra fields are not compared because the zip specification allows
-   * them to differ.
+   * them to differ. A local file header whose CRC-32 checksum and sizes are all zero without the data descriptor
+   * flag is tolerated, because some streaming writers leave these fields blank. When the entry has a data
+   * descriptor, its CRC-32 checksum and sizes are compared with the central directory record instead, provided
+   * the descriptor is read, i.e. when {@link ZipReaderOptions#checkOverlappingEntry} is set.
    *
    * This is the boolean form of {@link ZipReaderOptions#strictness}: `true` means `"strict"` and `false` means
    * any value but `"strict"`. When both options are set, the value passed to {@link FileEntry#getData} takes
@@ -2566,11 +2563,13 @@ export interface EntryMetaData {
    */
   lastModDate: Date;
   /**
-   * The last access date.
+   * The last access date, read from the extra fields of the central directory record or, when it holds none, from
+   * the extra fields of the local file header once the data of the entry has been read.
    */
   lastAccessDate?: Date;
   /**
-   * The creation date.
+   * The creation date, read from the extra fields of the central directory record or, when it holds none, from
+   * the extra fields of the local file header once the data of the entry has been read.
    */
   creationDate?: Date;
   /**
@@ -3073,15 +3072,25 @@ export class ZipWriter<Type> {
    * @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 disks of the output, which is a single zip file unless the writer is a split zip file writer. In that case,
+   * the bytes before the first entry (e.g. a self-extracting stub) are copied after the split zip file signature of
+   * the first disk, where no system runs them; use the {@link ZipWriterAppendZipOptions#filter} option to drop them. 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.
+   * are not applied to the copied entries. The comment and the digital signature of the zip file are not copied,
+   * since its central directory is rebuilt: pass them to {@link ZipWriter#close}.
    *
-   * 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
+   * Pending {@link ZipWriter#add} calls are completed before the data is copied. add() calls made while the
+   * `filter` option runs are written before the copied entries, and add() calls made once the copy has started
+   * 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 conflicts. The same error is thrown when two entries of the zip file share a filename, since a
+   * `ZipWriter` holds one entry per filename: use the {@link ZipWriterAppendZipOptions#filter} option to
+   * keep one of them. The entries passed to `filter` are not modified by the copy. An entry whose sizes or
+   * offset are unusable because its Zip64 extra field is missing (see
+   * {@link WARNING_MISSING_ZIP64_EXTRA_FIELD}) cannot be copied: the method throws
+   * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} and leaves the current zip unchanged, unless the
+   * {@link ZipWriterAppendZipOptions#filter} option leaves the entry out.
    *
    * 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.
@@ -3162,10 +3171,11 @@ export class ZipWriter<Type> {
    * Removes an entry from the central directory that will be written for the zip file. The entry
    * data itself cannot be removed because it has already been streamed to the output.
    *
-   * @param entry The entry to remove. This can be an {@link Entry} instance or the filename of the entry.
+   * @param entry The entry to remove. This can be an {@link Entry} instance, the {@link EntryMetaData} returned by
+   * {@link ZipWriter#add} or passed to the `filter` option of {@link ZipWriter#appendZip}, or the filename of the entry.
    * @returns `true` if the entry has been removed, `false` otherwise.
    */
-  remove(entry: Entry | string): boolean;
+  remove(entry: EntryMetaData | string): boolean;
 
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zip file
@@ -3328,20 +3338,52 @@ export interface ZipWriterAppendZipOptions {
   /**
    * Selects the entries of the zip file to copy: the function is called once per entry, in the order of the
    * central directory, and the entry is copied when it returns (or resolves to) `true`. The function can read
-   * the data of the entry with {@link Entry#getData} to decide, the zip file is closed after the last call.
+   * the data of the entry with {@link Entry#getData} to decide: every call completes before any data is copied.
+   *
+   * The second argument is the entry of the current zip which has the same filename, as {@link ZipWriter#add}
+   * or a previous call to {@link ZipWriter#appendZip} left it, or `undefined` when there is none. It is the way to
+   * apply a duplicate filename policy, since keeping both entries throws `ERR_DUPLICATED_NAME`: return
+   * `!existingEntry` to keep the entry of the current zip, call {@link ZipWriter#remove} with `existingEntry` and
+   * return `true` to replace it, or compare `crc32`, `uncompressedSize` or `lastModDate` to decide. An entry
+   * being added concurrently by a pending {@link ZipWriter#add} call is not passed.
    *
    * @remarks
    * When the option is set, the data of the zip file is copied entry by entry and the entries left out leave no
    * bytes behind in the output, unlike {@link ZipWriter#remove}, which drops an entry from the central directory
-   * after its data has been written. The bytes of the zip file outside its entries, e.g. a self-extracting stub
-   * before the first entry, are not copied either. Without the option, the data of the zip file is copied as a
-   * whole. The duplicate filename check applies to the entries kept only, so an entry can be replaced by
-   * leaving it out and adding its replacement with {@link ZipWriter#add}.
+   * after its data has been written. The bytes of the zip file outside the entries kept are not copied either:
+   * a self-extracting stub, the data of entries removed earlier and the padding between entries, so a zip file
+   * aligned with {@link ZipWriterConstructorOptions#usdz} is not aligned any more once filtered. Without the
+   * option, the data of the zip file is copied as a whole. The duplicate filename check applies to the entries
+   * kept only, so an entry can be replaced by leaving it out and adding its replacement with {@link ZipWriter#add}.
+   *
+   * An entry is copied from its local file header to the end of its data or, when it has one, of its data
+   * descriptor, whose layout is read back from the zip file; when no layout matches, the entry is copied up to
+   * the next entry or to the central directory. Before anything is written, each kept entry is checked to start
+   * with a local file header and to end before the next entry or the central directory; otherwise the method
+   * throws {@link ERR_LOCAL_FILE_HEADER_NOT_FOUND} or {@link ERR_OVERLAPPING_ENTRY} and leaves the current zip
+   * unchanged. The same checks apply when the output is a split zip file, whose entries are copied one by one
+   * as well.
    *
    * @param entry The entry read from the zip file.
+   * @param existingEntry The entry of the current zip with the same filename, if any.
    * @returns `true` to copy the entry.
    */
-  filter?: (entry: Entry) => boolean | Promise<boolean>;
+  filter?: (entry: Entry, existingEntry?: EntryMetaData) => boolean | Promise<boolean>;
+  /**
+   * The options of the {@link ZipReader} which reads the zip file.
+   *
+   * @remarks
+   * The zip file is read with the default options otherwise, so a zip file which a `ZipReader` rejects by default
+   * cannot be appended as-is: set {@link ZipReaderConstructorOptions#filenameValidation} or
+   * {@link ZipReaderConstructorOptions#strictness} here to copy the entries of a zip file holding unsafe or
+   * unusual filenames, {@link ZipReaderConstructorOptions#filenameEncoding} to decode the filenames the
+   * duplicate check and the `filter` option see, and {@link ZipReaderConstructorOptions#password} to let
+   * `filter` read the data of encrypted entries with {@link Entry#getData}. The bytes of the entries are copied
+   * as-is whatever the options are.
+   *
+   * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
+   */
+  readerOptions?: ZipReaderConstructorOptions;
 }
 
 export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
@@ -5046,6 +5088,9 @@ export const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
 export const ERR_CENTRAL_DIRECTORY_NOT_FOUND: string;
 /**
  * Local file header not found error
+ *
+ * @remarks Also thrown by {@link ZipWriter#appendZip} when a copied entry does not point at a local file header
+ * (see {@link ZipWriterAppendZipOptions#filter}).
  */
 export const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
 /**
@@ -5059,7 +5104,8 @@ export const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
  * {@link WARNING_MALFORMED_EXTRA_FIELD} on {@link EntryMetaData#warnings}, and an entry without a data descriptor
  * keeps the sentinels as its local sizes, which the local file header check reports as
  * {@link WARNING_MISMATCHED_LOCAL_FILE_HEADER_CRC32_OR_SIZES}, an error or a warning depending on
- * {@link ZipReaderOptions#strictness}.
+ * {@link ZipReaderOptions#strictness}. Also thrown by {@link ZipWriter#appendZip}, before anything is written,
+ * when an entry to copy lacks the field (see {@link WARNING_MISSING_ZIP64_EXTRA_FIELD}).
  */
 export const ERR_EXTRAFIELD_ZIP64_NOT_FOUND: string;
 /**
@@ -5281,13 +5327,16 @@ export const ERR_SPLIT_ZIP_FILE: string;
  *
  * @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.
+ * `overlappingEntry` property. Also thrown by {@link ZipWriter#appendZip} when the data of a copied entry runs
+ * into the next entry or into the central directory (see {@link ZipWriterAppendZipOptions#filter}).
  */
 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.
+ * @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 central directory or past the end of the zip file, whatever
+ * {@link ZipReaderOptions#strictness} and {@link ZipReaderOptions#checkOverlappingEntry} are set to.
  */
 export const ERR_ENTRY_DATA_OUT_OF_BOUNDS: string;
 /**
@@ -5295,7 +5344,8 @@ export const ERR_ENTRY_DATA_OUT_OF_BOUNDS: string;
  *
  * @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
+ * `"mismatched central directory offset"`, `"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)"`,
@@ -5477,7 +5527,8 @@ export const ERR_UNSUPPORTED_PASS_THROUGH_VALUE: 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)
+ * {@link ZipDirectoryEntryExportOptions#readerOptions} option is neither an object nor unset, and by
+ * {@link ZipWriter#appendZip} for {@link ZipWriterAppendZipOptions#readerOptions})
  *
  * @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
@@ -5637,24 +5688,26 @@ export const WARNING_PREPENDED_CENTRAL_DIRECTORY: string;
  */
 export const WARNING_TRAILING_CENTRAL_DIRECTORY_DATA: string;
 /**
- * Warning reason: the end of central directory record stores a central directory offset that points past the
- * central directory actually found before it, so the archive was read from the directory found rather than from
- * the stored offset (see {@link ZipReader#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
+ * Warning reason: the end of central directory record stores a central directory offset that does not point at
+ * the central directory actually found before it, so the archive was read from the directory found rather than
+ * from the stored offset (see {@link ZipReader#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
  * `strictness: "strict"`
  *
  * @remarks
  * Such an archive is typically one written with absolute offsets for a prefix that is no longer there, e.g. a
- * self-extracting archive whose stub was removed. When the local file header of the first entry is found at
- * the same shifted position, the entries are read from the shifted positions; otherwise the offsets stored in
- * the central directory are used as they are.
+ * self-extracting archive whose stub was removed, or one whose end of central directory record was damaged.
+ * When the local file header of the first entry is found at the same shifted position only, the entries are
+ * read from the shifted positions; otherwise the offsets stored in the central directory are used as they are.
+ * A stored offset short of the directory whose entries are found at the shifted positions is diagnosed as
+ * {@link WARNING_PREPENDED_DATA} instead.
  */
 export const WARNING_MISMATCHED_CENTRAL_DIRECTORY_OFFSET: string;
 /**
  * Warning reason: a central directory record holds the Zip64 sentinel in a size, offset or disk number field
  * but carries no Zip64 extra field resolving it (see {@link ZipReader#warnings}). The entry is listed, its
- * sizes and offset are unusable, and reading its data throws {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND}; the
- * other entries are unaffected. Under `strictness: "strict"`, {@link ZipReader#getEntries} throws
- * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} instead.
+ * sizes and offset are unusable, and reading its data or copying it with {@link ZipWriter#appendZip} throws
+ * {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND}; the other entries are unaffected. Under `strictness: "strict"`,
+ * {@link ZipReader#getEntries} throws {@link ERR_EXTRAFIELD_ZIP64_NOT_FOUND} instead.
  */
 export const WARNING_MISSING_ZIP64_EXTRA_FIELD: string;
 /**
@@ -5669,8 +5722,9 @@ export const WARNING_DUPLICATE_FILENAME: string;
 export const WARNING_MISMATCHED_ZIP64_END_OF_CENTRAL_DIRECTORY: string;
 /**
  * Warning reason: more than one end of central directory record reaches the end of the file, so another reader
- * may select a different one and list different entries; the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
- * {@link ZipReaderOptions#checkAmbiguity} is enabled
+ * may select a different one and list different entries; the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under
+ * `strictness: "strict"` and `"balanced"`. It is never deposited as a warning: `"tolerant"` reads the last
+ * record and reports the stale one as {@link WARNING_TRAILING_CENTRAL_DIRECTORY_DATA}.
  */
 export const WARNING_MULTIPLE_END_OF_CENTRAL_DIRECTORY: string;
 /**
@@ -5694,7 +5748,8 @@ export const WARNING_MISMATCHED_LOCAL_FILE_HEADER_BIT_FLAG: string;
  */
 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
+ * Warning reason: the crc32 or the sizes of the local file header, or of the data descriptor when it is read
+ * (see {@link ZipReaderOptions#checkOverlappingEntry}), contradict the central directory
  * (see {@link EntryMetaData#warnings}); the reason of {@link ERR_AMBIGUOUS_ARCHIVE} when
  * {@link ZipReaderOptions#checkLocalDirectory} is enabled
  */