@zip.js/zip.js 2.8.36 → 2.8.37

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}.
  */
@@ -667,6 +721,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;
@@ -1976,11 +2038,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`.
@@ -2096,7 +2168,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 +2901,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 +2923,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 +2972,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
  */

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}.
  */
@@ -667,6 +721,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;
@@ -1976,11 +2038,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`.
@@ -2096,7 +2168,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 +2901,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 +2923,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 +2972,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
  */