@zip.js/zip.js 2.8.29 → 2.8.31

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.
  *
@@ -338,6 +392,10 @@ export interface Initializable {
    * Initializes the instance asynchronously
    */
   init?(): Promise<void>;
+  /**
+   * `true` if the instance is initialized.
+   */
+  initialized?: boolean;
 }
 
 /**
@@ -646,6 +704,22 @@ export class SplitDataWriter implements Initializable, WritableWriter {
    * The `WritableStream` instance.
    */
   writable: WritableStream;
+  /**
+   * The number of the disk being written.
+   */
+  diskNumber: number;
+  /**
+   * The byte offset of the disk being written.
+   */
+  diskOffset: number;
+  /**
+   * The maximum size of each disk in bytes.
+   */
+  maxSize: number;
+  /**
+   * The number of bytes still available on the disk being written.
+   */
+  availableSize: number;
   /**
    * Initializes the instance asynchronously
    */
@@ -861,12 +935,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
@@ -931,6 +1048,168 @@ export interface ZipReaderOptions {
   preventClose?: boolean;
 }
 
+/**
+ * Represents the parsed general purpose bit flag of an entry.
+ */
+export interface EntryBitFlag {
+  /**
+   * The compression option bits.
+   */
+  level: number;
+  /**
+   * `true` if the entry data is followed by a data descriptor.
+   */
+  dataDescriptor: boolean;
+  /**
+   * `true` if the filename and the comment are encoded in UTF-8 (EFS).
+   */
+  languageEncodingFlag: boolean;
+}
+/**
+ * Represents an extra field record of an entry.
+ */
+export interface EntryExtraField {
+  /**
+   * The type (header id) of the extra field.
+   */
+  type: number;
+  /**
+   * The data of the extra field.
+   */
+  data: Uint8Array;
+}
+/**
+ * Represents the AES extra field record of an entry.
+ */
+export interface EntryExtraFieldAES extends EntryExtraField {
+  /**
+   * The encryption strength (1, 2 or 3).
+   */
+  strength?: number;
+  /**
+   * The compression method stored in the AES extra field.
+   */
+  originalCompressionMethod?: number;
+}
+/**
+ * Represents a Unicode path or comment extra field record of an entry.
+ */
+export interface EntryExtraFieldUnicode extends EntryExtraField {
+  /**
+   * `true` if the extra field is consistent with the entry metadata.
+   */
+  valid?: boolean;
+}
+/**
+ * Represents the local file header fields of an entry, read when getting the entry data.
+ */
+export interface LocalDirectory {
+  /**
+   * The "Version" field.
+   */
+  version: number;
+  /**
+   * `true` if the entry is encrypted.
+   */
+  encrypted: boolean;
+  /**
+   * The general purpose bit flag (raw).
+   */
+  rawBitFlag: number;
+  /**
+   * The general purpose bit flag.
+   */
+  bitFlag: EntryBitFlag;
+  /**
+   * The last modification date (raw).
+   */
+  rawLastModDate: number;
+  /**
+   * The last modification date.
+   */
+  lastModDate: Date;
+  /**
+   * The length of the filename in bytes.
+   */
+  filenameLength: number;
+  /**
+   * The length of the extra field in bytes.
+   */
+  extraFieldLength: number;
+  /**
+   * The extra field (raw).
+   */
+  rawExtraField: Uint8Array;
+  /**
+   * The extra field.
+   */
+  extraField?: Map<number, EntryExtraField>;
+  /**
+   * The signature (CRC32 checksum) of the content.
+   */
+  signature?: number;
+  /**
+   * The compressed size of the content.
+   */
+  compressedSize?: number;
+  /**
+   * The uncompressed size of the content.
+   */
+  uncompressedSize?: number;
+  /**
+   * The compression method.
+   */
+  compressionMethod?: number;
+  /**
+   * The Zip64 extra field.
+   */
+  extraFieldZip64?: EntryExtraField;
+  /**
+   * The AES extra field.
+   */
+  extraFieldAES?: EntryExtraFieldAES;
+  /**
+   * The NTFS extra field.
+   */
+  extraFieldNTFS?: EntryExtraField;
+  /**
+   * The Unix extra field.
+   */
+  extraFieldUnix?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix extra field.
+   */
+  extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The extended timestamp extra field.
+   */
+  extraFieldExtendedTimestamp?: EntryExtraField;
+  /**
+   * The Unicode path extra field.
+   */
+  extraFieldUnicodePath?: EntryExtraFieldUnicode;
+  /**
+   * The Unicode comment extra field.
+   */
+  extraFieldUnicodeComment?: EntryExtraFieldUnicode;
+  /**
+   * The USDZ extra field.
+   */
+  extraFieldUSDZ?: EntryExtraField;
+}
+/**
+ * Represents an error raised while processing an entry, decorated with entry context.
+ */
+export interface EntryError extends Error {
+  /**
+   * `true` if the zip file is corrupted because the entry data could not be written entirely.
+   */
+  corruptedEntry?: boolean;
+  /**
+   * The id of the related {@link ZipEntry} (filesystem API).
+   */
+  entryId?: number;
+}
 /**
  * Represents the metadata of an entry in a zip file (Core API).
  */
@@ -1128,6 +1407,62 @@ export interface EntryMetaData {
    * The compression method.
    */
   compressionMethod: number;
+  /**
+   * The general purpose bit flag (raw).
+   */
+  rawBitFlag?: number;
+  /**
+   * The general purpose bit flag.
+   */
+  bitFlag?: EntryBitFlag;
+  /**
+   * The length of the filename in bytes.
+   */
+  filenameLength?: number;
+  /**
+   * The length of the extra field in bytes.
+   */
+  extraFieldLength?: number;
+  /**
+   * The Zip64 extra field.
+   */
+  extraFieldZip64?: EntryExtraField;
+  /**
+   * The AES extra field.
+   */
+  extraFieldAES?: EntryExtraFieldAES;
+  /**
+   * The NTFS extra field.
+   */
+  extraFieldNTFS?: EntryExtraField;
+  /**
+   * The Unix extra field.
+   */
+  extraFieldUnix?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix extra field.
+   */
+  extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The extended timestamp extra field.
+   */
+  extraFieldExtendedTimestamp?: EntryExtraField;
+  /**
+   * The Unicode path extra field.
+   */
+  extraFieldUnicodePath?: EntryExtraFieldUnicode;
+  /**
+   * The Unicode comment extra field.
+   */
+  extraFieldUnicodeComment?: EntryExtraFieldUnicode;
+  /**
+   * The USDZ extra field.
+   */
+  extraFieldUSDZ?: EntryExtraField;
+  /**
+   * The local file header fields, set when the entry data has been read.
+   */
+  localDirectory?: LocalDirectory;
 }
 export interface DirectoryEntry extends EntryMetaData {
   /**
@@ -1486,8 +1821,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 +2503,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 +2558,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 +2613,7 @@ export interface FS
     | "exportData64URI"
     | "exportUint8Array"
     | "exportWritable"
+    | "exportFileSystemHandle"
     | "exportZip"
     | "isPasswordProtected"
     | "checkPassword"