@zip.js/zip.js 2.8.29 → 2.8.30

package/index.d.ts

@@ -327,6 +327,60 @@ declare class CodecStream extends TransformStream {}
  */
 export function getMimeType(fileExtension: string): string;
 
+/**
+ * A `TransformStream`-like temporary buffer returned by a {@link ZipWriterConstructorOptions.createTempStream} factory.
+ */
+export interface TempStream {
+  /**
+   * The writable side, receiving the compressed data of a buffered entry.
+   */
+  writable: WritableStream;
+  /**
+   * The readable side, replayed into the final zip stream once the entry is ready.
+   */
+  readable: ReadableStream;
+  /**
+   * Optional cleanup, called once the entry has been processed (on success, error, or abort) to release any backing resource.
+   */
+  dispose?: () => void | Promise<void>;
+}
+
+/**
+ * Options for {@link createOPFSTempStream}.
+ */
+export interface OPFSTempStreamOptions {
+  /**
+   * Spill a buffered entry to a file once its buffered data exceeds this size, in bytes. Smaller entries stay in memory.
+   *
+   * @defaultValue 1048576
+   */
+  thresholdBytes?: number;
+  /**
+   * Name of the OPFS sub-directory holding the temporary files.
+   *
+   * @defaultValue ".zip.js-temp"
+   */
+  directoryName?: string;
+  /**
+   * Returns (or resolves to) the root `FileSystemDirectoryHandle`. Defaults to `navigator.storage.getDirectory()`.
+   *
+   * Provide it to run inside a worker with a pre-obtained handle, or to test against a mock.
+   */
+  getDirectory?: () => FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
+}
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries to the Origin Private File System (OPFS) instead of keeping it in memory.
+ *
+ * An entry stays in memory until it exceeds `thresholdBytes`, then spills to a temporary OPFS file that is streamed back and deleted afterwards, so peak memory stays bounded on large buffered entries.
+ *
+ * OPFS is a browser/worker feature; feature-detect `navigator.storage.getDirectory` (or pass `getDirectory`) before using it, and let the writer use its in-memory default elsewhere.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createOPFSTempStream(options?: OPFSTempStreamOptions): () => Promise<TempStream>;
+
 /**
  * Represents an instance used to read or write unknown type of data.
  *
@@ -861,12 +915,55 @@ export interface GetEntriesOptions {
    * @defaultValue false
    */
   checkAmbiguity?: boolean;
+  /**
+   * How tolerant the reader should be when the archive can be parsed in more than one way.
+   *
+   * - `"strict"`: reject anything another tool could interpret differently. The end of central directory
+   * record must sit exactly at the end of the file, no data may precede the zip structure, and the local file
+   * headers must agree with the central directory records. Equivalent to {@link GetEntriesOptions#checkAmbiguity}
+   * set to `true`.
+   * - `"balanced"`: select the last end of central directory record whose comment reaches the end of the file
+   * and that points to a central directory, ignore stale records left by in-place updates as well as records
+   * forged inside a comment, and tolerate a self-extracting stub or up to
+   * {@link GetEntriesOptions#maxAppendedDataSize} bytes of appended data. Throw an {@link ERR_AMBIGUOUS_ARCHIVE}
+   * error only when two or more records reach the end of the file and each points to a central directory, which
+   * cannot be disambiguated. A record that reaches the end of the file but points to no central directory (an
+   * empty archive) is only selected when no record points to one.
+   * - `"tolerant"`: never reject a parseable archive, except when {@link GetEntriesOptions#maxAppendedDataSize}
+   * is set explicitly and exceeded; recover by selecting the last end of central directory record that reaches
+   * the end of the file and points to a central directory (or, failing that, the last one that reaches the end
+   * of the file).
+   *
+   * @defaultValue "balanced"
+   */
+  strictness?: "strict" | "balanced" | "tolerant";
+  /**
+   * The maximum number of bytes tolerated after the zip structure before the archive is rejected. Defaults to
+   * `0` when {@link GetEntriesOptions#strictness} is `"strict"`, `65535` when it is `"balanced"`, and `Infinity`
+   * when it is `"tolerant"`.
+   *
+   * An explicit value takes precedence over the strictness default at every level, so it can loosen `"strict"`
+   * or reintroduce a rejection under `"tolerant"`. It also bounds how far back the end of central directory
+   * record is searched for, so a value smaller than the amount of data actually appended surfaces an
+   * {@link ERR_EOCDR_NOT_FOUND} error when the record lies beyond the searched region and an
+   * {@link ERR_AMBIGUOUS_ARCHIVE} error otherwise.
+   */
+  maxAppendedDataSize?: number;
 }
 
 /**
  * Represents options passed to the constructor of {@link ZipReader} and {@link FileEntry#getData}.
  */
 export interface ZipReaderOptions {
+  /**
+   * How tolerant the reader should be when the local file header of an entry disagrees with its central
+   * directory record. `"strict"` throws an {@link ERR_AMBIGUOUS_ARCHIVE} error (equivalent to
+   * {@link ZipReaderOptions#checkAmbiguity} set to `true`); `"balanced"` and `"tolerant"` trust the central
+   * directory record.
+   *
+   * @defaultValue "balanced"
+   */
+  strictness?: "strict" | "balanced" | "tolerant";
   /**
    * `true` to throw an {@link ERR_AMBIGUOUS_ARCHIVE} error when calling {@link FileEntry#getData} if the local
    * file header of the entry disagrees with its central directory record in a way that could make other tools
@@ -1486,8 +1583,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * When provided, this replaces the default in-memory `TransformStream` buffer, allowing data to be stored externally (e.g. filesystem, OPFS, network).
    * The `writable` side receives compressed entry data. The `readable` side is consumed when the entry is replayed into the final zip stream.
+   * The optional `dispose` method is called once the entry has been processed (on success, error, or abort) so a resource-backed buffer can release its resource.
+   *
+   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation.
    */
-  createTempStream?: () => Promise<{ writable: WritableStream; readable: ReadableStream }>;
+  createTempStream?: () => TempStream | Promise<TempStream>;
   /**
    * `true` to keep the order of the entry physically in the zip file.
    *
@@ -2165,6 +2265,17 @@ export class ZipDirectoryEntry extends ZipEntry {
     writable?: WritableStream,
     options?: ZipDirectoryEntryExportOptions
   ): Promise<WritableStream>;
+  /**
+   * Writes the entry and its descendants into a directory as files and sub-directories via the File System Access API (e.g. the Origin Private File System). Files are streamed and directories are merged into the target; colliding files are overwritten. This is the inverse of {@link ZipDirectoryEntry#addFileSystemHandle}.
+   *
+   * @param directoryHandle The target `FileSystemDirectoryHandle` instance.
+   * @param options The options.
+   * @returns A promise resolving to the target `FileSystemDirectoryHandle` instance.
+   */
+  exportFileSystemHandle(
+    directoryHandle: FileSystemDirectoryHandle,
+    options?: ZipDirectoryEntryExportFileSystemHandleOptions
+  ): Promise<FileSystemDirectoryHandle>;
   /**
    * Creates a zip file via a custom {@link Writer} instance containing the entry and its descendants
    *
@@ -2209,6 +2320,19 @@ export interface ZipDirectoryEntryExportOptions
   readerOptions?: ZipReaderConstructorOptions;
 }
 
+/**
+ * Represents the options passed to {@link ZipDirectoryEntry#exportFileSystemHandle} and {@link FS#exportFileSystemHandle}.
+ */
+export interface ZipDirectoryEntryExportFileSystemHandleOptions
+  extends EntryGetDataOptions {
+  /**
+   * `true` to write independent files concurrently instead of one after another.
+   *
+   * @defaultValue false
+   */
+  concurrent?: boolean;
+}
+
 /**
  * Represents a Filesystem instance.
  *
@@ -2251,6 +2375,7 @@ export interface FS
     | "exportData64URI"
     | "exportUint8Array"
     | "exportWritable"
+    | "exportFileSystemHandle"
     | "exportZip"
     | "isPasswordProtected"
     | "checkPassword"