zip-writer 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test)",
+      "Bash(mkdir:*)",
+      "Bash(npm run test:e2e:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium firefox
+
+      - name: Install Playwright webkit (macOS only)
+        if: runner.os == 'macOS'
+        run: npx playwright install --with-deps webkit
+
+      - name: Run tests
+        run: npm test

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm test

package/eslint.config.mjs

@@ -0,0 +1,9 @@
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    languageOptions: { globals: { ...globals.browser, ...globals.node } },
+  },
+]);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "zip-writer",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "run-s test:types test:lint test:e2e",
+    "prepare": "husky",
+    "test:types": "tsc --noEmit",
+    "test:lint": "eslint .",
+    "test:e2e": "vitest",
+    "prepack": "tsc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@types/yauzl-promise": "^4.0.1",
+    "@vitest/browser": "^4.0.7",
+    "@vitest/browser-playwright": "^4.0.7",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.6",
+    "npm-run-all": "^4.1.5",
+    "playwright": "^1.56.1",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.7",
+    "yauzl-promise": "^4.0.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,31 @@
+// ZIP format constants (stored in file byte order)
+export const LOCAL_FILE_HEADER_SIGNATURE = 0x504b0304; // "PK\x03\x04"
+export const DATA_DESCRIPTOR_SIGNATURE = 0x504b0708; // "PK\x07\x08"
+export const CENTRAL_DIRECTORY_SIGNATURE = 0x504b0102; // "PK\x01\x02"
+export const END_OF_CENTRAL_DIR_SIGNATURE = 0x504b0506; // "PK\x05\x06"
+export const ZIP64_END_OF_CENTRAL_DIR_SIGNATURE = 0x504b0606; // "PK\x06\x06"
+export const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIGNATURE = 0x504b0607; // "PK\x06\x07"
+
+// Version constants
+export const VERSION_MADE_BY = 45; // Version 4.5 (ZIP64 support)
+export const VERSION_NEEDED_STANDARD = 20; // Version 2.0
+export const VERSION_NEEDED_ZIP64 = 45; // Version 4.5 for ZIP64
+
+// Flags
+export const GENERAL_PURPOSE_FLAGS = 0b0000_1000_0000_1000; // Bit 3: data descriptor, Bit 11: UTF-8
+
+// Compression methods
+export const COMPRESSION_METHOD_STORE = 0;
+export const COMPRESSION_METHOD_DEFLATE = 8;
+
+// Size constants
+export const LOCAL_FILE_HEADER_SIZE = 30;
+export const CENTRAL_DIRECTORY_HEADER_SIZE = 46;
+export const DATA_DESCRIPTOR_SIZE = 16;
+export const DATA_DESCRIPTOR_SIZE_ZIP64 = 24;
+export const EOCD_SIZE = 22;
+export const EOCD64_SIZE = 56;
+export const EOCD64_LOCATOR_SIZE = 20;
+
+// Limits
+export const ZIP64_LIMIT = BigInt(0xffffffff);

package/src/crc-lookup.ts

@@ -0,0 +1,27 @@
+/**
+ * From https://github.com/holepunchto/crc-universal/blob/main/lookup.js
+ * Licensed under Apache-2.0
+ */
+
+export const lookup = new Array(16) as Uint32Array<ArrayBuffer>[];
+
+for (let i = 0; i < 16; i++) {
+  lookup[i] = new Uint32Array(0x100);
+}
+
+for (let i = 0; i <= 0xff; i++) {
+  let crc = i;
+
+  for (let j = 0; j < 8; j++) {
+    crc = (crc >>> 1) ^ ((crc & 1) * 0xedb88320);
+  }
+
+  lookup[0][i] = crc;
+}
+
+for (let i = 0; i <= 0xff; i++) {
+  for (let j = 1; j < 16; j++) {
+    lookup[j][i] =
+      (lookup[j - 1][i] >>> 8) ^ lookup[0][lookup[j - 1][i] & 0xff];
+  }
+}

package/src/crc.ts

@@ -0,0 +1,70 @@
+/**
+ * The JavaScript implementation of CRC32 is a version of the slice-by-16 algorithm
+ * as implemented by Stephan Brumme, see https://github.com/stbrumme/crc32.
+ *
+ * Copyright (c) 2011-2016 Stephan Brumme
+ *
+ * This software is provided 'as-is', without any express or implied warranty.
+ * In no event will the authors be held liable for any damages arising from the
+ * use of this software.
+ *
+ * Permission is granted to anyone to use this software for any purpose,
+ * including commercial applications, and to alter it and redistribute it freely,
+ * subject to the following restrictions:
+ *
+ * 1. The origin of this software must not be misrepresented; you must not claim
+ *    that you wrote the original software.
+ *    If you use this software in a product, an acknowledgment in the product
+ *    documentation would be appreciated but is not required.
+ * 2. Altered source versions must be plainly marked as such, and must not be
+ *    misrepresented as being the original software.
+ * 3. This notice may not be removed or altered from any source distribution.
+ */
+
+import { lookup } from "./crc-lookup.js";
+
+/**
+ * Computes a 32-bit Cyclic Redundancy Check checksum of data. If value is
+ * specified, it is used as the starting value of the checksum, otherwise, 0 is
+ * used as the starting value.
+ *
+ * @param data - The input data to compute the checksum for.
+ * @param value -  An optional starting value. It must be a 32-bit unsigned integer. Default: 0
+ * @returns The computed CRC32 checksum.
+ */
+export function crc32(
+  data: Uint8Array<ArrayBuffer>,
+  value: number = 0
+): number {
+  let crc = ~value;
+  let i = 0;
+  let length = data.byteLength;
+
+  while (length >= 16) {
+    crc =
+      lookup[15][data[i++] ^ (crc & 0xff)] ^
+      lookup[14][data[i++] ^ ((crc >>> 8) & 0xff)] ^
+      lookup[13][data[i++] ^ ((crc >>> 16) & 0xff)] ^
+      lookup[12][data[i++] ^ (crc >>> 24)] ^
+      lookup[11][data[i++]] ^
+      lookup[10][data[i++]] ^
+      lookup[9][data[i++]] ^
+      lookup[8][data[i++]] ^
+      lookup[7][data[i++]] ^
+      lookup[6][data[i++]] ^
+      lookup[5][data[i++]] ^
+      lookup[4][data[i++]] ^
+      lookup[3][data[i++]] ^
+      lookup[2][data[i++]] ^
+      lookup[1][data[i++]] ^
+      lookup[0][data[i++]];
+
+    length -= 16;
+  }
+
+  while (length-- > 0) {
+    crc = (crc >>> 8) ^ lookup[0][(crc & 0xff) ^ data[i++]];
+  }
+
+  return ~crc >>> 0;
+}

package/src/index.ts

@@ -0,0 +1,342 @@
+import { writeZipEntry } from "./write-entry.js";
+import {
+  getCDFH,
+  getEOCDZip64,
+  getEOCDStandard,
+} from "./write-central-directory.js";
+import { ZIP64_LIMIT } from "./constants.js";
+import { noop } from "./utils.js";
+
+const BUFFER_SIZE = 16 * 1024; // 16 KB
+const bufferedQueue = new ByteLengthQueuingStrategy({
+  highWaterMark: BUFFER_SIZE,
+});
+const unbufferedQueue = { highWaterMark: 0 };
+
+export interface EntryOptions {
+  /** Entry name including internal path */
+  name: string;
+  /** Entry comment */
+  comment?: string;
+  /** Entry date */
+  date?: Date;
+  /** Entry permissions */
+  mode?: number;
+  /** Compression method to `STORE` (defaults to `DEFLATE`) */
+  store?: boolean;
+}
+
+export interface EntryInfoZip64 extends EntryOptions {
+  /** Byte offset of the local file header within the ZIP archive */
+  startOffset: bigint;
+  /** CRC32 checksum of the uncompressed data */
+  crc32: number;
+  /** Uncompressed size in bytes */
+  uncompressedSize: bigint;
+  /** Compressed size in bytes */
+  compressedSize: bigint;
+  /** Entry information is in ZIP64 format */
+  zip64: true;
+}
+
+export type EntryInfoStandard = {
+  [K in keyof EntryInfoZip64]: EntryInfoZip64[K] extends bigint
+    ? number
+    : K extends "zip64"
+      ? false
+      : EntryInfoZip64[K];
+};
+
+export type EntryInfo = EntryInfoZip64 | EntryInfoStandard;
+
+export class ZipWriter<TIsZip64 extends boolean = false> {
+  #offset = BigInt(0);
+  #zipStream = new TransformStream(
+    {
+      transform: (chunk, controller) => {
+        controller.enqueue(chunk);
+        this.#offset += BigInt(chunk.byteLength);
+      },
+    },
+    // Unbuffered on the writable side, we already queue entries
+    unbufferedQueue,
+    // Readable buffer, so that temporary delays on writable consumers don't
+    // block the zip writing.
+    bufferedQueue
+  );
+  #entries: EntryInfo[] = [];
+  #queued: Promise<unknown> = Promise.resolve();
+  #entryCount = 0;
+  #finalized = false;
+
+  get readable() {
+    return this.#zipStream.readable;
+  }
+
+  get entries(): ReadonlyArray<Readonly<EntryInfo>> {
+    return this.#entries;
+  }
+
+  /**
+   * Wait until all currently queued entries have been written.
+   */
+  async onceQueueEmpty(): Promise<void> {
+    while (this.#entries.length < this.#entryCount) {
+      await this.#queued;
+    }
+  }
+
+  /**
+   * Create a new entry in the Zip archive. Use the returned
+   * entryWriter.writable to write data to the entry. You can await
+   * entryWriter.entry() to get the entry info once all data has been written.
+   *
+   * @example
+   * ```ts
+   * const response = await fetch(imageUrl);
+   * response.body!.pipeTo(
+   *   zipWriter.entry({ name: "path/to/file.png" }).writable
+   * );
+   * ```
+   *
+   * @example
+   * ```ts
+   * const entryWriter = zipWriter.entry({ name: "hello.txt" });
+   * const writer = entryWriter.writable.getWriter();
+   * await writer.write(
+   *   new TextEncoder().encode("Hello, World!")
+   * );
+   * await writer.close();
+   * console.log(await entryWriter.entry()); // Entry info
+   * ```
+   *
+   * @param options Entry options
+   */
+  entry(options: EntryOptions) {
+    if (this.#finalized) {
+      throw new TypeError("Cannot add entry after finalize() has been called");
+    }
+    this.#entryCount++;
+
+    // Capture the previous queue position
+    const prevQueued = this.#queued;
+
+    // Create a promise that will be resolved when this entry completes
+    let entryDone: () => void;
+    let entryError: (reason: unknown) => void;
+    this.#queued = new Promise<void>((resolve, reject) => {
+      entryDone = resolve;
+      entryError = reject;
+    });
+    // prevent unhandled rejection, but we still want this.#queued to reject
+    // when awaited if there's an error
+    this.#queued.catch(noop);
+
+    return new EntryWriter(async (readable) => {
+      // Wait for previous entry to complete
+      await prevQueued;
+
+      const writer = this.#zipStream.writable.getWriter();
+      const reader = readable.getReader();
+      try {
+        const entryInfo = await writeZipEntry({
+          writer,
+          reader,
+          entryOptions: options,
+          startOffset: this.#offset,
+        });
+        this.#entries.push(entryInfo);
+        entryDone();
+        return entryInfo;
+      } catch (err) {
+        entryError(err);
+        await reader.cancel(err);
+        // Abort the zip stream - it's corrupted after a partial entry write
+        this.#zipStream.writable.abort(err);
+        // Don't call entryDone() - leave subsequent entries waiting forever
+        // since the zip stream is corrupted
+        // This error is handled in the EntryWriter constructor, and used to
+        // abort the entry writable stream
+        throw err;
+      } finally {
+        reader.releaseLock();
+        writer.releaseLock();
+      }
+    });
+  }
+
+  /**
+   * Set the entries of the Zip archive. This can be used to reorder,
+   * remove, or rename entries before finalizing the archive.
+   *
+   * @param entries New entries array
+   */
+  setEntries(entries: ReadonlyArray<Readonly<EntryInfo>>) {
+    const currentEntriesByOffset = new Map<bigint, EntryInfo>();
+    for (const entry of this.#entries) {
+      currentEntriesByOffset.set(BigInt(entry.startOffset), entry);
+    }
+    // Entries can't have their offset, crc32, compressed size, or uncompressed
+    // size changed, but they can be removed, reordered, or have the name and
+    // comment changed.
+    for (const entry of entries) {
+      const existingEntry = currentEntriesByOffset.get(
+        BigInt(entry.startOffset)
+      );
+      if (!existingEntry) {
+        throw new Error(
+          `Cannot set entries: entry at offset ${entry.startOffset} does not exist`
+        );
+      }
+      if (existingEntry.crc32 !== entry.crc32) {
+        throw new Error(
+          `Cannot set entries: entry at offset ${entry.startOffset} has different CRC32`
+        );
+      }
+      if (existingEntry.uncompressedSize !== entry.uncompressedSize) {
+        throw new Error(
+          `Cannot set entries: entry at offset ${entry.startOffset} has different uncompressed size`
+        );
+      }
+      if (existingEntry.compressedSize !== entry.compressedSize) {
+        throw new Error(
+          `Cannot set entries: entry at offset ${entry.startOffset} has different compressed size`
+        );
+      }
+    }
+    this.#entries = entries.map((entry) => ({ ...entry }));
+  }
+
+  async finalize(): Promise<{
+    /** Does the archive use ZIP64 format? */
+    zip64: boolean;
+    /** Total uncompressed size of all entries */
+    uncompressedEntriesSize: bigint;
+    /** Total compressed size of all entries */
+    compressedEntriesSize: bigint;
+    /** Total size of the ZIP file */
+    fileSize: bigint;
+  }> {
+    if (this.#finalized) {
+      throw new TypeError("finalize() has already been called");
+    }
+    this.#finalized = true;
+
+    // We do this as an IIFE to avoid an unhandled error, so that a user can
+    // call finalize() without needing to await and catch an error. Any error
+    // will be propagated to the stream output, but the user can optionally
+    // await finalize() to also see the error.
+    const finalizePromise = (async () => {
+      await this.onceQueueEmpty();
+
+      // Write central directory headers for all entries
+      const centralDirectoryStart = this.#offset;
+      const writer = this.#zipStream.writable.getWriter();
+
+      try {
+        let entryUsesZip64 = false;
+        let uncompressedEntriesSize = BigInt(0);
+        let compressedEntriesSize = BigInt(0);
+        for (const entry of this.#entries) {
+          if (entry.zip64) {
+            entryUsesZip64 = true;
+          }
+          uncompressedEntriesSize += BigInt(entry.uncompressedSize);
+          compressedEntriesSize += BigInt(entry.compressedSize);
+          await writer.write(getCDFH(entry));
+        }
+
+        const centralDirectorySize = this.#offset - centralDirectoryStart;
+
+        // Determine if the archive needs ZIP64 based on entries or central directory
+        const eocdNeedsZip64 =
+          this.#entries.length > 0xffff ||
+          centralDirectoryStart > ZIP64_LIMIT ||
+          centralDirectorySize > ZIP64_LIMIT;
+
+        let eocd: Uint8Array<ArrayBuffer>;
+        if (eocdNeedsZip64) {
+          eocd = getEOCDZip64(
+            BigInt(this.#entries.length),
+            centralDirectoryStart,
+            centralDirectorySize
+          );
+        } else {
+          eocd = getEOCDStandard(
+            this.#entries.length,
+            Number(centralDirectoryStart),
+            Number(centralDirectorySize)
+          );
+        }
+
+        await writer.write(eocd);
+
+        // Close the zip stream
+        await writer.close();
+
+        return {
+          zip64: eocdNeedsZip64 || entryUsesZip64,
+          uncompressedEntriesSize,
+          compressedEntriesSize,
+          fileSize: this.#offset,
+        };
+      } catch (err) {
+        await writer.abort(err);
+        throw err;
+      } finally {
+        writer.releaseLock();
+      }
+    })();
+    finalizePromise.catch(noop); // prevent unhandled rejection
+    return finalizePromise;
+  }
+}
+
+class EntryWriter {
+  // Unbuffered stream to directly pipe to the zip writer
+  #entryStream = new TransformStream(
+    undefined,
+    unbufferedQueue,
+    unbufferedQueue
+  );
+  #written: Promise<EntryInfo>;
+
+  /**
+   * @param enqueueAndPipe Function that enqueues the entry data readable, pipes it to the Zip stream, and returns a promise that resolves to the entry info once done.
+   */
+  constructor(
+    enqueueAndPipe: (
+      readable: ReadableStream<Uint8Array<ArrayBuffer>>
+    ) => Promise<EntryInfo>
+  ) {
+    // We could try to pass the zipstream writable to EntryWriter, but then
+    // EntryWriter would not know when the entry has finished writing, and would
+    // not have a way to get the entry info.
+    this.#written = enqueueAndPipe(this.#entryStream.readable);
+    // abort the writable quickly if there is an error, and ensure we don't
+    // throw an uncaught error.
+    this.#written.catch((reason) => {
+      this.#entryStream.writable.abort(reason);
+    });
+  }
+
+  /**
+   * Writable stream to write entry data to.
+   *
+   * @example
+   * ```ts
+   * ReadableStream.from([new TextEncoder().encode("Hello, World!")])
+   *   .pipeTo(entryWriter.writable);
+   * ```
+   */
+  get writable() {
+    return this.#entryStream.writable;
+  }
+
+  /**
+   * Get entry info. Resolves once all data has been written to the Zip stream.
+   */
+  async entry(): Promise<EntryInfo> {
+    return this.#written;
+  }
+}

package/src/utils.ts

@@ -0,0 +1,17 @@
+export function getDosTime(date: Date): number {
+  return (
+    (date.getHours() << 11) |
+    (date.getMinutes() << 5) |
+    (date.getSeconds() >> 1)
+  );
+}
+
+export function getDosDate(date: Date): number {
+  return (
+    ((date.getFullYear() - 1980) << 9) |
+    ((date.getMonth() + 1) << 5) |
+    date.getDate()
+  );
+}
+
+export function noop() {}