# fs-expand

> An extended fs traverser

Latest version **1.1.2** (published 2016-05-26) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2016-05-26 |
| First published | 2014-01-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.8.0 |
| Dependencies | 5 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | kael |
| Maintainers | kael |
| Keywords | fs, dir, find, ls, glob, ignore |

## Links

- npm: https://www.npmjs.com/package/fs-expand
- Repository: https://github.com/kaelzhang/node-fs-expand
- Homepage: https://github.com/kaelzhang/node-fs-expand#readme
- Issues: https://github.com/kaelzhang/node-fs-expand/issues
- npm.io page: https://npm.io/package/fs-expand

## Dependencies (5)

- [glob](https://npm.io/package/glob.md) ^7.0.3
- [async](https://npm.io/package/async.md) ^1.5.0
- [make-array](https://npm.io/package/make-array.md) ^1.0.1
- [underscore](https://npm.io/package/underscore.md) ^1.8.3
- [wrap-as-async](https://npm.io/package/wrap-as-async.md) ^1.2.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 1.1.2 (latest) — 2016-05-26
- 1.1.1 — 2016-01-28
- 1.1.0 — 2016-01-28
- 1.0.2 — 2015-12-29
- 1.0.1 — 2015-12-29
- 1.0.0 — 2015-07-23
- 0.2.2 — 2015-07-23
- 0.2.1 — 2014-06-16
- 0.2.0 — 2014-06-12
- 0.1.4 — 2014-06-11
- 0.1.3 — 2014-06-11
- 0.1.2 — 2014-02-17
- 0.1.1 — 2014-02-17
- 0.1.0 — 2014-01-27

## README

[![Build Status](https://travis-ci.org/kaelzhang/node-fs-expand.png?branch=master)](https://travis-ci.org/kaelzhang/node-fs-expand)
<!-- [![NPM version](https://badge.fury.io/js/fs-expand.png)](http://badge.fury.io/js/fs-expand)
[![Dependency Status](https://gemnasium.com/kaelzhang/node-fs-expand.png)](https://gemnasium.com/kaelzhang/node-fs-expand) -->

# fs-expand

fs-expand is a standalone module to fetch all file or directory paths that match the given globbing pattern(s), which is much like [`grunt.file.expand`](http://gruntjs.com/api/grunt.file#grunt.file.expand)

The difference from [`glob`](http://www.npmjs.org/package/glob) is that `fs-expand`

- could combine the results of several glob patterns.
- supports negative matching patterns, such as '!*.js'

## expand(pattern, [options], callback);

- pattern `String|Array.<String>` accepts either a single glob pattern or an array of globbing patterns. Paths matching patterns that begin with ! will be excluded from the returned array. Patterns are processed in order, so inclusion and exclusion order is significant.
- options `Object` supports all [glob](https://www.npmjs.org/package/glob) library options
- callback `function(err, files)` the callback function.
- err `Error`
- files `Array.<String>` filenames found matching the pattern(s)

### `options.globOnly`

Type `Boolean=false`

Only process glob patterns, if a file does not contain globstars, `fs-expand` will not check the existence of the file.

```
<cwd>/
     |-- a.js
     |-- b.js
```

```js
expand([
  '*.js',
  'abc.md'
], {
  cwd: cwd,
  globOnly: true

}, function(err, files){
  files;
  // ->
  // [
  //   'a.js',
  //   'b.js',
  //   'abc.md' // actually, abc.md doesn't exist.
  // ]
});
```

### `options.filter`

Type `String|Function`

Either a valid [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) method name or a function that is passed the matched `src` filepath and returns `true` or `false`.

##### `fs.Stats` method name

```js
{
  filter: 'isDirectory'
}
```

##### Filter function

```js
{
  filter: function (src) {
    return fs.statSync(src).isFile()
  }
}
```

It can also be asynchoronous function by using the common [`this.async()`](https://www.npmjs.com/package/wrap-as-async) style, see [wrap-as-async](https://www.npmjs.com/package/wrap-as-async) for details

```js
{
  filter: function (src) {
    // Turns the filter function into an async one by calling `this.async()`
    var done = this.async()
    fs.stat(src, function (err, stat) {
      if (err) {
        return done(err)
      }

      done(null, stat.isFile())
    })
  }
}
```

### Example

```
dir/
   |-- a.js
   |-- b.js
   |-- README.md
```

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

expand(['*.js', '*.md'], {
  cwd: dir
}, function(err, files){
	console.log(files); // ['a.js', 'b.js', README.md]
});
```

## expand.sync(pattern, [options]);

The synchronous version of `expand`.

Returns the filenames found.

```js
var files = expand.sync(['*.js', '!a.js']);

console.log(files); // ['b.js']
```

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