Compress Commons Archive Utilities

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported.

  cause Attempting to use `require()` to import `compress-commons` or its submodules, which are now ES Modules.
  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).

• Error: The "path" argument must be of type string. Received undefined

  cause An `Entry` or `Headers` object was likely constructed without a required `path` property in its configuration.
  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', ... })`.

• TypeError: Class constructor Headers cannot be invoked without 'new'

  cause Attempting to call `Headers` (or `Entry`) as a function instead of a constructor.
  fix Always instantiate `Headers` and `Entry` using the `new` keyword: `const header = new Headers({...});`.

Warnings

• breaking Version 7.0.0 of `compress-commons` is an ES Modules (ESM) only package. Projects using CommonJS `require()` will encounter `ERR_REQUIRE_ESM` errors.
  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.
• breaking `compress-commons` v7.0.0 and above explicitly require Node.js v18 or higher. Running with older Node.js versions will result in errors.
  Fix: Upgrade your Node.js environment to version 18 or newer.
• breaking 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.
  Fix: Upgrade your Node.js environment to version 14 or higher (or >=18 for v7.0.0+).
• breaking 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.
  Fix: Upgrade your Node.js environment to version 12 or higher (or >=18 for v7.0.0+).
• gotcha 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.
  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`.

Install

• npm install compress-commons npm
• yarn add compress-commons yarn
• pnpm add compress-commons pnpm

Imports

• Entry
  wrong:

  const { Entry } = require('compress-commons/zip');

  correct:

  import { Entry } from 'compress-commons/zip';

  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.
• Headers
  wrong:

  const { Headers } = require('compress-commons/zip');

  correct:

  import { Headers } from 'compress-commons/zip';

  Part of the low-level ZIP format definition. `Headers` encapsulates the metadata for a ZIP archive entry. ESM-only.
• constants
  wrong:

  const constants = require('compress-commons/lib/constants');

  correct:

  import * as constants from 'compress-commons/lib/constants';

  Provides various constants related to archive formats, such as magic numbers or flags. ESM-only.

Quickstart

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.

import { Entry, Headers } from 'compress-commons/zip';
import { pipeline } from 'stream/promises';
import { createReadStream, createWriteStream, promises as fsPromises } from 'fs';
import path from 'path';

async function createSimpleZipEntryDefinition() {
  const filePath = path.join(process.cwd(), 'temp_file.txt');
  const outputZipPath = path.join(process.cwd(), 'output.zip');
  const fileContent = 'This is a test file for compress-commons quickstart.';

  // Create a dummy file to simulate content
  await fsPromises.writeFile(filePath, fileContent);

  // Define the header for the ZIP entry
  const header = new Headers({
    path: 'my-entry.txt', // Name of the file inside the archive
    comment: 'A sample entry.',
    size: Buffer.byteLength(fileContent), // Uncompressed size
    crc32: 0, // Placeholder, actual CRC32 calculated by archiver
  });

  // Create an Entry object. In a real scenario, this would be fed into an archiver stream.
  const entry = new Entry(header, {
    type: 'file',
    source: createReadStream(filePath), // Source can be a stream or Buffer
  });

  console.log(`Defined ZIP entry: ${entry.header.path}`);
  console.log(`Entry size: ${entry.header.size} bytes`);

  // This library provides common interfaces, not a full archiver.
  // To actually create a .zip file, you'd typically use a library like 'archiver'
  // that consumes these 'Entry' objects.
  // For demonstration, we'll just show the entry definition.
  // A full archiver would look something like this (conceptual):
  // import archiver from 'archiver';
  // const archive = archiver('zip', { zlib: { level: 9 } });
  // archive.pipe(createWriteStream(outputZipPath));
  // archive.append(entry.source, { name: entry.header.path });
  // await archive.finalize();
  // console.log(`
Conceptually, 'my-entry.txt' would be added to a ZIP archive.`);
  
  await fsPromises.unlink(filePath);
}

createSimpleZipEntryDefinition().catch(console.error);