find-files-by-patterns v2.0.3
find-files-by-patterns
Use the iterator pattern to find files upwards and downwards in the file system.
Installation
Using npm:
npm install find-files-by-patterns
Assuming this file system, where the current working directory is
/Documents/project
:
/
└── Documents
├── data.csv
└── project
├── node_modules
└── package.json
In Node.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
findFile
andfindFileSync
findAllFiles
andfindAllFilesSync
findOnlyFile
andfindOnlyFileSync
downwardDirectories
anddownwardDirectoriesSync
upwardDirectories
andupwardDirectoriesSync
downwardFiles
anddownwardFilesSync
upwardFiles
andupwardFilesSync
ofBasename
,ofName
,ofDirname
andofExtname
hasPathSegments
isFile
andisFileSync
isDirectory
andisDirectorySync
hasFile
andhasFileSync
readdir
andreaddirSync
readdirs
andreaddirsSync
filter
andfilterSync
conjunction
andconjunctionSync
disjunction
anddisjunctionSync
allElements
andallElementsSync
firstElement
andfirstElementSync
onlyElement
andonlyElementSync
- About
API
Finders:
Files:
Directories:
Filters:
ofBasename
,ofName
,ofDirname
andofExtname
hasPathSegments
isFile
andisFileSync
isDirectory
andisDirectorySync
hasFile
andhasFileSync
conjunction
andconjunctionSync
disjunction
anddisjunctionSync
Iterable readdir
:
Iterable utilities:
filter
andfilterSync
allElements
andallElementsSync
firstElement
andfirstElementSync
onlyElement
andonlyElementSync
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
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
findFile(
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string | null>;
findFile(
directories: string | AsyncIterable<string> | Iterable<string>,
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string | null>;
findFileSync(...tests: Array<FilterSync<string>>): string | null;
findFileSync(
directories: string | Iterable<string>,
...tests: Array<FilterSync<string>>
): 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
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
findAllFiles(
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string[]>;
findAllFiles(
directories: string | AsyncIterable<string> | Iterable<string>,
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string[]>;
findAllFilesSync(...tests: Array<FilterSync<string>>): string[];
findAllFilesSync(
directories: string | Iterable<string>,
...tests: Array<FilterSync<string>>
): 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
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
findOnlyFile(
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string | null>;
findOnlyFile(
directories: string | AsyncIterable<string> | Iterable<string>,
...tests: Array<Filter<string> | FilterSync<string>>
): Promise<string | null>;
findOnlyFileSync(...tests: Array<FilterSync<string>>): string | null;
findOnlyFileSync(
directories: string | Iterable<string>,
...tests: Array<FilterSync<string>>
): 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
downwardDirectories(): AsyncIterable<string>;
downwardDirectories(maximumDepth: number): AsyncIterable<string>;
downwardDirectories(startDirectory: string): AsyncIterable<string>;
downwardDirectories(startDirectory: string,
maximumDepth: number): AsyncIterable<string>;
downwardDirectoriesSync(): Iterable<string>;
downwardDirectoriesSync(maximumDepth: number): Iterable<string>;
downwardDirectoriesSync(startDirectory: string): Iterable<string>;
downwardDirectoriesSync(startDirectory: string,
maximumDepth: number): Iterable<string>;
Example
Assuming this file system, where the current working directory is /Documents
:
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
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' ]`
upwardDirectories
and upwardDirectoriesSync
Returns an iterable over the existing directories upwards from a start path.
Specifications
upwardDirectories(): AsyncIterable<string>;
upwardDirectories(startPath: string): AsyncIterable<string>;
upwardDirectories(startPath: string,
maximumHeight: number): AsyncIterable<string>;
upwardDirectories(startPath: string, endPath: string): AsyncIterable<string>;
upwardDirectoriesSync(): Iterable<string>;
upwardDirectoriesSync(startPath: string): Iterable<string>;
upwardDirectoriesSync(startPath: string,
maximumHeight: number): Iterable<string>;
upwardDirectoriesSync(startPath: string, endPath: string): Iterable<string>;
Example
Assuming this file system, where the current working directory is
/Documents/project
:
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
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' ]`
downwardFiles
and downwardFilesSync
Returns and iterable over the files in each downward directory yielded by
downwardDirectories
or downwardDirectoriesSync
.
Specifications
downwardFiles(): AsyncIterable<string>;
downwardFiles(maximumDepth: number): AsyncIterable<string>;
downwardFiles(startDirectory: string): AsyncIterable<string>;
downwardFiles(startDirectory: string,
maximumDepth: number): AsyncIterable<string>;
downwardFilesSync(): Iterable<string>;
downwardFilesSync(maximumDepth: number): Iterable<string>;
downwardFilesSync(startDirectory: string): Iterable<string>;
downwardFilesSync(startDirectory: string,
maximumDepth: number): Iterable<string>;
upwardFiles
and upwardFilesSync
Returns and iterable over the files in each upward directory yielded by
upwardDirectories
or upwardDirectoriesSync
.
Specifications
upwardFiles(): AsyncIterable<string>;
upwardFiles(startPath: string): AsyncIterable<string>;
upwardFiles(startPath: string, maximumHeight: number): AsyncIterable<string>;
upwardFiles(startPath: string, endPath: string): AsyncIterable<string>;
upwardFilesSync(): Iterable<string>;
upwardFilesSync(startPath: string): Iterable<string>;
upwardFilesSync(startPath: string, maximumHeight: number): Iterable<string>;
upwardFilesSync(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
type SegmentTester = string | RegExp | ((segment: string) => boolean);
ofBasename(...tests: SegmentTester[]): FilterSync<string>;
ofName(...tests: SegmentTester[]): FilterSync<string>;
ofDirname(...tests: SegmentTester[]): FilterSync<string>;
ofExtname(...tests: SegmentTester[]): FilterSync<string>;
Example
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`
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
type SegmentTester = string | RegExp | ((segment: string) => boolean);
hasPathSegments(...tests: SegmentTester[]): FilterSync<string>;
Example
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`
isFile
and isFileSync
Determines whether or not a path exists on the file system and is a file.
Specifications
isFile(path: string): Promise<boolean>;
isFileSync(path: string): boolean;
isDirectory
and isDirectorySync
Determines whether or not a path exists on the file system and is a directory.
Specifications
isDirectory(path: string): Promise<boolean>;
isDirectorySync(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
hasFile(test: Filter<string> | FilterSync<string>): Filter<string>;
hasFileSync(test: FilterSync<string>): FilterSync<string>;
Example
Assuming this file system, where the current working directory is
/Documents/project
:
/
└── Documents
├── Images
| └── image.jpeg
└── project
├── node_modules
└── package.json
const { findFileSync, upwardDirectoriesSync,
hasFileSync, ofBasename } = require("find-files-by-patterns");
const imagesDirectory = findFileSync(
upwardDirectoriesSync(),
hasFileSync(ofBasename("image.jpeg"))
); //=> `/Documents/Images`
readdir
and readdirSync
Returns an iterable over the fully qualified file names in the given directory.
Specifications
readdir(directory: string): AsyncIterable<string>;
readdirSync(directory: string): Iterable<string>;
readdirs
and readdirsSync
Returns an iterable over the fully qualified file names in the given sequence of directories.
Specifications
readdirs(directory: string): AsyncIterable<string>;
readdirsSync(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
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
filter<T>(iterable: Iterable<T> | AsyncIterable<T>,
filter: Filter<T> | FilterSync<T>): AsyncIterable<T>;
filterSync<T>(iterable: Iterable<T>,
filter: FilterSync<T>): Iterable<T>;
Example
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' ]`
conjunction
and conjunctionSync
Compounds a sequence of filters using logical conjunction.
Specifications
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
conjunction<T>(filters: Array<Filter<T> | FilterSync<T>>): Filter<T>;
conjunctionSync<T>(filters: Array<FilterSync<T>>): FilterSync<T>;
Example
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`
disjunction
and disjunctionSync
Compounds a sequence of filters using logical disjunction.
Specifications
type Filter<T> = (element: T) => Promise<boolean>;
type FilterSync<T> = (element: T) => boolean;
disjunction<T>(filters: Array<Filter<T> | FilterSync<T>>): Filter<T>;
disjunctionSync<T>(filters: Array<FilterSync<T>>): FilterSync<T>;
Example
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`
allElements
and allElementsSync
Converts an iterable to an array.
Specifications
allElements<T>(iterable: AsyncIterable<T>): Promise<T[]>;
allElementsSync<T>(iterable: Iterable<T>): T[];
firstElement
and firstElementSync
Returns the first element of an iterable.
Specifications
firstElement<T>(iterable: AsyncIterable<T>): Promise<T | null>;
firstElementSync<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
onlyElement<T>(iterable: AsyncIterable<T>): Promise<T | null>;
onlyElementSync<T>(iterable: Iterable<T>): T | null;
About
Building the documentation
npm run doc
Running the tests
npm run test
Building the library
npm run build
Authors
- Marc-Antoine Ouimet - MartyO256
License
This project is licensed under the MIT License. See the LICENSE.md file for details.