Node.js Directory Comparison Utility

Common errors

• TypeError: dircompare.compare is not a function

  cause Attempting to call `dircompare.compare` directly after a CommonJS `require('dir-compare')` on versions 4.0.0+ when the library might expose named exports more prominently, or if trying to call an async function synchronously.
  fix For CommonJS, try `const { compare, compareSync } = require('dir-compare');` or for modern ES Modules: `import { compare, compareSync } from 'dir-compare';`. Ensure you are calling `compare` (async) with `.then()`/`await` or `compareSync` (sync) appropriately.

• Error: EACCES: permission denied, open 'path/to/file'

  cause The Node.js process does not have sufficient read permissions for one or both of the directories or files being compared.
  fix Ensure the user running the Node.js application has read and execute permissions on all directories and files within the comparison paths. Alternatively, `dir-compare` added support for handling permission denied errors in v3.2.0; investigate options for graceful error handling within the comparison process if appropriate.

• TypeError: Cannot read properties of undefined (reading 'diffSet')

  cause This usually happens if the `compare` or `compareSync` function failed to execute or returned an unexpected value (e.g., `null` or `undefined`) instead of a `Result` object, and subsequent code tries to access properties like `diffSet`.
  fix Wrap the comparison call in a `try...catch` block (for sync) or add a `.catch()` handler (for async) to properly handle potential errors during the comparison process. Also, verify that the input paths are valid and accessible.

Warnings

• breaking The `skipSubdirs` option now behaves slightly differently, potentially affecting how comparisons handle subdirectories. Review issue #77 for specifics.
  Fix: Carefully test existing comparison logic if `skipSubdirs` is used and adjust expectations or options if necessary.
• breaking When using `dir-compare` to compare two individual files (not directories), the names of the files are now ignored in the comparison. This primarily affects scenarios where `dir-compare` was used for direct file-to-file comparison and relied on name matching.
  Fix: If file name comparison is critical when comparing two specific files, implement a separate name check or ensure the files are placed within temporary directories for a full directory comparison.
• breaking The project was switched to TypeScript in v4.0.0. While existing JavaScript usage generally remains compatible, direct imports for types (`Options`, `Result`) are now available, and the internal structure is type-checked. This might implicitly affect type inference in certain editors for existing JavaScript projects.
  Fix: For TypeScript projects, update imports to use named imports (e.g., `import { compare, Options } from 'dir-compare';`). JavaScript projects should continue to function but may benefit from type definitions.
• breaking The command-line interface (CLI) utility was extracted into a separate package, `dir-compare-cli`. The `dir-compare` package now only provides the library API.
  Fix: If you rely on the `dir-compare` CLI, install `dir-compare-cli` separately (`npm install -g dir-compare-cli`) and use its commands instead.
• gotcha The `origin` field was added to the `Entry` interface (within `diffSet`) to distinguish whether an entry originated from the left or right directory. This provides more granular information but requires updating code that processed `diffSet` entries if `origin` is now relevant.
  Fix: Review code that processes `diffSet` entries to leverage the new `origin` field for more precise handling of left-only vs. right-only differences, if needed.
• gotcha Since v4.1.0, the library offers enhanced glob filter capabilities and the ability to implement `.gitignore` rules. If custom filtering logic was previously implemented manually, these new features can simplify the code.
  Fix: Consider refactoring custom filtering logic to utilize the new `glob filter` and `.gitignore` implementation features provided by the library, which can improve maintainability and robustness.

Install

• npm install dir-compare npm
• yarn add dir-compare yarn
• pnpm add dir-compare pnpm

Imports

• compare
  wrong:

  const dircompare = require('dir-compare'); dircompare.compare(...);

  correct:

  import { compare } from 'dir-compare';

  Asynchronous comparison function. Prefer named imports with TypeScript or modern JavaScript. CommonJS `require` works but requires accessing `dircompare.compare`.
• compareSync
  wrong:

  const dircompare = require('dir-compare'); dircompare.compareSync(...);

  correct:

  import { compareSync } from 'dir-compare';

  Synchronous comparison function. Named imports are recommended, especially with TypeScript since v4.0.0.
• Options

  import { Options } from 'dir-compare';

  TypeScript interface for comparison options. Essential when writing strongly-typed comparison logic.
• Result

  import { Result } from 'dir-compare';

  TypeScript interface for the comparison result object. Provides strong typing for accessing comparison statistics and the diffSet.

Quickstart

This quickstart demonstrates both synchronous and asynchronous directory comparison using `dir-compare`. It creates temporary directories, populates them with files, and then compares them using options for size and content, while excluding a specific file. It logs the comparison summary and detailed differences.

import { compare, compareSync, Options, Result } from 'dir-compare';
import * as path from 'path';
import * * as fs from 'fs';

// Create dummy directories and files for demonstration
const dir1 = path.join(__dirname, 'test-dir1');
const dir2 = path.join(__dirname, 'test-dir2');

fs.mkdirSync(dir1, { recursive: true });
fs.mkdirSync(dir2, { recursive: true });
fs.writeFileSync(path.join(dir1, 'fileA.txt'), 'Content A');
fs.writeFileSync(path.join(dir1, 'fileB.txt'), 'Content B');
fs.writeFileSync(path.join(dir2, 'fileA.txt'), 'Content A');
fs.writeFileSync(path.join(dir2, 'fileC.txt'), 'Content C');

const options: Options = { compareSize: true, compareContent: true, excludeFilter: 'fileB.txt' };

console.log('--- Synchronous Comparison ---');
try {
  const resSync: Result = compareSync(dir1, dir2, options);
  console.log('Directories are %s', resSync.same ? 'identical' : 'different');
  console.log('Equal entries: %s, Distinct entries: %s, Left only: %s, Right only: %s', 
    resSync.equal, resSync.distinct, resSync.left, resSync.right);
  resSync.diffSet.forEach(dif => {
    console.log(`- Path: ${dif.relativePath}, Name1: ${dif.name1}, Name2: ${dif.name2}, State: ${dif.state}`);
  });
} catch (error) {
  console.error('Synchronous comparison failed:', error);
}

console.log('\n--- Asynchronous Comparison ---');
compare(dir1, dir2, options)
  .then(resAsync => {
    console.log('Directories are %s', resAsync.same ? 'identical' : 'different');
    console.log('Equal entries: %s, Distinct entries: %s, Left only: %s, Right only: %s', 
      resAsync.equal, resAsync.distinct, resAsync.left, resAsync.right);
    resAsync.diffSet.forEach(dif => {
      console.log(`- Path: ${dif.relativePath}, Name1: ${dif.name1}, Name2: ${dif.name2}, State: ${dif.state}`);
    });
  })
  .catch(error => console.error('Asynchronous comparison failed:', error))
  .finally(() => {
    // Cleanup dummy directories
    fs.rmSync(dir1, { recursive: true, force: true });
    fs.rmSync(dir2, { recursive: true, force: true });
  });