@zip.js/zip.js 2.8.54 → 2.8.56

package/index.d.cts

@@ -265,6 +265,11 @@ export interface CodecDefinition {
    * The URL of a module exporting the `CompressionStream` and/or `DecompressionStream` classes of
    * the codec. Relative URLs are resolved against {@link Configuration#baseURI}; passing an absolute
    * URL (e.g. via `import.meta.resolve()`) is recommended.
+   *
+   * @remarks
+   * The module is imported dynamically at runtime. Bundlers and single-file builds (e.g.
+   * `deno compile`) cannot follow this import, so the module must be included explicitly
+   * (e.g. with `deno compile --include` or the equivalent option of the bundler).
    */
   codecURI?: string;
   /**
@@ -1195,6 +1200,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.
  * ```
@@ -1304,9 +1314,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;
   /**
@@ -1314,7 +1328,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;
   /**
@@ -3079,9 +3095,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
@@ -4310,6 +4328,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

package/index.d.ts

@@ -265,6 +265,11 @@ export interface CodecDefinition {
    * The URL of a module exporting the `CompressionStream` and/or `DecompressionStream` classes of
    * the codec. Relative URLs are resolved against {@link Configuration#baseURI}; passing an absolute
    * URL (e.g. via `import.meta.resolve()`) is recommended.
+   *
+   * @remarks
+   * The module is imported dynamically at runtime. Bundlers and single-file builds (e.g.
+   * `deno compile`) cannot follow this import, so the module must be included explicitly
+   * (e.g. with `deno compile --include` or the equivalent option of the bundler).
    */
   codecURI?: string;
   /**
@@ -1195,6 +1200,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.
  * ```
@@ -1304,9 +1314,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;
   /**
@@ -1314,7 +1328,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;
   /**
@@ -3079,9 +3095,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
@@ -4310,6 +4328,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