traverse-folders

Traverse nested folders and process each of the discovered files.

Prerequisites

This library assumes:

1. You are using NodeJS 8+

Install

Add traverse-folders as a dependency:

npm i traverse-folders

Examples

A common use of traverse-folders is to automatically load a nested hierarchy of functions into an index.js file.

Consolidating API route controllers

For example, let's say you are writing an API server with the following folder hierarchy.

src/
  api/
    index.js
    ping.js
    version.js
    /things
      /createThing.js
      /deleteThings.js
      /getThing.js
      /listThings.js
      /updateThing.js

In src/api/index.js you could put the following:

const path = require('path')
const traverse = require('traverse-folders')

const pathSeparator = new RegExp(path.sep, 'g')

const apis = {}
const base = __dirname

const processor = file => {
  const name = file.slice(base.length + 1, -3).replace(pathSeparator, '_')
  apis[name] = require(file)
}

traverse(base, processor)

module.exports = apis

Then when index.js is first required it will load all the underlying code and expose

{
  ping,
  version,
  things_createThing,
  things_deleteThing,
  things_getThing,
  things_listThings,
  things_updateThing,
}

with each api correctly linked to the underlying function.

Making a mockAPI that stays in sync with your real API

Now let's suppose, in your tests, you want to create a mock API that has the same function names, but instead of actually loading the functions, it associates each name with a stub

In test/utils/mockAPI.js you could write

const path = require('path')
const { stub } = require('sinon')
const traverse = require('traverse-folders')

const pathSeparator = new RegExp(path.sep, 'g')

const mockApi = {}
const apiPath = 'src/api'
const processor = file => {
  const name = file.slice(apiPath.length + 1, -3).replace(pathSeparator, '_')
  names[name] = stub()
}

traverse(apiPath, processor)

module.exports = mockApi

Now your mockAPI can be used in unit tests in place of the real API, without referencing the real API at all. This can be important if your API controllers refer to Sequelize models that might trigger an unwanted database connection. (Unit tests must not depend on external services.)

By customising the processor function you can use traverse-folders to auto-load Sequelize models, ExpressJS middleware, and all manner of other things.

Options

By default traverse will ignore any index.js files and only process files ending in '.js'. To override this behaviour you can pass an options object as the final parameter.

The defaults are:

{
  ignore: 'index.js',
  suffix: '.js'
}

So traverse(apiPath, processor, { ignore: 'index.jxs', suffix: '.jsx' }) will ensure that only files ending in .jsx get loaded, but will ignore 'index.jsx'.

Other ignore options

• ignore can be a regular expression, so traverse(apiPath, processor, { ignore: /-/ }) will ensure that only files ending in .js get loaded, and will ignore any files with a dash in their name.
• ignore can also be a function, so traverse(apiPath, processor, { ignore: file => file === 'index.js' }) will ensure that only files ending in .js get loaded, but will ignore 'index.js'.
• if ignore is not a string, regular expression, or function, it's ignored.

Development

Branches

| Branch | Status | Coverage | Notes | | ------ | ------ | -------- | - | | develop | | | Work in progress | | master | | | Latest stable release |

Prerequisites

• NodeJS — Version 8.10 or better.

Test it

• npm test — runs the unit tests.
• npm run test:unit:cov — runs the unit tests with coverage reporting.
• npm run test:mutants — runs the mutation tests.

Lint it

npm run lint

Contributing

Please see the contributing notes.

Thanks

• Thanks to reallinfo for the logo.