@zip.js/zip.js 2.8.57 → 2.8.58

package/index.d.cts

@@ -983,7 +983,8 @@ export interface WritableWriter {
   /**
    * 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.
+   * 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.
    */
   size?: number;
   /**
@@ -1280,6 +1281,13 @@ export class ZipReader<Type> {
   /**
    * Creates the instance
    *
+   * @remarks
+   * Reading a zip file requires random access because the central directory located at the end of the
+   * file is read first. A `ReadableStream` instance, or an object providing only a `readable` property
+   * (e.g. a file handle), is therefore buffered entirely in memory when the instance is initialized. To
+   * read a large seekable resource without buffering it, pass a custom {@link Reader} implementation
+   * that reads the requested byte ranges directly.
+   *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
    */
@@ -1957,6 +1965,12 @@ export interface LocalDirectory {
    * The length of the extra field in bytes.
    */
   extraFieldLength: number;
+  /**
+   * The byte offset of the entry data, i.e. {@link EntryMetaData#offset} plus the size of the local file header,
+   * of the filename and of the extra field. It can be used with {@link Reader#createReadable} to read the stored
+   * data directly, e.g. to serve ranged requests into an entry compressed with the `"store"` method.
+   */
+  dataOffset: number;
   /**
    * The extra field (raw).
    */
@@ -2316,9 +2330,6 @@ export interface EntryMetaData {
    * The upper 16-bit portion of {@link EntryMetaData#externalFileAttributes} when it represents Unix mode bits.
    */
   unixExternalUpper?: number;
-  /**
-   * The number of the disk where the entry data starts.
-   */
   /**
    * The internal file attribute (raw).
    * @deprecated Use {@link EntryMetaData#internalFileAttributes} instead.
@@ -2561,6 +2572,11 @@ export class ZipWriterStream {
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zipped file.
    *
+   * @remarks
+   * If an entry could not be written, this method aborts the zipped stream with the error — the
+   * readable side of the stream fails instead of ending — and throws it. The `entryErrors` property
+   * of the thrown error contains the errors of all the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2614,13 +2630,45 @@ export class ZipWriter<Type> {
    */
   readonly hasCorruptedEntries?: boolean;
 
+  /**
+   * Adds the entries of an existing zip file into the current zip. This method can be called at any
+   * time, including between calls to {@link ZipWriter#add} and repeatedly to merge several zip files.
+   *
+   * @remarks
+   * The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
+   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
+   * the disks of the output, which is a single zip file unless the writer is a split zip file writer. The data of
+   * the entries is copied as-is; in particular, the constraints set by {@link ZipWriterConstructorOptions#usdz}
+   * are not applied to the copied entries.
+   *
+   * Pending {@link ZipWriter#add} calls are completed before the data is copied, and add() calls made
+   * while the copy is in progress are written after it. If an entry of the zip file has the same
+   * filename as an entry of the current zip, the method throws with the `ERR_DUPLICATED_NAME` error
+   * message and leaves the current zip unchanged; call {@link ZipWriter#remove} beforehand to resolve
+   * the conflicts.
+   *
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the copy
+   * and throws its error if it was not caught.
+   *
+   * @param reader The {@link Reader} instance used to read the content of the zip file.
+   * @returns A promise resolving when the zip file has been added.
+   */
+  appendZip<ReaderType>(
+    reader:
+      | Reader<ReaderType>
+      | ReadableReader
+      | ReadableStream
+      | Reader<unknown>[]
+      | ReadableReader[]
+      | ReadableStream[]
+  ): Promise<void>;
+
   /**
    * Adds an existing zip file at the beginning of the current zip. This method
    * cannot be called after the first call to {@link ZipWriter#add}.
    *
-   * @remarks The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
-   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
-   * the disks of the output, which is a single zip file unless the writer is a split zip file writer.
+   * @deprecated Use {@link ZipWriter#appendZip} instead, which is equivalent when the zip file is
+   * empty and can also be called after entries have been added.
    *
    * @param reader The {@link Reader} instance used to read the content of the zip file.
    * @returns A promise resolving when the zip file has been added.
@@ -2638,6 +2686,10 @@ export class ZipWriter<Type> {
   /**
    * Adds an entry into the zip file
    *
+   * @remarks
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the entry
+   * and throws its error if it was not caught.
+   *
    * @param filename The filename of the entry. Paths must use forward slashes ("/") as separator,
    * as required by section 4.4.17.1 of the zip specification. The value is stored as-is; in
    * particular, Windows path separators ("\\") are not converted and become part of the filename,
@@ -2674,6 +2726,14 @@ export class ZipWriter<Type> {
    * The global comment is passed as raw bytes and the comment of an entry
    * ({@link ZipWriterAddDataOptions#comment}) as a string on purpose, see {@link ZipReader#comment}.
    *
+   * If {@link ZipWriter#add} or {@link ZipWriter#appendZip} calls failed and their rejection was
+   * never handled — e.g. the returned promise was not awaited — this method throws the first of
+   * these errors instead of finalizing the zip file. The `entryErrors` property of the thrown error
+   * contains all of them. Errors already caught by the caller do not resurface here, so entries can
+   * still be skipped by awaiting {@link ZipWriter#add} and catching the error. Throwing the errors
+   * counts as reporting them: catching the error of this method and calling it again finalizes the
+   * zip file without the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2874,6 +2934,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * @defaultValue The current date.
    */
   lastModDate?: Date;
+  /**
+   * The last modification date, as its raw 32-bit MS-DOS date and time value.
+   *
+   * @remarks
+   * The value is written verbatim into the local and central directory headers and takes precedence over
+   * {@link ZipWriterConstructorOptions#lastModDate}, which still fills the extended timestamp and NTFS extra
+   * fields. The filesystem API sets it when exporting entries with {@link ZipReaderOptions#passThrough} set in
+   * {@link ZipDirectoryEntryExportOptions#readerOptions}, so that the entries copied as-is keep the exact date
+   * and time of the source zip file.
+   */
+  rawLastModDate?: number;
   /**
    * The last access date.
    *
@@ -2920,7 +2991,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   zipCrypto?: boolean;
   /**
-   * The "Version" field.
+   * The "Version" field, i.e. the minimum version needed to extract the entry.
+   *
+   * @defaultValue the minimum version required by the features of the entry: 10 for entries stored without
+   * compression or encryption, 20 for deflated, folder or ZipCrypto-encrypted entries, raised to 45 for Zip64
+   * entries and 51 for AES-encrypted entries.
    */
   version?: number;
   /**
@@ -2942,7 +3017,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * `true` to mark the file names as UTF-8 setting the general purpose bit 11 in the header (see Appendix D -
    * Language Encoding (EFS)), `false` to mark the names as compliant with the original IBM Code Page 437.
    *
-   * Note that this does not ensure that the file names are in the correct encoding.
+   * Note that this option only sets the flag, it does not ensure that the file names are in the correct
+   * encoding: when it is set to `false`, the names are still encoded in UTF-8 unless the
+   * {@link ZipWriterConstructorOptions#encodeText} option is also set to encode them in the intended code page.
    *
    * @defaultValue true
    */
@@ -2973,6 +3050,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#msdosAttributesRaw} or {@link ZipWriterConstructorOptions#msdosAttributes}
    * turns it on, overriding an explicit `false`.
    *
+   * MS-DOS era extractors, e.g. PKUNZIP 2.04g, only honor the directory attribute of entries declaring the
+   * MS-DOS platform. Without this option, they extract folder entries as zero-length files, which can then
+   * prevent extracting the files stored below the folders.
+   *
    * @defaultValue false
    */
   msDosCompatible?: boolean;
@@ -3093,6 +3174,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterAddDataOptions#compressionMethod} options are set explicitly. Setting the
    * {@link ZipWriterConstructorOptions#password} option throws an {@link ERR_UNSUPPORTED_ENCRYPTION_USDZ} error.
    *
+   * These constraints apply to the entries written with {@link ZipWriter#add} only. The entries copied with
+   * {@link ZipWriter#appendZip} keep the layout of the source zip file and are not checked, so appending a
+   * zip file that does not comply with the USDZ specification, or appending it when the size of the output
+   * is not a multiple of 64 bytes, silently produces a non-compliant file.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3110,6 +3196,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#encrypted} option is set to `true` to declare that the data is already
    * encrypted. In that case the password encrypts the other entries only, and the data written as-is keeps the
    * password it was encrypted with, which is not verified.
+   *
+   * When the data was encrypted with ZipCrypto, the verification byte stored in the encrypted data depends on
+   * the last modification date of the source entry if the data descriptor is used. The
+   * {@link ZipWriterConstructorOptions#dataDescriptor} and {@link ZipWriterConstructorOptions#rawLastModDate}
+   * values of the source entry must then be forwarded, otherwise reading the copied entry fails with an
+   * {@link ERR_INVALID_PASSWORD} error. The filesystem API forwards them when exporting entries and throws an
+   * {@link ERR_ZIP_CRYPTO_LAST_MOD_DATE} error if the date is overridden.
    */
   passThrough?: boolean;
   /**
@@ -4426,6 +4519,17 @@ export const ERR_INVALID_PASS_THROUGH: string;
  * unknown property of a `readerOptions` object is still ignored, as everywhere else in the API.
  */
 export const ERR_INVALID_READER_OPTIONS: string;
+/**
+ * Locked last modification date error (thrown by `{@link ZipDirectoryEntry}#export*()` and
+ * {@link ZipDirectoryEntry#getExportedSize} when the date of an entry encrypted with ZipCrypto and exported with
+ * {@link ZipReaderOptions#passThrough} set in {@link ZipDirectoryEntryExportOptions#readerOptions} is changed)
+ *
+ * @remarks The ZipCrypto encryption header embeds a password verification byte derived from the time of the
+ * entry: the encrypted data, copied as-is, only decrypts when the time in the rewritten headers still matches.
+ * The error is thrown when the new date would prevent the entry from being decrypted; changes which keep the
+ * verification byte intact, e.g. a change of the day only, are written normally.
+ */
+export const ERR_ZIP_CRYPTO_LAST_MOD_DATE: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */

package/index.d.ts

@@ -983,7 +983,8 @@ export interface WritableWriter {
   /**
    * 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.
+   * 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.
    */
   size?: number;
   /**
@@ -1280,6 +1281,13 @@ export class ZipReader<Type> {
   /**
    * Creates the instance
    *
+   * @remarks
+   * Reading a zip file requires random access because the central directory located at the end of the
+   * file is read first. A `ReadableStream` instance, or an object providing only a `readable` property
+   * (e.g. a file handle), is therefore buffered entirely in memory when the instance is initialized. To
+   * read a large seekable resource without buffering it, pass a custom {@link Reader} implementation
+   * that reads the requested byte ranges directly.
+   *
    * @param reader The {@link Reader} instance used to read data.
    * @param options The options.
    */
@@ -1957,6 +1965,12 @@ export interface LocalDirectory {
    * The length of the extra field in bytes.
    */
   extraFieldLength: number;
+  /**
+   * The byte offset of the entry data, i.e. {@link EntryMetaData#offset} plus the size of the local file header,
+   * of the filename and of the extra field. It can be used with {@link Reader#createReadable} to read the stored
+   * data directly, e.g. to serve ranged requests into an entry compressed with the `"store"` method.
+   */
+  dataOffset: number;
   /**
    * The extra field (raw).
    */
@@ -2316,9 +2330,6 @@ export interface EntryMetaData {
    * The upper 16-bit portion of {@link EntryMetaData#externalFileAttributes} when it represents Unix mode bits.
    */
   unixExternalUpper?: number;
-  /**
-   * The number of the disk where the entry data starts.
-   */
   /**
    * The internal file attribute (raw).
    * @deprecated Use {@link EntryMetaData#internalFileAttributes} instead.
@@ -2561,6 +2572,11 @@ export class ZipWriterStream {
   /**
    * Writes the entries directory, writes the global comment, and returns the content of the zipped file.
    *
+   * @remarks
+   * If an entry could not be written, this method aborts the zipped stream with the error — the
+   * readable side of the stream fails instead of ending — and throws it. The `entryErrors` property
+   * of the thrown error contains the errors of all the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2614,13 +2630,45 @@ export class ZipWriter<Type> {
    */
   readonly hasCorruptedEntries?: boolean;
 
+  /**
+   * Adds the entries of an existing zip file into the current zip. This method can be called at any
+   * time, including between calls to {@link ZipWriter#add} and repeatedly to merge several zip files.
+   *
+   * @remarks
+   * The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
+   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
+   * the disks of the output, which is a single zip file unless the writer is a split zip file writer. The data of
+   * the entries is copied as-is; in particular, the constraints set by {@link ZipWriterConstructorOptions#usdz}
+   * are not applied to the copied entries.
+   *
+   * Pending {@link ZipWriter#add} calls are completed before the data is copied, and add() calls made
+   * while the copy is in progress are written after it. If an entry of the zip file has the same
+   * filename as an entry of the current zip, the method throws with the `ERR_DUPLICATED_NAME` error
+   * message and leaves the current zip unchanged; call {@link ZipWriter#remove} beforehand to resolve
+   * the conflicts.
+   *
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the copy
+   * and throws its error if it was not caught.
+   *
+   * @param reader The {@link Reader} instance used to read the content of the zip file.
+   * @returns A promise resolving when the zip file has been added.
+   */
+  appendZip<ReaderType>(
+    reader:
+      | Reader<ReaderType>
+      | ReadableReader
+      | ReadableStream
+      | Reader<unknown>[]
+      | ReadableReader[]
+      | ReadableStream[]
+  ): Promise<void>;
+
   /**
    * Adds an existing zip file at the beginning of the current zip. This method
    * cannot be called after the first call to {@link ZipWriter#add}.
    *
-   * @remarks The data of the zip file is copied, its central directory is rebuilt and its entries are relocated to
-   * the positions they get in the output. The disks of a split zip file passed as input are therefore unrelated to
-   * the disks of the output, which is a single zip file unless the writer is a split zip file writer.
+   * @deprecated Use {@link ZipWriter#appendZip} instead, which is equivalent when the zip file is
+   * empty and can also be called after entries have been added.
    *
    * @param reader The {@link Reader} instance used to read the content of the zip file.
    * @returns A promise resolving when the zip file has been added.
@@ -2638,6 +2686,10 @@ export class ZipWriter<Type> {
   /**
    * Adds an entry into the zip file
    *
+   * @remarks
+   * The returned promise can safely be left un-awaited: {@link ZipWriter#close} waits for the entry
+   * and throws its error if it was not caught.
+   *
    * @param filename The filename of the entry. Paths must use forward slashes ("/") as separator,
    * as required by section 4.4.17.1 of the zip specification. The value is stored as-is; in
    * particular, Windows path separators ("\\") are not converted and become part of the filename,
@@ -2674,6 +2726,14 @@ export class ZipWriter<Type> {
    * The global comment is passed as raw bytes and the comment of an entry
    * ({@link ZipWriterAddDataOptions#comment}) as a string on purpose, see {@link ZipReader#comment}.
    *
+   * If {@link ZipWriter#add} or {@link ZipWriter#appendZip} calls failed and their rejection was
+   * never handled — e.g. the returned promise was not awaited — this method throws the first of
+   * these errors instead of finalizing the zip file. The `entryErrors` property of the thrown error
+   * contains all of them. Errors already caught by the caller do not resurface here, so entries can
+   * still be skipped by awaiting {@link ZipWriter#add} and catching the error. Throwing the errors
+   * counts as reporting them: catching the error of this method and calling it again finalizes the
+   * zip file without the failed entries.
+   *
    * @param comment The global comment of the zip file.
    * @param options The options.
    * @returns The content of the zip file.
@@ -2874,6 +2934,17 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * @defaultValue The current date.
    */
   lastModDate?: Date;
+  /**
+   * The last modification date, as its raw 32-bit MS-DOS date and time value.
+   *
+   * @remarks
+   * The value is written verbatim into the local and central directory headers and takes precedence over
+   * {@link ZipWriterConstructorOptions#lastModDate}, which still fills the extended timestamp and NTFS extra
+   * fields. The filesystem API sets it when exporting entries with {@link ZipReaderOptions#passThrough} set in
+   * {@link ZipDirectoryEntryExportOptions#readerOptions}, so that the entries copied as-is keep the exact date
+   * and time of the source zip file.
+   */
+  rawLastModDate?: number;
   /**
    * The last access date.
    *
@@ -2920,7 +2991,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    */
   zipCrypto?: boolean;
   /**
-   * The "Version" field.
+   * The "Version" field, i.e. the minimum version needed to extract the entry.
+   *
+   * @defaultValue the minimum version required by the features of the entry: 10 for entries stored without
+   * compression or encryption, 20 for deflated, folder or ZipCrypto-encrypted entries, raised to 45 for Zip64
+   * entries and 51 for AES-encrypted entries.
    */
   version?: number;
   /**
@@ -2942,7 +3017,9 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * `true` to mark the file names as UTF-8 setting the general purpose bit 11 in the header (see Appendix D -
    * Language Encoding (EFS)), `false` to mark the names as compliant with the original IBM Code Page 437.
    *
-   * Note that this does not ensure that the file names are in the correct encoding.
+   * Note that this option only sets the flag, it does not ensure that the file names are in the correct
+   * encoding: when it is set to `false`, the names are still encoded in UTF-8 unless the
+   * {@link ZipWriterConstructorOptions#encodeText} option is also set to encode them in the intended code page.
    *
    * @defaultValue true
    */
@@ -2973,6 +3050,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#msdosAttributesRaw} or {@link ZipWriterConstructorOptions#msdosAttributes}
    * turns it on, overriding an explicit `false`.
    *
+   * MS-DOS era extractors, e.g. PKUNZIP 2.04g, only honor the directory attribute of entries declaring the
+   * MS-DOS platform. Without this option, they extract folder entries as zero-length files, which can then
+   * prevent extracting the files stored below the folders.
+   *
    * @defaultValue false
    */
   msDosCompatible?: boolean;
@@ -3093,6 +3174,11 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterAddDataOptions#compressionMethod} options are set explicitly. Setting the
    * {@link ZipWriterConstructorOptions#password} option throws an {@link ERR_UNSUPPORTED_ENCRYPTION_USDZ} error.
    *
+   * These constraints apply to the entries written with {@link ZipWriter#add} only. The entries copied with
+   * {@link ZipWriter#appendZip} keep the layout of the source zip file and are not checked, so appending a
+   * zip file that does not comply with the USDZ specification, or appending it when the size of the output
+   * is not a multiple of 64 bytes, silently produces a non-compliant file.
+   *
    * @defaultValue false
    */
   usdz?: boolean;
@@ -3110,6 +3196,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * {@link ZipWriterConstructorOptions#encrypted} option is set to `true` to declare that the data is already
    * encrypted. In that case the password encrypts the other entries only, and the data written as-is keeps the
    * password it was encrypted with, which is not verified.
+   *
+   * When the data was encrypted with ZipCrypto, the verification byte stored in the encrypted data depends on
+   * the last modification date of the source entry if the data descriptor is used. The
+   * {@link ZipWriterConstructorOptions#dataDescriptor} and {@link ZipWriterConstructorOptions#rawLastModDate}
+   * values of the source entry must then be forwarded, otherwise reading the copied entry fails with an
+   * {@link ERR_INVALID_PASSWORD} error. The filesystem API forwards them when exporting entries and throws an
+   * {@link ERR_ZIP_CRYPTO_LAST_MOD_DATE} error if the date is overridden.
    */
   passThrough?: boolean;
   /**
@@ -4426,6 +4519,17 @@ export const ERR_INVALID_PASS_THROUGH: string;
  * unknown property of a `readerOptions` object is still ignored, as everywhere else in the API.
  */
 export const ERR_INVALID_READER_OPTIONS: string;
+/**
+ * Locked last modification date error (thrown by `{@link ZipDirectoryEntry}#export*()` and
+ * {@link ZipDirectoryEntry#getExportedSize} when the date of an entry encrypted with ZipCrypto and exported with
+ * {@link ZipReaderOptions#passThrough} set in {@link ZipDirectoryEntryExportOptions#readerOptions} is changed)
+ *
+ * @remarks The ZipCrypto encryption header embeds a password verification byte derived from the time of the
+ * entry: the encrypted data, copied as-is, only decrypts when the time in the rewritten headers still matches.
+ * The error is thrown when the new date would prevent the entry from being decrypted; changes which keep the
+ * verification byte intact, e.g. a change of the day only, are written normally.
+ */
+export const ERR_ZIP_CRYPTO_LAST_MOD_DATE: string;
 /**
  * Entry already exists error (thrown by the filesystem API when adding an entry whose filename already exists)
  */