find-files-by-patterns

!Node Version

---

Use the iterator pattern to find files upwards and downwards in the file system.

---

Installation

Using npm:

``sh
npm install find-files-by-patterns
`

Assuming this file system, where the current working directory is
/Documents/project:

`plaintext
/
└── Documents
├── data.csv
└── project
├── node_modules
└── package.json
`

In Node.js:

`js
const { findFile, upwardDirectories,
ofBasename, downwardFiles } = require("find-files-by-patterns");

(async () => {
const dataFile = await findFile(upwardDirectories(), ofBasename("data.csv"));
console.log(dataFile); //=> /Documents/data.csv

for await (const file of downwardFiles("/Documents")) {
console.log(file);
}
//=> /Documents/data.csv
//=> /Documents/project
//=> /Documents/project/node_modules ...
//=> /Documents/project/package.json
})();

`

Table of Contents

API

$3

Finds the first file that matches all of the given filters in the given
directories.
If no directory is supplied, then the current working directory is read.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

findFile(
...tests: Array | FilterSync>
): Promise;

findFile(
directories: string | AsyncIterable | Iterable,
...tests: Array | FilterSync>
): Promise;

findFileSync(...tests: Array>): string | null;

findFileSync(
directories: string | Iterable,
...tests: Array>
): string | null;
`

$3

Finds all the files that match all of the given filters in the given
directories.
If no directory is supplied, then the current working directory is read.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

findAllFiles(
...tests: Array | FilterSync>
): Promise;

findAllFiles(
directories: string | AsyncIterable | Iterable,
...tests: Array | FilterSync>
): Promise;

findAllFilesSync(...tests: Array>): string[];

findAllFilesSync(
directories: string | Iterable,
...tests: Array>
): string[];
`

$3

Finds the first and only file in its directory that matches all of the given
filters.
If no directory is supplied, then the current working directory is read.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

findOnlyFile(
...tests: Array | FilterSync>
): Promise;

findOnlyFile(
directories: string | AsyncIterable | Iterable,
...tests: Array | FilterSync>
): Promise;

findOnlyFileSync(...tests: Array>): string | null;

findOnlyFileSync(
directories: string | Iterable,
...tests: Array>
): string | null;
`

$3

Returns an iterable over the existing downward files from a start path. Symbolic
links are followed and handled such that no directory is traversed twice.

> Specifications

`ts
downwardDirectories(): AsyncIterable;

downwardDirectories(maximumDepth: number): AsyncIterable;

downwardDirectories(startDirectory: string): AsyncIterable;

downwardDirectories(startDirectory: string,
maximumDepth: number): AsyncIterable;

downwardDirectoriesSync(): Iterable;

downwardDirectoriesSync(maximumDepth: number): Iterable;

downwardDirectoriesSync(startDirectory: string): Iterable;

downwardDirectoriesSync(startDirectory: string,
maximumDepth: number): Iterable;
`

> Example

Assuming this file system, where the current working directory is /Documents:

`plaintext
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
`

`js
const { downwardDirectoriesSync } = require("find-files-by-patterns");

[
...downwardDirectoriesSync()
]; /*=> [ '/Documents/Images',
'/Documents/project',
'/Documents/project/node_modules' ]*/
[...downwardDirectoriesSync(1)]; /*=> [ '/Documents/Images',
'/Documents/project' ]*/
[...downwardDirectoriesSync(
"/Documents/project"
)]; //=> [ '/Documents/project/node_modules' ]
[...downwardDirectoriesSync(
"/Documents", 1
)]; //=> [ '/Documents/Images', '/Documents/project' ]
`

$3

Returns an iterable over the existing directories upwards from a start path.

> Specifications

`ts
upwardDirectories(): AsyncIterable;

upwardDirectories(startPath: string): AsyncIterable;

upwardDirectories(startPath: string,
maximumHeight: number): AsyncIterable;

upwardDirectories(startPath: string, endPath: string): AsyncIterable;

upwardDirectoriesSync(): Iterable;

upwardDirectoriesSync(startPath: string): Iterable;

upwardDirectoriesSync(startPath: string,
maximumHeight: number): Iterable;

upwardDirectoriesSync(startPath: string, endPath: string): Iterable;
`

> Example

Assuming this file system, where the current working directory is
/Documents/project:

`plaintext
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
`

`js
const { upwardDirectoriesSync } = require("find-files-by-patterns");

[...upwardDirectoriesSync()]; //=> [ '/Documents', '/' ]
[...upwardDirectoriesSync(1)]; //=> [ '/Documents' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg"
)]; //=> [ '/Documents/Images', '/Documents', '/' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg", 2
)]; //=> [ '/Documents/Images', '/Documents' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg", "/Documents"
)]; //=> [ '/Documents/Images', '/Documents' ]
`

$3

Returns and iterable over the files in each downward directory yielded by
downwardDirectories or downwardDirectoriesSync.

> Specifications

`ts
downwardFiles(): AsyncIterable;

downwardFiles(maximumDepth: number): AsyncIterable;

downwardFiles(startDirectory: string): AsyncIterable;

downwardFiles(startDirectory: string,
maximumDepth: number): AsyncIterable;

downwardFilesSync(): Iterable;

downwardFilesSync(maximumDepth: number): Iterable;

downwardFilesSync(startDirectory: string): Iterable;

downwardFilesSync(startDirectory: string,
maximumDepth: number): Iterable;
`

$3

Returns and iterable over the files in each upward directory yielded by
upwardDirectories or upwardDirectoriesSync.

> Specifications

`ts
upwardFiles(): AsyncIterable;

upwardFiles(startPath: string): AsyncIterable;

upwardFiles(startPath: string, maximumHeight: number): AsyncIterable;

upwardFiles(startPath: string, endPath: string): AsyncIterable;

upwardFilesSync(): Iterable;

upwardFilesSync(startPath: string): Iterable;

upwardFilesSync(startPath: string, maximumHeight: number): Iterable;

upwardFilesSync(startPath: string, endPath: string): Iterable;
`

$3

Determines whether or not a path's basename, name, dirname or extname
matches any of a sequence of segment testers.
A segment tester can be a string, a regular expression or a function.

- If it is a string, then the segment must correspond to it for the path to
match.
- If it is a regular expression, then the segment must test against it for the
path to match.
- If it is a function, then the segment must make it return true for the path
to match.

> Specifications

`ts
type SegmentTester = string | RegExp | ((segment: string) => boolean);

ofBasename(...tests: SegmentTester[]): FilterSync;

ofName(...tests: SegmentTester[]): FilterSync;

ofDirname(...tests: SegmentTester[]): FilterSync;

ofExtname(...tests: SegmentTester[]): FilterSync;
`

> Example

`js
const { ofBasename, ofName,
ofDirname, ofExtname } = require("find-files-by-patterns");

const isMarkdownFile = ofExtname(".md", ".markdown");
const isIndexFile = ofName("index");
const isDataFilename = ofBasename(/^data/);
const isInDocuments = ofDirname("/Documents");

isMarkdownFile("/Documents/article.md"); //=> true
isMarkdownFile("/Documents/data.json"); //=> false
isIndexFile("/Documents/index.html"); //=> true
isIndexFile("/Documents/index.md"); //=> true
isDataFilename("/Documents/data.json"); //=> true
isInDocuments("/Documents/data.json"); //=> true
isInDocuments("/Documents/src/index.js"); //=> false
`

$3

Determines whether or not all the paths segments of a path match a sequence of
segment testers.
A segment tester can be a string, a regular expression or a function.

- If it is a string, then the segment must correspond to it for the path to
match.
- If it is a regular expression, then the segment must test against it for the
path to match.
- If it is a function, then the segment must make it return true for the path
to match.

> Specifications

`ts
type SegmentTester = string | RegExp | ((segment: string) => boolean);

hasPathSegments(...tests: SegmentTester[]): FilterSync;
`

> Example

`js
const { hasPathSegments } = require("find-files-by-patterns");

const isIgnored = hasPathSegments(segment => segment.startsWith("_"));

isIgnored("project/src/_ignored.json"); //=> true

isIgnored("project/_ignored/data.json"); //=> true

isIgnored("project/src/data.yaml"); //=> false
`

$3

Determines whether or not a path exists on the file system and is a file.

> Specifications

`ts
isFile(path: string): Promise;

isFileSync(path: string): boolean;
`

$3

Determines whether or not a path exists on the file system and is a directory.

> Specifications

`ts
isDirectory(path: string): Promise;

isDirectorySync(path: string): boolean;
`

$3

Returns a filter which determines whether or not a path is a directory that has
a file which matches a filter.

> Specifications

`ts
hasFile(test: Filter | FilterSync): Filter;

hasFileSync(test: FilterSync): FilterSync;
`

> Example

Assuming this file system, where the current working directory is
/Documents/project:

`plaintext
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
`

`js
const { findFileSync, upwardDirectoriesSync,
hasFileSync, ofBasename } = require("find-files-by-patterns");

const imagesDirectory = findFileSync(
upwardDirectoriesSync(),
hasFileSync(ofBasename("image.jpeg"))
); //=> /Documents/Images
`

$3

Returns an iterable over the fully qualified file names in the given directory.

> Specifications

`ts
readdir(directory: string): AsyncIterable;

readdirSync(directory: string): Iterable;
`

$3

Returns an iterable over the fully qualified file names in the given sequence of
directories.

> Specifications

`ts
readdirs(directory: string): AsyncIterable;

readdirsSync(directory: string): Iterable;
`

$3

Filters out the iterated elements of an iterable for which the filter function
returns false.
This is analogous to the array filter method.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

filter(iterable: Iterable | AsyncIterable,
filter: Filter | FilterSync): AsyncIterable;

filterSync(iterable: Iterable,
filter: FilterSync): Iterable;
`

> Example

`js
const { filterSync, hasPathSegments } = require("find-files-by-patterns");

const paths = [
"/Documents/project",
"/Documents/project/data.json",
"/Documents/project/_directory",
"/Documents/project/_directory/data.json"
];
[...filterSync(paths, hasPathSegments(segment => !segment.startsWith("_")))];
//=> [ '/Documents/project', '/Documents/project/data.json' ]
`

$3

Compounds a sequence of filters using logical conjunction.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

conjunction(filters: Array | FilterSync>): Filter;

conjunctionSync(filters: Array>): FilterSync;
`

> Example

`js
const { ofBasename, ofExtname,
conjunctionSync } = require("find-files-by-patterns");

const validDataExtensions = [".json", ".yaml", ".csv"];
const isDataFile = conjunctionSync([
ofBasename(basename => basename.startsWith("data")),
ofExtname(...validDataExtensions)
]);

isDataFile("/Documents/project/data.json"); //=> true
isDataFile("/Documents/project/data.yaml"); //=> true
isDataFile("/Documents/project/_data.json"); //=> false
`

$3

Compounds a sequence of filters using logical disjunction.

> Specifications

`ts
type Filter = (element: T) => Promise;
type FilterSync = (element: T) => boolean;

disjunction(filters: Array | FilterSync>): Filter;

disjunctionSync(filters: Array>): FilterSync;
`

> Example

`js
const { ofBasename, disjunctionSync } = require("find-files-by-patterns");

const isDataFilename = disjunctionSync([
ofBasename("data.json"),
ofBasename("_data.json")
]);

isDataFilename("/Documents/project/data.json"); //=> true
isDataFilename("/Documents/project/_data.json"); //=> true
isDataFilename("/Documents/project/data.yaml"); //=> false
`

$3

Converts an iterable to an array.

> Specifications

`ts
allElements(iterable: AsyncIterable): Promise;

allElementsSync(iterable: Iterable): T[];
`

$3

Returns the first element of an iterable.

> Specifications

`ts
firstElement(iterable: AsyncIterable): Promise;

firstElementSync(iterable: Iterable): T | null;
`

$3

Returns the only yielded element of an iterable.
If there is more than one element yielded by the iterable, then an error is
thrown.

> Specifications

`ts
onlyElement(iterable: AsyncIterable): Promise;

onlyElementSync(iterable: Iterable): T | null;
`

About

$3

`sh
npm run doc
`

$3

`sh
npm run test
`

$3

`sh
npm run build
``

$3

- Marc-Antoine Ouimet - MartyO256

$3

This project is licensed under the MIT License. See the LICENSE.md
file for details.