compress-commons 4.1.2: ZipArchiveOutputStream

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify compress-commons.ZipArchiveOutputStream in pkg:npm/compress-commons@4.1.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/compress-commons@4.1.2
Demonstrate these symbols/APIs:
  - compress-commons.ZipArchiveOutputStream

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:9d44337ddbe28295793477121290fce904e8a836c8c9c74c6abaeef8addc066f","contract":["ZipArchiveOutputStream configures stream options including forceZip64 and archive comment","ZipArchiveOutputStream.entry archives Buffer payload with accurate CRC32 and byte tracking","ZipArchiveOutputStream.entry archives Readable stream data asynchronously","ZipArchiveOutputStream.entry creates directory entries without payload","ZipArchiveOutputStream.entry supports STORED method for uncompressed entries","ZipArchiveOutputStream.finish finalizes stream output containing valid ZIP magic numbers"],"goal":"verify compress-commons.ZipArchiveOutputStream in pkg:npm/compress-commons@4.1.2","kind":"HOW","packages":["pkg:npm/compress-commons@4.1.2"],"schemaVersion":1,"symbols":["compress-commons.ZipArchiveOutputStream"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/compress-commons@4.1.2"],"schemaVersion":1,"subject":"pkg:npm/compress-commons@4.1.2","symbols":["compress-commons.ZipArchiveOutputStream"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-compress-commons",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-compress-commons",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "compress-commons": "4.1.2"
      }
    },
    "node_modules/buffer-crc32": {
      "version": "0.2.13",
      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
      "license": "MIT",
      "engines": {
        "node": "*"
      }
    },
    "node_modules/compress-commons": {
      "version": "4.1.2",
      "resolved": "https://registry.npmjs.org/compress-commons/-/compress-commons-4.1.2.tgz",
      "integrity": "sha512-D3uMHtGc/fcO1Gt1/L7i1e33VOvD4A9hfQLP+6ewd+BvG/gQ84Yh4oftEhAdjSMgBgwGL+jsppT7JYNpo6MHHg==",
      "license": "MIT",
      "dependencies": {
        "buffer-crc32": "^0.2.13",
        "crc32-stream": "^4.0.2",
        "normalize-path": "^3.0.0",
        "readable-stream": "^3.6.0"
      },
      "engines": {
        "node": ">= 10"
      }
    },
    "node_modules/crc-32": {
      "version": "1.2.2",
      "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz",
      "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==",
      "license": "Apache-2.0",
      "bin": {
        "crc32": "bin/crc32.njs"
      },
      "engines": {
        "node": ">=0.8"
      }
    },
    "node_modules/crc32-stream": {
      "version": "4.0.3",
      "resolved": "https://registry.npmjs.org/crc32-stream/-/crc32-stream-4.0.3.tgz",
      "integrity": "sha512-NT7w2JVU7DFroFdYkeq8cywxrgjPHWkdX1wjpRQXPX5Asews3tA+Ght6lddQO5Mkumffp3X7GEqku3epj2toIw==",
      "license": "MIT",
      "dependencies": {
        "crc-32": "^1.2.0",
        "readable-stream": "^3.4.0"
      },
      "engines": {
        "node": ">= 10"
      }
    },
    "node_modules/inherits": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
    "node_modules/normalize-path": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
      "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/readable-stream": {
      "version": "3.6.2",
      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
      "license": "MIT",
      "dependencies": {
        "inherits": "^2.0.3",
        "string_decoder": "^1.1.1",
        "util-deprecate": "^1.0.1"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.2.1",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.2.0"
      }
    },
    "node_modules/util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-compress-commons",
  "version": "1.0.0",
  "description": "Clean-room verification sample for compress-commons ZipArchiveOutputStream",
  "main": "src/index.js",
  "type": "commonjs",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "compress-commons": "4.1.2"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify compress-commons.ZipArchiveOutputStream in pkg:npm/compress-commons@4.1.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/compress-commons@4.1.2"
  ],
  "symbols": [
    "compress-commons.ZipArchiveOutputStream"
  ]
}

'use strict';

const { ZipArchiveOutputStream, ZipArchiveEntry } = require('compress-commons');

/**
 * Creates a configured ZipArchiveOutputStream instance.
 * @param {Object} [options] - Options passed to ZipArchiveOutputStream
 * @returns {ZipArchiveOutputStream}
 */
function createZipArchive(options = {}) {
  const archive = new ZipArchiveOutputStream(options);
  if (typeof options.comment === 'string') {
    archive.setComment(options.comment);
  }
  return archive;
}

/**
 * Appends a buffer or string entry to the zip stream.
 * @param {ZipArchiveOutputStream} archive
 * @param {string|ZipArchiveEntry} entryOrName
 * @param {Buffer|string|null} data
 * @param {Object} [options]
 * @returns {Promise<ZipArchiveEntry>}
 */
function appendBuffer(archive, entryOrName, data, options = {}) {
  return new Promise((resolve, reject) => {
    let entry;
    if (typeof entryOrName === 'string') {
      entry = new ZipArchiveEntry(entryOrName);
      if (options.date) entry.setTime(options.date);
      if (options.comment) entry.setComment(options.comment);
      if (options.mode) entry.setUnixMode(options.mode);
      if (options.store) entry.setMethod(0);
      else if (typeof options.method === 'number') entry.setMethod(options.method);
    } else {
      entry = entryOrName;
    }

    archive.entry(entry, data, (err, writtenEntry) => {
      if (err) return reject(err);
      resolve(writtenEntry);
    });
  });
}

/**
 * Appends a readable stream entry to the zip stream.
 * @param {ZipArchiveOutputStream} archive
 * @param {string|ZipArchiveEntry} entryOrName
 * @param {import('stream').Readable} readable
 * @param {Object} [options]
 * @returns {Promise<ZipArchiveEntry>}
 */
function appendStream(archive, entryOrName, readable, options = {}) {
  return new Promise((resolve, reject) => {
    let entry;
    if (typeof entryOrName === 'string') {
      entry = new ZipArchiveEntry(entryOrName);
      if (options.date) entry.setTime(options.date);
      if (options.comment) entry.setComment(options.comment);
      if (options.mode) entry.setUnixMode(options.mode);
      if (options.store) entry.setMethod(0);
      else if (typeof options.method === 'number') entry.setMethod(options.method);
    } else {
      entry = entryOrName;
    }

    archive.entry(entry, readable, (err, writtenEntry) => {
      if (err) return reject(err);
      resolve(writtenEntry);
    });
  });
}

/**
 * Collects emitted archive buffer chunks and finalizes the output.
 * @param {ZipArchiveOutputStream} archive
 * @returns {Promise<Buffer>}
 */
function collectArchive(archive) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    archive.on('data', chunk => chunks.push(chunk));
    archive.on('end', () => resolve(Buffer.concat(chunks)));
    archive.on('error', reject);
  });
}

module.exports = {
  ZipArchiveOutputStream,
  ZipArchiveEntry,
  createZipArchive,
  appendBuffer,
  appendStream,
  collectArchive
};

'use strict';

const assert = require('node:assert');
const { Readable } = require('node:stream');
const {
  ZipArchiveOutputStream,
  ZipArchiveEntry,
  createZipArchive,
  appendBuffer,
  appendStream,
  collectArchive
} = require('../src/index.js');

async function testZipArchiveOutputStream() {
  const modDate = new Date('2026-01-01T00:00:00.000Z');

  // Contract 1: ZipArchiveOutputStream configures stream options including forceZip64 and archive comment
  const archive1 = createZipArchive({ comment: 'sample archive comment', forceZip64: true });
  assert.ok(archive1 instanceof ZipArchiveOutputStream, 'archive1 must be instance of ZipArchiveOutputStream');
  assert.strictEqual(archive1.getComment(), 'sample archive comment', 'archive comment should match');
  assert.strictEqual(archive1.isZip64(), true, 'isZip64 should reflect forceZip64 setting');
  assert.strictEqual(typeof archive1.entry, 'function', 'entry method should exist');
  assert.strictEqual(typeof archive1.finish, 'function', 'finish method should exist');
  assert.strictEqual(typeof archive1.getBytesWritten, 'function', 'getBytesWritten should exist');

  // Contract 2: ZipArchiveOutputStream.entry archives Buffer payload with accurate CRC32 and byte tracking
  const archive2 = createZipArchive();
  const bufferPromise = collectArchive(archive2);

  const payload = Buffer.from('ZipArchiveOutputStream test content', 'utf8');
  const bufferEntry = await appendBuffer(archive2, 'hello.txt', payload, {
    date: modDate,
    comment: 'Greeting entry',
    mode: 0o644
  });

  assert.ok(bufferEntry instanceof ZipArchiveEntry, 'written entry should be ZipArchiveEntry');
  assert.strictEqual(bufferEntry.getName(), 'hello.txt');
  assert.strictEqual(bufferEntry.getSize(), payload.length);
  assert.ok(bufferEntry.getCrc() > 0, 'CRC should be computed');
  assert.strictEqual(bufferEntry.getComment(), 'Greeting entry');
  assert.strictEqual(bufferEntry.getUnixMode() & 0o777, 0o644);

  // Contract 3: ZipArchiveOutputStream.entry archives Readable stream data asynchronously
  const streamChunks = ['chunk-1 ', 'chunk-2 ', 'final-chunk'];
  const streamTotal = streamChunks.join('');
  const readStream = Readable.from(streamChunks);

  const streamEntry = await appendStream(archive2, 'data/stream.txt', readStream, {
    date: modDate
  });

  assert.strictEqual(streamEntry.getName(), 'data/stream.txt');
  assert.strictEqual(streamEntry.getSize(), Buffer.byteLength(streamTotal, 'utf8'));

  // Contract 4: ZipArchiveOutputStream.entry creates directory entries without payload
  const dirEntry = await appendBuffer(archive2, 'data/', null, {
    date: modDate
  });
  assert.strictEqual(dirEntry.getName(), 'data/');
  assert.strictEqual(dirEntry.isDirectory(), true);

  // Contract 5: ZipArchiveOutputStream.entry supports STORED method for uncompressed entries
  const uncompressedPayload = Buffer.from('Uncompressed stored data', 'utf8');
  const storedEntry = await appendBuffer(archive2, 'stored.bin', uncompressedPayload, {
    date: modDate,
    store: true
  });
  assert.strictEqual(storedEntry.getMethod(), 0, 'STORE method must be 0');
  assert.strictEqual(storedEntry.getSize(), uncompressedPayload.length);

  // Contract 6: ZipArchiveOutputStream.finish finalizes stream output containing valid ZIP magic numbers
  archive2.finish();
  const zipBuffer = await bufferPromise;

  assert.ok(Buffer.isBuffer(zipBuffer), 'output must be a Buffer');
  assert.ok(zipBuffer.length > 0, 'zip output must not be empty');
  assert.ok(archive2.getBytesWritten() > 0, 'getBytesWritten must be greater than zero');
  assert.strictEqual(archive2.getBytesWritten(), zipBuffer.length, 'getBytesWritten must match buffer size');

  // Verify ZIP local file header signature: PK\x03\x04
  const magicLocal = zipBuffer.subarray(0, 4);
  assert.deepStrictEqual(Array.from(magicLocal), [0x50, 0x4b, 0x03, 0x04], 'ZIP must start with PK\\x03\\x04');

  console.log('All contract assertions passed successfully.');
}

testZipArchiveOutputStream().catch(err => {
  console.error('Contract test failure:', err);
  process.exit(1);
});