Recursive, synchronous, and fast file system walker

Downloads in past


14146.0.04 years ago6 years agoMinified + gzip package size for klaw-sync in KB


npm Package Build Status windows Build status JavaScript Style Guide Known Vulnerabilities
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.


npm i klaw-sync


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).
- depthLimit: <Number>
- the number of times to recurse before stopping. `-1` for unlimited.
- fs: <Object>
- custom `fs`, useful when mocking `fs` object.
- filter <Function>
- function that gets one argument `fn({path: '', stats: {}})` and returns true to include or false to exclude the item.
- traverseAll <Boolean>
- traverse all subdirectories, regardless of `filter` option. (When set to `true`, `traverseAll` produces similar behavior to the default behavior prior to v4.0.0. The current default of  `traverseAll: false` is equivalent to the old `noRecurseOnFailedFilter: true`).
  • Return: <Array<Object>> [{path: '', stats: {}}]


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

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 hidden directories
const path = require('path')
const klawSync = require('klaw-sync')

const filterFn = item => {
  const basename = path.basename(item.path)
  return basename === '.' || basename[0] !== '.'

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

filter based on stats
Here traverseAll option is required since we still want to read all directories even if they don't pass the filter function, to see if their contents do 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
benchmark: npm run benchmark

Performance compare to other similar modules

Running some benchmark tests on these modules:

(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)
Running benchmark tests..

root dir length: 1110
walk-sync x 139 ops/sec ±2.48% (76 runs sampled)
klaw-sync x 163 ops/sec ±1.20% (80 runs sampled)
Fastest is klaw-sync

root dir length: 11110
walk-sync x 13.23 ops/sec ±1.10% (37 runs sampled)
klaw-sync x 15.10 ops/sec ±1.06% (41 runs sampled)
Fastest is klaw-sync

root dir length: 111110
walk-sync x 1.17 ops/sec ±2.06% (7 runs sampled)
klaw-sync x 1.25 ops/sec ±2.10% (8 runs sampled)
Fastest is klaw-sync


Special thanks to:

for their contribution and support.


Licensed under MIT