node-klaw-sync

klaw-sync is a Node.js recursive and fast 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)
  • nodir <Boolean> default: undefined
    • return only files (ignore directories).
  • nofile <Boolean> default: undefined
    • return only directories (ignore files).
  • depthLimit: <Number> default: -1
    • the number of times to recurse before stopping. -1 for unlimited.
  • fs: <Object> default: graceful-fs
    • custom fs, useful when mocking fs object.
  • filter <Function> default: undefined
    • function that gets one argument fn({path: '', stats: {}}) and returns true to include or false to exclude the item.
  • traverseAll <Boolean> default: undefined
    • traverse all subdirectories, regardless of filter option. This can be useful when you have a filter function and still want to traverse all subdirectories even if your filter function doesn't pass for some directories.
• Return: <Array<Object>> [{path: '', stats: {}}]

Examples

1const klawSync = require('klaw-sync')
2
3const paths = klawSync('/some/dir')
4// paths = [{path: '/some/dir/dir1', stats: {}}, {path: '/some/dir/file1', stats: {}}]

catch error

1const klawSync = require('klaw-sync')
2
3let paths
4try {
5  paths = klawSync('/some/dir')
6} catch (er) {
7  console.error(er)
8}
9console.dir(paths)

files only

1const klawSync = require('klaw-sync')
2
3const files = klawSync('/some/dir', {nodir: true})
4// files = [{path: '/some/dir/file1', stats: {}}, {path: '/some/dir/file2', stats: {}}]

directories only

1const klawSync = require('klaw-sync')
2
3const dirs = klawSync('/some/dir', {nofile: true})
4// dirs = [{path: '/some/dir/dir1', stats: {}}, {path: '/some/dir/dir2', stats: {}}]

ignore hidden directories

1const path = require('path')
2const klawSync = require('klaw-sync')
3
4const filterFn = item => {
5  const basename = path.basename(item.path)
6  return basename === '.' || basename[0] !== '.'
7}
8
9const paths = klawSync('/some/dir', { filter: filterFn})

filter based on stats

Here traverseAll option is required since we still want to read all subdirectories even if they don't pass the filter function, to see if their contents do pass the filter function.

1const klawSync = require('klaw-sync')
2
3const refTime = new Date(2017, 3, 24).getTime()
4const filterFn = item => item.stats.mtime.getTime() > refTime
5
6const paths = klawSync('/some/dir', { traverseAll: true, filter: filterFn })

Run tests

lint: npm run lint

unit test: npm run unit

lint & unit: npm test

benchmark: npm run benchmark

Performance compare to other similar modules

Running some benchmark tests on these modules:

• klaw-sync
• walk-sync

(as of Jan 25, 2017) klaw-sync is the fastest module!

results (tested on Ubuntu 18.04, Intel(R) Core(TM) i7-2630QM CPU @ 2.00GHz, 8 CPUs, 8g RAM, node v10.9.0)

1Running benchmark tests..
2
3root dir length: 1110
4walk-sync x 80.71 ops/sec ±1.42% (72 runs sampled)
5klaw-sync x 160 ops/sec ±1.17% (79 runs sampled)
6Fastest is klaw-sync
7
8root dir length: 11110
9walk-sync x 7.55 ops/sec ±3.39% (23 runs sampled)
10klaw-sync x 14.95 ops/sec ±0.27% (40 runs sampled)
11Fastest is klaw-sync
12
13root dir length: 111110
14walk-sync x 0.63 ops/sec ±6.92% (6 runs sampled)
15klaw-sync x 1.22 ops/sec ±0.96% (7 runs sampled)
16Fastest is klaw-sync

License

Licensed under MIT