{"id":10658,"library":"compress-commons","title":"Compress Commons Archive Utilities","description":"compress-commons is a Node.js library that provides a common, low-level interface for defining and working with various archive formats, particularly ZIP, within a Node.js environment. Inspired by the established Java library Apache Commons Compress, it aims to offer foundational building blocks and structures (like file headers and entry definitions) for handling archive data. The current stable version is 7.0.0, which transitioned to being an ESM-only package and requires Node.js v18 or newer. While its release cadence is regular, it does not follow a strict schedule. This library differentiates itself by focusing on the underlying components and specifications of archive formats, rather than providing a high-level API for creating or extracting archives directly, making it suitable for developers who need granular control over archive manipulation.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/archiverjs/node-compress-commons","tags":["javascript","compress","commons","archive"],"install":[{"cmd":"npm install compress-commons","lang":"bash","label":"npm"},{"cmd":"yarn add compress-commons","lang":"bash","label":"yarn"},{"cmd":"pnpm add compress-commons","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for CRC32 checksum calculations within archive operations.","package":"crc32-stream","optional":false}],"imports":[{"note":"Since v7.0.0, compress-commons is an ESM-only package. Use ES module import syntax. `Entry` represents a single file or directory within a ZIP archive.","wrong":"const { Entry } = require('compress-commons/zip');","symbol":"Entry","correct":"import { Entry } from 'compress-commons/zip';"},{"note":"Part of the low-level ZIP format definition. `Headers` encapsulates the metadata for a ZIP archive entry. ESM-only.","wrong":"const { Headers } = require('compress-commons/zip');","symbol":"Headers","correct":"import { Headers } from 'compress-commons/zip';"},{"note":"Provides various constants related to archive formats, such as magic numbers or flags. ESM-only.","wrong":"const constants = require('compress-commons/lib/constants');","symbol":"constants","correct":"import * as constants from 'compress-commons/lib/constants';"}],"quickstart":{"code":"import { Entry, Headers } from 'compress-commons/zip';\nimport { pipeline } from 'stream/promises';\nimport { createReadStream, createWriteStream, promises as fsPromises } from 'fs';\nimport path from 'path';\n\nasync function createSimpleZipEntryDefinition() {\n  const filePath = path.join(process.cwd(), 'temp_file.txt');\n  const outputZipPath = path.join(process.cwd(), 'output.zip');\n  const fileContent = 'This is a test file for compress-commons quickstart.';\n\n  // Create a dummy file to simulate content\n  await fsPromises.writeFile(filePath, fileContent);\n\n  // Define the header for the ZIP entry\n  const header = new Headers({\n    path: 'my-entry.txt', // Name of the file inside the archive\n    comment: 'A sample entry.',\n    size: Buffer.byteLength(fileContent), // Uncompressed size\n    crc32: 0, // Placeholder, actual CRC32 calculated by archiver\n  });\n\n  // Create an Entry object. In a real scenario, this would be fed into an archiver stream.\n  const entry = new Entry(header, {\n    type: 'file',\n    source: createReadStream(filePath), // Source can be a stream or Buffer\n  });\n\n  console.log(`Defined ZIP entry: ${entry.header.path}`);\n  console.log(`Entry size: ${entry.header.size} bytes`);\n\n  // This library provides common interfaces, not a full archiver.\n  // To actually create a .zip file, you'd typically use a library like 'archiver'\n  // that consumes these 'Entry' objects.\n  // For demonstration, we'll just show the entry definition.\n  // A full archiver would look something like this (conceptual):\n  // import archiver from 'archiver';\n  // const archive = archiver('zip', { zlib: { level: 9 } });\n  // archive.pipe(createWriteStream(outputZipPath));\n  // archive.append(entry.source, { name: entry.header.path });\n  // await archive.finalize();\n  // console.log(`\nConceptually, 'my-entry.txt' would be added to a ZIP archive.`);\n  \n  await fsPromises.unlink(filePath);\n}\n\ncreateSimpleZipEntryDefinition().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to define a basic ZIP archive entry using `Headers` and `Entry` classes. It creates a mock file and then defines its corresponding archive header and entry object. It's a low-level definition, not a complete archiving process."},"warnings":[{"fix":"Migrate your project to ES Modules and use `import` statements, or stick to an earlier version of `compress-commons` if CommonJS is strictly required.","message":"Version 7.0.0 of `compress-commons` is an ES Modules (ESM) only package. Projects using CommonJS `require()` will encounter `ERR_REQUIRE_ESM` errors.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or newer.","message":"`compress-commons` v7.0.0 and above explicitly require Node.js v18 or higher. Running with older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 14 or higher (or >=18 for v7.0.0+).","message":"Version 6.0.0 dropped official support for Node.js v12. While it might still function, compatibility is not guaranteed, and potential issues may arise.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"fix":"Upgrade your Node.js environment to version 12 or higher (or >=18 for v7.0.0+).","message":"Version 5.0.0 dropped support for Node.js v10. Using v5.0.0+ with Node.js v10 will lead to compatibility problems and errors.","severity":"breaking","affected_versions":">=5.0.0 <6.0.0"},{"fix":"Understand that `compress-commons` provides building blocks. For full archive creation or extraction, consider using higher-level libraries that leverage `compress-commons` internally, such as `archiver`.","message":"This library provides low-level interfaces for archive formats, such as defining ZIP entry headers. It is not a complete archiving solution like `archiver` itself. You will likely need to integrate it with another library to write complete archive files.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { Symbol } = require('compress-commons/zip');` to `import { Symbol } from 'compress-commons/zip';` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in package.json or using `.mjs` file extensions).","cause":"Attempting to use `require()` to import `compress-commons` or its submodules, which are now ES Modules.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported."},{"fix":"Ensure that the `path` property is explicitly provided as a string when creating `Headers` or `Entry` instances, e.g., `new Headers({ path: 'my-file.txt', ... })`.","cause":"An `Entry` or `Headers` object was likely constructed without a required `path` property in its configuration.","error":"Error: The \"path\" argument must be of type string. Received undefined"},{"fix":"Always instantiate `Headers` and `Entry` using the `new` keyword: `const header = new Headers({...});`.","cause":"Attempting to call `Headers` (or `Entry`) as a function instead of a constructor.","error":"TypeError: Class constructor Headers cannot be invoked without 'new'"}],"ecosystem":"npm"}