@zip.js/zip.js 2.13.0 → 2.14.0

package/index.d.cts

@@ -1043,7 +1043,13 @@ export interface HttpOptions extends HttpRangeOptions {
    */
   preventHeadRequest?: boolean;
   /**
-   * `true` to use `Range: bytes=-22` on the first request and cache the EOCD, make sure beforehand that the server supports a suffix range request.
+   * `true` to read the end of the archive with the same request that gives its size, and to serve the later reads
+   * landing in that range from the response instead of requesting them again, make sure beforehand that the server
+   * supports a suffix range request.
+   *
+   * The request asks for the last 65,557 bytes, which is how far back the reader scans for the end of central directory
+   * record, so it fetches nothing the reader was not going to read anyway. An archive shorter than that is fetched
+   * whole, and reading it then costs a single request.
    *
    * @defaultValue false
    */
@@ -1108,10 +1114,14 @@ export interface WritableWriter {
    */
   writable: WritableStream;
   /**
-   * The number of bytes written into the instance. It is set to 0 before the first write and
-   * updated as the data is written, so a writer needing the value (e.g. to compute the offset of a
-   * disk) can read it. A value set before the first write is kept and used as the starting offset
-   * instead of being reset to 0.
+   * The number of bytes written into the instance. It is set to 0 before the first write, and a value
+   * set beforehand is kept and used as the starting offset instead of being reset to 0.
+   *
+   * The bytes of a section are added once that section is written, so the value is settled between
+   * entries rather than after every chunk: an instance reading it from its own `write()` method sees
+   * the total of the sections already finished. The exception is an instance yielded by a generator of
+   * split disks, which is updated on each chunk written to it, so it can compute the offset of the disk
+   * it is filling.
    *
    * It must therefore be assignable, see {@link ERR_WRITER_SIZE_NOT_WRITABLE}: a getter with no setter
    * is rejected when the writer is passed, not once the first entry has been written.
@@ -2378,6 +2388,12 @@ export interface EntryError extends Error {
    * failure reason cannot carry it, which does not affect the salvage described in
    * {@link ZipWriter#close}: zip.js tracks the size of a failed entry on its own, so the offsets of
    * the entries written afterwards stay correct whatever the reason a stream was aborted with.
+   *
+   * When a stream is aborted or cancelled, the reason the caller passed is what reaches the caller
+   * back, unchanged and with its class and its own properties intact whether or not the codec ran in
+   * a worker, and this property is set on that object. So aborting with an error of your own leaves
+   * that error carrying an `outputSize` afterwards, and aborting with a value that cannot take a new
+   * property, e.g. a frozen error or a value that is not an object, simply leaves it unannotated.
    */
   outputSize?: number;
   /**
@@ -3492,7 +3508,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#bufferedWrite} option is set to `true`, or when the entry is a folder
    * or an empty entry stored without compression or encryption, since the header can then carry the sizes and
    * the CRC-32 directly. It will be automatically set to `true` when the
-   * {@link ZipWriterConstructorOptions#zipCrypto} option is set to `true`. Otherwise, the default value is `true`.
+   * {@link ZipWriterConstructorOptions#zipCrypto} option is set to `true`, except for such a folder or empty
+   * entry, which holds no encrypted data and therefore needs no descriptor either. Otherwise, the default
+   * value is `true`.
    */
   dataDescriptor?: boolean;
   /**
@@ -4197,6 +4215,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param blob The `Blob` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4204,12 +4225,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importBlob(
     blob: Blob,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided as a Data URI `string` encoded in Base64 into the entry
    *
    * @param dataURI The Data URI `string` encoded in Base64.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4217,12 +4241,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importData64URI(
     dataURI: string,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided as a `Uint8Array` instance into the entry
    *
    * @param array The `Uint8Array` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4230,12 +4257,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importUint8Array(
     array: Uint8Array,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file fetched from a URL into the entry
    *
    * @param url The URL.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4243,12 +4273,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importHttpContent(
     url: string,
     options?: ZipDirectoryEntryImportHttpOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided via a `ReadableStream` instance into the entry
    *
    * @param readable The `ReadableStream` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4260,13 +4293,16 @@ export class ZipDirectoryEntry extends ZipEntry {
   importReadable(
     readable: ReadableStream,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided via a custom {@link Reader} instance or a {@link ZipReader} instance into
    * the entry
    *
    * @param reader The {@link Reader} instance or the {@link ZipReader} instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @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
@@ -4296,7 +4332,7 @@ export class ZipDirectoryEntry extends ZipEntry {
       | ReadableStream[]
       | ZipReader<unknown>,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Returns a `Blob` instance containing a zip file of the entry and its descendants
    *
@@ -4472,6 +4508,16 @@ export interface ZipDirectoryEntryImportOptions
    * entry holding the node, which is the behavior of most zip tools. The entries that do not collide
    * are imported in both cases.
    *
+   * When both entries are directory records, `"keep-last"` replaces the record held by the node and keeps
+   * the entries already imported below it, which belong to the node rather than to either record. A
+   * directory record claiming a node created implicitly by the entries below it is not a collision, it is
+   * the record that node was missing.
+   *
+   * A file claiming a node already holding a directory is the one collision that also drops entries that
+   * did not collide: `"keep-last"` replaces the directory with the file, and the entries below it go with
+   * it, since a file node cannot hold them. `"keep-first"` keeps the directory and its entries and ignores
+   * the file instead, so the two policies are mirrors of each other for that shape.
+   *
    * @defaultValue "throw"
    */
   duplicates?: "throw" | "keep-first" | "keep-last";

package/index.d.ts

@@ -1043,7 +1043,13 @@ export interface HttpOptions extends HttpRangeOptions {
    */
   preventHeadRequest?: boolean;
   /**
-   * `true` to use `Range: bytes=-22` on the first request and cache the EOCD, make sure beforehand that the server supports a suffix range request.
+   * `true` to read the end of the archive with the same request that gives its size, and to serve the later reads
+   * landing in that range from the response instead of requesting them again, make sure beforehand that the server
+   * supports a suffix range request.
+   *
+   * The request asks for the last 65,557 bytes, which is how far back the reader scans for the end of central directory
+   * record, so it fetches nothing the reader was not going to read anyway. An archive shorter than that is fetched
+   * whole, and reading it then costs a single request.
    *
    * @defaultValue false
    */
@@ -1108,10 +1114,14 @@ export interface WritableWriter {
    */
   writable: WritableStream;
   /**
-   * The number of bytes written into the instance. It is set to 0 before the first write and
-   * updated as the data is written, so a writer needing the value (e.g. to compute the offset of a
-   * disk) can read it. A value set before the first write is kept and used as the starting offset
-   * instead of being reset to 0.
+   * The number of bytes written into the instance. It is set to 0 before the first write, and a value
+   * set beforehand is kept and used as the starting offset instead of being reset to 0.
+   *
+   * The bytes of a section are added once that section is written, so the value is settled between
+   * entries rather than after every chunk: an instance reading it from its own `write()` method sees
+   * the total of the sections already finished. The exception is an instance yielded by a generator of
+   * split disks, which is updated on each chunk written to it, so it can compute the offset of the disk
+   * it is filling.
    *
    * It must therefore be assignable, see {@link ERR_WRITER_SIZE_NOT_WRITABLE}: a getter with no setter
    * is rejected when the writer is passed, not once the first entry has been written.
@@ -2378,6 +2388,12 @@ export interface EntryError extends Error {
    * failure reason cannot carry it, which does not affect the salvage described in
    * {@link ZipWriter#close}: zip.js tracks the size of a failed entry on its own, so the offsets of
    * the entries written afterwards stay correct whatever the reason a stream was aborted with.
+   *
+   * When a stream is aborted or cancelled, the reason the caller passed is what reaches the caller
+   * back, unchanged and with its class and its own properties intact whether or not the codec ran in
+   * a worker, and this property is set on that object. So aborting with an error of your own leaves
+   * that error carrying an `outputSize` afterwards, and aborting with a value that cannot take a new
+   * property, e.g. a frozen error or a value that is not an object, simply leaves it unannotated.
    */
   outputSize?: number;
   /**
@@ -3492,7 +3508,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#bufferedWrite} option is set to `true`, or when the entry is a folder
    * or an empty entry stored without compression or encryption, since the header can then carry the sizes and
    * the CRC-32 directly. It will be automatically set to `true` when the
-   * {@link ZipWriterConstructorOptions#zipCrypto} option is set to `true`. Otherwise, the default value is `true`.
+   * {@link ZipWriterConstructorOptions#zipCrypto} option is set to `true`, except for such a folder or empty
+   * entry, which holds no encrypted data and therefore needs no descriptor either. Otherwise, the default
+   * value is `true`.
    */
   dataDescriptor?: boolean;
   /**
@@ -4197,6 +4215,9 @@ export class ZipDirectoryEntry extends ZipEntry {
    *
    * @param blob The `Blob` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4204,12 +4225,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importBlob(
     blob: Blob,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided as a Data URI `string` encoded in Base64 into the entry
    *
    * @param dataURI The Data URI `string` encoded in Base64.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4217,12 +4241,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importData64URI(
     dataURI: string,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided as a `Uint8Array` instance into the entry
    *
    * @param array The `Uint8Array` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4230,12 +4257,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importUint8Array(
     array: Uint8Array,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file fetched from a URL into the entry
    *
    * @param url The URL.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4243,12 +4273,15 @@ export class ZipDirectoryEntry extends ZipEntry {
   importHttpContent(
     url: string,
     options?: ZipDirectoryEntryImportHttpOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided via a `ReadableStream` instance into the entry
    *
    * @param readable The `ReadableStream` instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @remarks Use {@link ZipDirectoryEntry#importZip} with a {@link ZipReader} instance to read the data of the
    * zip file itself, e.g. its {@link ZipReader#prependedData} or its {@link ZipReader#comment} property.
@@ -4260,13 +4293,16 @@ export class ZipDirectoryEntry extends ZipEntry {
   importReadable(
     readable: ReadableStream,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Extracts a zip file provided via a custom {@link Reader} instance or a {@link ZipReader} instance into
    * the entry
    *
    * @param reader The {@link Reader} instance or the {@link ZipReader} instance.
    * @param options  The options.
+   * @returns A promise resolving to an array of the {@link ZipFileEntry} and {@link ZipDirectoryEntry}
+   * instances created by the import, which includes the directories created for the path components of
+   * the filenames.
    *
    * @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
@@ -4296,7 +4332,7 @@ export class ZipDirectoryEntry extends ZipEntry {
       | ReadableStream[]
       | ZipReader<unknown>,
     options?: ZipDirectoryEntryImportOptions
-  ): Promise<[ZipEntry]>;
+  ): Promise<ZipEntry[]>;
   /**
    * Returns a `Blob` instance containing a zip file of the entry and its descendants
    *
@@ -4472,6 +4508,16 @@ export interface ZipDirectoryEntryImportOptions
    * entry holding the node, which is the behavior of most zip tools. The entries that do not collide
    * are imported in both cases.
    *
+   * When both entries are directory records, `"keep-last"` replaces the record held by the node and keeps
+   * the entries already imported below it, which belong to the node rather than to either record. A
+   * directory record claiming a node created implicitly by the entries below it is not a collision, it is
+   * the record that node was missing.
+   *
+   * A file claiming a node already holding a directory is the one collision that also drops entries that
+   * did not collide: `"keep-last"` replaces the directory with the file, and the entries below it go with
+   * it, since a file node cannot hold them. `"keep-first"` keeps the directory and its entries and ignores
+   * the file instead, so the two policies are mirrors of each other for that shape.
+   *
    * @defaultValue "throw"
    */
   duplicates?: "throw" | "keep-first" | "keep-last";