@zip.js/zip.js 2.19.0 → 2.21.0

package/index.d.cts

@@ -1543,9 +1543,13 @@ export class ZipReader<Type> {
    * `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}.
-   * {@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_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 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.
    *
    * The warnings related to the local file header of an entry are deposited on
    * {@link EntryMetaData#warnings} when its data is read, not here.
@@ -1758,9 +1762,10 @@ export interface GetEntriesOptions {
    * systems, and it also occurs as the trail byte of legitimate double-byte filenames (e.g. CP932) decoded with
    * another charset.
    *
-   * Names are validated, never rewritten, so the filename reported for an entry always matches its central
-   * directory record. The name validated is the final one, i.e. the name of a valid Unicode Path extra field
-   * (see {@link EntryMetaData#extraFieldUnicodePath}) when the entry carries one.
+   * Names are validated, never rewritten: the filename reported for an entry is the one its central directory
+   * record stores, decoded, or the one of its Unicode Path extra field when the entry carries a valid one (see
+   * {@link EntryMetaData#extraFieldUnicodePath}), and the bytes of the record stay available in
+   * {@link EntryMetaData#rawFilename}. The name validated is that final name.
    *
    * @defaultValue The value of {@link GetEntriesOptions#strictness}.
    */
@@ -1885,7 +1890,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
@@ -2521,7 +2529,9 @@ export interface EntryMetaData {
    * `true` if the entry is an executable file
    *
    * Always `false` when {@link EntryMetaData#symlink} is `true`: the permissions of a symbolic link
-   * are not meaningful, Unix systems store them as `0o777`.
+   * are not meaningful, Unix systems store them as `0o777`. Always `false` when
+   * {@link EntryMetaData#directory} is `true` too: the execute bits of a directory mean that it can be
+   * searched, and every directory carries them; read {@link EntryMetaData#unixMode} for the bits themselves.
    */
   executable: boolean;
   /**
@@ -2560,17 +2570,20 @@ 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;
   /**
    * The last modification date (raw), as the MS-DOS date and time stored in the header. Unlike
-   * {@link EntryMetaData#lastModDate}, it is not replaced by the value of the NTFS extra field when that field
-   * is present; read {@link EntryMetaData#extraFieldNTFS} for the raw NTFS value.
+   * {@link EntryMetaData#lastModDate}, it is not replaced by the value of the extended timestamp or NTFS extra
+   * field when one is present (the NTFS value wins over the extended timestamp one, being the finer of the two);
+   * read {@link EntryMetaData#extraFieldNTFS} for the raw NTFS value.
    */
   rawLastModDate: number | bigint;
   /**
@@ -3066,20 +3079,32 @@ 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
    * 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. 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.
    *
+   * With the {@link ZipWriterAppendZipOptions#filter} option, only the entries the function keeps are copied.
+   * Combined with {@link ZipWriter#add}, this edits an existing zip file into a new one without decompressing
+   * its data: the entries to keep are copied as-is, the entries to delete or replace are left out, and the
+   * replacements and additions are added afterwards.
+   *
    * @param reader The {@link Reader} instance used to read the content of the zip file.
+   * @param options The options.
    * @returns A promise resolving when the zip file has been added.
    */
   appendZip<ReaderType>(
@@ -3089,7 +3114,8 @@ export class ZipWriter<Type> {
       | ReadableStream
       | Reader<unknown>[]
       | ReadableReader[]
-      | ReadableStream[]
+      | ReadableStream[],
+    options?: ZipWriterAppendZipOptions
   ): Promise<void>;
 
   /**
@@ -3307,6 +3333,38 @@ export interface ZipWriterAddDataOptions
 /**
  * Represents the options passed to  {@link ZipWriter#close}.
  */
+/**
+ * Represents the options passed to {@link ZipWriter#appendZip}.
+ */
+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: every call completes before any data is copied.
+   *
+   * @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 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.
+   * @returns `true` to copy the entry.
+   */
+  filter?: (entry: Entry) => boolean | Promise<boolean>;
+}
+
 export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
   /**
    * `true` to use Zip64 to write the entries directory.
@@ -4998,7 +5056,9 @@ export const ERR_BAD_FORMAT: string;
  */
 export const ERR_EOCDR_NOT_FOUND: string;
 /**
- * Zip64 End of Central Directory Locator not found error
+ * Zip64 End of Central Directory Locator not found error: the end of central directory record holds a Zip64
+ * sentinel in its offset, size or disk number field but no Zip64 locator precedes it, or the locator does not
+ * point at a Zip64 end of central directory record
  */
 export const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
 /**
@@ -5007,6 +5067,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;
 /**
@@ -5020,7 +5083,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;
 /**
@@ -5242,13 +5306,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;
 /**
@@ -5256,7 +5323,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)"`,
@@ -5597,6 +5665,29 @@ export const WARNING_PREPENDED_CENTRAL_DIRECTORY: string;
  * the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
  */
 export const WARNING_TRAILING_CENTRAL_DIRECTORY_DATA: string;
+/**
+ * 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, 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 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;
 /**
  * Warning reason: several entries share the same filename (see {@link ZipReader#warnings}); the reason of
  * {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
@@ -5609,8 +5700,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;
 /**
@@ -5634,7 +5726,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

@@ -1543,9 +1543,13 @@ export class ZipReader<Type> {
    * `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}.
-   * {@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_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 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.
    *
    * The warnings related to the local file header of an entry are deposited on
    * {@link EntryMetaData#warnings} when its data is read, not here.
@@ -1758,9 +1762,10 @@ export interface GetEntriesOptions {
    * systems, and it also occurs as the trail byte of legitimate double-byte filenames (e.g. CP932) decoded with
    * another charset.
    *
-   * Names are validated, never rewritten, so the filename reported for an entry always matches its central
-   * directory record. The name validated is the final one, i.e. the name of a valid Unicode Path extra field
-   * (see {@link EntryMetaData#extraFieldUnicodePath}) when the entry carries one.
+   * Names are validated, never rewritten: the filename reported for an entry is the one its central directory
+   * record stores, decoded, or the one of its Unicode Path extra field when the entry carries a valid one (see
+   * {@link EntryMetaData#extraFieldUnicodePath}), and the bytes of the record stay available in
+   * {@link EntryMetaData#rawFilename}. The name validated is that final name.
    *
    * @defaultValue The value of {@link GetEntriesOptions#strictness}.
    */
@@ -1885,7 +1890,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
@@ -2521,7 +2529,9 @@ export interface EntryMetaData {
    * `true` if the entry is an executable file
    *
    * Always `false` when {@link EntryMetaData#symlink} is `true`: the permissions of a symbolic link
-   * are not meaningful, Unix systems store them as `0o777`.
+   * are not meaningful, Unix systems store them as `0o777`. Always `false` when
+   * {@link EntryMetaData#directory} is `true` too: the execute bits of a directory mean that it can be
+   * searched, and every directory carries them; read {@link EntryMetaData#unixMode} for the bits themselves.
    */
   executable: boolean;
   /**
@@ -2560,17 +2570,20 @@ 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;
   /**
    * The last modification date (raw), as the MS-DOS date and time stored in the header. Unlike
-   * {@link EntryMetaData#lastModDate}, it is not replaced by the value of the NTFS extra field when that field
-   * is present; read {@link EntryMetaData#extraFieldNTFS} for the raw NTFS value.
+   * {@link EntryMetaData#lastModDate}, it is not replaced by the value of the extended timestamp or NTFS extra
+   * field when one is present (the NTFS value wins over the extended timestamp one, being the finer of the two);
+   * read {@link EntryMetaData#extraFieldNTFS} for the raw NTFS value.
    */
   rawLastModDate: number | bigint;
   /**
@@ -3066,20 +3079,32 @@ 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
    * 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. 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.
    *
+   * With the {@link ZipWriterAppendZipOptions#filter} option, only the entries the function keeps are copied.
+   * Combined with {@link ZipWriter#add}, this edits an existing zip file into a new one without decompressing
+   * its data: the entries to keep are copied as-is, the entries to delete or replace are left out, and the
+   * replacements and additions are added afterwards.
+   *
    * @param reader The {@link Reader} instance used to read the content of the zip file.
+   * @param options The options.
    * @returns A promise resolving when the zip file has been added.
    */
   appendZip<ReaderType>(
@@ -3089,7 +3114,8 @@ export class ZipWriter<Type> {
       | ReadableStream
       | Reader<unknown>[]
       | ReadableReader[]
-      | ReadableStream[]
+      | ReadableStream[],
+    options?: ZipWriterAppendZipOptions
   ): Promise<void>;
 
   /**
@@ -3307,6 +3333,38 @@ export interface ZipWriterAddDataOptions
 /**
  * Represents the options passed to  {@link ZipWriter#close}.
  */
+/**
+ * Represents the options passed to {@link ZipWriter#appendZip}.
+ */
+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: every call completes before any data is copied.
+   *
+   * @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 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.
+   * @returns `true` to copy the entry.
+   */
+  filter?: (entry: Entry) => boolean | Promise<boolean>;
+}
+
 export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
   /**
    * `true` to use Zip64 to write the entries directory.
@@ -4998,7 +5056,9 @@ export const ERR_BAD_FORMAT: string;
  */
 export const ERR_EOCDR_NOT_FOUND: string;
 /**
- * Zip64 End of Central Directory Locator not found error
+ * Zip64 End of Central Directory Locator not found error: the end of central directory record holds a Zip64
+ * sentinel in its offset, size or disk number field but no Zip64 locator precedes it, or the locator does not
+ * point at a Zip64 end of central directory record
  */
 export const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
 /**
@@ -5007,6 +5067,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;
 /**
@@ -5020,7 +5083,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;
 /**
@@ -5242,13 +5306,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;
 /**
@@ -5256,7 +5323,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)"`,
@@ -5597,6 +5665,29 @@ export const WARNING_PREPENDED_CENTRAL_DIRECTORY: string;
  * the reason of {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
  */
 export const WARNING_TRAILING_CENTRAL_DIRECTORY_DATA: string;
+/**
+ * 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, 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 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;
 /**
  * Warning reason: several entries share the same filename (see {@link ZipReader#warnings}); the reason of
  * {@link ERR_AMBIGUOUS_ARCHIVE} under `strictness: "strict"`
@@ -5609,8 +5700,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;
 /**
@@ -5634,7 +5726,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
  */