npm

Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »

listdirs

3.1.1 • Public • Published

listdirs

List Directories asynchronously in node.js.

Build Status codecov Dependency Status npm version Node.js Version

Why?

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:

  1. Untested (or incomplete tests)
  2. Patchy documentation (often none)
  3. Unmaintained or Abandoned (many open/unaddressed issues on GitHub)
  4. Unclear code (written without shoshin)
  5. Too Many Features trying to do too much. (we only need one thing a list of the directories)

too many features

What?

Given an initial directory (e.g. the Current Working Directory) give me a list of all the "child" directories.

How? (Usage)

Install from NPM

npm install listdirs --save

In your code:

var listdirs = require('listdirs');
var basedir = __dirname; // or which ever base directory you prefer
listdirs(basedir, function callback(err, list){
    if(err){
      console.log(err); // handle errors in your preferred way.
    }
    else {
      console.log(list); // use the array of directories as required.
    }
});

(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 = require('listdirs');
var ignored  = require('ignored')('./.gitignore'); // https://github.com/nelsonic/ignored
var basedir  = __dirname; // or which ever base directory you prefer
listdirs(basedir, function callback(err, list){
    if(err){
      console.log(err); // handle errors in your preferred way.
    }
    else {
      console.log(list); // use the array of directories as required.
    }
}, ignored); // 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.'];


Research

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!

Existing Options

As usual, a search on NPM (for list directories) returns many results:

npm-search-list-directories

A few of the modules we looked at before deciding to write our own:

Background Reading

Highly recommend reading the Unix Philosophy if you haven't already.

install

npm i listdirs

Downloadsweekly downloads

140

version

3.1.1

license

ISC

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability