API

The default output is a byte stream. The other modes are conveniences built on top of it: close() drives the same encoder and then wraps the result. The return type is inferred from the type argument, so TypeScript knows that new ZipWriter({ outputAs: "blob" }) resolves close() to a Blob.

"stream" (default)

ReadableStream<Uint8Array>. close() resolves immediately; bytes are pulled as the consumer reads.

"blob"

Blob. Ideal for object-URL downloads and FormData uploads.

"response"

A native Response whose body is the stream, tagged with mimeType.

"uint8array"

A single Uint8Array with the whole archive.

"arraybuffer"

The backing ArrayBuffer of that byte array.

// Stream straight into an upload without buffering the whole archive first.
const writer = new ZipWriter(); // default "stream"
const upload = fetch("/upload", { method: "POST", body: writer.output });
await writer.add({ path: "log.txt", data: bigLogBlob });
await writer.close();
await upload;

level sets the default DEFLATE effort for the writer; an individual entry may override it with its own level. The value must be an integer from 0 to 9, or a RangeError is thrown.

• level: 0, directory entries, and method: "store" are written uncompressed (ZIP method 0x0000).
• With no explicit method, JSZipp attempts DEFLATE but stores the entry instead when the compressed payload would be no smaller than the source.
• An explicit method: "deflate" always writes a DEFLATE entry (method 0x0008), even if that is slightly larger.

The ZIP compression-method field is per entry. A DEFLATE entry may still contain internal stored blocks for incompressible runs; that does not change the entry method from 0x0008 to 0x0000. ZIP metadata does not record the DEFLATE level, so a reader cannot report the level an archive was written with.

const writer = new ZipWriter({ level: 6 });

await writer.add({ path: "report.txt", data: text });               // DEFLATE or store fallback
await writer.add({ path: "already.png", data: png, method: "store" }); // never recompress
await writer.add({ path: "huge.log", data: log, level: 9 });        // override the writer level

ZIP64 records remove the classic 4 GiB / 65 535-entry ceilings. JSZipp implements ZIP64 framing itself rather than delegating to a ZIP dependency.

"auto" (default)

Emit ZIP64 records only when entry sizes, the entry count, or Central Directory placement exceed standard limits.

"force"

Always emit ZIP64 records.

"off"

Never emit ZIP64. If the archive would need it, close() throws a RangeError.

When ZIP64 is emitted, only the saturated 32-bit slots are carried in the extra field: the local header holds the uncompressed and compressed sizes (16 data bytes); the Central Directory header additionally carries the local-header offset (24 data bytes). 64-bit values beyond Number.MAX_SAFE_INTEGER are rejected.

Each entry's modifiedAt is written to the legacy DOS date/time fields as local wall-clock time. When timestamps includes TimestampMode.Unix (the default), the UTC mtime is also written to the Extended Timestamp extra field (0x5455) so timezone is preserved. Readers prefer 0x5455 and fall back to the DOS fields.

Pass a bitmask that ORs TimestampMode.Dos (1), TimestampMode.Unix (2), and TimestampMode.Ntfs (4). Values outside 0–7 are rejected.

Every ZIP entry already has a local file header before the file data and a Central Directory header near the end of the archive. The timestamp byte counts below are additional extra-field bytes written into those existing per-entry metadata locations; they do not include the base headers, filename bytes, comments, ZIP64 records, EOCD records, or compressed file data. In many-small-file archives this can make JSZipp's total larger than libraries that omit UTC timestamp extras, even when the compressed payloads are comparable.

TimestampMode.Unix writes a 9-byte 0x5455 record in both the local and central headers. TimestampMode.Ntfs writes a 36-byte 0x000a record in both headers for modification, access, and creation FILETIMEs. dosAttributes is rejected for Dos | Unix because a Unix-host archive carrying DOS attribute bits would confuse Unix-oriented tools.

For byte-identical (reproducible) archives, supply an explicit modifiedAt for every entry. When omitted it defaults to new Date() at write time, which is not reproducible.

const epoch = new Date("2020-01-01T00:00:00Z");
const writer = new ZipWriter({ outputAs: "uint8array" });
await writer.add({ path: "a.txt", data: "A", meta: { modifiedAt: epoch } });
await writer.add({ path: "b.txt", data: "B", meta: { modifiedAt: epoch } });
const bytes = await writer.close(); // byte-identical across runs

When true, each parent directory implied by an entry's path is written as a standalone entry. For example, a/b/c.txt also emits a/ and a/b/.

The default keeps the historical behavior: only caller-added directory entries are written. JSZipp never scans for empty directories; add those explicitly.

A writer runs in exactly one mode. add() / close() form the async mode and accept any supported data, including Blob and ReadableStream. writeSync() / closeSync() form the sync mode and accept only string, Uint8Array, and ArrayBuffer — values that can be read without awaiting.

Mixing the two would route some chunks to the stream and others to the sync buffer, silently dropping entries, so the second mode throws an InvalidStateError (DOMException). Re-using a closed writer also throws InvalidStateError.

// Sync path — no awaits, returns immediately.
const writer = new ZipWriter({ outputAs: "uint8array" });
writer.writeSync({ path: "a.txt", data: "A" });
writer.writeSync({ path: "b.txt", data: "B" });
const bytes = writer.closeSync(); // Uint8Array

// writer.add(...) here would throw InvalidStateError: modes cannot mix.

Before pathMode runs, writer paths are normalized: backslashes become /, leading / characters are stripped, and a path ending in / is treated as a directory entry. After normalization, writing the same normalized path twice is rejected with a SecurityError in every path mode.

await writer.add({ path: "docs\\guide.md", data: md }); // stored as docs/guide.md
await writer.add({ path: "/photos/", data: "" });       // directory entry "photos/"
// await writer.add({ path: "photos/" }) again -> SecurityError (duplicate)

JSZipp follows ZIP metadata first: if a valid Info-ZIP Unicode Path extra field (0x7075) is present and its embedded CRC-32 matches the header name bytes, its UTF-8 name is used; otherwise, if the ZIP UTF-8 flag is set, names decode as UTF-8. filenameEncoding only applies when the UTF-8 flag is absent, and the default fallback is "utf-8". It affects entry paths, entry comments, and the archive comment — never file contents.

It accepts "cp437", any charset label the runtime's TextDecoder supports, or a custom TextDecoder-shaped object:

// A built-in label:
const a = await openZip(file, { filenameEncoding: "shift_jis" });

// A custom decoder-shaped object:
const b = await openZip(file, {
  filenameEncoding: {
    encoding: "cp866",
    fatal: false,
    ignoreBOM: true,
    decode: (bytes) => iconv.decode(bytes, "cp866")
  }
});

These caps are for untrusted input. maxArchiveSize bounds the input byte length. maxEntrySize bounds each entry's decompressed size and is enforced during inflate (bounded reading), so a header that misreports its uncompressed size cannot expand past the cap. Breaching either throws a RangeError.

try {
  const zip = await openZip(untrusted, {
    maxArchiveSize: 20 * 1024 * 1024,
    maxEntrySize: 5 * 1024 * 1024
  });
} catch (err) {
  if (err instanceof RangeError) {
    // archive or an entry exceeded the configured limit
  }
}

openZip requires the Central Directory to be internally consistent: the number of records must equal the EOCD (or ZIP64 EOCD) entry count and must consume exactly the declared directory size, or parsing throws. The EOCD is chosen by content, so an EOCD-like sequence hidden in the archive comment, or a fake EOCD appended after a complete archive, cannot mask the real entries.

Each entry is also cross-checked against its local file header. A local/central filename mismatch, a disagreement in the security-relevant flag bits (encryption, data descriptor), and two central entries reusing the same local-header offset all throw. These checks do not affect archives whose local and central metadata agree.

Duplicate paths are preserved in append order; the default reader does not reject them. Encrypted entries and unsupported compression methods throw NotSupportedError.

modifiedAt, createdAt, and lastAccess must be valid Date values on or after the Unix epoch. modifiedAt defaults to write time when omitted.

When createdAt is supplied, neither modifiedAt nor lastAccess may be earlier than it; an inconsistent entry throws RangeError. When timestamps includes TimestampMode.Ntfs, omitted createdAt and lastAccess values each default to modifiedAt.

To set permissions, prefer unixPermissions over externalAttributes. Use three octal digits 0o000–0o777 (e.g. 0o644 or 0o755); file-type bits are added automatically. Out-of-range or non-integer values are rejected.

unixPermissions is accepted only when the timestamps mode includes TimestampMode.Unix (the default does); setting it without that flag throws RangeError. When an entry records a Unix store permission — via unixPermissions, a written Unix Extended Timestamp, or raw externalAttributes bits — its Central Directory header advertises the Unix host OS (3) in "version made by" so external tools apply those permissions; otherwise the DOS host (0) is used.

dosAttributes is the DOS-attribute counterpart: the MS-DOS attribute byte (0x00–0xff) written into the low 8 bits of the external attributes. The directory bit 0x10 encodes the file/folder distinction and must match the entry kind; a mismatch throws RangeError.

DOS attributes suit a DOS or NTFS host but would confuse Unix tools, so they are accepted for the Dos, Dos | Ntfs, and Dos | Unix | Ntfs modes and rejected when the Unix flag is set without the NTFS flag (Dos | Unix). With both Unix and Ntfs set, the external attributes carry the Unix mode (high 16 bits) and the DOS attributes (low byte) together. dosAttributes does not affect "version made by".

Caution: extraField and externalAttributes are unchecked manual overrides. JSZipp writes them as supplied and cannot detect every conflict with the entry kind or with the metadata it generates, so an inconsistent value can corrupt the archive.

extraField must contain raw, well-formed ZIP extra-field bytes (id(2)+size(2)+payload records). JSZipp writes those raw records before its own generated extras such as ZIP64, Extended Timestamp, and NTFS. It will not add a generated timestamp extra whose id already appears in the supplied bytes, so callers are responsible for emitting well-formed, non-conflicting records.

externalAttributes writes raw 32-bit external attributes verbatim (high 16 bits = Unix mode, low 8 bits = DOS attribute flags). It overrides unixPermissions and dosAttributes and is not reconciled with the entry's directory bit. Use it only to round-trip an exact value read from another archive.

On read, JSZipp exposes only the raw externalAttributes; derive the Unix mode with externalAttributes >>> 16 and the MS-DOS attribute byte with externalAttributes & 0xff.

Unsafe paths include .. segments, absolute paths, drive-letter paths (including drive-relative names like C:name), backslash-separated paths on read, and any path containing a NUL byte.

"strict" rejects these paths with SecurityError. "sanitize" strips unsafe components instead, but rejects the path if the result is empty.

This is an opt-in profile for archives crossing a trust boundary. Beyond strict per-path safety, it adds two cross-entry checks the default deliberately omits to preserve documented behavior:

• Local/central size cross-check. With general-purpose bit 3 clear, the local and central sizes must agree. Data-descriptor entries (bit 3 set) are exempt.
• Collision rejection. Entry paths that collide after Unicode (NFC) and case normalization are rejected — exact duplicates, case-only twins like Readme.txt / README.TXT, and NFC/NFD twins.

The default reader still preserves duplicate paths and defers size integrity to read time; only "strict-package" rejects them.