dir-compare

  • Version 4.2.0
  • Published
  • 206 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 compareNameHandlers

const compareNameHandlers: CompareNameHandlers;
  • List of CompareNameHandlers included with dir-compare.

    See [Name comparators](https://github.com/gliviu/dir-compare#name-comparators) for details.

variable fileCompareHandlers

const fileCompareHandlers: FileCompareHandlers;
  • List of CompareFileHandlers included with dir-compare.

    See [File content comparators](https://github.com/gliviu/dir-compare#file-content-comparators) for details.

variable filterHandlers

const filterHandlers: FilterHandlers;
  • List of FilterHandlers included with dir-compare.

    See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter) for details.

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 extOptions

    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 CompareNameHandlers

          interface CompareNameHandlers {}

            property defaultNameCompare

            defaultNameCompare: CompareNameHandler;

            interface Difference

            interface Difference {}

              property date1

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

              property date2

              date2?: Date;
              • 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 the root directory of the comparison.

              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;

              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;
                  isBrokenLink: boolean;

                    property isDirectory

                    isDirectory: boolean;

                      property isPermissionDenied

                      isPermissionDenied: boolean;
                      isSymlink: boolean;

                        property lstat

                        lstat: fs.Stats;

                          property name

                          name: string;

                            property origin

                            origin: EntryOrigin;
                            • Whether this entry originated from the left or the right dir.

                            property path

                            path: string;

                              property stat

                              stat: fs.Stats;

                                interface FileCompareHandlers

                                interface FileCompareHandlers {}

                                  property defaultFileCompare

                                  defaultFileCompare: CompareFileHandler;

                                  property lineBasedFileCompare

                                  lineBasedFileCompare: CompareFileHandler;
                                  • Compares files line by line.

                                    These additional options are available: * 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 FilterHandlers

                                  interface FilterHandlers {}

                                    property defaultFilterHandler

                                    defaultFilterHandler: FilterHandler;

                                    interface InitialStatistics

                                    interface InitialStatistics {}
                                    • Basic statistics information. Does not have any computed fields.

                                    brokenLinks: BrokenLinksStatistics;
                                    • Stats about broken links.

                                    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

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

                                    index signature

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

                                    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;

                                    property compareFileAsync

                                    compareFileAsync?: CompareFileAsync;
                                    • Extension point used to perform async file content comparison.

                                      See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).

                                    property compareFileSync

                                    compareFileSync?: CompareFileSync;
                                    • Extension point used to perform sync file content comparison.

                                      See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).

                                    property compareNameHandler

                                    compareNameHandler?: CompareNameHandler;
                                    • Extension point used to compare files or directories names.

                                      See [Name comparators](https://github.com/gliviu/dir-compare#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 filterHandler

                                    filterHandler?: FilterHandler;
                                    • Extension point used to control which files or directories should be included in the comparison.

                                      See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter).

                                    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

                                      {
                                      leftPermissionDenied: 0,
                                      rightPermissionDenied: 1,
                                      distinctPermissionDenied: 0,
                                      totalPermissionDenied: 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;
                                    • Extension point used for constructing the Result object.

                                      See [Result builder](https://github.com/gliviu/dir-compare#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?: DiffSet;

                                      interface Statistics

                                      interface Statistics extends InitialStatistics {}
                                      • In addition to fields inherited from InitialStatistics this class adds fields computed at the final stage of the comparison.

                                      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 same

                                      same: boolean;
                                      • True if directories are identical.

                                      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).

                                      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>;
                                        • Extension point used to perform async file content comparison.

                                        type CompareFileSync

                                        type CompareFileSync = (
                                        path1: string,
                                        stat1: fs.Stats,
                                        path2: string,
                                        stat2: fs.Stats,
                                        options: Options
                                        ) => boolean;
                                        • Extension point used to perform sync file content comparison.

                                        type CompareNameHandler

                                        type CompareNameHandler = (
                                        name1: string,
                                        name2: string,
                                        options: Options
                                        ) => 0 | 1 | -1;
                                        • Extension point used to compare files or directories names. 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 DiffSet

                                        type DiffSet = Array<Difference>;
                                        • List of differences occurred during comparison.

                                        type EntryOrigin

                                        type EntryOrigin = 'left' | 'right';

                                          type FilterHandler

                                          type FilterHandler = (
                                          entry: Entry,
                                          relativePath: string,
                                          options: Options
                                          ) => boolean;
                                          • Extension point used to control which files or directories should be included in the comparison.

                                            Parameter entry

                                            Filesystem entry to include or ignore.

                                            Parameter relativePath

                                            Path relative to the root directory of the comparison. It depends on Entry.origin.

                                            Parameter option

                                            Comparison options.

                                            Returns

                                            Returns true if the entry is to be processed or false to ignore it.

                                          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 {@link 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 = (
                                          entry1: Entry | undefined,
                                          entry2: Entry | undefined,
                                          state: DifferenceState,
                                          level: number,
                                          relativePath: string,
                                          options: Options,
                                          statistics: InitialStatistics,
                                          diffSet: DiffSet | undefined,
                                          reason: Reason | undefined,
                                          permissionDeniedState: PermissionDeniedState
                                          ) => void;
                                          • Extension point used for constructing the Result object. Called for each compared entry pair. Updates 'statistics' and 'diffSet'.

                                            Parameter entry1

                                            Left entry.

                                            Parameter entry2

                                            Right entry.

                                            Parameter state

                                            See DifferenceState.

                                            Parameter level

                                            Depth level relative to root dir.

                                            Parameter relativePath

                                            Path relative to the root directory of the comparison.

                                            Parameter statistics

                                            Statistics to be updated.

                                            Parameter diffSet

                                            Status per each entry to be appended. Do not append if Options.noDiffSet is false.

                                            Parameter reason

                                            See Reason. Not available if entries are equal.

                                          Package Files (2)

                                          Dependencies (2)

                                          Dev Dependencies (13)

                                          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>