@zip.js/zip.js 2.8.36 → 2.8.38

package/index.d.cts

@@ -202,6 +202,60 @@ export function configure(configuration: Configuration): void;
  */
 export function resetConfiguration(): void;
 
+/**
+ * Registers a codec for a custom compression method (e.g. Zstandard, method 93). Entries using a
+ * registered method can then be written with `ZipWriter#add` and read with `FileEntry#getData`.
+ *
+ * Codecs registered with `CompressionStream`/`DecompressionStream` classes run on the main thread.
+ * Codecs registered with a `codecURI` module URL also run in web workers: the module is imported
+ * dynamically on both sides of the worker boundary.
+ *
+ * @param codec The codec definition.
+ */
+export function registerCodec(codec: CodecDefinition): void;
+
+/**
+ * Unregisters a codec previously registered with {@link registerCodec}.
+ *
+ * @param compressionMethod The compression method of the codec.
+ */
+export function unregisterCodec(compressionMethod: number): void;
+
+/**
+ * Represents a codec definition passed to {@link registerCodec}.
+ */
+export interface CodecDefinition {
+  /**
+   * The compression method stored in zip entry headers (e.g. `93` for Zstandard). The values `0`
+   * (store), `8` (deflate), `9` (deflate64) and `99` (AES) are reserved.
+   */
+  compressionMethod: number;
+  /**
+   * The format name identifying the codec (e.g. `"zstd"`). It is passed as the first argument to
+   * the constructors of `CompressionStream` and `DecompressionStream`.
+   */
+  format: string;
+  /**
+   * The URL of a module exporting the `CompressionStream` and/or `DecompressionStream` classes of
+   * the codec. Relative URLs are resolved against `Configuration#baseURI`; passing an absolute URL
+   * (e.g. via `import.meta.resolve()`) is recommended.
+   */
+  codecURI?: string;
+  /**
+   * The stream implementation used to compress data, constructed with `(format, { level, chunkSize })`.
+   */
+  CompressionStream?: typeof TransformStreamLike;
+  /**
+   * The stream implementation used to decompress data, constructed with `(format, { chunkSize })`.
+   */
+  DecompressionStream?: typeof TransformStreamLike;
+  /**
+   * The minimum "version needed to extract" value written in zip entry headers (e.g. `63` for
+   * Zstandard).
+   */
+  versionNeeded?: number;
+}
+
 /**
  * Represents the configuration passed to {@link configure}.
  */
@@ -226,6 +280,14 @@ export interface Configuration extends WorkerConfiguration {
    * @defaultValue 5000
    */
   workerStarvationTimeout?: number;
+  /**
+   * The delay in milliseconds before a newly created web worker which has not sent any message is considered dead, terminated, and replaced with inline processing.
+   *
+   * It allows recovering from environments where web workers fail silently, e.g. extension pages blocking worker scripts via their Content Security Policy.
+   *
+   * @defaultValue 5000
+   */
+  workerStartupTimeout?: number;
   /**
    * The URI of the web worker.
    *
@@ -667,6 +729,14 @@ export interface HttpRangeOptions {
    * read with as many range requests as necessary, each response body being streamed, so that the
    * size of a request never depends on the size of the entry.
    *
+   * @remarks
+   * Because response bodies are streamed with backpressure, this value does not bound how much data
+   * is buffered in memory; it bounds the byte span, and therefore the lifetime, of each individual
+   * range request. Smaller windows keep each request short-lived, which avoids the idle or duration
+   * timeouts enforced by servers, CDNs and proxies when a slow consumer holds a connection open, and
+   * avoids relying on the server honoring very large ranges. Set it to `Infinity` to disable windowing
+   * and read each entry with a single range request covering its whole remaining length.
+   *
    * @defaultValue 16777216
    */
   maximumRangeSize?: number;
@@ -1419,7 +1489,9 @@ export interface EntryMetaData {
    *
    * - Writer vs Reader:
    *   - The writer composes `externalFileAttributes` from the provided options (`externalFileAttributes`,
-   *     `unixMode`/special flags, `msdosAttributesRaw`/`msdosAttributes`).
+   *     `unixMode`/special flags, `msdosAttributesRaw`/`msdosAttributes`). An explicitly provided
+   *     `externalFileAttributes` value is written verbatim (including `0`) unless mode-affecting options
+   *     are also set.
    *   - The reader decodes the stored `externalFileAttributes` and exposes convenience fields such as
    *     `msdosAttributesRaw`, `msdosAttributes`, `unixExternalUpper`, and `unixMode`.
    *
@@ -1976,11 +2048,21 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * `true` to store extended timestamp extra fields.
    *
-   * When set to `false`, the maximum last modification date cannot exceed November 31, 2107 and the maximum accuracy is 2 seconds.
+   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds.
    *
    * @defaultValue true
    */
   extendedTimestamp?: boolean;
+  /**
+   * `true` to always store the NTFS extra field, `false` to never store it.
+   *
+   * By default, the NTFS extra field is stored only when it preserves information the extended timestamp extra field cannot
+   * represent: a last modification date outside its supported range, or explicit {@link ZipWriterConstructorOptions#lastAccessDate}
+   * or {@link ZipWriterConstructorOptions#creationDate} values.
+   *
+   * This option is ignored if the {@link ZipWriterConstructorOptions#extendedTimestamp} option is set to `false`.
+   */
+  ntfsTimestamp?: boolean;
   /**
    * `true` to use the ZipCrypto algorithm to encrypt the content of the entry. Setting it to `true` will also
    * set the {@link ZipWriterConstructorOptions#dataDescriptor} to `true`.
@@ -2033,7 +2115,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * The external file attribute.
    *
-   * @defaultValue 0
+   * When set explicitly, the value is written verbatim (including `0`), unless `unixMode`, `setuid`, `setgid`
+   * or `sticky` is also set, in which case these options override the upper 16 bits while the lower 16 bits
+   * are preserved. When omitted, the value is derived from the other options (e.g. the MS-DOS directory
+   * attribute for folder entries, Unix default permissions when `msDosCompatible` is `false`).
    */
   externalFileAttributes?: number;
   /**
@@ -2096,7 +2181,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   supportZip64SplitFile?: boolean;
   /**
-   * `true`to produce zip files compatible with the USDZ specification.
+   * `true`to produce zip files compatible with the USDZ specification: the data of the entries is aligned on 64-byte
+   * boundaries and stored uncompressed unless the {@link ZipWriterConstructorOptions#level} or
+   * {@link ZipWriterAddDataOptions#compressionMethod} options are set explicitly. Setting the
+   * {@link ZipWriterConstructorOptions#password} option throws an {@link ERR_UNSUPPORTED_ENCRYPTION_USDZ} error.
    *
    * @defaultValue false
    */
@@ -2826,6 +2914,18 @@ export const ERR_UNSUPPORTED_ENCRYPTION: string;
  * Unsupported compression error
  */
 export const ERR_UNSUPPORTED_COMPRESSION: string;
+/**
+ * Invalid codec definition error
+ */
+export const ERR_INVALID_CODEC_DEFINITION: string;
+/**
+ * Reserved compression method error
+ */
+export const ERR_RESERVED_COMPRESSION_METHOD: string;
+/**
+ * Invalid codec module error
+ */
+export const ERR_INVALID_CODEC_MODULE: string;
 /**
  * Invalid signature error
  */
@@ -2836,6 +2936,17 @@ export const ERR_INVALID_SIGNATURE: string;
 export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
 /**
  * Invalid compressed data error
+ *
+ * @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 `checkSignature` is set), so it is never silently truncated; the backends
+ * differ only in whether trailing bytes are ignored or raised as an error.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;
 /**
@@ -2874,6 +2985,10 @@ export const ERR_INVALID_EXTRAFIELD_DATA: string;
  * Invalid encryption strength error
  */
 export const ERR_INVALID_ENCRYPTION_STRENGTH: string;
+/**
+ * Unsupported encryption in USDZ files error
+ */
+export const ERR_UNSUPPORTED_ENCRYPTION_USDZ: string;
 /**
  * Invalid format error
  */
@@ -2892,6 +3007,13 @@ export const ERR_OVERLAPPING_ENTRY: string;
  * @remarks The thrown error carries a `reason` property describing the ambiguity: `"appended data"`, `"prepended data"`, `"trailing central directory data"`, `"mismatched zip64 end of central directory record"`, or `"duplicate filename"`.
  */
 export const ERR_AMBIGUOUS_ARCHIVE: string;
+/**
+ * Encrypted central directory error
+ *
+ * @remarks Thrown when reading an archive using the Central Directory Encryption feature of the PKWARE Strong
+ * Encryption Specification, which is not supported.
+ */
+export const ERR_ENCRYPTED_CENTRAL_DIRECTORY: string;
 /**
  * Iteration completed too soon error
  */

package/index.d.ts

@@ -202,6 +202,60 @@ export function configure(configuration: Configuration): void;
  */
 export function resetConfiguration(): void;
 
+/**
+ * Registers a codec for a custom compression method (e.g. Zstandard, method 93). Entries using a
+ * registered method can then be written with `ZipWriter#add` and read with `FileEntry#getData`.
+ *
+ * Codecs registered with `CompressionStream`/`DecompressionStream` classes run on the main thread.
+ * Codecs registered with a `codecURI` module URL also run in web workers: the module is imported
+ * dynamically on both sides of the worker boundary.
+ *
+ * @param codec The codec definition.
+ */
+export function registerCodec(codec: CodecDefinition): void;
+
+/**
+ * Unregisters a codec previously registered with {@link registerCodec}.
+ *
+ * @param compressionMethod The compression method of the codec.
+ */
+export function unregisterCodec(compressionMethod: number): void;
+
+/**
+ * Represents a codec definition passed to {@link registerCodec}.
+ */
+export interface CodecDefinition {
+  /**
+   * The compression method stored in zip entry headers (e.g. `93` for Zstandard). The values `0`
+   * (store), `8` (deflate), `9` (deflate64) and `99` (AES) are reserved.
+   */
+  compressionMethod: number;
+  /**
+   * The format name identifying the codec (e.g. `"zstd"`). It is passed as the first argument to
+   * the constructors of `CompressionStream` and `DecompressionStream`.
+   */
+  format: string;
+  /**
+   * The URL of a module exporting the `CompressionStream` and/or `DecompressionStream` classes of
+   * the codec. Relative URLs are resolved against `Configuration#baseURI`; passing an absolute URL
+   * (e.g. via `import.meta.resolve()`) is recommended.
+   */
+  codecURI?: string;
+  /**
+   * The stream implementation used to compress data, constructed with `(format, { level, chunkSize })`.
+   */
+  CompressionStream?: typeof TransformStreamLike;
+  /**
+   * The stream implementation used to decompress data, constructed with `(format, { chunkSize })`.
+   */
+  DecompressionStream?: typeof TransformStreamLike;
+  /**
+   * The minimum "version needed to extract" value written in zip entry headers (e.g. `63` for
+   * Zstandard).
+   */
+  versionNeeded?: number;
+}
+
 /**
  * Represents the configuration passed to {@link configure}.
  */
@@ -226,6 +280,14 @@ export interface Configuration extends WorkerConfiguration {
    * @defaultValue 5000
    */
   workerStarvationTimeout?: number;
+  /**
+   * The delay in milliseconds before a newly created web worker which has not sent any message is considered dead, terminated, and replaced with inline processing.
+   *
+   * It allows recovering from environments where web workers fail silently, e.g. extension pages blocking worker scripts via their Content Security Policy.
+   *
+   * @defaultValue 5000
+   */
+  workerStartupTimeout?: number;
   /**
    * The URI of the web worker.
    *
@@ -667,6 +729,14 @@ export interface HttpRangeOptions {
    * read with as many range requests as necessary, each response body being streamed, so that the
    * size of a request never depends on the size of the entry.
    *
+   * @remarks
+   * Because response bodies are streamed with backpressure, this value does not bound how much data
+   * is buffered in memory; it bounds the byte span, and therefore the lifetime, of each individual
+   * range request. Smaller windows keep each request short-lived, which avoids the idle or duration
+   * timeouts enforced by servers, CDNs and proxies when a slow consumer holds a connection open, and
+   * avoids relying on the server honoring very large ranges. Set it to `Infinity` to disable windowing
+   * and read each entry with a single range request covering its whole remaining length.
+   *
    * @defaultValue 16777216
    */
   maximumRangeSize?: number;
@@ -1419,7 +1489,9 @@ export interface EntryMetaData {
    *
    * - Writer vs Reader:
    *   - The writer composes `externalFileAttributes` from the provided options (`externalFileAttributes`,
-   *     `unixMode`/special flags, `msdosAttributesRaw`/`msdosAttributes`).
+   *     `unixMode`/special flags, `msdosAttributesRaw`/`msdosAttributes`). An explicitly provided
+   *     `externalFileAttributes` value is written verbatim (including `0`) unless mode-affecting options
+   *     are also set.
    *   - The reader decodes the stored `externalFileAttributes` and exposes convenience fields such as
    *     `msdosAttributesRaw`, `msdosAttributes`, `unixExternalUpper`, and `unixMode`.
    *
@@ -1976,11 +2048,21 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * `true` to store extended timestamp extra fields.
    *
-   * When set to `false`, the maximum last modification date cannot exceed November 31, 2107 and the maximum accuracy is 2 seconds.
+   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds.
    *
    * @defaultValue true
    */
   extendedTimestamp?: boolean;
+  /**
+   * `true` to always store the NTFS extra field, `false` to never store it.
+   *
+   * By default, the NTFS extra field is stored only when it preserves information the extended timestamp extra field cannot
+   * represent: a last modification date outside its supported range, or explicit {@link ZipWriterConstructorOptions#lastAccessDate}
+   * or {@link ZipWriterConstructorOptions#creationDate} values.
+   *
+   * This option is ignored if the {@link ZipWriterConstructorOptions#extendedTimestamp} option is set to `false`.
+   */
+  ntfsTimestamp?: boolean;
   /**
    * `true` to use the ZipCrypto algorithm to encrypt the content of the entry. Setting it to `true` will also
    * set the {@link ZipWriterConstructorOptions#dataDescriptor} to `true`.
@@ -2033,7 +2115,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * The external file attribute.
    *
-   * @defaultValue 0
+   * When set explicitly, the value is written verbatim (including `0`), unless `unixMode`, `setuid`, `setgid`
+   * or `sticky` is also set, in which case these options override the upper 16 bits while the lower 16 bits
+   * are preserved. When omitted, the value is derived from the other options (e.g. the MS-DOS directory
+   * attribute for folder entries, Unix default permissions when `msDosCompatible` is `false`).
    */
   externalFileAttributes?: number;
   /**
@@ -2096,7 +2181,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   supportZip64SplitFile?: boolean;
   /**
-   * `true`to produce zip files compatible with the USDZ specification.
+   * `true`to produce zip files compatible with the USDZ specification: the data of the entries is aligned on 64-byte
+   * boundaries and stored uncompressed unless the {@link ZipWriterConstructorOptions#level} or
+   * {@link ZipWriterAddDataOptions#compressionMethod} options are set explicitly. Setting the
+   * {@link ZipWriterConstructorOptions#password} option throws an {@link ERR_UNSUPPORTED_ENCRYPTION_USDZ} error.
    *
    * @defaultValue false
    */
@@ -2826,6 +2914,18 @@ export const ERR_UNSUPPORTED_ENCRYPTION: string;
  * Unsupported compression error
  */
 export const ERR_UNSUPPORTED_COMPRESSION: string;
+/**
+ * Invalid codec definition error
+ */
+export const ERR_INVALID_CODEC_DEFINITION: string;
+/**
+ * Reserved compression method error
+ */
+export const ERR_RESERVED_COMPRESSION_METHOD: string;
+/**
+ * Invalid codec module error
+ */
+export const ERR_INVALID_CODEC_MODULE: string;
 /**
  * Invalid signature error
  */
@@ -2836,6 +2936,17 @@ export const ERR_INVALID_SIGNATURE: string;
 export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
 /**
  * Invalid compressed data error
+ *
+ * @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 `checkSignature` is set), so it is never silently truncated; the backends
+ * differ only in whether trailing bytes are ignored or raised as an error.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;
 /**
@@ -2874,6 +2985,10 @@ export const ERR_INVALID_EXTRAFIELD_DATA: string;
  * Invalid encryption strength error
  */
 export const ERR_INVALID_ENCRYPTION_STRENGTH: string;
+/**
+ * Unsupported encryption in USDZ files error
+ */
+export const ERR_UNSUPPORTED_ENCRYPTION_USDZ: string;
 /**
  * Invalid format error
  */
@@ -2892,6 +3007,13 @@ export const ERR_OVERLAPPING_ENTRY: string;
  * @remarks The thrown error carries a `reason` property describing the ambiguity: `"appended data"`, `"prepended data"`, `"trailing central directory data"`, `"mismatched zip64 end of central directory record"`, or `"duplicate filename"`.
  */
 export const ERR_AMBIGUOUS_ARCHIVE: string;
+/**
+ * Encrypted central directory error
+ *
+ * @remarks Thrown when reading an archive using the Central Directory Encryption feature of the PKWARE Strong
+ * Encryption Specification, which is not supported.
+ */
+export const ERR_ENCRYPTED_CENTRAL_DIRECTORY: string;
 /**
  * Iteration completed too soon error
  */