README.md

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

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.