@zip.js/zip.js 2.16.1 → 2.17.0

package/index.d.cts

@@ -2009,7 +2009,10 @@ export interface ZipReaderOptions {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being read rejects the operation as well, whether its compressed data is still being
+   * consumed or its content still being written; on those engines, the content is written to the end
+   * before the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -3423,7 +3426,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being added rejects the operation as well, whether its content is still being read or
+   * its compressed data still being written; on those engines, the data is written to the end before
+   * the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -4544,9 +4550,13 @@ export class ZipDirectoryEntry extends ZipEntry {
  * encrypted with ZipCrypto verifies the password on a single byte, so one wrong password in 256 passes
  * that check and fails while reading the content instead: for such entries the password is first
  * verified alone, the CRC32 of the content is then checked whatever the {@link ZipReaderOptions#checkCrc32}
- * option says, and any failure of the read is treated as a wrong password and the next candidate is
- * tried. An entry encrypted with AES verifies it on two bytes, so a failure of the read that follows is
- * reported as-is, e.g. as an {@link ERR_INVALID_AUTHENTICATION_CODE} error.
+ * option says, and a read failing with an {@link ERR_INVALID_CRC32}, {@link ERR_INVALID_COMPRESSED_DATA}
+ * or {@link ERR_INVALID_UNCOMPRESSED_SIZE} error is treated as a wrong password and the next candidate is
+ * tried. Any other failure, e.g. a failure of the reader or an {@link ERR_CODEC_OUT_OF_MEMORY} error, is
+ * reported as-is. A corrupted entry read with the right password is reported as a wrong password too,
+ * since nothing tells it from a wrong password passing the check. An entry encrypted with AES verifies
+ * the password on two bytes, so a failure of the read that follows is reported as-is, e.g. as an
+ * {@link ERR_INVALID_AUTHENTICATION_CODE} error.
  *
  * The options are set when importing the zip file, in the {@link ZipDirectoryEntryExportOptions#readerOptions}
  * option of an export, and when reading one entry with `{@link ZipFileEntry}#get*()`. They apply to the
@@ -4559,8 +4569,9 @@ export interface PasswordCandidatesOptions {
    * passwords already accepted by another entry of the same imported zip file. An empty string is
    * ignored.
    *
-   * When every candidate fails, the entry raises an {@link ERR_INVALID_PASSWORD} error, unless the
-   * {@link PasswordCandidatesOptions#requestPassword} option is set.
+   * When every candidate fails, the entry raises an {@link ERR_INVALID_PASSWORD} error whose `cause` is
+   * the error raised by the last candidate, unless the {@link PasswordCandidatesOptions#requestPassword}
+   * option is set.
    *
    * A value which is neither an array of strings nor unset throws an {@link ERR_INVALID_PASSWORDS}
    * error.
@@ -4573,8 +4584,9 @@ export interface PasswordCandidatesOptions {
    *
    * A string is tried on the entry, and the function is called again when it fails, with the
    * {@link ERR_INVALID_PASSWORD} error. `undefined` or `null` gives up: the entry raises an
-   * {@link ERR_INVALID_PASSWORD} error, or an {@link ERR_ENCRYPTED} error when no candidate was
-   * tried. A value of another type throws an {@link ERR_INVALID_REQUEST_PASSWORD} error. The
+   * {@link ERR_INVALID_PASSWORD} error whose `cause` is the error raised by the last candidate, or an
+   * {@link ERR_ENCRYPTED} error when no candidate was tried. A value of another type throws an
+   * {@link ERR_INVALID_REQUEST_PASSWORD} error. The
    * function is not called for the entries whose password is already known.
    *
    * When several entries are read concurrently, e.g. by `{@link ZipDirectoryEntry}#export*()` with the
@@ -5006,6 +5018,12 @@ export const ERR_INVALID_CODEC_MODULE: string;
 /**
  * Invalid CRC-32 checksum error, thrown when the {@link ZipReaderOptions#checkCrc32} option is set and the CRC-32
  * checksum of an entry does not match the value stored in the zip file.
+ *
+ * @remarks
+ * When the inflater verifies the checksum itself, through a gzip trailer that zip.js builds from the stored
+ * CRC-32 and uncompressed size, it rejects the trailer as a whole and its error is kept as the `cause`. A
+ * stored uncompressed size larger than the data therefore raises this error too on that route, whereas a
+ * stored size smaller than the data raises {@link ERR_INVALID_UNCOMPRESSED_SIZE} on every route.
  */
 export const ERR_INVALID_CRC32: string;
 /**
@@ -5014,24 +5032,44 @@ export const ERR_INVALID_CRC32: string;
  */
 export const ERR_INVALID_AUTHENTICATION_CODE: string;
 /**
- * Invalid uncompressed size error
+ * Invalid uncompressed size error, thrown when an entry inflates to more bytes than its stored uncompressed size.
+ *
+ * @remarks
+ * An entry encrypted with AES that stores no CRC-32 (AE-2) and inflated through a gzip container, on a host
+ * whose inflater lacks `"deflate-raw"`, raises this error when it inflates to fewer bytes as well, since the
+ * end of its data is told by the stored size alone.
  */
 export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
 /**
- * Invalid compressed data error
+ * Invalid compressed data error, thrown when the codec rejects the compressed data of an entry.
  *
  * @remarks
- * The way malformed compressed data is reported is not uniform across codec
- * backends. Bytes trailing a complete DEFLATE stream (e.g. a wrong
- * `compressedSize`) are tolerated by the bundled WASM and pure-JS codecs, which
- * decompress the valid data and ignore the extra bytes, but are rejected by the
- * native `DecompressionStream` with its own `TypeError` (on Node,
- * `ERR_TRAILING_JUNK_AFTER_STREAM_END`) rather than this error. Any data that is
- * returned is always validated against the entry's uncompressed size (and CRC
- * when `checkCrc32` is set), so it is never silently truncated; the backends
- * differ only in whether trailing bytes are ignored or raised as an error.
+ * The error is the same whatever inflates the data, and the error the codec raised is kept as its
+ * `cause`: the `TypeError` of a native `DecompressionStream`, whose message depends on the engine,
+ * or the error of the bundled WASM or pure-JS codec. An error raised while reading the data, e.g.
+ * by the reader of the zip file or by the decryption of the entry, is not a codec failure and
+ * reaches the caller unchanged.
+ *
+ * Bytes trailing a complete DEFLATE stream (e.g. a wrong `compressedSize`) are rejected by every
+ * codec, the native `DecompressionStream` (on Node.js, with `ERR_TRAILING_JUNK_AFTER_STREAM_END`
+ * as the `code` of the cause) and the bundled WASM and pure-JS codecs alike. Any data that is
+ * returned is always validated against the entry's uncompressed size (and CRC when
+ * {@link ZipReaderOptions#checkCrc32} is set), so it is never silently truncated.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;
+/**
+ * Codec out of memory error, thrown when the codec of an entry cannot allocate the memory it needs, e.g. when
+ * the fixed heap of the bundled WASM module is exhausted by too many entries processed concurrently in the same
+ * scope.
+ *
+ * @remarks
+ * The error the codec raised is kept as the `cause`. The failure is recognized by the `code` property of that
+ * error, `"Z_MEM_ERROR"`, which the bundled WASM codec sets and the native `DecompressionStream` of Node.js
+ * would set; a codec reporting the failure without it is reported as {@link ERR_INVALID_COMPRESSED_DATA} when
+ * reading, or with its own error when writing. When writing, only a codec that fails to allocate its state is
+ * reported with this error: a failure while compressing keeps the error of the codec.
+ */
+export const ERR_CODEC_OUT_OF_MEMORY: string;
 /**
  * Invalid password error
  */

package/index.d.ts

@@ -2009,7 +2009,10 @@ export interface ZipReaderOptions {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being read rejects the operation as well, whether its compressed data is still being
+   * consumed or its content still being written; on those engines, the content is written to the end
+   * before the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -3423,7 +3426,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being added rejects the operation as well, whether its content is still being read or
+   * its compressed data still being written; on those engines, the data is written to the end before
+   * the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -4544,9 +4550,13 @@ export class ZipDirectoryEntry extends ZipEntry {
  * encrypted with ZipCrypto verifies the password on a single byte, so one wrong password in 256 passes
  * that check and fails while reading the content instead: for such entries the password is first
  * verified alone, the CRC32 of the content is then checked whatever the {@link ZipReaderOptions#checkCrc32}
- * option says, and any failure of the read is treated as a wrong password and the next candidate is
- * tried. An entry encrypted with AES verifies it on two bytes, so a failure of the read that follows is
- * reported as-is, e.g. as an {@link ERR_INVALID_AUTHENTICATION_CODE} error.
+ * option says, and a read failing with an {@link ERR_INVALID_CRC32}, {@link ERR_INVALID_COMPRESSED_DATA}
+ * or {@link ERR_INVALID_UNCOMPRESSED_SIZE} error is treated as a wrong password and the next candidate is
+ * tried. Any other failure, e.g. a failure of the reader or an {@link ERR_CODEC_OUT_OF_MEMORY} error, is
+ * reported as-is. A corrupted entry read with the right password is reported as a wrong password too,
+ * since nothing tells it from a wrong password passing the check. An entry encrypted with AES verifies
+ * the password on two bytes, so a failure of the read that follows is reported as-is, e.g. as an
+ * {@link ERR_INVALID_AUTHENTICATION_CODE} error.
  *
  * The options are set when importing the zip file, in the {@link ZipDirectoryEntryExportOptions#readerOptions}
  * option of an export, and when reading one entry with `{@link ZipFileEntry}#get*()`. They apply to the
@@ -4559,8 +4569,9 @@ export interface PasswordCandidatesOptions {
    * passwords already accepted by another entry of the same imported zip file. An empty string is
    * ignored.
    *
-   * When every candidate fails, the entry raises an {@link ERR_INVALID_PASSWORD} error, unless the
-   * {@link PasswordCandidatesOptions#requestPassword} option is set.
+   * When every candidate fails, the entry raises an {@link ERR_INVALID_PASSWORD} error whose `cause` is
+   * the error raised by the last candidate, unless the {@link PasswordCandidatesOptions#requestPassword}
+   * option is set.
    *
    * A value which is neither an array of strings nor unset throws an {@link ERR_INVALID_PASSWORDS}
    * error.
@@ -4573,8 +4584,9 @@ export interface PasswordCandidatesOptions {
    *
    * A string is tried on the entry, and the function is called again when it fails, with the
    * {@link ERR_INVALID_PASSWORD} error. `undefined` or `null` gives up: the entry raises an
-   * {@link ERR_INVALID_PASSWORD} error, or an {@link ERR_ENCRYPTED} error when no candidate was
-   * tried. A value of another type throws an {@link ERR_INVALID_REQUEST_PASSWORD} error. The
+   * {@link ERR_INVALID_PASSWORD} error whose `cause` is the error raised by the last candidate, or an
+   * {@link ERR_ENCRYPTED} error when no candidate was tried. A value of another type throws an
+   * {@link ERR_INVALID_REQUEST_PASSWORD} error. The
    * function is not called for the entries whose password is already known.
    *
    * When several entries are read concurrently, e.g. by `{@link ZipDirectoryEntry}#export*()` with the
@@ -5006,6 +5018,12 @@ export const ERR_INVALID_CODEC_MODULE: string;
 /**
  * Invalid CRC-32 checksum error, thrown when the {@link ZipReaderOptions#checkCrc32} option is set and the CRC-32
  * checksum of an entry does not match the value stored in the zip file.
+ *
+ * @remarks
+ * When the inflater verifies the checksum itself, through a gzip trailer that zip.js builds from the stored
+ * CRC-32 and uncompressed size, it rejects the trailer as a whole and its error is kept as the `cause`. A
+ * stored uncompressed size larger than the data therefore raises this error too on that route, whereas a
+ * stored size smaller than the data raises {@link ERR_INVALID_UNCOMPRESSED_SIZE} on every route.
  */
 export const ERR_INVALID_CRC32: string;
 /**
@@ -5014,24 +5032,44 @@ export const ERR_INVALID_CRC32: string;
  */
 export const ERR_INVALID_AUTHENTICATION_CODE: string;
 /**
- * Invalid uncompressed size error
+ * Invalid uncompressed size error, thrown when an entry inflates to more bytes than its stored uncompressed size.
+ *
+ * @remarks
+ * An entry encrypted with AES that stores no CRC-32 (AE-2) and inflated through a gzip container, on a host
+ * whose inflater lacks `"deflate-raw"`, raises this error when it inflates to fewer bytes as well, since the
+ * end of its data is told by the stored size alone.
  */
 export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
 /**
- * Invalid compressed data error
+ * Invalid compressed data error, thrown when the codec rejects the compressed data of an entry.
  *
  * @remarks
- * The way malformed compressed data is reported is not uniform across codec
- * backends. Bytes trailing a complete DEFLATE stream (e.g. a wrong
- * `compressedSize`) are tolerated by the bundled WASM and pure-JS codecs, which
- * decompress the valid data and ignore the extra bytes, but are rejected by the
- * native `DecompressionStream` with its own `TypeError` (on Node,
- * `ERR_TRAILING_JUNK_AFTER_STREAM_END`) rather than this error. Any data that is
- * returned is always validated against the entry's uncompressed size (and CRC
- * when `checkCrc32` is set), so it is never silently truncated; the backends
- * differ only in whether trailing bytes are ignored or raised as an error.
+ * The error is the same whatever inflates the data, and the error the codec raised is kept as its
+ * `cause`: the `TypeError` of a native `DecompressionStream`, whose message depends on the engine,
+ * or the error of the bundled WASM or pure-JS codec. An error raised while reading the data, e.g.
+ * by the reader of the zip file or by the decryption of the entry, is not a codec failure and
+ * reaches the caller unchanged.
+ *
+ * Bytes trailing a complete DEFLATE stream (e.g. a wrong `compressedSize`) are rejected by every
+ * codec, the native `DecompressionStream` (on Node.js, with `ERR_TRAILING_JUNK_AFTER_STREAM_END`
+ * as the `code` of the cause) and the bundled WASM and pure-JS codecs alike. Any data that is
+ * returned is always validated against the entry's uncompressed size (and CRC when
+ * {@link ZipReaderOptions#checkCrc32} is set), so it is never silently truncated.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;
+/**
+ * Codec out of memory error, thrown when the codec of an entry cannot allocate the memory it needs, e.g. when
+ * the fixed heap of the bundled WASM module is exhausted by too many entries processed concurrently in the same
+ * scope.
+ *
+ * @remarks
+ * The error the codec raised is kept as the `cause`. The failure is recognized by the `code` property of that
+ * error, `"Z_MEM_ERROR"`, which the bundled WASM codec sets and the native `DecompressionStream` of Node.js
+ * would set; a codec reporting the failure without it is reported as {@link ERR_INVALID_COMPRESSED_DATA} when
+ * reading, or with its own error when writing. When writing, only a codec that fails to allocate its state is
+ * reported with this error: a failure while compressing keeps the error of the codec.
+ */
+export const ERR_CODEC_OUT_OF_MEMORY: string;
 /**
  * Invalid password error
  */