@zip.js/zip.js 2.8.45 → 2.8.47

package/index.d.cts

@@ -314,6 +314,19 @@ export interface Configuration extends WorkerConfiguration {
    * @defaultValue "./core/web-worker.js"
    */
   workerURI?: string;
+  /**
+   * The function used to create the web workers, taking precedence over `workerURI`.
+   *
+   * It lets bundlers detect the worker script statically and compile it with its imports, e.g. a custom worker script embedding alternative compression streams.
+   *
+   * Here is an example with a custom worker script (see {@link initWorker} for the content of the script):
+   * ```
+   * configure({
+   *   createWorker: () => new Worker(new URL("./zip-worker.js", import.meta.url), { type: "module" })
+   * });
+   * ```
+   */
+  createWorker?: () => Worker;
   /**
    * The URI of the WebAssembly module used by default implementations to compress/decompress data. It is ignored if `useCompressionStream` is set to `true` and `CompressionStream`/`DecompressionStream` are supported by the environment.
    *
@@ -352,12 +365,20 @@ export interface Configuration extends WorkerConfiguration {
    *
    * @defaultValue {@link CodecStream}
    */
-  CompressionStreamZlib?: typeof TransformStreamLike;
+  CompressionStreamFallback?: typeof TransformStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `false`.
    *
    * @defaultValue {@link CodecStream}
    */
+  DecompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * @deprecated Use {@link Configuration#CompressionStreamFallback} instead.
+   */
+  CompressionStreamZlib?: typeof TransformStreamLike;
+  /**
+   * @deprecated Use {@link Configuration#DecompressionStreamFallback} instead.
+   */
   DecompressionStreamZlib?: typeof TransformStreamLike;
 }
 
@@ -390,6 +411,75 @@ export interface WorkerConfiguration {
  */
 export function terminateWorkers(): Promise<void>;
 
+/**
+ * Initializes a custom web worker script. This function is exposed by the `@zip.js/zip.js/worker` entry point and must be called
+ * in the worker script created by {@link Configuration#createWorker} or referenced by {@link Configuration#workerURI}.
+ *
+ * Here is a complete example of a worker script using fflate as the compression engine, e.g. to reduce the bundle size:
+ * ```
+ * import { initWorker } from "@zip.js/zip.js/worker";
+ * import { Deflate, Inflate } from "fflate";
+ *
+ * const FORMAT_DEFLATE_RAW = "deflate-raw";
+ *
+ * class FflateStream extends TransformStream {
+ *   constructor(codec) {
+ *     super({
+ *       start(controller) {
+ *         codec.ondata = chunk => {
+ *           if (chunk.length) {
+ *             controller.enqueue(chunk);
+ *           }
+ *         };
+ *       },
+ *       transform(chunk) {
+ *         codec.push(chunk);
+ *       },
+ *       flush() {
+ *         codec.push(new Uint8Array(0), true);
+ *       }
+ *     });
+ *   }
+ * }
+ *
+ * class CompressionStreamFallback extends FflateStream {
+ *   constructor(format, { level } = {}) {
+ *     checkFormat(format);
+ *     super(new Deflate(level === undefined ? {} : { level }));
+ *   }
+ * }
+ *
+ * class DecompressionStreamFallback extends FflateStream {
+ *   constructor(format) {
+ *     checkFormat(format);
+ *     super(new Inflate());
+ *   }
+ * }
+ *
+ * function checkFormat(format) {
+ *   if (format != FORMAT_DEFLATE_RAW) {
+ *     throw new TypeError("Unsupported compression format: " + format);
+ *   }
+ * }
+ *
+ * initWorker({ CompressionStreamFallback, DecompressionStreamFallback });
+ * ```
+ */
+export function initWorker(options?: {
+  /**
+   * The stream implementation used to compress data when `useCompressionStream` is set to `false` or when `CompressionStream` is unsupported.
+   */
+  CompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * The stream implementation used to decompress data when `useCompressionStream` is set to `false` or when `DecompressionStream` is unsupported.
+   */
+  DecompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * The function called before resolving the stream implementations, e.g. to load a WebAssembly module.
+   */
+  init?(config: Configuration): Promise<unknown> | unknown;
+}): void;
+
 /**
  * Represents a class implementing `CompressionStream` or `DecompressionStream` interfaces.
  */
@@ -1029,6 +1119,21 @@ export class ZipReader<Type> {
    * The data appended after the zip file.
    */
   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.
+   */
+  digitalSignature?: Uint8Array;
+  /**
+   * The offset of the central directory in the zip file.
+   */
+  directoryOffset?: number;
+  /**
+   * The length in bytes of the central directory as declared in the end of central directory record.
+   */
+  directoryLength?: number;
   /**
    * Returns all the entries in the zip file
    *
@@ -1144,6 +1249,66 @@ export interface GetEntriesOptions {
    * {@link ERR_AMBIGUOUS_ARCHIVE} error otherwise.
    */
   maxAppendedDataSize?: number;
+  /**
+   * The function called for decrypting the central directory when it is encrypted (see the Strong Encryption
+   * Specification in the ZIP format specification). Without this function, reading such an archive throws an
+   * {@link ERR_ENCRYPTED_CENTRAL_DIRECTORY} error. zip.js provides the encrypted data and the related metadata
+   * but does not implement the decryption itself.
+   *
+   * @param data The raw data stored in place of the central directory, i.e. the decryption header followed by
+   * the encrypted (and possibly compressed) central directory, as stored in the zip file.
+   * @param encryptionInfo The encryption metadata read from the Zip64 end of central directory record, or
+   * `undefined` if the zip file does not contain a version 2 record.
+   * @returns The decrypted and decompressed central directory records.
+   */
+  decryptCentralDirectory?(
+    data: Uint8Array,
+    encryptionInfo?: DirectoryEncryptionInfo
+  ): Uint8Array | PromiseLike<Uint8Array>;
+}
+
+/**
+ * Represents the encryption metadata of an encrypted central directory (see
+ * {@link GetEntriesOptions#decryptCentralDirectory}), read from the version 2 Zip64 end of central directory
+ * record.
+ */
+export interface DirectoryEncryptionInfo {
+  /**
+   * The raw data of the extensible data sector of the record.
+   */
+  rawExtensibleData: Uint8Array;
+  /**
+   * The compression method applied to the central directory before encryption.
+   */
+  compressionMethod?: number;
+  /**
+   * The size of the compressed and encrypted central directory.
+   */
+  compressedSize?: number;
+  /**
+   * The size of the central directory once decrypted and decompressed.
+   */
+  uncompressedSize?: number;
+  /**
+   * The identifier of the encryption algorithm (e.g. `0x6610` for AES-256).
+   */
+  encryptionAlgorithm?: number;
+  /**
+   * The key size in bits.
+   */
+  bitLength?: number;
+  /**
+   * The processing flags (e.g. `0x0001` for password-based encryption).
+   */
+  flags?: number;
+  /**
+   * The identifier of the hash algorithm used for the password validation data.
+   */
+  hashAlgorithm?: number;
+  /**
+   * The password validation data.
+   */
+  hashData?: Uint8Array;
 }
 
 /**
@@ -2051,6 +2216,19 @@ export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
    * @defaultValue false
    */
   preventClose?: boolean;
+  /**
+   * The function called for signing the central directory. The returned data (e.g. a PKCS#7 signature computed
+   * over the central directory records) is stored in a digital signature record written between the central
+   * directory and the end of central directory record, and exposed by {@link ZipReader#digitalSignature} when
+   * reading the zip file. It must not exceed 64KB, otherwise an {@link ERR_INVALID_SIGNATURE_DATA} error is
+   * thrown. zip.js stores the data as-is and does not implement the signature computation itself.
+   *
+   * @param directory The raw data of the central directory records.
+   * @returns The data of the digital signature record.
+   */
+  signCentralDirectory?(
+    directory: Uint8Array
+  ): Uint8Array | PromiseLike<Uint8Array>;
 }
 
 /**
@@ -3164,3 +3342,56 @@ export const ERR_WRITER_NOT_INITIALIZED: string;
  * Zip file not empty error
  */
 export const ERR_ZIP_NOT_EMPTY: string;
+/**
+ * Signature data exceeding 64KB error (see {@link ZipWriterCloseOptions#signCentralDirectory})
+ */
+export const ERR_INVALID_SIGNATURE_DATA: string;
+/**
+ * Invalid uid error (thrown when the `uid` option is not an integer in the range 0..2^32-1)
+ */
+export const ERR_INVALID_UID: string;
+/**
+ * Invalid gid error (thrown when the `gid` option is not an integer in the range 0..2^32-1)
+ */
+export const ERR_INVALID_GID: string;
+/**
+ * Invalid UNIX mode error (thrown when the `unixMode` option is not an integer in the range 0..65535)
+ */
+export const ERR_INVALID_UNIX_MODE: string;
+/**
+ * Invalid unixExtraFieldType error (thrown when the `unixExtraFieldType` option is not `"infozip"` or `"unix"`)
+ */
+export const ERR_INVALID_UNIX_EXTRA_FIELD_TYPE: string;
+/**
+ * Invalid UNIX uid/gid size error (thrown when `uid`/`gid` exceeds 65535 with `unixExtraFieldType` set to `"unix"`; use `"infozip"` for larger ids)
+ */
+export const ERR_INVALID_UNIX_ID_SIZE: string;
+/**
+ * Invalid msdosAttributesRaw error (thrown when the `msdosAttributesRaw` option is not an integer in the range 0..255)
+ */
+export const ERR_INVALID_MSDOS_ATTRIBUTES: string;
+/**
+ * Invalid msdosAttributes error (thrown when the `msdosAttributes` option is not an object with boolean flags)
+ */
+export const ERR_INVALID_MSDOS_DATA: string;
+/**
+ * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
+ */
+export const ERR_ENTRY_EXISTS: string;
+/**
+ * Readable stream already consumed error (thrown by the filesystem API when a readable stream is read more than once)
+ */
+export const ERR_READABLE_CONSUMED: string;
+/**
+ * Unsupported context error (thrown when {@link createSyncAccessHandleTempStream} is used outside a dedicated worker)
+ */
+export const ERR_UNSUPPORTED_CONTEXT: string;
+/**
+ * Unsupported Crypto API error (thrown when writing encrypted entries while `crypto.getRandomValues` is unavailable)
+ */
+export const ERR_UNSUPPORTED_CRYPTO_API: string;
+/**
+ * Web worker startup timeout error (thrown when a web worker does not start in time, e.g. in browser extensions
+ * disallowing workers; set `useWebWorkers` to `false` in {@link configure} to work around it)
+ */
+export const ERR_WORKER_STARTUP_TIMEOUT: string;

package/index.d.ts

@@ -314,6 +314,19 @@ export interface Configuration extends WorkerConfiguration {
    * @defaultValue "./core/web-worker.js"
    */
   workerURI?: string;
+  /**
+   * The function used to create the web workers, taking precedence over `workerURI`.
+   *
+   * It lets bundlers detect the worker script statically and compile it with its imports, e.g. a custom worker script embedding alternative compression streams.
+   *
+   * Here is an example with a custom worker script (see {@link initWorker} for the content of the script):
+   * ```
+   * configure({
+   *   createWorker: () => new Worker(new URL("./zip-worker.js", import.meta.url), { type: "module" })
+   * });
+   * ```
+   */
+  createWorker?: () => Worker;
   /**
    * The URI of the WebAssembly module used by default implementations to compress/decompress data. It is ignored if `useCompressionStream` is set to `true` and `CompressionStream`/`DecompressionStream` are supported by the environment.
    *
@@ -352,12 +365,20 @@ export interface Configuration extends WorkerConfiguration {
    *
    * @defaultValue {@link CodecStream}
    */
-  CompressionStreamZlib?: typeof TransformStreamLike;
+  CompressionStreamFallback?: typeof TransformStreamLike;
   /**
    * The stream implementation used to decompress data when `useCompressionStream` is set to `false`.
    *
    * @defaultValue {@link CodecStream}
    */
+  DecompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * @deprecated Use {@link Configuration#CompressionStreamFallback} instead.
+   */
+  CompressionStreamZlib?: typeof TransformStreamLike;
+  /**
+   * @deprecated Use {@link Configuration#DecompressionStreamFallback} instead.
+   */
   DecompressionStreamZlib?: typeof TransformStreamLike;
 }
 
@@ -390,6 +411,75 @@ export interface WorkerConfiguration {
  */
 export function terminateWorkers(): Promise<void>;
 
+/**
+ * Initializes a custom web worker script. This function is exposed by the `@zip.js/zip.js/worker` entry point and must be called
+ * in the worker script created by {@link Configuration#createWorker} or referenced by {@link Configuration#workerURI}.
+ *
+ * Here is a complete example of a worker script using fflate as the compression engine, e.g. to reduce the bundle size:
+ * ```
+ * import { initWorker } from "@zip.js/zip.js/worker";
+ * import { Deflate, Inflate } from "fflate";
+ *
+ * const FORMAT_DEFLATE_RAW = "deflate-raw";
+ *
+ * class FflateStream extends TransformStream {
+ *   constructor(codec) {
+ *     super({
+ *       start(controller) {
+ *         codec.ondata = chunk => {
+ *           if (chunk.length) {
+ *             controller.enqueue(chunk);
+ *           }
+ *         };
+ *       },
+ *       transform(chunk) {
+ *         codec.push(chunk);
+ *       },
+ *       flush() {
+ *         codec.push(new Uint8Array(0), true);
+ *       }
+ *     });
+ *   }
+ * }
+ *
+ * class CompressionStreamFallback extends FflateStream {
+ *   constructor(format, { level } = {}) {
+ *     checkFormat(format);
+ *     super(new Deflate(level === undefined ? {} : { level }));
+ *   }
+ * }
+ *
+ * class DecompressionStreamFallback extends FflateStream {
+ *   constructor(format) {
+ *     checkFormat(format);
+ *     super(new Inflate());
+ *   }
+ * }
+ *
+ * function checkFormat(format) {
+ *   if (format != FORMAT_DEFLATE_RAW) {
+ *     throw new TypeError("Unsupported compression format: " + format);
+ *   }
+ * }
+ *
+ * initWorker({ CompressionStreamFallback, DecompressionStreamFallback });
+ * ```
+ */
+export function initWorker(options?: {
+  /**
+   * The stream implementation used to compress data when `useCompressionStream` is set to `false` or when `CompressionStream` is unsupported.
+   */
+  CompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * The stream implementation used to decompress data when `useCompressionStream` is set to `false` or when `DecompressionStream` is unsupported.
+   */
+  DecompressionStreamFallback?: typeof TransformStreamLike;
+  /**
+   * The function called before resolving the stream implementations, e.g. to load a WebAssembly module.
+   */
+  init?(config: Configuration): Promise<unknown> | unknown;
+}): void;
+
 /**
  * Represents a class implementing `CompressionStream` or `DecompressionStream` interfaces.
  */
@@ -1029,6 +1119,21 @@ export class ZipReader<Type> {
    * The data appended after the zip file.
    */
   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.
+   */
+  digitalSignature?: Uint8Array;
+  /**
+   * The offset of the central directory in the zip file.
+   */
+  directoryOffset?: number;
+  /**
+   * The length in bytes of the central directory as declared in the end of central directory record.
+   */
+  directoryLength?: number;
   /**
    * Returns all the entries in the zip file
    *
@@ -1144,6 +1249,66 @@ export interface GetEntriesOptions {
    * {@link ERR_AMBIGUOUS_ARCHIVE} error otherwise.
    */
   maxAppendedDataSize?: number;
+  /**
+   * The function called for decrypting the central directory when it is encrypted (see the Strong Encryption
+   * Specification in the ZIP format specification). Without this function, reading such an archive throws an
+   * {@link ERR_ENCRYPTED_CENTRAL_DIRECTORY} error. zip.js provides the encrypted data and the related metadata
+   * but does not implement the decryption itself.
+   *
+   * @param data The raw data stored in place of the central directory, i.e. the decryption header followed by
+   * the encrypted (and possibly compressed) central directory, as stored in the zip file.
+   * @param encryptionInfo The encryption metadata read from the Zip64 end of central directory record, or
+   * `undefined` if the zip file does not contain a version 2 record.
+   * @returns The decrypted and decompressed central directory records.
+   */
+  decryptCentralDirectory?(
+    data: Uint8Array,
+    encryptionInfo?: DirectoryEncryptionInfo
+  ): Uint8Array | PromiseLike<Uint8Array>;
+}
+
+/**
+ * Represents the encryption metadata of an encrypted central directory (see
+ * {@link GetEntriesOptions#decryptCentralDirectory}), read from the version 2 Zip64 end of central directory
+ * record.
+ */
+export interface DirectoryEncryptionInfo {
+  /**
+   * The raw data of the extensible data sector of the record.
+   */
+  rawExtensibleData: Uint8Array;
+  /**
+   * The compression method applied to the central directory before encryption.
+   */
+  compressionMethod?: number;
+  /**
+   * The size of the compressed and encrypted central directory.
+   */
+  compressedSize?: number;
+  /**
+   * The size of the central directory once decrypted and decompressed.
+   */
+  uncompressedSize?: number;
+  /**
+   * The identifier of the encryption algorithm (e.g. `0x6610` for AES-256).
+   */
+  encryptionAlgorithm?: number;
+  /**
+   * The key size in bits.
+   */
+  bitLength?: number;
+  /**
+   * The processing flags (e.g. `0x0001` for password-based encryption).
+   */
+  flags?: number;
+  /**
+   * The identifier of the hash algorithm used for the password validation data.
+   */
+  hashAlgorithm?: number;
+  /**
+   * The password validation data.
+   */
+  hashData?: Uint8Array;
 }
 
 /**
@@ -2051,6 +2216,19 @@ export interface ZipWriterCloseOptions extends EntryOnprogressOptions {
    * @defaultValue false
    */
   preventClose?: boolean;
+  /**
+   * The function called for signing the central directory. The returned data (e.g. a PKCS#7 signature computed
+   * over the central directory records) is stored in a digital signature record written between the central
+   * directory and the end of central directory record, and exposed by {@link ZipReader#digitalSignature} when
+   * reading the zip file. It must not exceed 64KB, otherwise an {@link ERR_INVALID_SIGNATURE_DATA} error is
+   * thrown. zip.js stores the data as-is and does not implement the signature computation itself.
+   *
+   * @param directory The raw data of the central directory records.
+   * @returns The data of the digital signature record.
+   */
+  signCentralDirectory?(
+    directory: Uint8Array
+  ): Uint8Array | PromiseLike<Uint8Array>;
 }
 
 /**
@@ -3164,3 +3342,56 @@ export const ERR_WRITER_NOT_INITIALIZED: string;
  * Zip file not empty error
  */
 export const ERR_ZIP_NOT_EMPTY: string;
+/**
+ * Signature data exceeding 64KB error (see {@link ZipWriterCloseOptions#signCentralDirectory})
+ */
+export const ERR_INVALID_SIGNATURE_DATA: string;
+/**
+ * Invalid uid error (thrown when the `uid` option is not an integer in the range 0..2^32-1)
+ */
+export const ERR_INVALID_UID: string;
+/**
+ * Invalid gid error (thrown when the `gid` option is not an integer in the range 0..2^32-1)
+ */
+export const ERR_INVALID_GID: string;
+/**
+ * Invalid UNIX mode error (thrown when the `unixMode` option is not an integer in the range 0..65535)
+ */
+export const ERR_INVALID_UNIX_MODE: string;
+/**
+ * Invalid unixExtraFieldType error (thrown when the `unixExtraFieldType` option is not `"infozip"` or `"unix"`)
+ */
+export const ERR_INVALID_UNIX_EXTRA_FIELD_TYPE: string;
+/**
+ * Invalid UNIX uid/gid size error (thrown when `uid`/`gid` exceeds 65535 with `unixExtraFieldType` set to `"unix"`; use `"infozip"` for larger ids)
+ */
+export const ERR_INVALID_UNIX_ID_SIZE: string;
+/**
+ * Invalid msdosAttributesRaw error (thrown when the `msdosAttributesRaw` option is not an integer in the range 0..255)
+ */
+export const ERR_INVALID_MSDOS_ATTRIBUTES: string;
+/**
+ * Invalid msdosAttributes error (thrown when the `msdosAttributes` option is not an object with boolean flags)
+ */
+export const ERR_INVALID_MSDOS_DATA: string;
+/**
+ * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
+ */
+export const ERR_ENTRY_EXISTS: string;
+/**
+ * Readable stream already consumed error (thrown by the filesystem API when a readable stream is read more than once)
+ */
+export const ERR_READABLE_CONSUMED: string;
+/**
+ * Unsupported context error (thrown when {@link createSyncAccessHandleTempStream} is used outside a dedicated worker)
+ */
+export const ERR_UNSUPPORTED_CONTEXT: string;
+/**
+ * Unsupported Crypto API error (thrown when writing encrypted entries while `crypto.getRandomValues` is unavailable)
+ */
+export const ERR_UNSUPPORTED_CRYPTO_API: string;
+/**
+ * Web worker startup timeout error (thrown when a web worker does not start in time, e.g. in browser extensions
+ * disallowing workers; set `useWebWorkers` to `false` in {@link configure} to work around it)
+ */
+export const ERR_WORKER_STARTUP_TIMEOUT: string;