@zip.js/zip.js 2.8.44 → 2.8.46

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.
  */
@@ -1292,6 +1382,30 @@ export interface EntryExtraFieldAES extends EntryExtraField {
    */
   originalCompressionMethod?: number;
 }
+/**
+ * Represents a Unix extra field record storing timestamps: the Info-ZIP Unix type 1 extra field (0x5855),
+ * written notably by macOS Archive Utility and `ditto`, or the PKWARE Unix extra field (0x000d). Both store
+ * the last access/modification dates as 32-bit Unix times, followed by the optional uid/gid in the local
+ * file header.
+ */
+export interface EntryExtraFieldUnixDates extends EntryExtraField {
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The Unix user id.
+   */
+  uid?: number;
+  /**
+   * The Unix group id.
+   */
+  gid?: number;
+}
 /**
  * Represents a Unicode path or comment extra field record of an entry.
  */
@@ -1387,6 +1501,14 @@ export interface LocalDirectory {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1660,6 +1782,14 @@ export interface EntryMetaData {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1968,15 +2098,23 @@ export interface ZipWriterAddDataOptions
    */
   comment?: string;
   /**
-   * The extra field of the entry.
+   * The extra field of the entry, written in the local file header and the central directory.
    */
   extraField?: Map<number, Uint8Array>;
+  /**
+   * The extra field of the entry written only in the local file header.
+   */
+  localExtraField?: Map<number, Uint8Array>;
   /**
    * The uncompressed size of the entry. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
    */
   uncompressedSize?: number;
   /**
    * The CRC-32 checksum of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * When the entry is AES-encrypted (see {@link ZipWriterConstructorOptions#encrypted}), setting this option marks the entry as AE-1
+   * and stores the checksum in the entry headers, e.g. when copying an AE-1 entry read with the
+   * {@link ZipReaderOptions#passThrough} option. Otherwise, the entry is marked as AE-2 and the checksum fields are set to 0.
    */
   crc32?: number;
   /**

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.
  */
@@ -1292,6 +1382,30 @@ export interface EntryExtraFieldAES extends EntryExtraField {
    */
   originalCompressionMethod?: number;
 }
+/**
+ * Represents a Unix extra field record storing timestamps: the Info-ZIP Unix type 1 extra field (0x5855),
+ * written notably by macOS Archive Utility and `ditto`, or the PKWARE Unix extra field (0x000d). Both store
+ * the last access/modification dates as 32-bit Unix times, followed by the optional uid/gid in the local
+ * file header.
+ */
+export interface EntryExtraFieldUnixDates extends EntryExtraField {
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The Unix user id.
+   */
+  uid?: number;
+  /**
+   * The Unix group id.
+   */
+  gid?: number;
+}
 /**
  * Represents a Unicode path or comment extra field record of an entry.
  */
@@ -1387,6 +1501,14 @@ export interface LocalDirectory {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1660,6 +1782,14 @@ export interface EntryMetaData {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1968,15 +2098,23 @@ export interface ZipWriterAddDataOptions
    */
   comment?: string;
   /**
-   * The extra field of the entry.
+   * The extra field of the entry, written in the local file header and the central directory.
    */
   extraField?: Map<number, Uint8Array>;
+  /**
+   * The extra field of the entry written only in the local file header.
+   */
+  localExtraField?: Map<number, Uint8Array>;
   /**
    * The uncompressed size of the entry. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
    */
   uncompressedSize?: number;
   /**
    * The CRC-32 checksum of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * When the entry is AES-encrypted (see {@link ZipWriterConstructorOptions#encrypted}), setting this option marks the entry as AE-1
+   * and stores the checksum in the entry headers, e.g. when copying an AE-1 entry read with the
+   * {@link ZipReaderOptions#passThrough} option. Otherwise, the entry is marked as AE-2 and the checksum fields are set to 0.
    */
   crc32?: number;
   /**