# expand-files

> Expand glob patterns in a declarative configuration into src-dest mappings.

Latest version **0.8.4** (published 2016-06-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install expand-files
pnpm add expand-files
yarn add expand-files
bun add expand-files
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.4 |
| Published | 2016-06-25 |
| First published | 2015-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 13 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Jon Schlinkert |
| Maintainers | doowb, jonschlinkert |
| Keywords | config, configuration, dest, destination, expand, files, files array, files object, normalize, options, src, src-dest, target, task |

## Links

- npm: https://www.npmjs.com/package/expand-files
- Repository: https://github.com/jonschlinkert/expand-files
- Issues: https://github.com/jonschlinkert/expand-files/issues
- npm.io page: https://npm.io/package/expand-files

## Dependencies (13)

- [base](https://npm.io/package/base.md) ^0.11.1
- [matched](https://npm.io/package/matched.md) ^0.4.1
- [has-glob](https://npm.io/package/has-glob.md) ^0.1.1
- [relative](https://npm.io/package/relative.md) ^3.0.2
- [lazy-cache](https://npm.io/package/lazy-cache.md) ^2.0.1
- [glob-parent](https://npm.io/package/glob-parent.md) ^2.0.0
- [object.omit](https://npm.io/package/object.omit.md) ^2.0.0
- [resolve-dir](https://npm.io/package/resolve-dir.md) ^0.1.0
- [base-plugins](https://npm.io/package/base-plugins.md) ^0.4.13
- [expand-utils](https://npm.io/package/expand-utils.md) ^0.2.1
- [extend-shallow](https://npm.io/package/extend-shallow.md) ^2.0.1
- [define-property](https://npm.io/package/define-property.md) ^0.2.5
- [normalize-config](https://npm.io/package/normalize-config.md) ^0.4.8

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.8.4 (latest) — 2016-06-25
- 0.8.3 — 2016-06-03
- 0.8.2 — 2016-06-03
- 0.8.1 — 2016-06-03
- 0.8.0 — 2016-06-03
- 0.7.1 — 2016-01-06
- 0.7.0 — 2016-01-06
- 0.6.7 — 2016-01-06
- 0.6.6 — 2015-11-14
- 0.6.5 — 2015-11-13
- 0.6.4 — 2015-11-13
- 0.6.3 — 2015-11-12
- 0.6.2 — 2015-11-12
- 0.6.1 — 2015-11-12
- 0.6.0 — 2015-11-12
- … 17 more at https://npm.io/package/expand-files/versions

## README

# expand-files [![NPM version](https://img.shields.io/npm/v/expand-files.svg?style=flat)](https://www.npmjs.com/package/expand-files) [![NPM downloads](https://img.shields.io/npm/dm/expand-files.svg?style=flat)](https://npmjs.org/package/expand-files) [![Build Status](https://img.shields.io/travis/jonschlinkert/expand-files.svg?style=flat)](https://travis-ci.org/jonschlinkert/expand-files)

Expand glob patterns in a declarative configuration into src-dest mappings.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save expand-files
```

**Examples**

Expands `src` glob patterns and creates `dest` mappings:

```js
var files = require('expand-files');

// pass any "global" options to `files`
config = files({cwd: 'test/fixtures'});

// src, dest list
config.expand('*.txt', 'dist/');

// expand src-dest object 
config.expand({
  src: '*.txt',
  dest: 'dist/'
});

// expand src-dest mappings 
config.expand({
  'dist/': '*.txt'
});

// expand files objects
config.expand({
  files: {
    'dist/': '*.txt'
  }
});

// expand files arrays
config.expand({
  files: [
    {src: '*.txt', dest: 'dist/'}
    //...
  ]
});
```

**Results**

All of the above result in the following array:

```js
[
  {src: ['test/fixtures/a.txt'], dest: 'dist/a.txt'},
  {src: ['test/fixtures/b.txt'], dest: 'dist/b.txt'},
  {src: ['test/fixtures/c.txt'], dest: 'dist/c.txt'},
  {src: ['test/fixtures/d.txt'], dest: 'dist/d.txt'}
]
```

See [examples](./examples.md) of possible configurations.

## Table of contents

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save expand-files
```

## Usage

```js
var files = require('expand-files');
var config = files(options);

// pass a list of arguments
config.expand('src', 'dest', options);

// or an object with `src`/`dest`
config.expand({
  options: options,
  src: ['src'], 
  dest: 'dest'
});

// or an object with a `files` object
config.expand({
  options: options,
  files: {
    src: 'src',
    dest: 'dest'
  }
});

// or an object with `files` mappings
config.expand({
  options: options,
  files: {
    'foo/': '*.js',
    'bar/': '*.js',
    'baz/': '*.js'
  }
});

// or an object with an array of `files` objects
config.expand({
  options: options,
  files: [
    {src: 'src', dest: 'dest'}
  ]
});

// or an object with an array of glob patterns
config.expand({
  options: options,
  files: ['*.js', '*.txt']
});
```

## dest behavior

By default, `src` is appended to the defined `dest`. If `flatten` is true, then `src` basename is appended to `dest`.

**Examples**

```js
config.expand({src: 'index.js', dest: 'dist/'});
//=> [ { src: [ 'index.js' ], dest: 'dist/' } ]

config.expand({src: 'index.js', dest: 'dist/', mapDest: true});
//=> [{ src: [ 'index.js' ], dest: 'dist/index.js' } ]
```

## Plugins

Plugins can be used to modify to resulting object. A plugin is a function that takes `config` as its only parameter.

**Example**

```js
var config = new Files();
function addFoo(config) {
  config.foo = 'bar';
}
config.use(addFoo);
console.log(config.expand({src: '*.js'}).files);
```

Results in an object that looks something like:

```js
{
  options: {},
  foo: 'bar', //<= our added property
  files: [{ 
    options: {}, 
    src: ['examples.js', 'gulpfile.js', 'index.js', 'utils.js'], 
    dest: '' } 
  ] 
}
```

### Nodes

It's also possible to modify individual files nodes as they're created on the `files` array. To do so, simply return a function in the plugin and it will be called on each node.

Additionally, you can either modify the node before it's normalized or after, by checking for the `rawNode` property or `filesNode` respectively.

**Examples**

```js
var config = new Files();
function updateNode(config) {
  config.foo = 'bar';

  return function fn(node) {
    if (!node.filesNode) return fn;
    // return the plugin function if it's not a filesNode
    // this way we know with certainty that `node`
    // will be a filesNode
    node.options.one = 'two';
    node.dest = 'baz/';
    node.abc = 'xyz';
  };
}
config.use(updateNode);
console.log(config.expand({src: '*.js'}).files);
```

Results in an object that looks something like:

```js
{
  options: {},
  foo: 'bar', //<= our added `config` property
  files: [{ 
    options: { one: 'two' }, 
    src: ['examples.js', 'gulpfile.js', 'index.js', 'utils.js'], 
    dest: 'baz/',
    abc: 'xyz' } 
  ] 
}
```

## Examples

Supports any of the formats supported by the [files-objects](https://github.com/jonschlinkert/files-objects) library as well as any of the configurations in [examples.md](./examples.md).

## options

### mapDest

Expand src-dest mappings. Creates a `dest` filepath for each `src` filepath.

**Type**: `Boolean`

**Default**: `undefined`

**Example:**

```js
config.expand({src: 'test/fixtures/*.js', dest: 'dist/', mapDest: true});
```

**results in**

```js
[ 
  {src: [ 'test/fixtures/x.js' ], dest: 'dist/test/fixtures/x.js' },
  {src: [ 'test/fixtures/y.js' ], dest: 'dist/test/fixtures/y.js' },
  {src: [ 'test/fixtures/z.js' ], dest: 'dist/test/fixtures/z.js' } 
]
```

### flatten

Flatten destination paths. Joins the `src` basename to the defined `dest` path.

**Type**: `Boolean`

**Default**: `undefined`

**Example:**

```js
config.expand({src: 'test/fixtures/*.js', dest: 'dist/', mapDest: true, flatten: true});
```

**results in**

```js
[ 
  {src: [ 'test/fixtures/x.js' ], dest: 'dist/x.js' },
  {src: [ 'test/fixtures/y.js' ], dest: 'dist/y.js' },
  {src: [ 'test/fixtures/z.js' ], dest: 'dist/z.js' } 
]
```

### ext

The extension to use on dest files.

**Type**: `String`

**Default**: `undefined`

**Example:**

```js
config.expand({src: '*.coffee', dest: 'dist/', ext: '.js'});
```

### extDot

The part of the extension to use on dest files when the extension is automatically mapped from `src` files.

**Type**: `String`

**Default**: `undefined`

**Choices**:

* `first`: everything after the first dot
* `last`: everything after the last dot

**Example:**

```js
config.expand({src: '*.js', dest: 'dist/', extDot: 'first'});
```

### cwd

**Type**: `String`

**Default**: `undefined`

**Example:**

```js
config.expand({src: '*.js', dest: 'dist/', cwd: true});
```

### rename

**Type**: `Function`

**Default**: `src` is appended to the defined `dest`. If `flatten` is true, then `src` basename is appended to `dest`.

**Example:**

```js
config.expand({
  src: '*.js', 
  dest: 'dist/', 
  rename: true
});
```

### filter

Filter by `fs.lstat` "type" or using a custom filter function.

**Type**: `Function|String`.

**Default**: `undefined`

**Example:**

Filter by `fs.lstat` method name:

```js
config.expand({src: '**/*', dest: 'dist/', filter: 'isFile'});
```

Filter function:

```js
config.expand({
  options: {
    filter: function (str) {
      return !/DS_Store/.test(str);
    }
  },
  // dotfiles
  src: ['.*']
});

// [ { src:
//      [ '.editorconfig',
//        '.git',
//        '.gitattributes',
//        '.gitignore',
//        '.jshintrc',
//        '.travis.yml',
//        '.verb.md' ],
//     dest: '' } ]
```

### options properties

The below "special" properties are fine to use either on an `options` object or on the root of the object passed to `expand-files`.

Either way they will be normalized onto the `options` object to ensure that [globby](https://github.com/sindresorhus/globby) and consuming libraries are passed the correct arguments.

**special properties**

* `base`
* `cwd`
* `destBase`
* `mapDest`
* `ext`
* `extDot`
* `extend`
* `flatten`
* `rename`
* `process`
* `srcBase`

**example**

Both of the following will result in `mapDest` being on the `options` object.

```js
config.expand({src: '*.js', dest: 'dist/', options: {mapDest: true}});
config.expand({src: '*.js', dest: 'dist/', mapDest: true});
```

Both result in something like:

```js
{
  options: { mapDest: true },
  files:
   [ { options: {}, src: [...], dest: 'dist/examples.js' },
     { options: {}, src: [...], dest: 'dist/gulpfile.js' },
     { options: {}, src: [...], dest: 'dist/index.js' },
     { options: {}, src: [...], dest: 'dist/utils.js' } ] 
}
```

## Coverage

```
Statements   : 100% (106/106)
Branches     : 100% (57/57)
Functions    : 100% (11/11)
Lines        : 100% (104/104)
```

## Related projects

You might also be interested in these projects:

* [expand](https://www.npmjs.com/package/expand): Recursively resolve templates in an object, string or array. | [homepage](https://github.com/jonschlinkert/expand "Recursively resolve templates in an object, string or array.")
* [expand-config](https://www.npmjs.com/package/expand-config): Expand tasks, targets and files in a declarative configuration. | [homepage](https://github.com/jonschlinkert/expand-config "Expand tasks, targets and files in a declarative configuration.")
* [expand-files](https://www.npmjs.com/package/expand-files): Expand glob patterns in a declarative configuration into src-dest mappings. | [homepage](https://github.com/jonschlinkert/expand-files "Expand glob patterns in a declarative configuration into src-dest mappings.")
* [expand-target](https://www.npmjs.com/package/expand-target): Expand target definitions in a declarative configuration. | [homepage](https://github.com/jonschlinkert/expand-target "Expand target definitions in a declarative configuration.")
* [expand-task](https://www.npmjs.com/package/expand-task): Expand and normalize task definitions in a declarative configuration. | [homepage](https://github.com/jonschlinkert/expand-task "Expand and normalize task definitions in a declarative configuration.")
* [expand-utils](https://www.npmjs.com/package/expand-utils): Utils shared by the expand libs. | [homepage](https://github.com/jonschlinkert/expand-utils "Utils shared by the expand libs.")
* [map-dest](https://www.npmjs.com/package/map-dest): Map the destination path for a file based on the given source path and options. | [homepage](https://github.com/jonschlinkert/map-dest "Map the destination path for a file based on the given source path and options.")
* [normalize-config](https://www.npmjs.com/package/normalize-config): Normalize a declarative configuration with any combination of src-dest mappings, files arrays, files objects and… [more](https://github.com/jonschlinkert/normalize-config) | [homepage](https://github.com/jonschlinkert/normalize-config "Normalize a declarative configuration with any combination of src-dest mappings, files arrays, files objects and options into a consistent format so the config can easily be passed to any build system.")

## Contributing

This document was generated by [verb-readme-generator](https://github.com/verbose/verb-readme-generator) (a [verb](https://github.com/verbose/verb) generator), please don't edit directly. Any changes to the readme must be made in [.verb.md](.verb.md). See [Building Docs](#building-docs).

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

Or visit the [verb-readme-generator](https://github.com/verbose/verb-readme-generator) project to submit bug reports or pull requests for the readme layout template.

## Building docs

_(This document was generated by [verb-readme-generator](https://github.com/verbose/verb-readme-generator) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

Generate readme and API documentation with [verb](https://github.com/verbose/verb):

```sh
$ npm install -g verb verb-readme-generator && verb
```

## Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

## Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

## License

Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT license](https://github.com/jonschlinkert/expand-files/blob/master/LICENSE).

***

_This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on June 25, 2016._

---
_Source: https://npm.io/package/expand-files · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._