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`
})();

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.

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.

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.

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.

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>;

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.

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>;

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.

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.

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.

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>;

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.

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

hasPathSegments(...tests: SegmentTester[]): FilterSync<string>;

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.

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.

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.

hasFile(test: Filter<string> | FilterSync<string>): Filter<string>;

hasFileSync(test: FilterSync<string>): FilterSync<string>;

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.

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.

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.

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>;

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.

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>;

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.

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>;

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.

allElements<T>(iterable: AsyncIterable<T>): Promise<T[]>;

allElementsSync<T>(iterable: Iterable<T>): T[];

`firstElement` and `firstElementSync`

Returns the first element of an iterable.

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.

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.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.yarn/releases		.yarn/releases
src		src
test		test
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.prettierrc		.prettierrc
.yarnrc.yml		.yarnrc.yml
LICENSE.md		LICENSE.md
README.md		README.md
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Navigation Menu

Repository navigation

About

Repository files navigation

find-files-by-patterns

Installation

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

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

find-files-by-patterns

Installation

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

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`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`