@zip.js/zip.js 2.9.0 → 2.10.0

package/index.d.ts

@@ -1594,10 +1594,17 @@ export interface ZipReaderGetEntriesOptions
 export interface GetEntriesOptions {
   /**
    * The encoding of the filename of the entry.
+   *
+   * The option is ignored when the general purpose bit 11 is set in the header of the entry: such a
+   * filename is always decoded as UTF-8. It is only read when the bit is not set, and the filename is
+   * then decoded as IBM Code Page 437 when the option is not set either.
    */
   filenameEncoding?: string;
   /**
    * The encoding of the comment of the entry.
+   *
+   * The option is ignored when the general purpose bit 11 is set in the header of the entry, see
+   * {@link GetEntriesOptions#filenameEncoding}.
    */
   commentEncoding?: string;
   /**
@@ -3244,6 +3251,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * Note that this option only sets the flag, it does not ensure that the file names are in the correct
    * encoding: when it is set to `false`, the names are still encoded in UTF-8 unless the
    * {@link ZipWriterConstructorOptions#encodeText} option is also set to encode them in the intended code page.
+   * Setting it to `false` alone therefore produces an archive whose file names are mislabeled, holding UTF-8
+   * bytes announced as Code Page 437: the names holding characters outside of ASCII are decoded incorrectly
+   * by the readers honoring the flag, including {@link ZipReader} unless
+   * {@link GetEntriesOptions#filenameEncoding} is set to `"utf-8"`.
    *
    * @defaultValue true
    */
@@ -3458,6 +3469,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * The function called for encoding the filename and the comment of the entry.
    *
+   * zip.js encodes them in UTF-8 when the option is not set, so it must be set to write them in another
+   * code page, together with {@link ZipWriterConstructorOptions#useUnicodeFileNames} set to `false` to
+   * announce them as Code Page 437 instead of UTF-8.
+   *
    * @param text The text to encode.
    * @param type The type of the encoded text, `"filename"` or `"comment"`.
    * @returns The encoded text or `undefined` if the text should be encoded by zip.js.
@@ -3545,6 +3560,9 @@ export class ZipEntry {
    * @remarks It is the size of the raw compressed content when the entry has been imported with the
    * `passThrough` option set to `true`, since the entry holds the compressed data in that case. The
    * uncompressed size of the original entry remains available in {@link ZipEntry#data}.
+   *
+   * It is updated by the `{@link ZipFileEntry}#replace*()` methods, and it is `0` for an entry holding
+   * a `ReadableStream` instance, whose size is only known once the entry has been read.
    */
   uncompressedSize: number;
   /**
@@ -3594,6 +3612,12 @@ export class ZipEntry {
   /**
    * Set the name of the entry
    *
+   * @remarks A name holding `"/"` is split into path components, like the name passed to a
+   * `{@link ZipDirectoryEntry}#add*()` method, so it moves the entry into the directories it names,
+   * creating them when they do not exist. Renaming an entry to the name it already has does nothing.
+   * Renaming it onto an existing sibling throws an {@link ERR_ENTRY_EXISTS} error, and renaming it
+   * into itself or into one of its descendants throws.
+   *
    * @param name The new name of the entry.
    */
   rename(name: string): void;
@@ -3619,6 +3643,11 @@ export class ZipEntry {
 
 /**
  * Represents a file entry in the zip (Filesystem API).
+ *
+ * @remarks A `{@link ZipFileEntry}#replace*()` method describes the entry with the content it is
+ * given: it updates {@link ZipEntry#uncompressedSize} and clears the pass-through state of an entry
+ * imported with the {@link ZipReaderOptions#passThrough} option, since the bytes copied verbatim are
+ * gone. Replacing the content of an entry therefore keeps {@link ZipFS#getExportedSize} exact.
  */
 export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
   /**
@@ -3737,6 +3766,10 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
   /**
    * Replaces the content of the entry with a `ReadableStream` instance
    *
+   * @remarks The size of a `ReadableStream` instance is unknown, so the entry reports an undetermined
+   * size, like an entry added with {@link ZipDirectoryEntry#addReadable}. {@link ZipFS#getExportedSize}
+   * then throws an {@link ERR_UNDETERMINED_SIZE} error instead of returning a size it cannot predict.
+   *
    * @param readable The `ReadableStream` instance.
    */
   replaceReadable(readable: ReadableStream): void;
@@ -3744,6 +3777,13 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
 
 /**
  * Represents a directory entry in the zip (Filesystem API).
+ *
+ * @remarks The `name` passed to an `{@link ZipDirectoryEntry}#add*()` method is split into path
+ * components, exactly like the filename of an imported entry, so `addText("a/b.txt", text)` adds
+ * `"b.txt"` to the `"a"` directory and creates that directory when it does not exist. Empty
+ * components and `"."` components are ignored. The directories created that way are navigable like
+ * any other entry but are not written when the tree is exported, so the zip file holds the same
+ * entries whichever way the path was built.
  */
 export class ZipDirectoryEntry extends ZipEntry {
   /**
@@ -3916,7 +3956,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    */
   importBlob(
     blob: Blob,
-    options?: ZipReaderConstructorOptions
+    options?: ZipDirectoryEntryImportOptions
   ): Promise<[ZipEntry]>;
   /**
    * Extracts a zip file provided as a Data URI `string` encoded in Base64 into the entry
@@ -3929,7 +3969,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    */
   importData64URI(
     dataURI: string,
-    options?: ZipReaderConstructorOptions
+    options?: ZipDirectoryEntryImportOptions
   ): Promise<[ZipEntry]>;
   /**
    * Extracts a zip file provided as a `Uint8Array` instance into the entry
@@ -3942,7 +3982,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    */
   importUint8Array(
     array: Uint8Array,
-    options?: ZipReaderConstructorOptions
+    options?: ZipDirectoryEntryImportOptions
   ): Promise<[ZipEntry]>;
   /**
    * Extracts a zip file fetched from a URL into the entry
@@ -3972,7 +4012,7 @@ export class ZipDirectoryEntry extends ZipEntry {
    */
   importReadable(
     readable: ReadableStream,
-    options?: ZipReaderConstructorOptions
+    options?: ZipDirectoryEntryImportOptions
   ): Promise<[ZipEntry]>;
   /**
    * Extracts a zip file provided via a custom {@link Reader} instance or a {@link ZipReader} instance into
@@ -4008,7 +4048,7 @@ export class ZipDirectoryEntry extends ZipEntry {
       | ReadableReader[]
       | ReadableStream[]
       | ZipReader<unknown>,
-    options?: ZipReaderConstructorOptions
+    options?: ZipDirectoryEntryImportOptions
   ): Promise<[ZipEntry]>;
   /**
    * Returns a `Blob` instance containing a zip file of the entry and its descendants
@@ -4112,7 +4152,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    * This happens when `usdz` is set, since the alignment padding depends on the offset of each
    * entry, and when the archive exceeds 4GB, since the offsets recorded in the central directory
    * are then extended to 64 bits. Passing `bufferedWrite: false` makes both determinable again,
-   * as does exporting a directory whose children are all files. It is thrown as well when
+   * as does exporting a directory whose children are all files. A name holding `"/"` creates the
+   * directories it names, so `addText("a/b.txt", text)` builds a tree whose children are not all
+   * files, even though the directories created that way are not written. It is thrown as well when
    * `signCentralDirectory` is set, the length of the signature being unknown until it is computed.
    *
    * @param options The options.
@@ -4122,11 +4164,39 @@ export class ZipDirectoryEntry extends ZipEntry {
   getExportedSize(options?: ZipDirectoryEntryExportOptions): Promise<number>;
 }
 
+/**
+ * Represents the options passed to `{@link ZipDirectoryEntry}#import*()`.
+ */
+export interface ZipDirectoryEntryImportOptions
+  extends ZipReaderConstructorOptions {
+  /**
+   * The policy applied when two entries of the imported zip file claim the same node of the tree
+   *
+   * @remarks
+   * The tree indexes the entries by path, whereas a zip file stores a flat list of filenames, so two
+   * entries can claim one node: they can hold the same filename, hold filenames differing only by the
+   * path components ignored when building the tree (e.g. `"a/b.txt"` and `"./a/b.txt"`), or one can be
+   * a file and the other a directory holding it (e.g. `"a"` and `"a/b.txt"`).
+   *
+   * `"throw"` refuses the zip file with an {@link ERR_DUPLICATE_IMPORTED_ENTRY} error, whose `cause`
+   * property holds the {@link EntryMetaData} instance of the entry that could not be imported. The
+   * filesystem is left unchanged, i.e. the entries imported before the error are removed and the
+   * content held before the import is restored.
+   *
+   * `"keep-first"` ignores the entry claiming a node already taken, and `"keep-last"` replaces the
+   * entry holding the node, which is the behavior of most zip tools. The entries that do not collide
+   * are imported in both cases.
+   *
+   * @defaultValue "throw"
+   */
+  duplicates?: "throw" | "keep-first" | "keep-last";
+}
+
 /**
  * Represents the options passed to {@link ZipDirectoryEntry#importHttpContent}.
  */
 export interface ZipDirectoryEntryImportHttpOptions
-  extends ZipReaderConstructorOptions,
+  extends ZipDirectoryEntryImportOptions,
     HttpOptions {}
 
 /**
@@ -4779,6 +4849,16 @@ export const ERR_ZIP_CRYPTO_LAST_MOD_DATE: string;
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */
 export const ERR_ENTRY_EXISTS: string;
+/**
+ * Duplicate imported entry error (thrown by `{@link ZipDirectoryEntry}#import*()` when two entries of the
+ * zip file claim the same node of the tree and the {@link ZipDirectoryEntryImportOptions#duplicates} option
+ * is set to `"throw"`)
+ */
+export const ERR_DUPLICATE_IMPORTED_ENTRY: string;
+/**
+ * Invalid duplicates option error
+ */
+export const ERR_INVALID_DUPLICATES: string;
 /**
  * Readable stream already consumed error (thrown by the filesystem API when a readable stream is read more than once)
  */