Find files by patterns in directories, upwards or downwards from other paths.
npm install find-files-by-patterns
!Node Version




---
Use the iterator pattern to find files upwards and downwards in the file system.
---
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
//=>
})();
`
- 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
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
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
type FilterSync
findFile(
...tests: Array
): Promise
findFile(
directories: string | AsyncIterable
...tests: Array
): Promise
findFileSync(...tests: Array
findFileSync(
directories: string | Iterable
...tests: Array
): string | null;
`
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
type FilterSync
findAllFiles(
...tests: Array
): Promise
findAllFiles(
directories: string | AsyncIterable
...tests: Array
): Promise
findAllFilesSync(...tests: Array
findAllFilesSync(
directories: string | Iterable
...tests: Array
): string[];
`
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
type FilterSync
findOnlyFile(
...tests: Array
): Promise
findOnlyFile(
directories: string | AsyncIterable
...tests: Array
): Promise
findOnlyFileSync(...tests: Array
findOnlyFileSync(
directories: string | Iterable
...tests: Array
): string | null;
`
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' ]*/[ '/Documents/Images',
[...downwardDirectoriesSync(1)]; /*=>
'/Documents/project' ]*/[ '/Documents/project/node_modules' ]
[...downwardDirectoriesSync(
"/Documents/project"
)]; //=> [ '/Documents/Images', '/Documents/project' ]
[...downwardDirectoriesSync(
"/Documents", 1
)]; //=> `
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', '/' ][ '/Documents' ]
[...upwardDirectoriesSync(1)]; //=> [ '/Documents/Images', '/Documents', '/' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg"
)]; //=> [ '/Documents/Images', '/Documents' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg", 2
)]; //=> [ '/Documents/Images', '/Documents' ]
[...upwardDirectoriesSync(
"/Documents/Images/image.jpeg", "/Documents"
)]; //=> `
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
`
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
`
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"); //=> truefalse
isMarkdownFile("/Documents/data.json"); //=> true
isIndexFile("/Documents/index.html"); //=> true
isIndexFile("/Documents/index.md"); //=> true
isDataFilename("/Documents/data.json"); //=> true
isInDocuments("/Documents/data.json"); //=> false
isInDocuments("/Documents/src/index.js"); //=> `
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`
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;
`
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;
`
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
hasFileSync(test: 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`
Returns an iterable over the fully qualified file names in the given directory.
> Specifications
`ts
readdir(directory: string): AsyncIterable
readdirSync(directory: string): Iterable
`
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
`
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
type FilterSync
filter
filter: Filter
filterSync
filter: FilterSync
`
> 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' ]`
Compounds a sequence of filters using logical conjunction.
> Specifications
`ts
type Filter
type FilterSync
conjunction
conjunctionSync
`
> 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"); //=> truetrue
isDataFile("/Documents/project/data.yaml"); //=> false
isDataFile("/Documents/project/_data.json"); //=> `
Compounds a sequence of filters using logical disjunction.
> Specifications
`ts
type Filter
type FilterSync
disjunction
disjunctionSync
`
> Example
`js
const { ofBasename, disjunctionSync } = require("find-files-by-patterns");
const isDataFilename = disjunctionSync([
ofBasename("data.json"),
ofBasename("_data.json")
]);
isDataFilename("/Documents/project/data.json"); //=> truetrue
isDataFilename("/Documents/project/_data.json"); //=> false
isDataFilename("/Documents/project/data.yaml"); //=> `
Converts an iterable to an array.
> Specifications
`ts
allElements
allElementsSync
`
Returns the first element of an iterable.
> Specifications
`ts
firstElement
firstElementSync
`
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
onlyElementSync
`
`sh`
npm run doc
`sh`
npm run test
`sh``
npm run build
- Marc-Antoine Ouimet - MartyO256
This project is licensed under the MIT License. See the LICENSE.md
file for details.