@zip.js/zip.js 2.8.59 → 2.8.61

package/index.d.cts

@@ -216,6 +216,12 @@ declare class DecompressionStreamLike extends TransformStreamLike {
   constructor(format: string, options?: DecompressionStreamOptions);
 }
 
+/**
+ * The version of zip.js (e.g. `"2.8.59"`), i.e. the `version` declared in the `package.json` file
+ * of the library.
+ */
+export const VERSION: string;
+
 /**
  * Configures zip.js
  *
@@ -247,6 +253,61 @@ export function registerCodec(codec: CodecDefinition): void;
  */
 export function unregisterCodec(compressionMethod: number): void;
 
+/**
+ * Returns the definitions of the codecs registered with {@link registerCodec}, in registration
+ * order. The returned objects are snapshots: modifying them does not alter the registered codecs.
+ *
+ * @remarks
+ * The `CompressionStream` and `DecompressionStream` classes of a codec registered with
+ * {@link CodecDefinition#codecURI} only appear once the module has been imported, i.e. after the
+ * first entry using the codec has been read or written.
+ *
+ * @returns The codec definitions.
+ */
+export function getRegisteredCodecs(): CodecDefinition[];
+
+/**
+ * Returns the compression methods supported in the current environment and configuration: the
+ * built-in methods followed by the codecs registered with {@link registerCodec}, in registration
+ * order.
+ *
+ * @remarks
+ * The support of the built-in methods is resolved against the compression streams available when
+ * the function is called, i.e. the classes set with {@link configure} and the implementations
+ * embedded in the build. A caller can test whether an entry is readable by looking up
+ * {@link EntryMetaData#compressionMethod} in the result and checking
+ * {@link EntryMetaData#encrypted}; `FileEntry#getData` remains the authority.
+ *
+ * @returns The supported compression methods.
+ */
+export function getSupportedCompressionMethods(): SupportedCompressionMethod[];
+
+/**
+ * Represents the support of a compression method, see {@link getSupportedCompressionMethods}.
+ */
+export interface SupportedCompressionMethod {
+  /**
+   * The compression method stored in zip entry headers (e.g. `8` for Deflate).
+   */
+  compressionMethod: number;
+  /**
+   * `true` if entries can be compressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  compression?: boolean;
+  /**
+   * `true` if entries can be decompressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  decompression?: boolean;
+  /**
+   * `true` if the method comes from a codec registered with {@link registerCodec}.
+   */
+  registered: boolean;
+}
+
 /**
  * Represents a codec definition passed to {@link registerCodec}.
  */
@@ -310,6 +371,13 @@ export interface CompressionStreamOptions {
    * It is only set for the codecs registered with {@link registerCodec}.
    */
   compressionMethod?: number;
+  /**
+   * The uncompressed size of the entry, undefined when the size is unknown.
+   * It allows codecs such as Zstandard to include the content size in the compressed frame.
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  uncompressedSize?: number;
 }
 
 /**
@@ -757,6 +825,48 @@ export interface ReadableReader {
  *   }
  * }
  * ```
+ *
+ * @example
+ * Reading a file on the filesystem with random access does not always require a custom {@link Reader}:
+ * on runtimes exposing files as lazily-read `Blob` instances, the `Blob` returned by
+ * `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun can be passed directly to
+ * {@link ZipReader}. Deno has no equivalent API yet, see https://github.com/denoland/deno/issues/32316.
+ * The class below reads a
+ * `Deno.FsFile` with random access instead of buffering it entirely in memory. The `seek()` and `read()`
+ * calls are serialized in a queue because zip.js can read multiple byte ranges concurrently:
+ * ```
+ * class FsFileReader extends Reader {
+ *
+ *   constructor(file) {
+ *     super();
+ *     this.file = file;
+ *     this.queue = Promise.resolve();
+ *   }
+ *
+ *   async init() {
+ *     super.init();
+ *     this.size = (await this.file.stat()).size;
+ *   }
+ *
+ *   readUint8Array(offset, length) {
+ *     const result = this.queue.then(async () => {
+ *       await this.file.seek(offset, Deno.SeekMode.Start);
+ *       const data = new Uint8Array(length);
+ *       let bytesRead = 0;
+ *       while (bytesRead < length) {
+ *         const count = await this.file.read(data.subarray(bytesRead));
+ *         if (count === null) {
+ *           return data.subarray(0, bytesRead);
+ *         }
+ *         bytesRead += count;
+ *       }
+ *       return data;
+ *     });
+ *     this.queue = result.catch(() => undefined);
+ *     return result;
+ *   }
+ * }
+ * ```
  */
 export class Reader<Type> implements Initializable, ReadableReader {
   /**
@@ -1286,7 +1396,9 @@ export class ZipReader<Type> {
    * file is read first. A `ReadableStream` instance, or an object providing only a `readable` property
    * (e.g. a file handle), is therefore buffered entirely in memory when the instance is initialized. To
    * read a large seekable resource without buffering it, pass a custom {@link Reader} implementation
-   * that reads the requested byte ranges directly.
+   * that reads the requested byte ranges directly, or a lazily-read `Blob` instance when the runtime
+   * provides one, e.g. `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun. See
+   * {@link Reader} for an example reading a `Deno.FsFile` with random access.
    *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
@@ -3289,6 +3401,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * zip file that does not comply with the USDZ specification, or appending it when the size of the output
    * is not a multiple of 64 bytes, silently produces a non-compliant file.
    *
+   * The option is only read when the {@link ZipWriter} is created; a value passed to
+   * {@link ZipWriter#add} is ignored.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3321,6 +3436,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   encrypted?: boolean;
   /**
    * The offset of the first entry in the zip file.
+   *
+   * @remarks
+   * When the option is undefined, the offset is the number of bytes already written into the
+   * destination, read from its `size` property, see {@link WritableWriter#size}. A `size` property
+   * set on a `WritableStream` instance passed directly to the {@link ZipWriter} constructor is
+   * also read, for backward compatibility. When the option is set, the bytes between the size of
+   * the destination and the offset are assumed to exist in the final zip file without being
+   * written, e.g. when writing one part of a zip file assembled by the caller.
+   *
+   * The option is only read when the {@link ZipWriter} is created, e.g. by
+   * {@link ZipDirectoryEntry#exportZip}; a value passed to {@link ZipWriter#add} is ignored.
    */
   offset?: number;
   /**
@@ -3837,6 +3963,10 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
+   *
+   * The stream is buffered entirely in memory, because reading a zip file requires random access. To import
+   * a large file without buffering it, use {@link ZipDirectoryEntry#importZip} with a seekable input, see
+   * the {@link ZipReader} constructor remarks and the {@link Reader} examples.
    */
   importReadable(
     readable: ReadableStream,
@@ -3863,6 +3993,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    * {@link ZipReader#prependedData} or its {@link ZipReader#comment} property, since the instance created
    * otherwise is not exposed. Its options are used as defaults for the options passed here, and it must not
    * have read its entries yet when it is created over a `ReadableStream` instance, which can only be read once.
+   *
+   * Like the {@link ZipReader} constructor, a `ReadableStream` input is buffered entirely in memory, see
+   * its remarks and the {@link Reader} examples for reading large seekable resources with random access.
    */
   importZip(
     reader:

package/index.d.ts

@@ -216,6 +216,12 @@ declare class DecompressionStreamLike extends TransformStreamLike {
   constructor(format: string, options?: DecompressionStreamOptions);
 }
 
+/**
+ * The version of zip.js (e.g. `"2.8.59"`), i.e. the `version` declared in the `package.json` file
+ * of the library.
+ */
+export const VERSION: string;
+
 /**
  * Configures zip.js
  *
@@ -247,6 +253,61 @@ export function registerCodec(codec: CodecDefinition): void;
  */
 export function unregisterCodec(compressionMethod: number): void;
 
+/**
+ * Returns the definitions of the codecs registered with {@link registerCodec}, in registration
+ * order. The returned objects are snapshots: modifying them does not alter the registered codecs.
+ *
+ * @remarks
+ * The `CompressionStream` and `DecompressionStream` classes of a codec registered with
+ * {@link CodecDefinition#codecURI} only appear once the module has been imported, i.e. after the
+ * first entry using the codec has been read or written.
+ *
+ * @returns The codec definitions.
+ */
+export function getRegisteredCodecs(): CodecDefinition[];
+
+/**
+ * Returns the compression methods supported in the current environment and configuration: the
+ * built-in methods followed by the codecs registered with {@link registerCodec}, in registration
+ * order.
+ *
+ * @remarks
+ * The support of the built-in methods is resolved against the compression streams available when
+ * the function is called, i.e. the classes set with {@link configure} and the implementations
+ * embedded in the build. A caller can test whether an entry is readable by looking up
+ * {@link EntryMetaData#compressionMethod} in the result and checking
+ * {@link EntryMetaData#encrypted}; `FileEntry#getData` remains the authority.
+ *
+ * @returns The supported compression methods.
+ */
+export function getSupportedCompressionMethods(): SupportedCompressionMethod[];
+
+/**
+ * Represents the support of a compression method, see {@link getSupportedCompressionMethods}.
+ */
+export interface SupportedCompressionMethod {
+  /**
+   * The compression method stored in zip entry headers (e.g. `8` for Deflate).
+   */
+  compressionMethod: number;
+  /**
+   * `true` if entries can be compressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  compression?: boolean;
+  /**
+   * `true` if entries can be decompressed with the method. It is `undefined` when the support is
+   * unknown, i.e. for a codec registered with {@link CodecDefinition#codecURI} whose module has not
+   * been imported yet.
+   */
+  decompression?: boolean;
+  /**
+   * `true` if the method comes from a codec registered with {@link registerCodec}.
+   */
+  registered: boolean;
+}
+
 /**
  * Represents a codec definition passed to {@link registerCodec}.
  */
@@ -310,6 +371,13 @@ export interface CompressionStreamOptions {
    * It is only set for the codecs registered with {@link registerCodec}.
    */
   compressionMethod?: number;
+  /**
+   * The uncompressed size of the entry, undefined when the size is unknown.
+   * It allows codecs such as Zstandard to include the content size in the compressed frame.
+   *
+   * It is only set for the codecs registered with {@link registerCodec}.
+   */
+  uncompressedSize?: number;
 }
 
 /**
@@ -757,6 +825,48 @@ export interface ReadableReader {
  *   }
  * }
  * ```
+ *
+ * @example
+ * Reading a file on the filesystem with random access does not always require a custom {@link Reader}:
+ * on runtimes exposing files as lazily-read `Blob` instances, the `Blob` returned by
+ * `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun can be passed directly to
+ * {@link ZipReader}. Deno has no equivalent API yet, see https://github.com/denoland/deno/issues/32316.
+ * The class below reads a
+ * `Deno.FsFile` with random access instead of buffering it entirely in memory. The `seek()` and `read()`
+ * calls are serialized in a queue because zip.js can read multiple byte ranges concurrently:
+ * ```
+ * class FsFileReader extends Reader {
+ *
+ *   constructor(file) {
+ *     super();
+ *     this.file = file;
+ *     this.queue = Promise.resolve();
+ *   }
+ *
+ *   async init() {
+ *     super.init();
+ *     this.size = (await this.file.stat()).size;
+ *   }
+ *
+ *   readUint8Array(offset, length) {
+ *     const result = this.queue.then(async () => {
+ *       await this.file.seek(offset, Deno.SeekMode.Start);
+ *       const data = new Uint8Array(length);
+ *       let bytesRead = 0;
+ *       while (bytesRead < length) {
+ *         const count = await this.file.read(data.subarray(bytesRead));
+ *         if (count === null) {
+ *           return data.subarray(0, bytesRead);
+ *         }
+ *         bytesRead += count;
+ *       }
+ *       return data;
+ *     });
+ *     this.queue = result.catch(() => undefined);
+ *     return result;
+ *   }
+ * }
+ * ```
  */
 export class Reader<Type> implements Initializable, ReadableReader {
   /**
@@ -1286,7 +1396,9 @@ export class ZipReader<Type> {
    * file is read first. A `ReadableStream` instance, or an object providing only a `readable` property
    * (e.g. a file handle), is therefore buffered entirely in memory when the instance is initialized. To
    * read a large seekable resource without buffering it, pass a custom {@link Reader} implementation
-   * that reads the requested byte ranges directly.
+   * that reads the requested byte ranges directly, or a lazily-read `Blob` instance when the runtime
+   * provides one, e.g. `await fs.openAsBlob(path)` on Node.js or `Bun.file(path)` on Bun. See
+   * {@link Reader} for an example reading a `Deno.FsFile` with random access.
    *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
@@ -3289,6 +3401,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * zip file that does not comply with the USDZ specification, or appending it when the size of the output
    * is not a multiple of 64 bytes, silently produces a non-compliant file.
    *
+   * The option is only read when the {@link ZipWriter} is created; a value passed to
+   * {@link ZipWriter#add} is ignored.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3321,6 +3436,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   encrypted?: boolean;
   /**
    * The offset of the first entry in the zip file.
+   *
+   * @remarks
+   * When the option is undefined, the offset is the number of bytes already written into the
+   * destination, read from its `size` property, see {@link WritableWriter#size}. A `size` property
+   * set on a `WritableStream` instance passed directly to the {@link ZipWriter} constructor is
+   * also read, for backward compatibility. When the option is set, the bytes between the size of
+   * the destination and the offset are assumed to exist in the final zip file without being
+   * written, e.g. when writing one part of a zip file assembled by the caller.
+   *
+   * The option is only read when the {@link ZipWriter} is created, e.g. by
+   * {@link ZipDirectoryEntry#exportZip}; a value passed to {@link ZipWriter#add} is ignored.
    */
   offset?: number;
   /**
@@ -3837,6 +3963,10 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
+   *
+   * The stream is buffered entirely in memory, because reading a zip file requires random access. To import
+   * a large file without buffering it, use {@link ZipDirectoryEntry#importZip} with a seekable input, see
+   * the {@link ZipReader} constructor remarks and the {@link Reader} examples.
    */
   importReadable(
     readable: ReadableStream,
@@ -3863,6 +3993,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    * {@link ZipReader#prependedData} or its {@link ZipReader#comment} property, since the instance created
    * otherwise is not exposed. Its options are used as defaults for the options passed here, and it must not
    * have read its entries yet when it is created over a `ReadableStream` instance, which can only be read once.
+   *
+   * Like the {@link ZipReader} constructor, a `ReadableStream` input is buffered entirely in memory, see
+   * its remarks and the {@link Reader} examples for reading large seekable resources with random access.
    */
   importZip(
     reader: