dir-compare

  • Version 3.3.0
  • Published
  • 180 kB
  • 2 dependencies
  • MIT license

Install

npm i dir-compare
yarn add dir-compare
pnpm add dir-compare

Overview

Node JS directory compare

Index

Variables

variable fileCompareHandlers

const fileCompareHandlers: FileCompareHandlers;
  • File comparison handlers. These handlers are used when [[Options.compareContent]] is set.

Functions

function compare

compare: (path1: string, path2: string, options?: Options) => Promise<Result>;
  • Asynchronously compares given paths.

    Parameter path1

    Left file or directory to be compared.

    Parameter path2

    Right file or directory to be compared.

    Parameter options

    Comparison options.

function compareSync

compareSync: (path1: string, path2: string, options?: Options) => Result;
  • Synchronously compares given paths.

    Parameter path1

    Left file or directory to be compared.

    Parameter path2

    Right file or directory to be compared.

    Parameter options

    Comparison options.

Interfaces

interface BrokenLinksStatistics

interface BrokenLinksStatistics {}
    distinctBrokenLinks: number;
    • Number of broken links with same name appearing in both path1 and path2 (leftBrokenLinks + rightBrokenLinks + distinctBrokenLinks)

    leftBrokenLinks: number;
    • Number of broken links only in path1

    rightBrokenLinks: number;
    • Number of broken links only in path2

    totalBrokenLinks: number;
    • Total number of broken links

    interface CompareFileHandler

    interface CompareFileHandler {}

      property compareAsync

      compareAsync: CompareFileAsync;

        property compareSync

        compareSync: CompareFileSync;

          interface Difference

          interface Difference {}

            property date1

            date1?: number;
            • Left entry modification date (stat.mtime). Is undefined if missing on the left side.

            property date2

            date2?: number;
            • Right entry modification date (stat.mtime). Is undefined if missing on the right side.

            property level

            level: number;
            • Depth level relative to root dir.

            property name1

            name1?: string;
            • Left file/directory name. Is undefined if missing on the left side.

            property name2

            name2?: string;
            • Right file/directory name. Is undefined if missing on the right side.

            property path1

            path1?: string;
            • Path not including file/directory name; can be relative or absolute depending on call to compare(). Is undefined if missing on the left side.

            property path2

            path2?: string;
            • Path not including file/directory name; can be relative or absolute depending on call to compare(). Is undefined if missing on the right side.

            property permissionDeniedState

            permissionDeniedState: PermissionDeniedState;
            • Permission related state of left/right entries.

            property reason

            reason: Reason;
            • Provides reason when two identically named entries are distinct.

            property relativePath

            relativePath: string;
            • Path relative to root dir.

            property size1

            size1?: number;
            • Left file size. Is undefined if missing on the left side.

            property size2

            size2?: number;
            • Right file size. Is undefined if missing on the right side.

            property state

            state: DifferenceState;
            • See [[DifferenceState]]

            property type1

            type1: DifferenceType;
            • Type of left entry. Is undefined if missing on the left side.

            property type2

            type2: DifferenceType;
            • Type of right entry. Is undefined if missing on the right side.

            index signature

            [key: string]: any;
            • Any property is allowed if default result builder is not used.

            interface Entry

            interface Entry {}

              property absolutePath

              absolutePath: string;

                property isPermissionDenied

                isPermissionDenied: boolean;
                • True when this entry is not readable. This value is set only when [[Options.handlePermissionDenied]] is enabled.

                property lstat

                lstat: fs.Stats;

                  property name

                  name: string;

                    property path

                    path: string;

                      property stat

                      stat: fs.Stats;
                        symlink: boolean;

                          interface FileCompareHandlers

                          interface FileCompareHandlers {}

                            property defaultFileCompare

                            defaultFileCompare: CompareFileHandler;
                            • Default file content comparison handlers, used if [[Options.compareFileAsync]] or [[Options.compareFileSync]] are not specified.

                              Performs binary comparison.

                            property lineBasedFileCompare

                            lineBasedFileCompare: CompareFileHandler;
                            • Compares files line by line.

                              Options: * ignoreLineEnding - true/false (default: false) - Ignore cr/lf line endings * ignoreWhiteSpaces - true/false (default: false) - Ignore white spaces at the beginning and ending of a line (similar to 'diff -b') * ignoreAllWhiteSpaces - true/false (default: false) - Ignore all white space differences (similar to 'diff -w') * ignoreEmptyLines - true/false (default: false) - Ignores differences caused by empty lines (similar to 'diff -B')

                            interface Options

                            interface Options {}
                            • Comparison options.

                            property compareContent

                            compareContent?: boolean;
                            • Compares files by content. Defaults to 'false'.

                              Usually one of compareSize or compareContent options has to be activated. Otherwise files are compared by name disregarding size or content.

                            property compareDate

                            compareDate?: boolean;
                            • Compares files by date of modification (stat.mtime). Defaults to 'false'.

                              Also see [[Options.dateTolerance]].

                            property compareFileAsync

                            compareFileAsync?: CompareFileAsync;
                            • File comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).

                            property compareFileSync

                            compareFileSync?: CompareFileSync;
                            • File comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).

                            property compareNameHandler

                            compareNameHandler?: CompareNameHandler;
                            • Entry name comparison handler. See [Custom name comparators](https://github.com/gliviu/dir-compare#custom-name-comparators).

                            property compareSize

                            compareSize?: boolean;
                            • Compares files by size. Defaults to 'false'.

                              Usually one of compareSize or compareContent options has to be activated. Otherwise files are compared by name disregarding size or content.

                            compareSymlink?: boolean;
                            • Compares entries by symlink. Defaults to 'false'.

                              If this option is enabled two entries must have the same type in order to be considered equal. They have to be either two fies, two directories or two symlinks.

                              If left entry is a file and right entry is a symlink, they are considered distinct disregarding the content of the file.

                              Further if both entries are symlinks they need to have the same link value. For example if one symlink points to '/x/b.txt' and the other to '/x/../x/b.txt' the symlinks are considered distinct even if they point to the same file.

                            property dateTolerance

                            dateTolerance?: number;
                            • Two files are considered to have the same date if the difference between their modification dates fits within date tolerance. Defaults to 1000 ms.

                            property excludeFilter

                            excludeFilter?: string;
                            • File/directory name exclude filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns)

                            property handlePermissionDenied

                            handlePermissionDenied?: boolean;
                            • Handle permission denied errors. Defaults to 'false'.

                              By default when some entry cannot be read due to EACCES error the comparison will stop immediately with an exception.

                              If handlePermissionDenied is set to true the comparison will continue when unreadable entries are encountered.

                              Offending entries will be reported within [[Difference.permissionDeniedState]], [[Difference.reason]] and [[Result.permissionDenied]].

                              Lets consider we want to compare two identical folders A and B with B/dir2 being unreadable for the current user.

                              A B
                              ├── dir1 ├── dir1
                              ├──── file1 ├──── file1
                              ├── dir2 ├── dir2 (permission denied)
                              └─────file2 └─────file2

                              [[Result.diffSet]] will look like:

                              |relativePath |path1 |path2 | state |reason |permissionDeniedState| |--------------|---------|---------|------------|------------------------|---------------------| |[/] |dir1 |dir1 |equal | | | |[/dir1] |file1 |file1 |equal | | | |[/] |dir2 |dir2 |distinct | permission-denied |access-error-right | |[/dir2] |file2 |missing |left | | |

                              And [[Result.permissionDenied]] statistics look like - left: 0, right: 1, distinct: 0, total: 1

                            property ignoreCase

                            ignoreCase?: boolean;
                            • Ignores case when comparing names. Defaults to 'false'.

                            property includeFilter

                            includeFilter?: string;
                            • File name filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns).

                            property noDiffSet

                            noDiffSet?: boolean;
                            • Toggles presence of diffSet in output. If true, only statistics are provided. Use this when comparing large number of files to avoid out of memory situations. Defaults to 'false'.

                            property resultBuilder

                            resultBuilder?: ResultBuilder;
                            • Callback for constructing result. Called for each compared entry pair.

                              Updates 'statistics' and 'diffSet'.

                              See [Custom result builder](https://github.com/gliviu/dir-compare#custom-result-builder).

                            property skipEmptyDirs

                            skipEmptyDirs?: boolean;
                            • Ignore empty directories. Defaults to 'false'.

                            property skipSubdirs

                            skipSubdirs?: boolean;
                            • Skips sub directories. Defaults to 'false'.

                            skipSymlinks?: boolean;
                            • Ignore symbolic links. Defaults to 'false'.

                            index signature

                            [key: string]: any;
                            • Properties to be used in various extension points ie. result builder.

                            interface PermissionDeniedStatistics

                            interface PermissionDeniedStatistics {}

                              property distinctPermissionDenied

                              distinctPermissionDenied: number;
                              • Number of forbidden entries with same name appearing in both path1 and path2 (leftPermissionDenied + rightPermissionDenied + distinctPermissionDenied)

                              property leftPermissionDenied

                              leftPermissionDenied: number;
                              • Number of forbidden entries found only in path1

                              property rightPermissionDenied

                              rightPermissionDenied: number;
                              • Number of forbidden entries found only in path2

                              property totalPermissionDenied

                              totalPermissionDenied: number;
                              • Total number of forbidden entries

                              interface Result

                              interface Result extends Statistics {}
                              • Comparison result.

                              property diffSet

                              diffSet?: Array<Difference>;
                              • List of changes (present if [[Options.noDiffSet]] is false).

                              interface Statistics

                              interface Statistics {}
                                brokenLinks: BrokenLinksStatistics;
                                • Stats about broken links.

                                property differences

                                differences: number;
                                • Total number of differences (distinct+left+right).

                                property differencesDirs

                                differencesDirs: number;
                                • Total number of different directories (distinctDirs+leftDirs+rightDirs).

                                property differencesFiles

                                differencesFiles: number;
                                • Total number of different files (distinctFiles+leftFiles+rightFiles).

                                property distinct

                                distinct: number;
                                • Number of distinct entries.

                                property distinctDirs

                                distinctDirs: number;
                                • Number of distinct directories.

                                property distinctFiles

                                distinctFiles: number;
                                • Number of distinct files.

                                property equal

                                equal: number;
                                • Number of equal entries.

                                property equalDirs

                                equalDirs: number;
                                • Number of equal directories.

                                property equalFiles

                                equalFiles: number;
                                • Number of equal files.

                                property left

                                left: number;
                                • Number of entries only in path1.

                                property leftDirs

                                leftDirs: number;
                                • Number of directories only in path1.

                                property leftFiles

                                leftFiles: number;
                                • Number of files only in path1.

                                property permissionDenied

                                permissionDenied: PermissionDeniedStatistics;
                                • Stats about entries that could not be accessed.

                                property right

                                right: number;
                                • Number of entries only in path2.

                                property rightDirs

                                rightDirs: number;
                                • Number of directories only in path2.

                                property rightFiles

                                rightFiles: number;
                                • Number of files only in path2

                                property same

                                same: boolean;
                                • True if directories are identical.

                                symlinks?: SymlinkStatistics;
                                • Statistics available if 'compareSymlink' options is used.

                                property total

                                total: number;
                                • Total number of entries (differences+equal).

                                property totalDirs

                                totalDirs: number;
                                • Total number of directories (differencesDirs+equalDirs).

                                property totalFiles

                                totalFiles: number;
                                • Total number of files (differencesFiles+equalFiles).

                                index signature

                                [key: string]: any;
                                • Any property is allowed if default result builder is not used.

                                interface SymlinkStatistics

                                interface SymlinkStatistics {}
                                  differencesSymlinks: number;
                                  • Total number of different links (distinctSymlinks+leftSymlinks+rightSymlinks).

                                  distinctSymlinks: number;
                                  • Number of distinct links.

                                  equalSymlinks: number;
                                  • Number of equal links.

                                  leftSymlinks: number;
                                  • Number of links only in path1.

                                  rightSymlinks: number;
                                  • Number of links only in path2

                                  totalSymlinks: number;
                                  • Total number of links (differencesSymlinks+equalSymlinks).

                                  Type Aliases

                                  type CompareFileAsync

                                  type CompareFileAsync = (
                                  path1: string,
                                  stat1: fs.Stats,
                                  path2: string,
                                  stat2: fs.Stats,
                                  options: Options
                                  ) => Promise<boolean>;
                                  • Asynchronous file content comparison handler.

                                  type CompareFileSync

                                  type CompareFileSync = (
                                  path1: string,
                                  stat1: fs.Stats,
                                  path2: string,
                                  stat2: fs.Stats,
                                  options: Options
                                  ) => boolean;
                                  • Synchronous file content comparison handler.

                                  type CompareNameHandler

                                  type CompareNameHandler = (
                                  name1: string,
                                  name2: string,
                                  options: Options
                                  ) => 0 | 1 | -1;
                                  • Compares the names of two entries. The comparison should be dependent on received options (ie. case sensitive, ...). Returns 0 if names are identical, -1 if name1<name2, 1 if name1>name2.

                                  type DifferenceState

                                  type DifferenceState = 'equal' | 'left' | 'right' | 'distinct';
                                  • State of left/right entries relative to each other. * equal - Identical entries are found in both left/right dirs. * left - Entry is found only in left dir. * right - Entry is found only in right dir. * distinct - Entries exist in both left/right dir but have different content. See [[Difference.reason]] to understan why entries are considered distinct.

                                  type DifferenceType

                                  type DifferenceType = 'missing' | 'file' | 'directory' | 'broken-link';
                                  • Type of entry.

                                  type PermissionDeniedState

                                  type PermissionDeniedState =
                                  | 'access-ok'
                                  | 'access-error-both'
                                  | 'access-error-left'
                                  | 'access-error-right';
                                  • Permission related state of left/right entries. Available only when [[Options.handlePermissionDenied]] is enabled. * access-ok - Both entries are accessible. * access-error-both - Neither entry can be accessed. * access-error-left - Left entry cannot be accessed. * access-error-right - Right entry cannot be accessed.

                                  type Reason

                                  type Reason =
                                  | undefined
                                  | 'different-size'
                                  | 'different-date'
                                  | 'different-content'
                                  | 'broken-link'
                                  | 'different-symlink'
                                  | 'permission-denied';
                                  • Provides reason when two identically named entries are distinct.

                                    Not available if entries are equal.

                                    * different-size - Files differ in size. * different-date - Entry dates are different. Used when [[Options.compareDate]] is true`. * different-content - File contents are different. Used when [[Options.compareContent]] is true. * broken-link - Both left/right entries are broken links. * different-symlink - Symlinks are different. See [[Options.compareSymlink]] for details. * permission-denied - One or both left/right entries are not accessible. See [[Options.handlePermissionDenied]] for details.

                                  type ResultBuilder

                                  type ResultBuilder =
                                  /**
                                  * @param entry1 Left entry.
                                  * @param entry2 Right entry.
                                  * @param state See [[DifferenceState]].
                                  * @param level Depth level relative to root dir.
                                  * @param relativePath Path relative to root dir.
                                  * @param statistics Statistics to be updated.
                                  * @param diffSet Status per each entry to be appended.
                                  * Do not append if [[Options.noDiffSet]] is false.
                                  * @param reason See [[Reason]]. Not available if entries are equal.
                                  */
                                  (
                                  entry1: Entry | undefined,
                                  entry2: Entry | undefined,
                                  state: DifferenceState,
                                  level: number,
                                  relativePath: string,
                                  options: Options,
                                  statistics: Statistics,
                                  diffSet: Array<Difference> | undefined,
                                  reason: Reason | undefined
                                  ) => void;
                                  • Callback for constructing result. Called for each compared entry pair.

                                    Updates 'statistics' and 'diffSet'.

                                  Package Files (3)

                                  Dependencies (2)

                                  Dev Dependencies (14)

                                  Peer Dependencies (0)

                                  No peer dependencies.

                                  Badge

                                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/dir-compare.

                                  • Markdown
                                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/dir-compare)
                                  • HTML
                                    <a href="https://www.jsdocs.io/package/dir-compare"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>