@zip.js/zip.js 2.14.0 → 2.15.0

package/index.d.cts

@@ -1646,15 +1646,18 @@ 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.
+   * filename is always decoded as UTF-8. It is only read when the bit is not set. When the option is not
+   * set either, a filename holding bytes outside ASCII is decoded as UTF-8 if they form valid UTF-8, since
+   * many writers store UTF-8 without setting the bit (macOS Archive Utility, `ditto`, the macOS build of
+   * Info-ZIP `zip`, Java 6), and as IBM Code Page 437 otherwise. Set the option to decode such filenames
+   * as another legacy encoding instead.
    */
   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}.
+   * The option is ignored when the general purpose bit 11 is set in the header of the entry, and valid
+   * UTF-8 is detected when the option is not set, see {@link GetEntriesOptions#filenameEncoding}.
    */
   commentEncoding?: string;
   /**
@@ -1670,9 +1673,11 @@ export interface GetEntriesOptions {
    * `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
    * concatenated archive), central directory records not accounted for by the end of central directory record, an
-   * end of central directory record disagreeing with its zip64 counterpart, and duplicate filenames. When reading
-   * the content of an entry, it also validates the local file header against the central directory record (see
-   * {@link ZipReaderOptions#checkAmbiguity}).
+   * end of central directory record disagreeing with its zip64 counterpart, and duplicate filenames. Filenames are
+   * compared exactly, after {@link GetEntriesOptions#normalizeFilename}: two names differing only by letter case or
+   * by Unicode normalization form are distinct entries, even though they collide on a case-insensitive or
+   * normalizing filesystem. When reading the content of an entry, it also validates the local file header against
+   * the central directory record (see {@link ZipReaderOptions#checkAmbiguity}).
    *
    * This is the boolean form of {@link GetEntriesOptions#strictness}: `true` means `"strict"` and `false` means
    * any value but `"strict"`. When both options are set, the value passed to {@link ZipReader#getEntries} takes
@@ -1710,15 +1715,17 @@ export interface GetEntriesOptions {
    * {@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"`).
+   * path, i.e. empty names, names containing a `"."` path component or an empty one (e.g. `"a//b.txt"`), and
+   * names containing a NUL character.
    * - `"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).
+   * a `".."` path component delimited by slashes or by backslashes (e.g. `"..\\file.txt"`, which a Windows host
+   * resolves as a parent directory), and absolute names, i.e. names starting with `"/"`, with a drive letter
+   * (e.g. `"C:/file.txt"`) or with a backslash (root-relative and UNC paths on Windows).
    * - `"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.
+   * A backslash is otherwise not 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.

package/index.d.ts

@@ -1646,15 +1646,18 @@ 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.
+   * filename is always decoded as UTF-8. It is only read when the bit is not set. When the option is not
+   * set either, a filename holding bytes outside ASCII is decoded as UTF-8 if they form valid UTF-8, since
+   * many writers store UTF-8 without setting the bit (macOS Archive Utility, `ditto`, the macOS build of
+   * Info-ZIP `zip`, Java 6), and as IBM Code Page 437 otherwise. Set the option to decode such filenames
+   * as another legacy encoding instead.
    */
   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}.
+   * The option is ignored when the general purpose bit 11 is set in the header of the entry, and valid
+   * UTF-8 is detected when the option is not set, see {@link GetEntriesOptions#filenameEncoding}.
    */
   commentEncoding?: string;
   /**
@@ -1670,9 +1673,11 @@ export interface GetEntriesOptions {
    * `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
    * concatenated archive), central directory records not accounted for by the end of central directory record, an
-   * end of central directory record disagreeing with its zip64 counterpart, and duplicate filenames. When reading
-   * the content of an entry, it also validates the local file header against the central directory record (see
-   * {@link ZipReaderOptions#checkAmbiguity}).
+   * end of central directory record disagreeing with its zip64 counterpart, and duplicate filenames. Filenames are
+   * compared exactly, after {@link GetEntriesOptions#normalizeFilename}: two names differing only by letter case or
+   * by Unicode normalization form are distinct entries, even though they collide on a case-insensitive or
+   * normalizing filesystem. When reading the content of an entry, it also validates the local file header against
+   * the central directory record (see {@link ZipReaderOptions#checkAmbiguity}).
    *
    * This is the boolean form of {@link GetEntriesOptions#strictness}: `true` means `"strict"` and `false` means
    * any value but `"strict"`. When both options are set, the value passed to {@link ZipReader#getEntries} takes
@@ -1710,15 +1715,17 @@ export interface GetEntriesOptions {
    * {@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"`).
+   * path, i.e. empty names, names containing a `"."` path component or an empty one (e.g. `"a//b.txt"`), and
+   * names containing a NUL character.
    * - `"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).
+   * a `".."` path component delimited by slashes or by backslashes (e.g. `"..\\file.txt"`, which a Windows host
+   * resolves as a parent directory), and absolute names, i.e. names starting with `"/"`, with a drive letter
+   * (e.g. `"C:/file.txt"`) or with a backslash (root-relative and UNC paths on Windows).
    * - `"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.
+   * A backslash is otherwise not 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.