@zip.js/zip.js 2.18.2 → 2.19.0

package/index.d.ts

@@ -569,7 +569,11 @@ export interface Configuration extends WorkerConfiguration {
    * Values lower than 64 are raised to 64, and a value that is not an integer greater than 0 is replaced with the default
    * value.
    *
-   * @defaultValue 65536
+   * @remarks
+   * Every stage of the pipeline of an entry holds up to one chunk, and the data crosses the boundary of a web worker one
+   * chunk per message, so a larger value costs more memory per entry in progress and buys fewer messages.
+   *
+   * @defaultValue 262144
    */
   chunkSize?: number;
   /**
@@ -634,7 +638,8 @@ export interface WorkerConfiguration {
   /**
    * `true` to transfer stream ownership to web workers.
    *
-   * @defaultValue true
+   * @deprecated The option is ignored whatever its value: the data always crosses the worker boundary chunk by
+   * chunk, transferring the streams instead was slower on every engine measured.
    */
   transferStreams?: boolean;
 }
@@ -919,7 +924,7 @@ export class Reader<Type> implements Initializable, ReadableReader {
    */
   constructor(value: Type);
   /**
-   * The `ReadableStream` instance.
+   * The `ReadableStream` instance, a new one reading the data from its start on each access.
    */
   readable: ReadableStream;
   /**
@@ -1754,7 +1759,8 @@ export interface GetEntriesOptions {
    * another charset.
    *
    * Names are validated, never rewritten, so the filename reported for an entry always matches its central
-   * directory record.
+   * directory record. The name validated is the final one, i.e. the name of a valid Unicode Path extra field
+   * (see {@link EntryMetaData#extraFieldUnicodePath}) when the entry carries one.
    *
    * @defaultValue The value of {@link GetEntriesOptions#strictness}.
    */
@@ -1763,8 +1769,9 @@ export interface GetEntriesOptions {
    * 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 called with the decoded filename, after {@link GetEntriesOptions#decodeText} and after a valid Unicode
+   * Path extra field (see {@link EntryMetaData#extraFieldUnicodePath}) has replaced the name, 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
@@ -2378,13 +2385,13 @@ export interface LocalDirectory {
   extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
    * The Info-ZIP Unix type 2 extra field (0x7855). Its uid/gid are stored in the local file header only, the
-   * central directory version carries no data and merely flags their presence.
+   * central directory version carries no data and merely flags their presence. Its ids are used when the
+   * header holds no New Unix extra field (0x7875).
    */
   extraFieldUnix?: EntryExtraFieldUnix;
   /**
-   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It is read
-   * whenever the type 2 extra field (0x7855) is absent or carries no ids, which is its usual state in the
-   * central directory.
+   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It takes
+   * precedence over the type 2 extra field (0x7855) when a header carries both.
    */
   extraFieldInfoZip?: EntryExtraFieldUnix;
   /**
@@ -2747,13 +2754,13 @@ export interface EntryMetaData {
   extraFieldNTFS?: EntryExtraFieldNTFS;
   /**
    * The Info-ZIP Unix type 2 extra field (0x7855). Its uid/gid are stored in the local file header only, the
-   * central directory version carries no data and merely flags their presence.
+   * central directory version carries no data and merely flags their presence. Its ids are used when the
+   * header holds no New Unix extra field (0x7875).
    */
   extraFieldUnix?: EntryExtraFieldUnix;
   /**
-   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It is read
-   * whenever the type 2 extra field (0x7855) is absent or carries no ids, which is its usual state in the
-   * central directory.
+   * The Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid in both headers. It takes
+   * precedence over the type 2 extra field (0x7855) when a header carries both.
    */
   extraFieldInfoZip?: EntryExtraFieldUnix;
   /**
@@ -2785,8 +2792,8 @@ export interface EntryMetaData {
    *
    * The local file header is the only place where the Info-ZIP Unix extra fields type 1 (0x5855) and type 2
    * (0x7855) store the uid/gid, so this is where they are read for entries carrying just these fields, e.g.
-   * with `entry.localDirectory.extraFieldUnixType1.uid`. The values are not merged into
-   * {@link EntryMetaData#uid} and {@link EntryMetaData#gid}, which are read from the central directory.
+   * with `entry.localDirectory.extraFieldUnixType1.uid`. The values fill in {@link EntryMetaData#uid} and
+   * {@link EntryMetaData#gid} only when the central directory gave none, see {@link EntryMetaData#uid}.
    */
   localDirectory?: LocalDirectory;
   /**
@@ -3649,8 +3656,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * Which Unix extra field format to write when creating entries that include Unix metadata.
    * - "infozip": Info-ZIP New Unix extra field (0x7875), storing variable-length uid/gid up to 32 bits.
    * - "unix": Info-ZIP Unix extra field type 2 (0x7855), storing fixed 2-byte uid/gid (0..65535); a
-   *   larger uid or gid is rejected. The Unix mode is not part of this field; it is written to the
-   *   external file attributes.
+   *   larger uid or gid is rejected. The ids are written in the local file header only, the central
+   *   directory copy is empty as Info-ZIP specifies, so a reader working from the central directory,
+   *   {@link ZipReader} included, reports them once the entry data has been read. The Unix mode is not
+   *   part of this field; it is written to the external file attributes.
    *
    * When {@link ZipFS} exports imported entries, their uid/gid are re-emitted as "infozip" regardless
    * of the field type found in the imported zip file, unless this option is set explicitly.