npm package: @jsenv/file-collector
Description: Collect subset of files from a directory
Latest version: 2.0.0

# File collector

[![github package](https://img.shields.io/github/package-json/v/jsenv/jsenv-file-collector.svg?logo=github&label=package)](https://github.com/jsenv/jsenv-file-collector/packages)
[![npm package](https://img.shields.io/npm/v/@jsenv/file-collector.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/file-collector)
[![github ci](https://github.com/jsenv/jsenv-file-collector/workflows/ci/badge.svg)](https://github.com/jsenv/jsenv-file-collector/actions?workflow=ci)
[![codecov coverage](https://codecov.io/gh/jsenv/jsenv-file-collector/branch/master/graph/badge.svg)](https://codecov.io/gh/jsenv/jsenv-file-collector)

Collect subset of files from a directory.

## Table of contents

- [Presentation](#Presentation)
- [collectFiles example](#collectFiles-example)
- [collectFiles parameters](#collectFiles-parameters)
  - [directoryUrl](#directoryUrl)
  - [specifierMetaMap](#specifierMetaMap)
  - [predicate](#predicate)
- [collectFiles return value](#collectFiles-return-value)
- [Installation](#Installation)

## Presentation

This github repository corresponds to `@jsenv/file-collector` package published on github and npm package registries.

`@jsenv/file-collector` can be used to recursively collect files inside a directory.<br />
You can collect only a subset of files using basic pattern matching.

## collectFiles example

> `collectFiles` is an async function collectings a subset of files inside a directory

Implemented in [src/collectFiles.js](./src/collectFiles.js) and could be used as shown below.

```js
import { collectFiles } from "@jsenv/file-collector"

const files = await collectFiles({
  directoryUrl: "file:///Users/you/directory",
  specifierMetaMap: {
    "./**/*.js": {
      whatever: 42,
    },
  },
  predicate: (meta) => {
    return meta.whatever === 42
  },
})
```

## collectFiles parameters

### directoryPath

> `directoryUrl` is a string leading to a directory on your filesystem.

This parameter is **required**, an example value could be:

```js
"file:///Users/you/directory"
```

Values like `"/Users/you/directory"` or `"C:\\Users\\you\\directory"` are also accepted.

### specifierMetaMap

> `specifierMetaMap` is an object associating `specifier` that looks like file paths to arbitrary objects called `meta`.

This parameter is **required**, an example value could be:

```js
{
  "./**/*.js": {
    whatever: 42,
  }
}
```

### predicate

> `predicate` is a function responsible to decide if the file will be collected.

This parameter is **required**, an example value could be:

<!-- prettier-ignore -->
```js
(meta) => meta.whatever === 42
```

## collectFiles return value

`collectFiles` return value is called `matchingFileResultArray`

### matchingFileResultArray

> `matchingFileResultArray` is an array of `matchingFileResult` representing collected files.

See below an example of `matchingFileResultArray`:

```js
[
  {
    relativeUrl: 'directory/file.js',
    meta: { whatever: 42 },
    lstat: {} // Object returned by node.js lstat on that file,
    operationResult: undefined, // not documented, ignore this
  }
]
```

## Installation

If you have never installed a jsenv package, read [Installing a jsenv package](https://github.com/jsenv/jsenv-core/blob/master/docs/installing-jsenv-package.md#installing-a-jsenv-package) before going further.

This documentation is up-to-date with a specific version so prefer any of the following commands

```console
npm install --save-dev @jsenv/file-collector@2.0.0
```

```console
yarn add --dev @jsenv/file-collector@2.0.0
```