# @jsdevtools/file-path-filter
> Filters file paths using globs, regular expressions, or custom criteria
Latest version **3.0.2** (published 2020-07-16) · MIT license · 0 weekly downloads
## Install
```sh
npm install @jsdevtools/file-path-filter
pnpm add @jsdevtools/file-path-filter
yarn add @jsdevtools/file-path-filter
bun add @jsdevtools/file-path-filter
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 3.0.2 |
| Published | 2020-07-16 |
| First published | 2020-02-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 1 |
| Unpacked size | 30.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | James Messinger |
| Maintainers | james_messinger, jamesmessinger |
| Keywords | filter, find, file, path, regex, regexp, glob, include, exclude |
## Links
- npm: https://www.npmjs.com/package/@jsdevtools/file-path-filter
- Repository: https://github.com/JS-DevTools/file-path-filter
- Homepage: https://jstools.dev/file-path-filter
- Issues: https://github.com/JS-DevTools/file-path-filter/issues
- npm.io page: https://npm.io/package/@jsdevtools/file-path-filter
## Dependencies (1)
- [glob-to-regexp](https://npm.io/package/glob-to-regexp.md) ^0.4.1
## 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
- 3.0.2 (latest) — 2020-07-16
- 3.0.1 — 2020-03-15
- 3.0.0 — 2020-02-16
- 2.2.2 — 2020-02-16
## README
# File Path Filter
Filters file paths using globs, regular expressions, or custom criteria
[](https://github.com/JS-DevTools/file-path-filter/actions)
[](https://github.com/JS-DevTools/file-path-filter/actions)
[](https://coveralls.io/github/JS-DevTools/file-path-filter)
[](https://david-dm.org/JS-DevTools/file-path-filter)
[](https://www.npmjs.com/package/@jsdevtools/file-path-filter)
[](LICENSE)
[](https://plant.treeware.earth/JS-DevTools/file-path-filter)
Example
--------------------------
```javascript
const filePathFilter = require("@jsdevtools/file-path-filter");
const paths = [
"/some/path/index.html",
"/some/path/contact.html",
"/some/path/about.html",
"/some/path/favicon.ico",
"/some/path/img/logo.png",
];
// Filter using a glob pattern
paths.filter(filePathFilter("**/*.html"));
// Exclude glob patterns with "!"
paths.filter(filePathFilter("**/*.html", "!**/index.html"));
// Filter using a regular expression
paths.filter(filePathFilter(/\.(ico|png)$/));
// Filter using custom criteria
paths.filter(filePathFilter(path => path.length === 23));
// Use any combination of filters
paths.filter(filePathFilter([
"**/*.html",
"!**/index.html",
/\.(ico|png)$/,
path => path.length === 23
]));
// Explicitly specify include and exclude criteria
paths.filter(filePathFilter({
include: [
"**/*.html",
/\.(ico|png)$/,
path => path.length === 23
],
exclude: "**/index.html",
));
```
Installation
--------------------------
You can install File Path Filter via [npm](https://docs.npmjs.com/about-npm/).
```bash
npm install @jsdevtools/file-path-filter
```
Usage
--------------------------
### filePathFilter(criteria)
- **`criteria`** - The filter criteria. This can be any of the following:
- A boolean. `true` will match all files. `false` will not match any files.
- A [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)). If the pattern starts with `!`, then it will be treated as an `exclude` pattern (see below)
- A [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
- A [filter function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter#Syntax) that accepts a file path and returns `true` if the file should be matched
- An array containing any combination of the above types
- An object with `include` and `exclude` properties. Each of these properties can be any of the above types. File paths will be matched if they match any of the `include` criteria and do not match any of the `exclude` criteria.
- **`return value`** - A [filter function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter#Syntax) that matches file paths that meet the specified criteria
### createFilter(options, criteria)
- **`options`** - An object with some or all of the following properties:
- `map` - A function that maps filtered items to file paths
- `sep` - A custom path separator, such as `\` or `/`
- **`criteria`** - The filter criteria. See the [`filePathFilter`](#filepathfiltercriteria) for details.
- **`return value`** - A [filter function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter#Syntax) that matches file paths that meet the specified criteria
The `createFilter` function is an alternative to the `filePathFilter` function that allows you to customize the behavior to suit your needs.
#### Filtering objects
The `filePathFilter` function creates a function that filters arrays of strings, but what if you need to filter an array of objects instead? That's where the `map` option comes in handy. You can use it to map objects (or any other value) to file paths. Here's an example:
```javascript
const { createFilter } = require("@jsdevtools/file-path-filter");
const path = require("path");
const files = [
{ dir: "/my/website", filename: "index.html" },
{ dir: "/my/website", filename: "contact.html" },
{ dir: "/my/website/blog", filename: "post-1.html" },
{ dir: "/my/website/blog", filename: "post-2.html" },
];
// A function to returns the path of each file
function map(file) {
return path.join(file.dir, file.filename);
}
// Filter the file objects - return all HTML files except the blog posts
files.filter(createFilter({ map }, "**/*.html", "!**/blog/*.html"));
```
Contributing
--------------------------
Contributions, enhancements, and bug-fixes are welcome! [Open an issue](https://github.com/JS-DevTools/file-path-filter/issues) on GitHub and [submit a pull request](https://github.com/JS-DevTools/file-path-filter/pulls).
#### Building
To build the project locally on your computer:
1. __Clone this repo__
`git clone https://github.com/JS-DevTools/file-path-filter.git`
2. __Install dependencies__
`npm install`
3. __Build the code__
`npm run build`
4. __Run the tests__
`npm test`
License
--------------------------
File Path Filter is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/JS-DevTools/file-path-filter) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Big Thanks To
--------------------------
Thanks to these awesome companies for their support of Open Source developers ❤
[](https://travis-ci.com)
[](https://saucelabs.com)
[](https://coveralls.io)
---
_Source: https://npm.io/package/@jsdevtools/file-path-filter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._