dir-compare

dir-compare is a Node.js library for comparing two directories and reporting the differences between them. It supports multiple comparison strategies at once — size, content, modification date, and symbolic links — and returns detailed results including matched, distinct, and missing entries plus aggregate statistics.

Both synchronous and Promise-based asynchronous APIs are provided, along with glob-based include/exclude filters and extension points for custom file-content comparators, name comparators, filters, and result builders. This makes it a flexible building block for backup tools, sync utilities, test assertions, and any workflow that needs to diff filesystem trees.

What You Get

• Synchronous (compareSync) and asynchronous (compare) directory comparison APIs
• Multiple simultaneous strategies: compareSize, compareContent, compareDate, compareSymlink
• Detailed results with matched, distinct, left-only, and right-only entries plus statistics
• Glob-based include/exclude filtering of files and directories
• Extension points for custom content comparators, name comparators, filters, and result builders

Common Use Cases

• Verifying that a backup or copy matches the source directory
• Building file synchronization and mirroring tools
• Asserting directory contents in tests
• Detecting drift between two versions of a folder tree

Under The Hood

Architecture — src/ splits the two entry points, compareSync.ts and compareAsync.ts, over shared modules: Entry for filesystem traversal, FileCompareHandler for content/size/date/symlink strategies, FilterHandler and NameCompare for glob filtering and name matching, ResultBuilder for assembling the diff, and Statistics for the rollup. ExtOptions.ts wires the pluggable comparators, so the same traversal drives both sync and async paths.

Tech Stack — Written in TypeScript and published with type definitions. It has just two runtime dependencies — minimatch for glob matching and p-limit to cap concurrent file operations in the async path.

Code Quality — The project reports Codecov coverage and has a long-standing test suite across comparison modes and symlink/permission edge cases. Modules are small and single-purpose with explicit handling for permission-denied errors.

API Design — The surface is two functions plus an options object; strategies are enabled by boolean flags and combined naturally. Extension points (content comparator, name comparator, filter, result builder) let advanced users customize behavior without forking, and results are plain data objects easy to inspect.