node-walk-sync

Return an array containing all recursive files and directories under a given directory, similar to Unix find. Follows symlinks. Optimized for speed.

fs.readdirSync() comparison

As of Node 20, I recommend using the built-in function fs.readdirSync with { recursive: true } for basic use cases, which tends to be even faster:

const paths = fs.readdirSync('some/dir', { recursive: true }).sort()
// equivalent to walkSync('some/dir')

This walk-sync package differs from fs.readdirSync in the following ways:

• It adds trailing slashes to directories.
• It provides a few extra options (see below).
• It sorts by default, in order to avoid non-deterministic behavior.
• Like fs.readdirSync, it follows symlinks, but it avoids descending into cycles caused by symlinks.

Installation

npm install walk-sync

Usage

const walkSync = require('walk-sync');
const paths = walkSync('project')

Given project/one.txt and project/subdir/two.txt, paths will be the following array:

['one.txt', 'subdir/', 'subdir/two.txt']

Directories come before their contents, and have a trailing forward-slash (on all platforms).

Symlinks are followed.

Entries

Sometimes, it is important to get additional information from a walk of a directory; for instance if the downstream consumer needs to stat the files we can leverage the stats from the walk.

To accommodate, walkSync.entries(path [, options]) is also provided, instead of returning a list of files and/or directories it returns an array of objects which correspond to a given file or directory, except with more data.

entry.relativePath
entry.mode  // => fs.statSync(fullPath).mode
entry.size  // => fs.statSync(fullPath).size
entry.mtime // => fs.statSync(fullPath).mtime.getTime()

entry.isDirectory() // => true if directory

Options

• globs: An array of globs. Only files and directories that match at least one of the provided globs will be returned.

    const paths = walkSync('project', { globs: ['subdir/**/*.txt'] });
    // => ['subdir/two.txt']
  

  As an alternative to string globs, you can pass an array of precompiled minimatch.Minimatch instances. This is faster and allows to specify your own globbing options.

• directories (default: true): Pass false to only return files, not directories:

    const paths = walkSync('project', { directories: false })
    // => ['one.txt', 'subdir/two.txt']
  

• ignore: An array of globs. Files and directories that match at least one of the provided globs will be pruned while searching.

    const paths = walkSync('project', { ignore: ['subdir'] })
    // => ['one.txt']
  

  As an alternative to string globs, you can pass an array of precompiled minimatch.Minimatch instances. This is faster and allows to specify your own globbing options.

• includeBasePath (default: false): Pass true to include the basePath in the output. note: this flag is only for walkSync(..) not walkSync.entries(..)

    const paths = walkSync('project', { includeBasePath: true });
    // => ['project/one.txt', 'project/subdir/two.txt']
  

• fs: Allows an alternative implementation of fs to be supplied. examples of alternative file systems include memfs or graceful-fs

    import {Volume, createFsFromVolume} from 'memfs'
    const fs = createFsFromVolume(Volume.fromJSON({'aDir/aFile': 'some-contents'}))
    const paths = walkSync('project', { fs });
    // => ['aDir/', 'aDir/aFile']
  

• globOptions: Pass any options for Minimatch that will be applied to all items in globs and ignore that are strings.

  If items in globs or ignore are instances of minimatch.Minimatch, the globOptions will not be applied.

Background

walkSync(baseDir) is a faster substitute for

```js glob.sync('**', { cwd: baseDir, dot: true, mark: true, strict: true })

master

4.0.1

• Update README

4.0.0

• Upgrade dependencies, in particular minimatch 10
• Require Node version 20 or newer
• Fix z/OS compatibility (#72)

3.0.0

• [BREAKING] drop node 8
• upgrade all deps
• move to GH Actions
• [Bugfix] handle EPERM from windows filesystems correctly

2.2.0

• add globOptions to provide the capability to configure string globs with all minimatch options passed to globs and ignored

2.1.0

• Add the ability to provide an alternative fs implementation via options.

2.0.0

• Drop support for unsupported Node versions (Support 8.* + >= 10)

1.1.0

• [Bugfix] break cycles caused by symlinks. Specifically, when traversing directory structures we now no longer re-enter.

1.0.1

• fix typescript typings entry.mtime is number not date

1.0.0

• no changes, simply releasing as 1.0.0 to signify stability

0.3.4

• added includeBaseDir to doc
• ES6ify the readme

0.3.3

• Added Typescript types

0.3.2

• add includeBasePath so walkSync results are prepended with the basePath.

0.3.1

• whitelist index.js for publish (don't publish uneeded files)

0.3.0

• add ignore globs

0.2.7

• [BUGFIX] Previously walkSync returned entries sorted by relativePath almost, but not quite, lexicographically. This now sorts lexicographically in all cases.

0.2.6

• On Windows, normalize backslashes in root path to forward slashes

0.2.5

• Exclude all non-essential files from npm

0.2.4

• Fix file entries to have a numeric timestamp rather than a Date

0.2.3

• Extract matcher-collection into separate package

0.2.2

• Add walkSync.entries, which returns objects instead of files

0.2.1

• Add directories flag
• Allow passing the globs array as a globs option

0.2.0

• Add optional globArray parameter

0.1.3

• Switch to fs.statSync (instead of fs.lstatSync) to follow symlinks.

0.1.2

• Sort readdir entries for deterministic behavior

0.1.1

• Do not follow symlinks (as advertised)

0.1.0

• Bump version without change, to allow for caret/tilde dependencies

0.0.1

• Initial release