Skip to content

Find files by patterns in directories, upwards or downwards from other paths.

License

Notifications You must be signed in to change notification settings

MartyO256/find-files-by-patterns

Repository files navigation

find-files-by-patterns

npm Information Page Node Version Documentation Coverage Status Maintainability MIT license


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

Complete list of exported functions

Finders:

Files:

Directories:

Filters:

Iterable readdir:

Iterable utilities:

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

License

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