Broccoli Funnel

Given an input node, the Broccoli Funnel plugin returns a new node with only a subset of the files from the input node. The files can be moved to different paths. You can use regular expressions to select which files to include or exclude.

Documentation

funnel(inputNode, options)

inputNode {Single node}

A Broccoli node (formerly: "tree"). A node in Broccoli can be either a string that references a directory in your project or a node object returned from running another Broccoli plugin.

If your project has the following file structure:

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select a subsection of the tree via Funnel:

1const funnel = require('broccoli-funnel');
2const cssFiles = funnel('src/css');
3
4/*
5  cssFiles contains the following files:
6
7  ├── reset.css
8  └── todos.css
9*/
10
11// export the node for Broccoli to begin processing
12module.exports = cssFiles;

Options

srcDir {String}

A string representing the portion of the input node to start the funneling from. This will be the base path for any include/exclude regexps.

Default: '.', the root path of the input node.

If your project has the following file structure:

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select a subsection of the node via Funnel:

1const funnel = require('broccoli-funnel');
2const merge = require('broccoli-merge-trees');
3
4// root of our source files
5const projectFiles = 'src';
6
7/* get a new node of only files in the 'src/css' directory
8  cssFiles contains the following files:
9
10  ├── reset.css
11  └── todos.css
12*/
13const cssFiles = funnel(projectFiles, {
14  srcDir: 'css'
15});
16
17/* get a new node of only files in the 'src/icons' directory
18  imageFiles contains the following files:
19
20  ├── check-mark.png
21  └── logo.jpg
22*/
23const imageFiles = funnel(projectFiles, {
24  srcDir: 'icons'
25});
26
27
28module.exports = merge([cssFiles, imageFiles]);

---

destDir {String}

A string representing the destination path that filtered files will be copied to.

Default: '.', the root path of input node.

If your project has the following file structure:

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select a subsection of the directory structure via Funnel and copy it to a new location:

1const funnel = require('broccoli-funnel');
2
3const cssFiles = funnel('src/css', {
4  destDir: 'build'
5});
6
7/*
8  cssFiles contains the following files:
9
10  build/
11  ├── reset.css
12  └── todos.css
13*/
14
15module.exports = cssFiles;

---

allowEmpty {Boolean}

When using srcDir/destDir options only (aka no filtering via include/exclude options), if the srcDir were missing an error would be thrown. Setting allowEmpty to true, will prevent that error by creating an empty directory at the destination path.

---

include {Array of GlobStrings|RegExps|Functions}

One or more matcher expression (regular expression, glob string, or function). Files within the node whose names match this expression will be copied (with the location inside their parent directories preserved) to the destDir.

Default: [].

If your project has the following file structure

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select files that match a glob expression and copy those subdirectories to a new location, preserving their location within parent directories:

1const funnel = require('broccoli-funnel');
2
3// finds all files that match /todo/ and moves them
4// the destDir
5const todoRelatedFiles = funnel('src', {
6  include: ['**/todo*']
7});
8
9/*
10  todoRelatedFiles contains the following files:
11  .
12  ├── css
13  │   └── todos.css
14  └── javascript
15      └── todo.js
16*/
17
18module.exports = todoRelatedFiles;

---

exclude {Array of Glob Strings|Function}

One or more matcher expression (regular expression, glob string, or function). Files within the node whose names match this expression will not be copied to the destDir if they otherwise would have been.

Note, in the case when a file matches both an include and exclude pattern, the exclude pattern wins

Default: [].

If your project has the following file structure:

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select files that match a glob expression and exclude them from copying:

1const funnel = require('broccoli-funnel');
2
3// finds all files in 'src' EXCEPT `todo.js` in any directory
4// or sub-directory and adds them to a node.
5const nobodyLikesTodosAnyway = funnel('src', {
6  exclude: ['**/todo.js']
7});
8
9/*
10  nobodyLikesTodosAnyway contains the following files:
11  .
12  ├── css
13  │   └── reset.css
14  ├── icons
15  │   ├── check-mark.png
16  │   └── logo.jpg
17  └── javascript
18      └── app.js
19*/
20
21module.exports = nobodyLikesTodosAnyway;

---

files {Array of Strings}

One or more relative file paths. Files within the node whose relative paths match will be copied (with the location inside their parent directories preserved) to the destDir.

Default: [].

If your project has the following file structure

1.
2├── Brocfile.js
3└── src/
4    ├── css/
5    │   ├── reset.css
6    │   └── todos.css
7    ├── icons/
8    │   ├── check-mark.png
9    │   └── logo.jpg
10    └── javascript/
11        ├── app.js
12        └── todo.js

You can select a specific list of files copy those subdirectories to a new location, preserving their location within parent directories:

1const funnel = require('broccoli-funnel');
2
3// finds these specific files and moves them to the destDir
4const someFiles = funnel('src', {
5  files: ['css/reset.css', 'icons/check-mark.png']
6});
7
8/*
9  someFiles contains the following files:
10  .
11  ├── css
12  │   └── reset.css
13  └── icons
14      └── check-mark.png
15*/
16
17module.exports = someFiles;

---

getDestinationPath {Function}

This method will get called for each file, receiving the currently processing relativePath as its first argument. The value returned from getDestinationPath will be used as the destination for the new node. This is a very simple way to rename files or move them from one path to another (replacing the need for broccoli-file-mover for example).

The return value of this method is cached for each input file. This means that getDestinationPath will only be called once per relativePath.

In the following example, getDestinationPath is used to move main.js to ember-metal.js:

1const node = funnel('packages/ember-metal/lib', {
2  destDir: 'ember-metal',
3
4  getDestinationPath: function(relativePath) {
5    if (relativePath === 'lib/main.js') {
6      return 'ember-metal.js';
7    }
8
9    return relativePath;
10  }
11});

Extending Funnel

If you desire to extend funnel follow the below snippet

1const { Funnel } = require('broccoli-funnel');
2class CustomFunnel extends Funnel {
3  // cutstom implementation
4}

ZOMG!!! TESTS?!?!!?

I know, right?

Running the tests:

1npm install
2npm test

License

This project is distributed under the MIT license.