find-files-by-patterns

---

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

---

Installation

Using npm:

1npm install find-files-by-patterns

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

1/
2└── Documents
3    ├── data.csv
4    └── project
5        ├── node_modules
6        └── package.json

In Node.js:

1const { findFile, upwardDirectories,
2  ofBasename, downwardFiles } = require("find-files-by-patterns");
3
4(async () => {
5  const dataFile = await findFile(upwardDirectories(), ofBasename("data.csv"));
6  console.log(dataFile); //=> `/Documents/data.csv`
7
8  for await (const file of downwardFiles("/Documents")) {
9    console.log(file);
10  }
11  //=> `/Documents/data.csv`
12  //=> `/Documents/project`
13  //=> `/Documents/project/node_modules` ...
14  //=> `/Documents/project/package.json`
15})();
16

Table of Contents

• API
  • findFile and findFileSync
  • findAllFiles and findAllFilesSync
  • findOnlyFile and findOnlyFileSync
  • downwardDirectories and downwardDirectoriesSync
  • upwardDirectories and upwardDirectoriesSync
  • downwardFiles and downwardFilesSync
  • upwardFiles and upwardFilesSync
  • ofBasename, ofName, ofDirname and ofExtname
  • hasPathSegments
  • isFile and isFileSync
  • isDirectory and isDirectorySync
  • hasFile and hasFileSync
  • readdir and readdirSync
  • readdirs and readdirsSync
  • filter and filterSync
  • conjunction and conjunctionSync
  • disjunction and disjunctionSync
  • allElements and allElementsSync
  • firstElement and firstElementSync
  • onlyElement and onlyElementSync
• About
  • Building the documentation
  • Running the tests
  • Building the library
  • Authors
  • License

API

Complete list of exported functions

Finders:

• findFile and findFileSync
• findAllFiles and findAllFilesSync
• findOnlyFile and findOnlyFileSync

Files:

• downwardFiles and downwardFilesSync
• upwardFiles and upwardFilesSync

Directories:

• downwardDirectories and downwardDirectoriesSync
• upwardDirectories and upwardDirectoriesSync

Filters:

• ofBasename, ofName, ofDirname and ofExtname
• hasPathSegments
• isFile and isFileSync
• isDirectory and isDirectorySync
• hasFile and hasFileSync
• conjunction and conjunctionSync
• disjunction and disjunctionSync

Iterable readdir:

• readdir and readdirSync
• readdirs and readdirsSync

Iterable utilities:

• filter and filterSync
• allElements and allElementsSync
• firstElement and firstElementSync
• onlyElement and onlyElementSync

findFile and findFileSync

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

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4findFile(
5  ...tests: Array<Filter<string> | FilterSync<string>>
6): Promise<string | null>;
7
8findFile(
9  directories: string | AsyncIterable<string> | Iterable<string>,
10  ...tests: Array<Filter<string> | FilterSync<string>>
11): Promise<string | null>;
12
13findFileSync(...tests: Array<FilterSync<string>>): string | null;
14
15findFileSync(
16  directories: string | Iterable<string>,
17  ...tests: Array<FilterSync<string>>
18): string | null;

findAllFiles and findAllFilesSync

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

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4findAllFiles(
5  ...tests: Array<Filter<string> | FilterSync<string>>
6): Promise<string[]>;
7
8findAllFiles(
9  directories: string | AsyncIterable<string> | Iterable<string>,
10  ...tests: Array<Filter<string> | FilterSync<string>>
11): Promise<string[]>;
12
13findAllFilesSync(...tests: Array<FilterSync<string>>): string[];
14
15findAllFilesSync(
16  directories: string | Iterable<string>,
17  ...tests: Array<FilterSync<string>>
18): string[];

findOnlyFile and findOnlyFileSync

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

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4findOnlyFile(
5  ...tests: Array<Filter<string> | FilterSync<string>>
6): Promise<string | null>;
7
8findOnlyFile(
9  directories: string | AsyncIterable<string> | Iterable<string>,
10  ...tests: Array<Filter<string> | FilterSync<string>>
11): Promise<string | null>;
12
13findOnlyFileSync(...tests: Array<FilterSync<string>>): string | null;
14
15findOnlyFileSync(
16  directories: string | Iterable<string>,
17  ...tests: Array<FilterSync<string>>
18): string | null;

downwardDirectories and downwardDirectoriesSync

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

1downwardDirectories(): AsyncIterable<string>;
2
3downwardDirectories(maximumDepth: number): AsyncIterable<string>;
4
5downwardDirectories(startDirectory: string): AsyncIterable<string>;
6
7downwardDirectories(startDirectory: string,
8                    maximumDepth: number): AsyncIterable<string>;
9
10downwardDirectoriesSync(): Iterable<string>;
11
12downwardDirectoriesSync(maximumDepth: number): Iterable<string>;
13
14downwardDirectoriesSync(startDirectory: string): Iterable<string>;
15
16downwardDirectoriesSync(startDirectory: string,
17                        maximumDepth: number): Iterable<string>;

Example

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

1/
2└── Documents
3    ├── Images
4    |   └── image.jpeg
5    └── project
6        ├── node_modules
7        └── package.json

1const { downwardDirectoriesSync } = require("find-files-by-patterns");
2
3[
4  ...downwardDirectoriesSync()
5]; /*=> `[ '/Documents/Images',
6           '/Documents/project',
7           '/Documents/project/node_modules' ]`*/
8[...downwardDirectoriesSync(1)]; /*=> `[ '/Documents/Images',
9                                         '/Documents/project' ]`*/
10[...downwardDirectoriesSync(
11  "/Documents/project"
12)]; //=> `[ '/Documents/project/node_modules' ]`
13[...downwardDirectoriesSync(
14  "/Documents", 1
15)]; //=> `[ '/Documents/Images', '/Documents/project' ]`

upwardDirectories and upwardDirectoriesSync

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

Specifications

1upwardDirectories(): AsyncIterable<string>;
2
3upwardDirectories(startPath: string): AsyncIterable<string>;
4
5upwardDirectories(startPath: string,
6                  maximumHeight: number): AsyncIterable<string>;
7
8upwardDirectories(startPath: string, endPath: string): AsyncIterable<string>;
9
10upwardDirectoriesSync(): Iterable<string>;
11
12upwardDirectoriesSync(startPath: string): Iterable<string>;
13
14upwardDirectoriesSync(startPath: string,
15                      maximumHeight: number): Iterable<string>;
16
17upwardDirectoriesSync(startPath: string, endPath: string): Iterable<string>;

Example

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

1/
2└── Documents
3    ├── Images
4    |   └── image.jpeg
5    └── project
6        ├── node_modules
7        └── package.json

1const { upwardDirectoriesSync } = require("find-files-by-patterns");
2
3[...upwardDirectoriesSync()]; //=> `[ '/Documents', '/' ]`
4[...upwardDirectoriesSync(1)]; //=> `[ '/Documents' ]`
5[...upwardDirectoriesSync(
6  "/Documents/Images/image.jpeg"
7)]; //=> `[ '/Documents/Images', '/Documents', '/' ]`
8[...upwardDirectoriesSync(
9  "/Documents/Images/image.jpeg", 2
10)]; //=> `[ '/Documents/Images', '/Documents' ]`
11[...upwardDirectoriesSync(
12  "/Documents/Images/image.jpeg", "/Documents"
13)]; //=> `[ '/Documents/Images', '/Documents' ]`

downwardFiles and downwardFilesSync

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

Specifications

1downwardFiles(): AsyncIterable<string>;
2
3downwardFiles(maximumDepth: number): AsyncIterable<string>;
4
5downwardFiles(startDirectory: string): AsyncIterable<string>;
6
7downwardFiles(startDirectory: string,
8              maximumDepth: number): AsyncIterable<string>;
9
10downwardFilesSync(): Iterable<string>;
11
12downwardFilesSync(maximumDepth: number): Iterable<string>;
13
14downwardFilesSync(startDirectory: string): Iterable<string>;
15
16downwardFilesSync(startDirectory: string,
17                  maximumDepth: number): Iterable<string>;

upwardFiles and upwardFilesSync

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

Specifications

1upwardFiles(): AsyncIterable<string>;
2
3upwardFiles(startPath: string): AsyncIterable<string>;
4
5upwardFiles(startPath: string, maximumHeight: number): AsyncIterable<string>;
6
7upwardFiles(startPath: string, endPath: string): AsyncIterable<string>;
8
9upwardFilesSync(): Iterable<string>;
10
11upwardFilesSync(startPath: string): Iterable<string>;
12
13upwardFilesSync(startPath: string, maximumHeight: number): Iterable<string>;
14
15upwardFilesSync(startPath: string, endPath: string): Iterable<string>;

ofBasename, ofName, ofDirname and ofExtname

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

1type SegmentTester = string | RegExp | ((segment: string) => boolean);
2
3ofBasename(...tests: SegmentTester[]): FilterSync<string>;
4
5ofName(...tests: SegmentTester[]): FilterSync<string>;
6
7ofDirname(...tests: SegmentTester[]): FilterSync<string>;
8
9ofExtname(...tests: SegmentTester[]): FilterSync<string>;

Example

1const { ofBasename, ofName,
2        ofDirname, ofExtname } = require("find-files-by-patterns");
3
4const isMarkdownFile = ofExtname(".md", ".markdown");
5const isIndexFile = ofName("index");
6const isDataFilename = ofBasename(/^data/);
7const isInDocuments = ofDirname("/Documents");
8
9isMarkdownFile("/Documents/article.md"); //=> `true`
10isMarkdownFile("/Documents/data.json"); //=> `false`
11isIndexFile("/Documents/index.html"); //=> `true`
12isIndexFile("/Documents/index.md"); //=> `true`
13isDataFilename("/Documents/data.json"); //=> `true`
14isInDocuments("/Documents/data.json"); //=> `true`
15isInDocuments("/Documents/src/index.js"); //=> `false`

hasPathSegments

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

1type SegmentTester = string | RegExp | ((segment: string) => boolean);
2
3hasPathSegments(...tests: SegmentTester[]): FilterSync<string>;

Example

1const { hasPathSegments } = require("find-files-by-patterns");
2
3const isIgnored = hasPathSegments(segment => segment.startsWith("_"));
4
5isIgnored("project/src/_ignored.json"); //=> `true`
6
7isIgnored("project/_ignored/data.json"); //=> `true`
8
9isIgnored("project/src/data.yaml"); //=> `false`

isFile and isFileSync

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

Specifications

1isFile(path: string): Promise<boolean>;
2
3isFileSync(path: string): boolean;

isDirectory and isDirectorySync

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

Specifications

1isDirectory(path: string): Promise<boolean>;
2
3isDirectorySync(path: string): boolean;

hasFile and hasFileSync

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

Specifications

1hasFile(test: Filter<string> | FilterSync<string>): Filter<string>;
2
3hasFileSync(test: FilterSync<string>): FilterSync<string>;

Example

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

1/
2└── Documents
3    ├── Images
4    |   └── image.jpeg
5    └── project
6        ├── node_modules
7        └── package.json

1const { findFileSync, upwardDirectoriesSync,
2  hasFileSync, ofBasename } = require("find-files-by-patterns");
3
4const imagesDirectory = findFileSync(
5  upwardDirectoriesSync(),
6  hasFileSync(ofBasename("image.jpeg"))
7); //=> `/Documents/Images`

readdir and readdirSync

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

Specifications

1readdir(directory: string): AsyncIterable<string>;
2
3readdirSync(directory: string): Iterable<string>;

readdirs and readdirsSync

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

Specifications

1readdirs(directory: string): AsyncIterable<string>;
2
3readdirsSync(directory: string): Iterable<string>;

filter and filterSync

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

Specifications

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4filter<T>(iterable: Iterable<T> | AsyncIterable<T>,
5          filter: Filter<T> | FilterSync<T>): AsyncIterable<T>;
6
7filterSync<T>(iterable: Iterable<T>,
8              filter: FilterSync<T>): Iterable<T>;

Example

1const { filterSync, hasPathSegments } = require("find-files-by-patterns");
2
3const paths = [
4  "/Documents/project",
5  "/Documents/project/data.json",
6  "/Documents/project/_directory",
7  "/Documents/project/_directory/data.json"
8];
9[...filterSync(paths, hasPathSegments(segment => !segment.startsWith("_")))];
10//=> `[ '/Documents/project', '/Documents/project/data.json' ]`

conjunction and conjunctionSync

Compounds a sequence of filters using logical conjunction.

Specifications

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4conjunction<T>(filters: Array<Filter<T> | FilterSync<T>>): Filter<T>;
5
6conjunctionSync<T>(filters: Array<FilterSync<T>>): FilterSync<T>;

Example

1const { ofBasename, ofExtname,
2  conjunctionSync } = require("find-files-by-patterns");
3
4const validDataExtensions = [".json", ".yaml", ".csv"];
5const isDataFile = conjunctionSync([  ofBasename(basename => basename.startsWith("data")),  ofExtname(...validDataExtensions)]);
6
7isDataFile("/Documents/project/data.json"); //=> `true`
8isDataFile("/Documents/project/data.yaml"); //=> `true`
9isDataFile("/Documents/project/_data.json"); //=> `false`

disjunction and disjunctionSync

Compounds a sequence of filters using logical disjunction.

Specifications

1type Filter<T> = (element: T) => Promise<boolean>;
2type FilterSync<T> = (element: T) => boolean;
3
4disjunction<T>(filters: Array<Filter<T> | FilterSync<T>>): Filter<T>;
5
6disjunctionSync<T>(filters: Array<FilterSync<T>>): FilterSync<T>;

Example

1const { ofBasename, disjunctionSync } = require("find-files-by-patterns");
2
3const isDataFilename = disjunctionSync([  ofBasename("data.json"),  ofBasename("_data.json")]);
4
5isDataFilename("/Documents/project/data.json"); //=> `true`
6isDataFilename("/Documents/project/_data.json"); //=> `true`
7isDataFilename("/Documents/project/data.yaml"); //=> `false`

allElements and allElementsSync

Converts an iterable to an array.

Specifications

1allElements<T>(iterable: AsyncIterable<T>): Promise<T[]>;
2
3allElementsSync<T>(iterable: Iterable<T>): T[];

firstElement and firstElementSync

Returns the first element of an iterable.

Specifications

1firstElement<T>(iterable: AsyncIterable<T>): Promise<T | null>;
2
3firstElementSync<T>(iterable: Iterable<T>): T | null;

onlyElement and onlyElementSync

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

1onlyElement<T>(iterable: AsyncIterable<T>): Promise<T | null>;
2
3onlyElementSync<T>(iterable: Iterable<T>): T | null;

About

Building the documentation

1npm run doc

Running the tests

1npm run test

Building the library

1npm run build

Authors

• Marc-Antoine Ouimet - MartyO256

License

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