@zip.js/zip.js 2.7.61 → 2.7.63

package/index.d.ts

@@ -7,7 +7,7 @@
  *
  * @author Gildas Lormeau
  * @license BSD-3-Clause
- *  
+ *
  * @example
  * Hello world
  * ```js
@@ -19,39 +19,39 @@
  *   ZipReader,
  *   ZipWriter,
  * } from from "@zip-js/zip-js";
- * 
+ *
  * // ----
  * // Write the zip file
  * // ----
- * 
+ *
  * // Creates a BlobWriter object where the zip content will be written.
  * const zipFileWriter = new BlobWriter();
- * 
+ *
  * // Creates a TextReader object storing the text of the entry to add in the zip
  * // (i.e. "Hello world!").
  * const helloWorldReader = new TextReader("Hello world!");
- * 
+ *
  * // Creates a ZipWriter object writing data via `zipFileWriter`, adds the entry
  * // "hello.txt" containing the text "Hello world!" via `helloWorldReader`, and
  * // closes the writer.
  * const zipWriter = new ZipWriter(zipFileWriter);
  * await zipWriter.add("hello.txt", helloWorldReader);
  * await zipWriter.close();
- * 
+ *
  * // Retrieves the Blob object containing the zip content into `zipFileBlob`. It
  * // is also returned by zipWriter.close() for more convenience.
  * const zipFileBlob = await zipFileWriter.getData();
- * 
+ *
  * // ----
  * // Read the zip file
  * // ----
- * 
+ *
  * // Creates a BlobReader object used to read `zipFileBlob`.
  * const zipFileReader = new BlobReader(zipFileBlob);
  * // Creates a TextWriter object where the content of the first entry in the zip
  * // will be written.
  * const helloWorldWriter = new TextWriter();
- * 
+ *
  * // Creates a ZipReader object reading the zip content via `zipFileReader`,
  * // retrieves metadata (name, dates, etc.) of the first entry, retrieves its
  * // content via `helloWorldWriter`, and closes the reader.
@@ -59,11 +59,11 @@
  * const firstEntry = (await zipReader.getEntries()).shift();
  * const helloWorldText = await firstEntry.getData(helloWorldWriter);
  * await zipReader.close();
- * 
+ *
  * // Displays "Hello world!".
  * console.log(helloWorldText);
  * ```
- * 
+ *
  * @example
  * Hello world with Streams
  * ```js
@@ -72,11 +72,11 @@
  *   ZipReader,
  *   ZipWriter,
  * } from "@zip-js/zip-js";
- * 
+ *
  * // ----
  * // Write the zip file
  * // ----
- * 
+ *
  * // Creates a TransformStream object, the zip content will be written in the
  * // `writable` property.
  * const zipFileStream = new TransformStream();
@@ -86,21 +86,21 @@
  * // Creates a ReadableStream object storing the text of the entry to add in the
  * // zip (i.e. "Hello world!").
  * const helloWorldReadable = new Blob(["Hello world!"]).stream();
- * 
+ *
  * // Creates a ZipWriter object writing data into `zipFileStream.writable`, adds
  * // the entry "hello.txt" containing the text "Hello world!" retrieved from
  * // `helloWorldReadable`, and closes the writer.
  * const zipWriter = new ZipWriter(zipFileStream.writable);
  * await zipWriter.add("hello.txt", helloWorldReadable);
  * await zipWriter.close();
- * 
+ *
  * // Retrieves the Blob object containing the zip content into `zipFileBlob`.
  * const zipFileBlob = await zipFileBlobPromise;
- * 
+ *
  * // ----
  * // Read the zip file
  * // ----
- * 
+ *
  * // Creates a BlobReader object used to read `zipFileBlob`.
  * const zipFileReader = new BlobReader(zipFileBlob);
  * // Creates a TransformStream object, the content of the first entry in the zip
@@ -109,7 +109,7 @@
  * // Creates a Promise object resolved to the content of the first entry returned
  * // as text from `helloWorldStream.readable`.
  * const helloWorldTextPromise = new Response(helloWorldStream.readable).text();
- * 
+ *
  * // Creates a ZipReader object reading the zip content via `zipFileReader`,
  * // retrieves metadata (name, dates, etc.) of the first entry, retrieves its
  * // content into `helloWorldStream.writable`, and closes the reader.
@@ -117,12 +117,12 @@
  * const firstEntry = (await zipReader.getEntries()).shift();
  * await firstEntry.getData(helloWorldStream.writable);
  * await zipReader.close();
- * 
+ *
  * // Displays "Hello world!".
  * const helloWorldText = await helloWorldTextPromise;
  * console.log(helloWorldText);
  * ```
- * 
+ *
  * @example
  * Adding concurrently multiple entries in a zip file
  * ```js
@@ -132,11 +132,11 @@
  *   TextReader,
  *   ZipWriter,
  * } from "@zip-js/zip-js";
- * 
+ *
  * const README_URL = "https://unpkg.com/@zip.js/zip.js/README.md";
  * getZipFileBlob()
  *   .then(downloadFile);
- * 
+ *
  * async function getZipFileBlob() {
  *   const zipWriter = new ZipWriter(new BlobWriter("application/zip"));
  *   await Promise.all([
@@ -145,7 +145,7 @@
  *   ]);
  *   return zipWriter.close();
  * }
- * 
+ *
  * function downloadFile(blob) {
  *   document.body.appendChild(Object.assign(document.createElement("a"), {
  *     download: "hello.zip",
@@ -154,7 +154,7 @@
  *   }));
  * }
  * ```
- * 
+ *
  * @module
 */
 
@@ -286,7 +286,7 @@ export interface Configuration extends WorkerConfiguration {
 }
 
 /**
- * Represents configuration passed to {@link configure}, the constructor of {@link ZipReader}, {@link Entry#getData}, the constructor of {@link ZipWriter}, and {@link ZipWriter#add}.
+ * Represents configuration passed to {@link configure}, the constructor of {@link ZipReader}, {@link FileEntry#getData}, the constructor of {@link ZipWriter}, and {@link ZipWriter#add}.
  */
 export interface WorkerConfiguration {
   /**
@@ -479,7 +479,7 @@ export interface ReadableReader {
  *     this.size = this.binaryString.length;
  *   }
  *
- *   readCompatibleUint8Array(offset, length) {
+ *   readUint8Array(offset, length) {
  *     const result = new Uint8Array(length);
  *     for (let indexCharacter = 0; indexCharacter < length; indexCharacter++) {
  *       result[indexCharacter] = this.binaryString.charCodeAt(indexCharacter + offset) & 0xFF;
@@ -515,7 +515,7 @@ export class Reader<Type> implements Initializable, ReadableReader {
    * @param length The length of the data to read in bytes.
    * @returns A promise resolving to a chunk of data.
    */
-  readCompatibleUint8Array(index: number, length: number): Promise<Uint8Array>;
+  readUint8Array(index: number, length: number): Promise<Uint8Array>;
 }
 
 /**
@@ -536,7 +536,7 @@ export class Data64URIReader extends Reader<string> { }
 /**
  * Represents a {@link Reader} instance used to read data provided as a `Uint8Array` instance.
  */
-export class CompatibleUint8ArrayReader extends Reader<Uint8Array> { }
+export class Uint8ArrayReader extends Reader<Uint8Array> { }
 
 /**
  * Represents a {@link Reader} instance used to read data provided as an array of {@link ReadableReader} instances (e.g. split zip files).
@@ -638,7 +638,7 @@ export interface WritableWriter {
    */
   writable: WritableStream;
   /**
-   * The maximum size of split data when creating a {@link ZipWriter} instance or when calling {@link Entry#getData} with a generator of {@link WritableWriter} instances.
+   * The maximum size of split data when creating a {@link ZipWriter} instance or when calling {@link FileEntry#getData} with a generator of {@link WritableWriter} instances.
    */
   maxSize?: number;
 }
@@ -656,7 +656,7 @@ export interface WritableWriter {
  *     this.binaryString = "";
  *   }
  *
- *   writeCompatibleUint8Array(array) {
+ *   writeUint8Array(array) {
  *     for (let indexCharacter = 0; indexCharacter < array.length; indexCharacter++) {
  *       this.binaryString += String.fromCharCode(array[indexCharacter]);
  *     }
@@ -686,7 +686,7 @@ export class Writer<Type> implements Initializable, WritableWriter {
    *
    * @virtual
    */
-  writeCompatibleUint8Array(array: Uint8Array): Promise<void>;
+  writeUint8Array(array: Uint8Array): Promise<void>;
   /**
    * Retrieves all the written data
    *
@@ -782,7 +782,7 @@ export class SplitDataWriter implements Initializable, WritableWriter {
 /**
  * Represents a {@link Writer}  instance used to retrieve the written data as a `Uint8Array` instance.
  */
-export class CompatibleUint8ArrayWriter extends Writer<Uint8Array> { }
+export class Uint8ArrayWriter extends Writer<Uint8Array> { }
 
 /**
  * Represents an instance used to create an unzipped stream.
@@ -948,7 +948,7 @@ export interface GetEntriesOptions {
   commentEncoding?: string;
   /**
    * The function called for decoding the filename and the comment of the entry.
-   * 
+   *
    * @param value The raw text value.
    * @param encoding The encoding of the text.
    * @returns The decoded text value or `undefined` if the raw text value should be decoded by zip.js.
@@ -957,7 +957,7 @@ export interface GetEntriesOptions {
 }
 
 /**
- * Represents options passed to the constructor of {@link ZipReader} and {@link Entry#getData}.
+ * Represents options passed to the constructor of {@link ZipReader} and {@link FileEntry#getData}.
  */
 export interface ZipReaderOptions {
   /**
@@ -989,7 +989,7 @@ export interface ZipReaderOptions {
    */
   signal?: AbortSignal;
   /**
-   * `true` to prevent closing of {@link Writer#writable} when calling {@link Entry#getData}.
+   * `true` to prevent closing of {@link Writer#writable} when calling {@link FileEntry#getData}.
    *
    * @defaultValue false
    */
@@ -1140,11 +1140,13 @@ export interface EntryMetaData {
    */
   compressionMethod: number;
 }
+export interface DirectoryEntry extends Omit<EntryMetaData, 'directory'> {
+  directory: true;
+  getData?: undefined;
+}
 
-/**
- * Represents an entry with its data and metadata in a zip file (Core API).
- */
-export interface Entry extends EntryMetaData {
+export interface FileEntry extends Omit<EntryMetaData, 'directory'> {
+  directory: false;
   /**
    * Returns the content of the entry
    *
@@ -1152,7 +1154,7 @@ export interface Entry extends EntryMetaData {
    * @param options The options.
    * @returns A promise resolving to the type to data associated to `writer`.
    */
-  getData?<Type>(
+  getData<Type>(
     writer:
       | Writer<Type>
       | WritableWriter
@@ -1166,13 +1168,34 @@ export interface Entry extends EntryMetaData {
 }
 
 /**
- * Represents the options passed to {@link Entry#getData} and `{@link ZipFileEntry}.get*`.
+ * Represents an entry with its data and metadata in a zip file (Core API).
+ * This is a union type of {@link DirectoryEntry} and {@link FileEntry}.
+ *
+ * Before using getData, you should check if the entry is a file.
+ *
+ * @example
+ *
+ * ```ts
+ * for await (const entry of reader.getEntriesGenerator()) {
+ *   if (entry.directory) continue;
+ *
+ *   // entry is a FileEntry
+ *   const plainTextData = await entry.getData(new TextWriter());
+ *
+ *   // Do something with the plainTextData
+ * }
+ * ```
+ */
+export type Entry = DirectoryEntry | FileEntry;
+
+/**
+ * Represents the options passed to {@link FileEntry#getData} and `{@link ZipFileEntry}.get*`.
  */
 export interface EntryGetDataOptions
   extends EntryDataOnprogressOptions, ZipReaderOptions, WorkerConfiguration { }
 
 /**
- * Represents the options passed to {@link Entry#getData} and `{@link ZipFileEntry}.get*`.
+ * Represents the options passed to {@link FileEntry#getData} and `{@link ZipFileEntry}.get*`.
  */
 export interface EntryGetDataCheckPasswordOptions
   extends EntryGetDataOptions { }
@@ -1503,7 +1526,7 @@ export interface ZipWriterConstructorOptions {
   versionMadeBy?: number;
   /**
    * `true` to mark the file names as UTF-8 setting the general purpose bit 11 in the header (see Appendix D - Language Encoding (EFS)), `false` to mark the names as compliant with the original IBM Code Page 437.
-   * 
+   *
    * Note that this does not ensure that the file names are in the correct encoding.
    *
    * @defaultValue true
@@ -1571,7 +1594,7 @@ export interface ZipWriterConstructorOptions {
   compressionMethod?: number
   /**
    * The function called for encoding the filename and the comment of the entry.
-   * 
+   *
    * @param text The text to encode.
    * @returns The encoded text or `undefined` if the text should be encoded by zip.js.
    */
@@ -1579,7 +1602,7 @@ export interface ZipWriterConstructorOptions {
 }
 
 /**
- * Represents options passed to {@link Entry#getData}, {@link ZipWriter.add} and `{@link ZipDirectory}.export*`.
+ * Represents options passed to {@link FileEntry#getData}, {@link ZipWriter.add} and `{@link ZipDirectory}.export*`.
  */
 export interface EntryDataOnprogressOptions {
   /**
@@ -1751,7 +1774,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    * @param options The options.
    * @returns A promise resolving to a `Uint8Array` instance.
    */
-  getCompatibleUint8Array(options?: EntryGetDataOptions): Promise<Uint8Array>;
+  getUint8Array(options?: EntryGetDataOptions): Promise<Uint8Array>;
   /**
    * Retrieves the content of the entry via a `WritableStream` instance
    *
@@ -1801,7 +1824,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    *
    * @param array The `Uint8Array` instance.
    */
-  replaceCompatibleUint8Array(array: Uint8Array): void;
+  replaceUint8Array(array: Uint8Array): void;
   /**
    * Replaces the content of the entry with a `ReadableStream` instance
    *
@@ -1883,7 +1906,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    * @param options The options.
    * @returns A {@link ZipFileEntry} instance.
    */
-  addCompatibleUint8Array(
+  addUint8Array(
     name: string,
     array: Uint8Array,
     options?: ZipWriterAddDataOptions,
@@ -1973,7 +1996,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    * @param array The `Uint8Array` instance.
    * @param options  The options.
    */
-  importCompatibleUint8Array(
+  importUint8Array(
     array: Uint8Array,
     options?: ZipReaderConstructorOptions,
   ): Promise<[ZipEntry]>;
@@ -2033,7 +2056,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    * @param options  The options.
    * @returns A promise resolving to the `Uint8Array` instance.
    */
-  exportCompatibleUint8Array(
+  exportUint8Array(
     options?: ZipDirectoryEntryExportOptions,
   ): Promise<Uint8Array>;
   /**
@@ -2261,7 +2284,7 @@ export const ERR_ITERATOR_COMPLETED_TOO_SOON: string;
 /**
  * Undefined uncompressed size error
  */
-export const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string
+export const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string;
 /**
  * Writer not initialized error
  */