Gzipper CLI and Module

Common errors

• gzipper: command not found

  cause `gzipper` is not installed globally or is not in your system's PATH.
  fix Install `gzipper` globally using `npm i -g gzipper` or ensure your shell's PATH includes `$(npm bin -g)`.

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/gzipper/dist/index.js from .../my-script.js not supported.

  cause You are trying to `require()` gzipper in a CommonJS module, but gzipper's main entry point might be an ESM module or your project configuration is conflicting.
  fix Either convert your consuming script to an ES Module (e.g., add `"type": "module"` to package.json or use `.mjs` extension) and use `import { compress } from 'gzipper';`, or ensure you are using the CommonJS compatible entry point with `const { compress } = require('gzipper/cjs');` if available, or simply `require('gzipper');` which should resolve correctly based on the package.json `exports` field.

• Error: The 'path' argument must be of type string or an instance of Buffer or URL. Received undefined

  cause The input or output directory arguments to the `compress` function (or CLI) were not provided or were undefined.
  fix Ensure that the input path and output path arguments are correctly provided as strings to the `compress` function or CLI command.

Warnings

• breaking Gzipper requires Node.js version 20.11.0 or higher. Running it with older Node.js versions will result in execution errors.
  Fix: Upgrade your Node.js environment to version 20.11.0 or newer (e.g., using nvm or your package manager).
• gotcha By default, `gzipper` will compress ALL files in the specified input directory. This can lead to unintended compression of files you don't want processed if `--include` or `--exclude` options are not used.
  Fix: Always use the `--include <extensions>` (e.g., `--include js,css,html`) or `--exclude <extensions>` options to specify exactly which file types should be compressed, especially when working with entire project output directories.
• gotcha When using `gzipper` programmatically or via CLI, environment variables with option names (e.g., `GZIPPER_BROTLI_QUALITY=11`) will override any corresponding CLI arguments or programmatic options passed directly to the `compress` function.
  Fix: Be aware of your environment variables if CLI arguments or programmatic options seem to be ignored. Explicitly unset relevant `GZIPPER_` prefixed environment variables if you want CLI/code arguments to take precedence.
• gotcha When using multiple compression algorithms (e.g., both `--gzip` and `--brotli`), ensure your `--output-file-format` or algorithm-specific output format options (e.g., `--gzip-output-file-name-format`) prevent filename collisions, otherwise files might be overwritten.
  Fix: Define distinct output file formats for each algorithm, such as `[name].[ext].gz` for Gzip and `[name].[ext].br` for Brotli, to avoid accidental overwrites. The `compress` function also accepts `gzipOutputFileNameFormat` and `brotliOutputFileNameFormat` options.

Install

• npm install gzipper npm
• yarn add gzipper yarn
• pnpm add gzipper pnpm

Imports

• compress
  wrong:

  const { compress } = require('gzipper');

  correct:

  import { compress } from 'gzipper';

  For programmatic use in ESM modules. Prefer named imports for clarity and tree-shaking.
• compress

  const { compress } = require('gzipper');

  CommonJS import for Node.js environments. This is demonstrated in the official README.
• GzipperOptions

  import type { GzipperOptions } from 'gzipper';

  Import for TypeScript type definitions when using the programmatic API with custom options.

Quickstart

Demonstrates programmatic usage of `gzipper` to compress a dummy file within a temporary directory using both Brotli and Gzip algorithms, with verbose output and cleanup.

import { compress } from 'gzipper';
import * as fs from 'node:fs';
import * as path from 'node:path';

const tempDir = path.join(process.cwd(), 'temp-gzipper-test');
const dummyFile = path.join(tempDir, 'example.txt');

async function runCompression() {
  // Create a temporary directory and file for testing
  if (!fs.existsSync(tempDir)) {
    fs.mkdirSync(tempDir, { recursive: true });
  }
  fs.writeFileSync(dummyFile, 'This is a test file to demonstrate gzipper compression. It should be long enough to get some compression benefit.', 'utf8');

  console.log('Compressing files in', tempDir);
  try {
    await compress(tempDir, tempDir, {
      brotli: true, // Enable Brotli compression
      gzip: true,   // Also enable Gzip compression
      outputFileFormat: '[name].[ext].br', // Brotli output format
      gzipOutputFileNameFormat: '[name].[ext].gz', // Gzip specific output format
      verbose: true,
      removeLarger: true // Remove original if compressed is smaller
    });
    console.log('Compression complete. Checking created files...');
    console.log('Files in temp directory:', fs.readdirSync(tempDir));
  } catch (error) {
    console.error('Compression failed:', error);
  } finally {
    // Clean up temporary files and directory
    if (fs.existsSync(tempDir)) {
      fs.rmSync(tempDir, { recursive: true, force: true });
      console.log('Cleaned up temporary directory:', tempDir);
    }
  }
}

runCompression();