klaw-sync

node-klaw-sync

klaw-sync is a Node.js recursive file system walker, which is the synchronous counterpart of klaw. It lists all files and directories inside a directory recursively and returns an array of objects that each object has two properties: path and stats. path is the full path of the file or directory and stats is an instance of fs.Stats.

Install

npm i klaw-sync

Usage

klawSync(directory[, options])

• directory <String>

• options <Object> (optional) all options are false by default

  • nodir <Boolean>
    • return only files (ignore directories)
  • nofile <Boolean>
    • return only directories (ignore files)
  • noRecurseOnFailedFilter <Boolean>
    • when filter function is used, the default behavior is to read all directories even if they don't pass the filter function (won't be included but still will be traversed). If you set true, there will be neither inclusion nor traversal for directories that don't pass the filter function
  • filter <Function>
    • function that gets one argument fn({path: '', stats: {}}) and returns true to include or false to exclude the item

• Return: <Array<Object>> [{path: '', stats: {}}]

Examples

const klawSync = require('klaw-sync')

const paths = klawSync('/some/dir')
// paths = [{path: '/some/dir/dir1', stats: {}}, {path: '/some/dir/file1', stats: {}}]

catch error

const klawSync = require('klaw-sync')

let paths
try {
  paths = klawSync('/some/dir')
} catch (er) {
  console.error(er)
}
console.dir(paths)

files only

const klawSync = require('klaw-sync')

const files = klawSync('/some/dir', {nodir: true})
// files = [{path: '/some/dir/file1', stats: {}}, {path: '/some/dir/file2', stats: {}}]

directories only

const klawSync = require('klaw-sync')

const dirs = klawSync('/some/dir', {nofile: true})
// dirs = [{path: '/some/dir/dir1', stats: {}}, {path: '/some/dir/dir2', stats: {}}]

ignore node_modules

Notice here noRecurseOnFailedFilter: true option is used since we don't want anything from node_modules (no inclusion and no traversal).

const klawSync = require('klaw-sync')

const filterFn = item => item.path.indexOf('node_modules') < 0

const paths = klawSync('/some/dir', { filter: filterFn, noRecurseOnFailedFilter: true })

ignore node_modules and .git

const klawSync = require('klaw-sync')

const filterFn = item => item.path.indexOf('node_modules') < 0 && item.path.indexOf('.git') < 0

const paths = klawSync('/some/dir', { filter: filterFn, noRecurseOnFailedFilter: true })

get all js files

Here noRecurseOnFailedFilter option is not required since we are interested in all js files. In other words, although no directories pass the filter function, we still want to read them and see if they have any js files.

const path = require('path')
const klawSync = require('klaw-sync')

const filterFn = item => path.extname(item.path) === '.js'

const paths = klawSync('/some/dir', { filter: filterFn })

filter based on stats

Again here noRecurseOnFailedFilter option is not required since we still want to read all directories even though they don't pass the filter function, to see if their contents pass the filter function.

const klawSync = require('klaw-sync')

const refTime = new Date(2017, 3, 24).getTime()
const filterFn = item => item.stats.mtime.getTime() > refTime

const paths = klawSync('/some/dir', { filter: filterFn })

Run tests

lint: npm run lint

unit test: npm run unit

lint & unit: npm test

Performance compare to other similar modules

The bm.js runs some basic benchmark tests for two cases: basic usage and with --nodir=true (get files only), on these modules:

• klaw-sync
• walk-sync
• glob.sync

It turned out (as of January 25, 2017) for the most cases klaw-sync is faster than other modules!

run benchmark

npm run benchmark -- --dir=/some/dir

npm run benchmark -- --dir=/some/dir --nodir=true

Credit

Special thanks to:

• agnivade
• jprichardson
• RyanZim

for their contribution and support.

License

Licensed under MIT