listdirs3.1.1 • Public • Published
List Directories asynchronously in node.js.
We needed an easy way of listing all the directories in a project
so we could watch them for changes.
We reviewed many available options and found them lacking in one of the following areas:
- Untested (or incomplete tests)
- Patchy documentation (often none)
- Unmaintained or Abandoned (many open/unaddressed issues on GitHub)
- Unclear code (written without shoshin)
- Too Many Features trying to do too much. (we only need one thing a list of the directories)
Given an initial directory (e.g. the Current Working Directory) give me a list of all the "child" directories.
Install from NPM
npm install listdirs --save
In your code:
var listdirs = ;var basedir = __dirname; // or which ever base directory you prefer;
(Optional) Supply a List of Files/Directories to Ignore
If you have a large project and want to ignore the files in your .gitignore file (e.g. node_modules), there's an easy way to do this:
var listdirs = ;var ignored = './.gitignore'; //var basedir = __dirname; // or which ever base directory you prefer; // include ignored list as 3rd Parameter (after callback)
Note: This example uses our ignored module: https://www.npmjs.com/package/ignored
as an optional helper to list the entries in .gitignore file
but you can supply your list of ignored files as a simple array e.g:
var ignored = ['node_modules', '.git', '.vagrant', 'etc.'];
Asynchronous (non-blocking) without Async (the module)
The async (module) is good
(as evidenced by its popularity!)
But way too many people use it as a crutch instead of understanding how to write their own asynchronous code.
We have deliberately avoided using async (the module) here, and as a result, listdirs is faster (we benchmarked it!) and includes less bloat.
We have included one dependency on isdir for the sake of splitting out code into "does-only-one-thing" (micro-modules) but isdir has zero dependencies so we know the stack!
As usual, a search on NPM (for list directories) returns many results:
A few of the modules we looked at before deciding to write our own:
- nodejs-walker: https://github.com/daaku/nodejs-walker unclear docs.
- dirtree: https://www.npmjs.com/package/dirtree comes really close to what we want! except it returns a tree object where we want a simple array.
- dirs: https://github.com/jonschlinkert/dirs unclear docs. uses async (=== lazy).
- dirlist: https://www.npmjs.com/package/dirlist (is a directory listing server - not a utility module)
Highly recommend reading the Unix Philosophy if you haven't already.