@zip.js/zip.js 2.8.49 → 2.8.50

package/index.d.cts

@@ -1201,9 +1201,10 @@ export interface GetEntriesOptions {
    *
    * @param value The raw text value.
    * @param encoding The encoding of the text.
+   * @param type The type of the decoded text, `"filename"` or `"comment"`.
    * @returns The decoded text value or `undefined` if the raw text value should be decoded by zip.js.
    */
-  decodeText?(value: Uint8Array, encoding: string): string | undefined;
+  decodeText?(value: Uint8Array, encoding: string, type: "filename" | "comment"): string | undefined;
   /**
    * `true` to throw an {@link ERR_AMBIGUOUS_ARCHIVE} error when the archive could be parsed differently by other
    * tools. This detects data before or after the zip structure (e.g. a self-extracting archive stub or a
@@ -1237,6 +1238,42 @@ export interface GetEntriesOptions {
    * @defaultValue "balanced"
    */
   strictness?: "strict" | "balanced" | "tolerant";
+  /**
+   * How strictly the filename of each entry should be validated. A rejected name throws an
+   * {@link ERR_UNSAFE_FILENAME} error carrying the offending name in its `filename` property.
+   *
+   * - `"strict"`: reject the names rejected by `"balanced"`, plus the names that do not map cleanly to a file
+   * path, i.e. empty names and names containing a `"."` path component or an empty one (e.g. `"a//b.txt"`).
+   * - `"balanced"`: reject names that would escape the directory they are extracted into, i.e. names containing
+   * a `".."` path component, and absolute names, i.e. names starting with `"/"`, with a drive letter (e.g.
+   * `"C:/file.txt"`) or with two backslashes (UNC paths).
+   * - `"tolerant"`: never reject a name.
+   *
+   * A backslash is never interpreted as a path separator: it is a valid filename character on UNIX systems, and
+   * it also occurs as the trail byte of legitimate double-byte filenames (e.g. CP932) decoded with another
+   * charset.
+   *
+   * Names are validated, never rewritten, so the filename reported for an entry always matches its central
+   * directory record.
+   *
+   * @defaultValue The value of {@link GetEntriesOptions#strictness}.
+   */
+  filenameValidation?: "strict" | "balanced" | "tolerant";
+  /**
+   * The function called for normalizing the filename of each entry, e.g. to repair the names rejected by
+   * {@link GetEntriesOptions#filenameValidation}.
+   *
+   * It is called with the decoded filename, after {@link GetEntriesOptions#decodeText} and before the name is
+   * validated, so a name it fails to repair is still rejected. The returned name becomes the name of the entry:
+   * it is used to detect directory entries by their trailing `"/"`, and to detect duplicate filenames when
+   * {@link GetEntriesOptions#checkAmbiguity} is set, so two names normalized into the same name are reported as
+   * an {@link ERR_AMBIGUOUS_ARCHIVE} error instead of silently shadowing each other. The raw filename remains
+   * available in {@link EntryMetaData#rawFilename}.
+   *
+   * @param filename The decoded filename.
+   * @returns The normalized filename or `undefined` to keep the decoded filename.
+   */
+  normalizeFilename?(filename: string): string | undefined;
   /**
    * 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`
@@ -1613,6 +1650,27 @@ export interface EntryError extends Error {
    * The id of the related {@link ZipEntry} (filesystem API).
    */
   entryId?: number;
+  /**
+   * The name of the related {@link ZipEntry}, or of the related `FileSystemHandle` when importing
+   * one (filesystem API). Set by {@link ZipDirectoryEntry#addFileSystemHandle} and
+   * {@link ZipDirectoryEntry#exportFileSystemHandle}, which rethrow the original error rather than
+   * wrapping it, so its `message` stays comparable to the exported `ERR_*` constants.
+   */
+  entryName?: string;
+  /**
+   * The other entries that also failed, when {@link ZipDirectoryEntry#exportFileSystemHandle} runs
+   * with `concurrent` set to `true` and more than one entry fails (filesystem API). The error it is
+   * set on is not repeated in the list, and failures raised deeper in the tree are flattened into
+   * it, so the list holds every failure of the export except this one.
+   */
+  entryErrors?: EntryError[];
+  /**
+   * The names of the files {@link ZipDirectoryEntry#exportFileSystemHandle} finished writing before
+   * it failed, relative to the exported entry (filesystem API). Directories are not listed. Every
+   * other file of the export is either missing or empty, so this is the only way to tell a file the
+   * export completed from one it created but never filled.
+   */
+  exportedEntryNames?: string[];
 }
 /**
  * Represents the metadata of an entry in a zip file (Core API).
@@ -2497,9 +2555,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * The function called for encoding the filename and the comment of the entry.
    *
    * @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.
    */
-  encodeText?(text: string): Uint8Array | undefined;
+  encodeText?(text: string, type: "filename" | "comment"): Uint8Array | undefined;
 }
 
 /**
@@ -2867,6 +2926,10 @@ export class ZipDirectoryEntry extends ZipEntry {
   /**
    * Adds an entry with content provided via a `FileSystemHandle` instance
    *
+   * If a handle cannot be read, the original error is rethrown unmodified as an {@link EntryError},
+   * whose {@link EntryError#entryName} is the path of the handle that failed, relative to the parent
+   * of `fileSystemHandle`.
+   *
    * @param fileSystemHandle The `fileSystemHandle` instance.
    * @param options The options.
    * @returns A promise resolving to an array of {@link ZipFileEntry} or a {@link ZipDirectoryEntry} instances.
@@ -2930,6 +2993,11 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param reader The {@link Reader} instance.
    * @param options  The options.
+   *
+   * @remarks The filename of each entry is split into path components to build the tree of entries. Empty
+   * components and `"."` components are ignored, so `"a//b.txt"`, `"./a/b.txt"` and `"a/./b.txt"` all produce
+   * the same `"a/b.txt"` entry. Filenames are normalized and validated beforehand, see
+   * {@link GetEntriesOptions#normalizeFilename} and {@link GetEntriesOptions#filenameValidation}.
    */
   importZip(
     reader:
@@ -2978,6 +3046,24 @@ export class ZipDirectoryEntry extends ZipEntry {
   /**
    * 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}.
    *
+   * If an entry cannot be written, the original error is rethrown unmodified as an {@link EntryError},
+   * whose {@link EntryError#entryName} is the name of the entry that failed, relative to this entry.
+   *
+   * The export is not atomic and nothing is rolled back, because the target is merged into rather
+   * than replaced: a file that already existed cannot be restored once overwritten. On failure the
+   * target is left as follows, and {@link EntryError#exportedEntryNames} lists the files that
+   * completed:
+   * - files written before the failure are left in place, complete and valid;
+   * - a file whose write started but did not finish is left empty, because it is created before its
+   *   content is streamed; this includes the entry that failed and, with `concurrent`, every entry
+   *   cancelled alongside it;
+   * - files that already existed in the target keep their previous content unless they were
+   *   overwritten in full;
+   * - entries not started yet are missing, as are the directories that would have held them.
+   *
+   * Running the same export again is the supported way to recover, since directories are merged and
+   * files are overwritten.
+   *
    * @param directoryHandle The target `FileSystemDirectoryHandle` instance.
    * @param options The options.
    * @returns A promise resolving to the target `FileSystemDirectoryHandle` instance.
@@ -3038,6 +3124,11 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
   /**
    * `true` to write independent files concurrently instead of one after another.
    *
+   * When an entry fails, the entries still in flight are cancelled and the ones not started yet are
+   * skipped, so a failed export stops as early as it does when writing one file after another. An
+   * entry whose write has already been requested may still be created, because the File System
+   * Access API cannot cancel a pending `getFileHandle` or `getDirectoryHandle` call.
+   *
    * @defaultValue false
    */
   concurrent?: boolean;
@@ -3322,6 +3413,26 @@ export const ERR_AMBIGUOUS_ARCHIVE: string;
  * Encryption Specification, which is not supported.
  */
 export const ERR_ENCRYPTED_CENTRAL_DIRECTORY: string;
+/**
+ * Unsafe filename error
+ *
+ * @remarks Thrown when reading an archive containing an entry whose filename is rejected by
+ * {@link GetEntriesOptions#filenameValidation}. The thrown error carries the offending name in its `filename`
+ * property.
+ */
+export const ERR_UNSAFE_FILENAME: string;
+/**
+ * Invalid strictness error (thrown when the `strictness` option is not `"strict"`, `"balanced"` or `"tolerant"`)
+ */
+export const ERR_INVALID_STRICTNESS: string;
+/**
+ * Invalid filenameValidation error (thrown when the `filenameValidation` option is not `"strict"`, `"balanced"` or `"tolerant"`)
+ */
+export const ERR_INVALID_FILENAME_VALIDATION: string;
+/**
+ * Invalid maxAppendedDataSize error (thrown when the `maxAppendedDataSize` option is not a number greater than or equal to 0)
+ */
+export const ERR_INVALID_MAX_APPENDED_DATA_SIZE: string;
 /**
  * Iteration completed too soon error
  */
@@ -3374,6 +3485,17 @@ export const ERR_INVALID_MSDOS_ATTRIBUTES: string;
  * Invalid msdosAttributes error (thrown when the `msdosAttributes` option is not an object with boolean flags)
  */
 export const ERR_INVALID_MSDOS_DATA: string;
+/**
+ * Invalid level error (thrown when the `level` option is not an integer in the range 0..9)
+ */
+export const ERR_INVALID_LEVEL: string;
+/**
+ * Invalid password error (thrown when the `password` option is not a string, or the `rawPassword` option is not a `Uint8Array`)
+ *
+ * @remarks A value of another type would silently produce an unencrypted archive, and a `rawPassword` passed as a string
+ * would produce an archive that cannot be opened with the equivalent {@link ZipWriterConstructorOptions#password}.
+ */
+export const ERR_INVALID_PASSWORD_TYPE: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */

package/index.d.ts

@@ -1201,9 +1201,10 @@ export interface GetEntriesOptions {
    *
    * @param value The raw text value.
    * @param encoding The encoding of the text.
+   * @param type The type of the decoded text, `"filename"` or `"comment"`.
    * @returns The decoded text value or `undefined` if the raw text value should be decoded by zip.js.
    */
-  decodeText?(value: Uint8Array, encoding: string): string | undefined;
+  decodeText?(value: Uint8Array, encoding: string, type: "filename" | "comment"): string | undefined;
   /**
    * `true` to throw an {@link ERR_AMBIGUOUS_ARCHIVE} error when the archive could be parsed differently by other
    * tools. This detects data before or after the zip structure (e.g. a self-extracting archive stub or a
@@ -1237,6 +1238,42 @@ export interface GetEntriesOptions {
    * @defaultValue "balanced"
    */
   strictness?: "strict" | "balanced" | "tolerant";
+  /**
+   * How strictly the filename of each entry should be validated. A rejected name throws an
+   * {@link ERR_UNSAFE_FILENAME} error carrying the offending name in its `filename` property.
+   *
+   * - `"strict"`: reject the names rejected by `"balanced"`, plus the names that do not map cleanly to a file
+   * path, i.e. empty names and names containing a `"."` path component or an empty one (e.g. `"a//b.txt"`).
+   * - `"balanced"`: reject names that would escape the directory they are extracted into, i.e. names containing
+   * a `".."` path component, and absolute names, i.e. names starting with `"/"`, with a drive letter (e.g.
+   * `"C:/file.txt"`) or with two backslashes (UNC paths).
+   * - `"tolerant"`: never reject a name.
+   *
+   * A backslash is never interpreted as a path separator: it is a valid filename character on UNIX systems, and
+   * it also occurs as the trail byte of legitimate double-byte filenames (e.g. CP932) decoded with another
+   * charset.
+   *
+   * Names are validated, never rewritten, so the filename reported for an entry always matches its central
+   * directory record.
+   *
+   * @defaultValue The value of {@link GetEntriesOptions#strictness}.
+   */
+  filenameValidation?: "strict" | "balanced" | "tolerant";
+  /**
+   * The function called for normalizing the filename of each entry, e.g. to repair the names rejected by
+   * {@link GetEntriesOptions#filenameValidation}.
+   *
+   * It is called with the decoded filename, after {@link GetEntriesOptions#decodeText} and before the name is
+   * validated, so a name it fails to repair is still rejected. The returned name becomes the name of the entry:
+   * it is used to detect directory entries by their trailing `"/"`, and to detect duplicate filenames when
+   * {@link GetEntriesOptions#checkAmbiguity} is set, so two names normalized into the same name are reported as
+   * an {@link ERR_AMBIGUOUS_ARCHIVE} error instead of silently shadowing each other. The raw filename remains
+   * available in {@link EntryMetaData#rawFilename}.
+   *
+   * @param filename The decoded filename.
+   * @returns The normalized filename or `undefined` to keep the decoded filename.
+   */
+  normalizeFilename?(filename: string): string | undefined;
   /**
    * 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`
@@ -1613,6 +1650,27 @@ export interface EntryError extends Error {
    * The id of the related {@link ZipEntry} (filesystem API).
    */
   entryId?: number;
+  /**
+   * The name of the related {@link ZipEntry}, or of the related `FileSystemHandle` when importing
+   * one (filesystem API). Set by {@link ZipDirectoryEntry#addFileSystemHandle} and
+   * {@link ZipDirectoryEntry#exportFileSystemHandle}, which rethrow the original error rather than
+   * wrapping it, so its `message` stays comparable to the exported `ERR_*` constants.
+   */
+  entryName?: string;
+  /**
+   * The other entries that also failed, when {@link ZipDirectoryEntry#exportFileSystemHandle} runs
+   * with `concurrent` set to `true` and more than one entry fails (filesystem API). The error it is
+   * set on is not repeated in the list, and failures raised deeper in the tree are flattened into
+   * it, so the list holds every failure of the export except this one.
+   */
+  entryErrors?: EntryError[];
+  /**
+   * The names of the files {@link ZipDirectoryEntry#exportFileSystemHandle} finished writing before
+   * it failed, relative to the exported entry (filesystem API). Directories are not listed. Every
+   * other file of the export is either missing or empty, so this is the only way to tell a file the
+   * export completed from one it created but never filled.
+   */
+  exportedEntryNames?: string[];
 }
 /**
  * Represents the metadata of an entry in a zip file (Core API).
@@ -2497,9 +2555,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * The function called for encoding the filename and the comment of the entry.
    *
    * @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.
    */
-  encodeText?(text: string): Uint8Array | undefined;
+  encodeText?(text: string, type: "filename" | "comment"): Uint8Array | undefined;
 }
 
 /**
@@ -2867,6 +2926,10 @@ export class ZipDirectoryEntry extends ZipEntry {
   /**
    * Adds an entry with content provided via a `FileSystemHandle` instance
    *
+   * If a handle cannot be read, the original error is rethrown unmodified as an {@link EntryError},
+   * whose {@link EntryError#entryName} is the path of the handle that failed, relative to the parent
+   * of `fileSystemHandle`.
+   *
    * @param fileSystemHandle The `fileSystemHandle` instance.
    * @param options The options.
    * @returns A promise resolving to an array of {@link ZipFileEntry} or a {@link ZipDirectoryEntry} instances.
@@ -2930,6 +2993,11 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param reader The {@link Reader} instance.
    * @param options  The options.
+   *
+   * @remarks The filename of each entry is split into path components to build the tree of entries. Empty
+   * components and `"."` components are ignored, so `"a//b.txt"`, `"./a/b.txt"` and `"a/./b.txt"` all produce
+   * the same `"a/b.txt"` entry. Filenames are normalized and validated beforehand, see
+   * {@link GetEntriesOptions#normalizeFilename} and {@link GetEntriesOptions#filenameValidation}.
    */
   importZip(
     reader:
@@ -2978,6 +3046,24 @@ export class ZipDirectoryEntry extends ZipEntry {
   /**
    * 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}.
    *
+   * If an entry cannot be written, the original error is rethrown unmodified as an {@link EntryError},
+   * whose {@link EntryError#entryName} is the name of the entry that failed, relative to this entry.
+   *
+   * The export is not atomic and nothing is rolled back, because the target is merged into rather
+   * than replaced: a file that already existed cannot be restored once overwritten. On failure the
+   * target is left as follows, and {@link EntryError#exportedEntryNames} lists the files that
+   * completed:
+   * - files written before the failure are left in place, complete and valid;
+   * - a file whose write started but did not finish is left empty, because it is created before its
+   *   content is streamed; this includes the entry that failed and, with `concurrent`, every entry
+   *   cancelled alongside it;
+   * - files that already existed in the target keep their previous content unless they were
+   *   overwritten in full;
+   * - entries not started yet are missing, as are the directories that would have held them.
+   *
+   * Running the same export again is the supported way to recover, since directories are merged and
+   * files are overwritten.
+   *
    * @param directoryHandle The target `FileSystemDirectoryHandle` instance.
    * @param options The options.
    * @returns A promise resolving to the target `FileSystemDirectoryHandle` instance.
@@ -3038,6 +3124,11 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
   /**
    * `true` to write independent files concurrently instead of one after another.
    *
+   * When an entry fails, the entries still in flight are cancelled and the ones not started yet are
+   * skipped, so a failed export stops as early as it does when writing one file after another. An
+   * entry whose write has already been requested may still be created, because the File System
+   * Access API cannot cancel a pending `getFileHandle` or `getDirectoryHandle` call.
+   *
    * @defaultValue false
    */
   concurrent?: boolean;
@@ -3322,6 +3413,26 @@ export const ERR_AMBIGUOUS_ARCHIVE: string;
  * Encryption Specification, which is not supported.
  */
 export const ERR_ENCRYPTED_CENTRAL_DIRECTORY: string;
+/**
+ * Unsafe filename error
+ *
+ * @remarks Thrown when reading an archive containing an entry whose filename is rejected by
+ * {@link GetEntriesOptions#filenameValidation}. The thrown error carries the offending name in its `filename`
+ * property.
+ */
+export const ERR_UNSAFE_FILENAME: string;
+/**
+ * Invalid strictness error (thrown when the `strictness` option is not `"strict"`, `"balanced"` or `"tolerant"`)
+ */
+export const ERR_INVALID_STRICTNESS: string;
+/**
+ * Invalid filenameValidation error (thrown when the `filenameValidation` option is not `"strict"`, `"balanced"` or `"tolerant"`)
+ */
+export const ERR_INVALID_FILENAME_VALIDATION: string;
+/**
+ * Invalid maxAppendedDataSize error (thrown when the `maxAppendedDataSize` option is not a number greater than or equal to 0)
+ */
+export const ERR_INVALID_MAX_APPENDED_DATA_SIZE: string;
 /**
  * Iteration completed too soon error
  */
@@ -3374,6 +3485,17 @@ export const ERR_INVALID_MSDOS_ATTRIBUTES: string;
  * Invalid msdosAttributes error (thrown when the `msdosAttributes` option is not an object with boolean flags)
  */
 export const ERR_INVALID_MSDOS_DATA: string;
+/**
+ * Invalid level error (thrown when the `level` option is not an integer in the range 0..9)
+ */
+export const ERR_INVALID_LEVEL: string;
+/**
+ * Invalid password error (thrown when the `password` option is not a string, or the `rawPassword` option is not a `Uint8Array`)
+ *
+ * @remarks A value of another type would silently produce an unencrypted archive, and a `rawPassword` passed as a string
+ * would produce an archive that cannot be opened with the equivalent {@link ZipWriterConstructorOptions#password}.
+ */
+export const ERR_INVALID_PASSWORD_TYPE: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */