# matched [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [](https://www.npmjs.com/package/matched) [](https://npmjs.org/package/matched) [](https://npmjs.org/package/matched) [](https://travis-ci.org/jonschlinkert/matched)
> Adds array support to node-glob, sync and async. Also supports tilde expansion (user home) and resolving to global npm modules.
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
## Install
Install with [npm](https://www.npmjs.com/) (requires [Node.js](https://nodejs.org/en/) >=10):
```sh
$ npm install --save matched
```
## Usage
```js
const glob = require('matched');
// async signature
glob(patterns[, options]);
// sync signature
glob.sync(patterns[, options]);
```
* `patterns` (string|array) - one or more glob patterns
* `options` - options to pass to [node-glob](https://github.com/isaacs/node-glob);
_Also note that if non-glob file paths are passed, only paths that exist on the file system will be returned._
**promise**
```js
glob(['*.txt'])
.then(files => console.log(files)) //=> ['a.txt', 'b.txt', 'c.txt']
.catch(console.error)
// or with async-await
(async() => {
const files = await glob('*.txt');
console.log(files);
//=> ['foo.txt', 'bar.txt']
})();
```
**callback**
```js
glob(['*.js'], (err, files) => {
console.log(files);
//=> ['utils.js', 'index.js']
});
```
**sync**
```js
const files = glob.sync(['*.js']);
//=> ['utils.js', 'index.js']
```
**options**
All methods take an options object to be forwarded to [node-glob](https://github.com/isaacs/node-glob) as the second argument.
```js
const files = glob(['*.js'], { cwd: 'test' });
console.log(files);
//=> ['test.js']
```
## v4.1
* Adds support for `options.onMatch()` which is passed to [node-glob](https://github.com/isaacs/node-glob) as a listener for the `match` event.
* Adds support for `options.onFiles()` to allow the user to get the files returned by each glob pattern.
* Small optimizations in logic for handling non-glob patterns that are passed for matching literal file names.
## v4.0
* Use [picomatch](https://github.com/micromatch/picomatch) for parsing glob patterns.
## v3.0
* Removes `cache` property from results array.
* Optimizations
## v0.4.1
* Exposes a non-enumerable `cache` property on the returned files array. This is a patch release since the property does not change the existing API and should not otherwise effect behavior or results.
## About
<details>
<summary><strong>Contributing</strong></summary>
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
</details>
<details>
<summary><strong>Running Tests</strong></summary>
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
</details>
<details>
<summary><strong>Building docs</strong></summary>
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
</details>
### Related projects
You might also be interested in these projects:
* [findup-sync](https://www.npmjs.com/package/findup-sync): Find the first file matching a given pattern in the current directory or the nearest… [more](https://github.com/gulpjs/findup-sync#readme) | [homepage](https://github.com/gulpjs/findup-sync#readme "Find the first file matching a given pattern in the current directory or the nearest ancestor directory.")
* [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/micromatch/is-glob) | [homepage](https://github.com/micromatch/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet")
* [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/micromatch/micromatch "Glob matching for javascript/node.js. A replacement and faster alternative to minimatch and multimatch.")
### Contributors
| **Commits** | **Contributor** |
| --- | --- |
| 73 | [jonschlinkert](https://github.com/jonschlinkert) |
| 8 | [TrySound](https://github.com/TrySound) |
| 1 | [sindresorhus](https://github.com/sindresorhus) |
### Author
**Jon Schlinkert**
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
### License
Copyright © 2020, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on January 15, 2020._