@zip.js/zip.js 2.8.30 → 2.8.32

package/index.d.ts

@@ -381,6 +381,45 @@ export interface OPFSTempStreamOptions {
  */
 export function createOPFSTempStream(options?: OPFSTempStreamOptions): () => Promise<TempStream>;
 
+/**
+ * Options for {@link createBlobTempStream}.
+ */
+export interface BlobTempStreamOptions {
+  /**
+   * Spill a buffered entry to a `Blob` once its buffered data exceeds this size, in bytes. Smaller entries stay in memory.
+   *
+   * @defaultValue 1048576
+   */
+  thresholdBytes?: number;
+}
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries into a `Blob` instead of keeping it in memory.
+ *
+ * An entry stays in memory until it exceeds `thresholdBytes`, then its data is transferred incrementally into a `Blob` built with `new Response(stream).blob()` and streamed back afterwards.
+ * In Chromium-based browsers, `Blob` data is managed outside the page and paged to disk under memory pressure, so peak memory stays bounded on large buffered entries without any storage permission or cleanup obligation.
+ * In Firefox, the `Blob` stays in memory but the helper still reduces peak memory usage moderately (roughly 30% on large entries) by releasing staged chunks earlier.
+ * In Safari, building the `Blob` retains several copies of the staged data (roughly 4 times the entry size at peak); do not use this helper there.
+ * In non-browser runtimes, the helper stays functional but roughly doubles peak memory usage (staged bytes plus their `Blob` copy).
+ * Outside Chromium-based browsers, prefer {@link createOPFSTempStream} or a file-backed implementation.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createBlobTempStream(options?: BlobTempStreamOptions): () => TempStream;
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries to the Origin Private File System (OPFS) via `FileSystemSyncAccessHandle` instead of keeping it in memory.
+ *
+ * This is the fastest disk-backed temporary storage on the web platform: it behaves like {@link createOPFSTempStream} (same options, same bounded-memory profile) but writes roughly 2.5 times faster in Chromium and Firefox and reads back several times faster in Firefox and Safari, making disk-backed staging nearly as fast as the in-memory default.
+ *
+ * `FileSystemSyncAccessHandle` is only exposed in dedicated workers, so this helper requires running the {@link ZipWriter} inside a worker; it throws when created in an unsupported context unless `getDirectory` is provided.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createSyncAccessHandleTempStream(options?: OPFSTempStreamOptions): () => TempStream;
+
 /**
  * Represents an instance used to read or write unknown type of data.
  *
@@ -392,6 +431,10 @@ export interface Initializable {
    * Initializes the instance asynchronously
    */
   init?(): Promise<void>;
+  /**
+   * `true` if the instance is initialized.
+   */
+  initialized?: boolean;
 }
 
 /**
@@ -700,6 +743,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
    */
@@ -1028,6 +1087,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).
  */
@@ -1225,6 +1446,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 {
   /**
@@ -1585,7 +1862,7 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * 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.
+   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation, {@link createSyncAccessHandleTempStream} for a faster worker-only variant, and {@link createBlobTempStream} for a `Blob`-backed one.
    */
   createTempStream?: () => TempStream | Promise<TempStream>;
   /**