Interface ZipWriterConstructorOptions

Represents options passed to the constructor of ZipWriter, ZipWriter#add and {@link ZipDirectoryEntry}#export*.

interface ZipWriterConstructorOptions {
    bufferedWrite?: boolean;
    compressionMethod?: number;
    createTempStream?: () => TempStream | Promise<TempStream>;
    creationDate?: Date;
    dataDescriptor?: boolean;
    dataDescriptorSignature?: boolean;
    encrypted?: boolean;
    encryptionStrength?: 2 | 1 | 3;
    extendedTimestamp?: boolean;
    externalFileAttributes?: number;
    gid?: number;
    internalFileAttributes?: number;
    keepOrder?: boolean;
    lastAccessDate?: Date;
    lastModDate?: Date;
    level?: number;
    msdosAttributes?: {
        archive?: boolean;
        directory?: boolean;
        hidden?: boolean;
        readOnly?: boolean;
        system?: boolean;
    };
    msdosAttributesRaw?: number;
    msDosCompatible?: boolean;
    ntfsTimestamp?: boolean;
    offset?: number;
    passThrough?: boolean;
    password?: string;
    preventClose?: boolean;
    rawLastModDate?: number;
    rawPassword?: Uint8Array<ArrayBufferLike>;
    setgid?: boolean;
    setuid?: boolean;
    signal?: AbortSignal;
    sticky?: boolean;
    supportZip64SplitFile?: boolean;
    transferStreams?: boolean;
    uid?: number;
    unixExtraFieldType?: "infozip" | "unix";
    unixMode?: number;
    usdz?: boolean;
    useCompressionStream?: boolean;
    useUnicodeFileNames?: boolean;
    useWebWorkers?: boolean;
    version?: number;
    versionMadeBy?: number;
    zip64?: boolean;
    zipCrypto?: boolean;
    encodeText?(
        text: string,
        type: "filename" | "comment",
    ): Uint8Array<ArrayBufferLike> | undefined;
}

Hierarchy (View Summary)

WorkerConfiguration
- ZipWriterConstructorOptions
  - ZipWriterAddDataOptions
  - ZipDirectoryEntryExportOptions

Properties

`Optional`bufferedWrite

bufferedWrite?: boolean

true to write entry data in a buffer before appending it to the zip file.

bufferedWrite is automatically set to true when compressing more than one entry in parallel.

Default Value

false

`Optional`compressionMethod

compressionMethod?: number

The compression method (e.g. 8 for DEFLATE, 0 for STORE).

`Optional`createTempStream

createTempStream?: () => TempStream | Promise<TempStream>

An async factory function that returns a TransformStream-like object ({ writable, readable }) used as a temporary buffer when entries are written in parallel.

When provided, this replaces the default in-memory TransformStream buffer, allowing data to be stored externally (e.g. filesystem, OPFS, network). The writable side receives compressed entry data. The readable side is consumed when the entry is replayed into the final zip stream. The optional dispose method is called once the entry has been processed (on success, error, or abort) so a resource-backed buffer can release its resource.

See createOPFSTempStream for a ready-made OPFS-backed implementation, createSyncAccessHandleTempStream for a faster worker-only variant, and createBlobTempStream for a Blob-backed one.

Remarks

The readable side is consumed only once the writable side has been closed, since the local header written before it holds the size and the CRC-32 of the entry. The object must therefore be able to hold a whole entry, either by buffering it like the default new TransformStream(undefined, undefined, { highWaterMark: Infinity }) does, or by draining it like the three implementations above do. A factory returning new TransformStream() deadlocks instead, its default queuing strategy holding a single chunk.

`Optional`creationDate

creationDate?: Date

The creation date.

This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.

Unlike ZipWriterConstructorOptions#lastModDate, it has no default: the date is written only when the option is set, so that the entries do not carry a meaningless creation time.

`Optional`dataDescriptor

dataDescriptor?: boolean

true to add a data descriptor.

When set to false, the ZipWriterConstructorOptions#bufferedWrite option will automatically be set to true. It will be automatically set to false when it is undefined and the 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 ZipWriterConstructorOptions#zipCrypto option is set to true. Otherwise, the default value is true.

`Optional`dataDescriptorSignature

dataDescriptorSignature?: boolean

true to add the signature of the data descriptor.

Default Value

true

`Optional`encrypted

encrypted?: boolean

true to write encrypted data when passThrough is set to true.

`Optional`encryptionStrength

encryptionStrength?: 2 | 1 | 3

The encryption strength (AES):

1: 128-bit encryption key
2: 192-bit encryption key
3: 256-bit encryption key

Default Value

`Optional`extendedTimestamp

extendedTimestamp?: boolean

true to store extended timestamp extra fields.

When set to false, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds, dates being truncated to the whole second and odd seconds rounded up to the next even second.

Default Value

true

`Optional`externalFileAttributes

externalFileAttributes?: number

The external file attribute.

When set explicitly, the value is written verbatim (including 0), unless unixMode, setuid, setgid or sticky is also set, in which case these options override the upper 16 bits while the lower 16 bits are preserved. When omitted, the value is derived from the other options (e.g. the MS-DOS directory attribute for folder entries, Unix default permissions when msDosCompatible is false).

`Optional`gid

gid?: number

The Unix group id to write in the Unix extra field or as part of the external attributes.

`Optional`internalFileAttributes

internalFileAttributes?: number

The internal file attribute.

Default Value

`Optional`keepOrder

keepOrder?: boolean

true to keep the order of the entry physically in the zip file.

Remarks

The entries are then written one after another, so concurrent calls to ZipWriter#add compress one entry at a time and use a single web worker. Set ZipWriterConstructorOptions#bufferedWrite to true to compress them concurrently while still keeping the order, at the cost of buffering each entry until the previous ones are written.

Default Value

true

`Optional`lastAccessDate

lastAccessDate?: Date

The last access date.

This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.

Unlike ZipWriterConstructorOptions#lastModDate, it has no default: the date is written only when the option is set, so that the entries do not carry a meaningless access time.

`Optional`lastModDate

lastModDate?: Date

The last modification date.

Remarks

This option and the two below must be Date instances: a timestamp expressed in milliseconds, e.g. File#lastModified, and an invalid Date are both rejected with ERR_INVALID_DATE. An invalid Date used to be written as an entry carrying no timestamp at all.

Default Value

The current date.

`Optional`level

level?: number

The level of compression.

The minimum value is 0 and means that no compression is applied. The maximum value is 9.

The native API CompressionStream does not support compression levels. Any value other than 6, its de facto level, disables useCompressionStream and compresses the data with the embedded implementation instead. Note that the compressed data produced at a given level can still vary between platforms. Set useCompressionStream to false to get deterministic output across platforms.

Default Value

`Optional`msdosAttributes

msdosAttributes?: {
    archive?: boolean;
    directory?: boolean;
    hidden?: boolean;
    readOnly?: boolean;
    system?: boolean;
}

When provided, MS-DOS attribute flags (boolean object) to write into external file attributes low byte.

Remarks

See ZipWriterConstructorOptions#msdosAttributesRaw for the platform this option selects and for the Unix metadata it leaves out of the entry.

`Optional`msdosAttributesRaw

msdosAttributesRaw?: number

When provided, the low 8-bit MS-DOS attributes to write into external file attributes. Must be an integer between 0 and 255.

Remarks

Setting this option or ZipWriterConstructorOptions#msdosAttributes selects the MS-DOS platform for the entry exactly as ZipWriterConstructorOptions#msDosCompatible does, and overrides that option when it is explicitly set to false. EntryMetaData#versionMadeBy then loses its Unix upper byte and no Unix mode is written, so the 0o100644 of a file entry and the 0o040755 of a folder entry are lost. What counts is that the option is provided, not its value: 0 and {} trigger it too.

Setting any Unix metadata option, i.e. ZipWriterConstructorOptions#uid, ZipWriterConstructorOptions#gid, ZipWriterConstructorOptions#unixMode, ZipWriterConstructorOptions#unixExtraFieldType or ZipWriterAddDataOptions#executable, takes precedence and keeps the Unix attributes, with the MS-DOS attributes written into the low byte. ZipWriterConstructorOptions#externalFileAttributes is preserved as well, although the entry still declares the MS-DOS platform.

`Optional`msDosCompatible

msDosCompatible?: boolean

true to write EntryMetaData#externalFileAttributes in MS-DOS format for folder entries.

It also selects the MS-DOS platform for ZipWriterConstructorOptions#versionMadeBy and leaves the Unix attributes out of the entries. Setting any Unix metadata option, e.g. ZipWriterConstructorOptions#unixMode or ZipWriterAddDataOptions#executable, turns it back off, and setting ZipWriterConstructorOptions#msdosAttributesRaw or 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.

Default Value

false

`Optional`ntfsTimestamp

ntfsTimestamp?: boolean

true to always store the NTFS extra field, false to never store it.

By default, the NTFS extra field is stored only when it preserves information the extended timestamp extra field cannot represent: a last modification date outside its supported range, or explicit ZipWriterConstructorOptions#lastAccessDate or ZipWriterConstructorOptions#creationDate values.

This option is ignored if the ZipWriterConstructorOptions#extendedTimestamp option is set to false.

`Optional`offset

offset?: number

The offset of the first entry in the zip file.

Remarks

When the option is undefined, the offset is the number of bytes already written into the destination, read from its size property, see WritableWriter#size. A size property set on a WritableStream instance passed directly to the ZipWriter constructor is also read, for backward compatibility. When the option is set, the bytes between the size of the destination and the offset are assumed to exist in the final zip file without being written, e.g. when writing one part of a zip file assembled by the caller.

The option is only read when the ZipWriter is created, e.g. by ZipDirectoryEntry#exportZip; a value passed to ZipWriter#add is ignored.

`Optional`passThrough

passThrough?: boolean

true to write the data as-is without compressing it and without crypting it.

Remarks

The data is never compressed, so the ZipWriterConstructorOptions#level option does not apply and is ignored. The ZipWriterAddDataOptions#compressionMethod option selects no codec either, it declares how the data is already compressed and is written as-is in the entry headers. It must be set, otherwise an ERR_UNDEFINED_COMPRESSION_METHOD error is thrown. The entries with no content, e.g. the directories, ignore this option entirely. Setting the ZipWriterConstructorOptions#password or the ZipWriterConstructorOptions#rawPassword option throws an ERR_UNSUPPORTED_ENCRYPTION_PASS_THROUGH error, unless the 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 ZipWriterConstructorOptions#dataDescriptor and ZipWriterConstructorOptions#rawLastModDate values of the source entry must then be forwarded, otherwise reading the copied entry fails with an ERR_INVALID_PASSWORD error. The filesystem API forwards them when exporting entries and throws an ERR_ZIP_CRYPTO_LAST_MOD_DATE error if the date is overridden.

`Optional`password

password?: string

The password used to encrypt the content of the entry.

Remarks

When a password is set and the ZipWriterConstructorOptions#zipCrypto option is not set to true, the entry is encrypted in AES AE-2 format: the CRC-32 checksum of the content is stored as 0 so that the zip file reveals no information about the encrypted content. A stored checksum would allow an attacker to verify guessed content without knowing the password. The integrity of the data is guaranteed by the authentication code instead.

`Optional`preventClose

preventClose?: boolean

true to prevent closing of WritableWriter#writable.

Default Value

false

`Optional`rawLastModDate

rawLastModDate?: number

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 ZipWriterConstructorOptions#lastModDate, which still fills the extended timestamp and NTFS extra fields. The filesystem API sets it when exporting entries with ZipReaderOptions#passThrough set in ZipDirectoryEntryExportOptions#readerOptions, so that the entries copied as-is keep the exact date and time of the source zip file.

`Optional`rawPassword

rawPassword?: Uint8Array<ArrayBufferLike>

The password used to encrypt the content of the entry (raw).

`Optional`setgid

setgid?: boolean

true to set the setgid bit when writing the Unix mode.

`Optional`setuid

setuid?: boolean

true to set the setuid bit when writing the Unix mode.

`Optional`signal

signal?: AbortSignal

The AbortSignal instance used to cancel the compression.

`Optional`sticky

sticky?: boolean

true to set the sticky bit when writing the Unix mode.

`Optional`supportZip64SplitFile

supportZip64SplitFile?: boolean

false to never write disk numbers in zip64 data.

Default Value

true

`Optional`transferStreams

transferStreams?: boolean

true to transfer stream ownership to web workers.

Default Value

true

`Optional`uid

uid?: number

The Unix owner id to write in the Unix extra field or as part of the external attributes.

`Optional`unixExtraFieldType

unixExtraFieldType?: "infozip" | "unix"

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.

When 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.

`Optional`unixMode

unixMode?: number

The Unix mode (st_mode bits) to use when writing external attributes.

The value includes the Unix file type, so it is also how a symbolic link is written: pass 0o120777 and use the path of the link target as the content of the entry. Extractors that support symbolic links, e.g. Info-ZIP unzip, then restore the entry as a link.

A folder entry is always written with S_IFDIR (0o040000), replacing any file type carried by the value, so the same mode can be set once on the writer and reused for every entry. Any other entry keeps the file type it is given, and is written with S_IFREG (0o100000) when the value carries none. Set ZipWriterConstructorOptions#externalFileAttributes instead to write a mode with no file type.

`Optional`usdz

usdz?: boolean

trueto produce zip files compatible with the USDZ specification: the data of the entries is aligned on 64-byte boundaries and stored uncompressed unless the ZipWriterConstructorOptions#level or ZipWriterAddDataOptions#compressionMethod options are set explicitly. Setting the ZipWriterConstructorOptions#password option throws an ERR_UNSUPPORTED_ENCRYPTION_USDZ error.

These constraints apply to the entries written with ZipWriter#add only. The entries copied with 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.

The option is only read when the ZipWriter is created; a value passed to ZipWriter#add is ignored.

Default Value

false

`Optional`useCompressionStream

useCompressionStream?: boolean

true to use the native API CompressionStream/DecompressionStream to compress/decompress data.

When compressing, the native API is only used when level is undefined or equal to 6, see ZipWriterConstructorOptions#level.

Default Value

true

`Optional`useUnicodeFileNames

useUnicodeFileNames?: boolean

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 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 ZipWriterConstructorOptions#encodeText option is also set to encode them in the intended code page. Setting it to false alone therefore produces an archive whose file names are mislabeled, holding UTF-8 bytes announced as Code Page 437: the names holding characters outside of ASCII are decoded incorrectly by the readers honoring the flag, including ZipReader unless GetEntriesOptions#filenameEncoding is set to "utf-8".

Default Value

true

`Optional`useWebWorkers

useWebWorkers?: boolean

true to use web workers to compress/decompress data in non-blocking background processes.

Default Value

true

`Optional`version

version?: number

The "Version" field, i.e. the minimum version needed to extract the entry.

Default Value

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.

`Optional`versionMadeBy

versionMadeBy?: number

The "Version made by" field, whose upper byte is the platform and lower byte the version of the specification.

The platform is not taken from the value passed here. It is forced to Unix (3) when the entry carries Unix metadata, i.e. when ZipWriterConstructorOptions#uid, ZipWriterConstructorOptions#gid, ZipWriterConstructorOptions#unixMode or ZipWriterConstructorOptions#unixExtraFieldType is set, since Unix mode bits stored under another platform are ignored by the extractors. It is forced to MS-DOS (0) when ZipWriterConstructorOptions#msdosAttributes or ZipWriterConstructorOptions#msdosAttributesRaw is set. Only the lower byte of the value survives in both cases.

Default Value

768, i.e. 3 << 8, or 20 when ZipWriterConstructorOptions#msDosCompatible is set to true

`Optional`zip64

zip64?: boolean

true to use Zip64 to store the entry.

zip64 is automatically set to true when necessary (e.g. compressed data larger than 4GB or with unknown size).

Default Value

false

`Optional`zipCrypto

zipCrypto?: boolean

true to use the ZipCrypto algorithm to encrypt the content of the entry. Setting it to true will also set the ZipWriterConstructorOptions#dataDescriptor to true.

It is not recommended to set zipCrypto to true because the ZipCrypto encryption can be easily broken.

Default Value

false

Methods

`Optional`encodeText

encodeText?(
text: string,
type: "filename" | "comment",
): Uint8Array<ArrayBufferLike> | undefined
The function called for encoding the filename and the comment of the entry.

zip.js encodes them in UTF-8 when the option is not set, so it must be set to write them in another code page, together with ZipWriterConstructorOptions#useUnicodeFileNames set to false to announce them as Code Page 437 instead of UTF-8.
Parameters
- text: string
  The text to encode.
- type: "filename" | "comment"
  The type of the encoded text, "filename" or "comment".
Returns Uint8Array<ArrayBufferLike> | undefined
The encoded text or undefined if the text should be encoded by zip.js.
- Defined in index.d.ts:3462

Interface ZipWriterConstructorOptions

Hierarchy (View Summary)

Index

Properties

Methods

Properties

OptionalbufferedWrite

Default Value

OptionalcompressionMethod

OptionalcreateTempStream

Remarks

OptionalcreationDate

OptionaldataDescriptor

OptionaldataDescriptorSignature

Default Value

Optionalencrypted

OptionalencryptionStrength

Default Value

OptionalextendedTimestamp

Default Value

OptionalexternalFileAttributes

Optionalgid

OptionalinternalFileAttributes

Default Value

OptionalkeepOrder

Remarks

Default Value

OptionallastAccessDate

OptionallastModDate

Remarks

Default Value

Optionallevel

Default Value

OptionalmsdosAttributes

Remarks

OptionalmsdosAttributesRaw

Remarks

OptionalmsDosCompatible

Default Value

OptionalntfsTimestamp

Optionaloffset

Remarks

OptionalpassThrough

Remarks

Optionalpassword

Remarks

OptionalpreventClose

Default Value

OptionalrawLastModDate

Remarks

OptionalrawPassword

Optionalsetgid

Optionalsetuid

Optionalsignal

Optionalsticky

OptionalsupportZip64SplitFile

Default Value

OptionaltransferStreams

Default Value

Optionaluid

OptionalunixExtraFieldType

OptionalunixMode

Optionalusdz

Default Value

OptionaluseCompressionStream

Default Value

OptionaluseUnicodeFileNames

Default Value

OptionaluseWebWorkers

Default Value

Optionalversion

Default Value

OptionalversionMadeBy

Default Value

Optionalzip64

Default Value

OptionalzipCrypto

Default Value

Methods

OptionalencodeText

`Optional`bufferedWrite

`Optional`compressionMethod

`Optional`createTempStream

`Optional`creationDate

`Optional`dataDescriptor

`Optional`dataDescriptorSignature

`Optional`encrypted

`Optional`encryptionStrength

`Optional`extendedTimestamp

`Optional`externalFileAttributes

`Optional`gid

`Optional`internalFileAttributes

`Optional`keepOrder

`Optional`lastAccessDate

`Optional`lastModDate

`Optional`level

`Optional`msdosAttributes

`Optional`msdosAttributesRaw

`Optional`msDosCompatible

`Optional`ntfsTimestamp

`Optional`offset

`Optional`passThrough

`Optional`password

`Optional`preventClose

`Optional`rawLastModDate

`Optional`rawPassword

`Optional`setgid

`Optional`setuid

`Optional`signal

`Optional`sticky

`Optional`supportZip64SplitFile

`Optional`transferStreams

`Optional`uid

`Optional`unixExtraFieldType

`Optional`unixMode

`Optional`usdz

`Optional`useCompressionStream

`Optional`useUnicodeFileNames

`Optional`useWebWorkers

`Optional`version

`Optional`versionMadeBy

`Optional`zip64

`Optional`zipCrypto

`Optional`encodeText