@zip.js/zip.js 2.18.1 → 2.19.0

package/index.d.cts

@@ -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
@@ -2240,8 +2247,8 @@ export interface LocalDataDescriptor {
    * `true` if the record is preceded by its optional signature.
    *
    * The signature is not part of the original format, it is a later convention writers are free to follow. It is
-   * reported as absent when the values following it disagree with the central directory, since the record is then
-   * read as starting at the first byte.
+   * `false` when the record is read as starting at its first byte, see {@link LocalDataDescriptor#zip64} for how the
+   * layout is chosen.
    */
   signature: boolean;
   /**
@@ -2251,9 +2258,10 @@ export interface LocalDataDescriptor {
    * sizes, and the Zip64 extra field of the central directory record, written last, describes that record, not the
    * descriptor, so e.g. an entry placed past 4 GB can carry a Zip64 extra field in its central directory record for
    * its offset alone and a descriptor with 4-byte sizes. The record is therefore read with the layout, among the two
-   * widths with and without the signature, whose values agree with the central directory; when none does, the width
-   * announced by the Zip64 extra field of the local file header or of the central directory record is used, without
-   * the signature.
+   * widths with and without the signature, whose sizes agree with the central directory, its CRC-32 too when the
+   * central directory stores one and several layouts qualify; when none does, the width announced by the Zip64 extra
+   * field of the local file header or of the central directory record is used, with the signature when the record
+   * starts with one.
    */
   zip64: boolean;
   /**
@@ -2377,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;
   /**
@@ -2746,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;
   /**
@@ -2784,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;
   /**
@@ -3648,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.

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
@@ -2240,8 +2247,8 @@ export interface LocalDataDescriptor {
    * `true` if the record is preceded by its optional signature.
    *
    * The signature is not part of the original format, it is a later convention writers are free to follow. It is
-   * reported as absent when the values following it disagree with the central directory, since the record is then
-   * read as starting at the first byte.
+   * `false` when the record is read as starting at its first byte, see {@link LocalDataDescriptor#zip64} for how the
+   * layout is chosen.
    */
   signature: boolean;
   /**
@@ -2251,9 +2258,10 @@ export interface LocalDataDescriptor {
    * sizes, and the Zip64 extra field of the central directory record, written last, describes that record, not the
    * descriptor, so e.g. an entry placed past 4 GB can carry a Zip64 extra field in its central directory record for
    * its offset alone and a descriptor with 4-byte sizes. The record is therefore read with the layout, among the two
-   * widths with and without the signature, whose values agree with the central directory; when none does, the width
-   * announced by the Zip64 extra field of the local file header or of the central directory record is used, without
-   * the signature.
+   * widths with and without the signature, whose sizes agree with the central directory, its CRC-32 too when the
+   * central directory stores one and several layouts qualify; when none does, the width announced by the Zip64 extra
+   * field of the local file header or of the central directory record is used, with the signature when the record
+   * starts with one.
    */
   zip64: boolean;
   /**
@@ -2377,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;
   /**
@@ -2746,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;
   /**
@@ -2784,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;
   /**
@@ -3648,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.