Cleanly traverse directories in Coffeescript & Javascript

npm install ls
13 downloads in the last day
156 downloads in the last week
698 downloads in the last month

What's "ls"?

ls is a Coffeescript and Javascript module for cleanly traversing directories and listing files.

It has flexible and variable length arguments.


First require:

ls = require "ls"

Then we can be as sparse as

for file in ls "/path"

Or as elaborate as

ls ["/path", "/another/path/"], { recurse: true }, /jpg/, ->
    console.log @name, "is in", @path, "and is", @stat.size


The only required argument is the initial path, the rest can be omitted.

ls [path/s], {config}, /file regex/, -> iterator function

Each file produces an object with the following parameters:

  • path: The path to the file (/foo/bar/)
  • full: The path and file (/foo/bar/baz.jpg)
  • file: The file (baz.jpg)
  • name: The file without an extension (baz)
  • stat: A lazy loaded stat object from fs.Stats

You can either grab the whole list

all_files = ls "/path"
for file in all_files
    console.log, "is", file.stat.size

Or use an iterator function, with the context being the file's object

ls "/path", ->
    console.log @name, "is", @stat.size

The {config} object accepts the following parameters:

  • recurse: Should we recurse into directories? (Boolean, default is false)
  • type: What kind of files should we return? ("all", "dir", "file", default is "all")

The /regex/ will only return matching files. All directories will still be recursed.

The -> iterator function is mostly a style preference, but can be handy if you need to throw an error and stop traversal.


The recommended way is through the excellent npm:

$ npm install ls

Otherwise, you can check it in your repository and then expose it:

$ git clone git:// node_modules/ls/


npm loves you