{"id":18351668,"url":"https://github.com/MartyO256/find-files-by-patterns","last_synced_at":"2025-04-06T11:32:35.930Z","repository":{"id":33838880,"uuid":"152904603","full_name":"MartyO256/find-files-by-patterns","owner":"MartyO256","description":"Find files by patterns in directories, upwards or downwards from other paths.","archived":false,"fork":false,"pushed_at":"2024-04-11T00:35:25.000Z","size":1867,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-04T00:50:04.932Z","etag":null,"topics":["directory-traversal","file-finder","filter","filter-iterable","findfile","iterable-readdir","map-iterable","nodejs"],"latest_commit_sha":null,"homepage":"https://martyo256.github.io/find-files-by-patterns/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MartyO256.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-10-13T18:56:26.000Z","updated_at":"2024-08-03T00:24:13.000Z","dependencies_parsed_at":"2023-10-11T12:52:04.738Z","dependency_job_id":"7e4d45d0-e8bb-48b7-93e1-c6e403d65a7f","html_url":"https://github.com/MartyO256/find-files-by-patterns","commit_stats":{"total_commits":62,"total_committers":3,"mean_commits":"20.666666666666668","dds":"0.12903225806451613","last_synced_commit":"09acd96e2460c1523c7b8883ce29abeca1cf2695"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartyO256%2Ffind-files-by-patterns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartyO256%2Ffind-files-by-patterns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartyO256%2Ffind-files-by-patterns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartyO256%2Ffind-files-by-patterns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MartyO256","download_url":"https://codeload.github.com/MartyO256/find-files-by-patterns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478151,"owners_count":20945257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["directory-traversal","file-finder","filter","filter-iterable","findfile","iterable-readdir","map-iterable","nodejs"],"created_at":"2024-11-05T21:32:10.904Z","updated_at":"2025-04-06T11:32:35.138Z","avatar_url":"https://github.com/MartyO256.png","language":"TypeScript","funding_links":[],"categories":["Packages"],"sub_categories":[],"readme":"# find-files-by-patterns\n\n[![npm Information Page](https://img.shields.io/npm/v/find-files-by-patterns.svg)](https://www.npmjs.com/package/find-files-by-patterns)\n![Node Version](https://img.shields.io/badge/node-%3E%3D%2010.0.0-green.svg)\n[![Documentation](https://img.shields.io/website-up-down-green-red/https/martyo256.github.io/find-files-by-patterns.svg?label=documentation)](https://martyo256.github.io/find-files-by-patterns/)\n[![Coverage Status](https://coveralls.io/repos/github/MartyO256/find-files-by-patterns/badge.svg)](https://coveralls.io/github/MartyO256/find-files-by-patterns?branch=development)\n[![Maintainability](https://api.codeclimate.com/v1/badges/6d2069677a848c509e3a/maintainability)](https://codeclimate.com/github/MartyO256/find-files-by-patterns/maintainability)\n[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)\n\n---\n\nUse the iterator pattern to find files upwards and downwards in the file system.\n\n---\n\n## Installation\n\nUsing npm:\n\n```sh\nnpm install find-files-by-patterns\n```\n\nAssuming this file system, where the current working directory is\n`/Documents/project`:\n\n```plaintext\n/\n└── Documents\n    ├── data.csv\n    └── project\n        ├── node_modules\n        └── package.json\n```\n\nIn Node.js:\n\n```js\nconst { findFile, upwardDirectories,\n  ofBasename, downwardFiles } = require(\"find-files-by-patterns\");\n\n(async () =\u003e {\n  const dataFile = await findFile(upwardDirectories(), ofBasename(\"data.csv\"));\n  console.log(dataFile); //=\u003e `/Documents/data.csv`\n\n  for await (const file of downwardFiles(\"/Documents\")) {\n    console.log(file);\n  }\n  //=\u003e `/Documents/data.csv`\n  //=\u003e `/Documents/project`\n  //=\u003e `/Documents/project/node_modules` ...\n  //=\u003e `/Documents/project/package.json`\n})();\n\n```\n\n## Table of Contents\n\n\u003cdetails\u003e\n\n\u003c!-- toc --\u003e\n\n- [API](#api)\n  - [`findFile` and `findFileSync`](#findfile-and-findfilesync)\n  - [`findAllFiles` and `findAllFilesSync`](#findallfiles-and-findallfilessync)\n  - [`findOnlyFile` and `findOnlyFileSync`](#findonlyfile-and-findonlyfilesync)\n  - [`downwardDirectories` and `downwardDirectoriesSync`](#downwarddirectories-and-downwarddirectoriessync)\n  - [`upwardDirectories` and `upwardDirectoriesSync`](#upwarddirectories-and-upwarddirectoriessync)\n  - [`downwardFiles` and `downwardFilesSync`](#downwardfiles-and-downwardfilessync)\n  - [`upwardFiles` and `upwardFilesSync`](#upwardfiles-and-upwardfilessync)\n  - [`ofBasename`, `ofName`, `ofDirname` and `ofExtname`](#ofbasename-ofname-ofdirname-and-ofextname)\n  - [`hasPathSegments`](#haspathsegments)\n  - [`isFile` and `isFileSync`](#isfile-and-isfilesync)\n  - [`isDirectory` and `isDirectorySync`](#isdirectory-and-isdirectorysync)\n  - [`hasFile` and `hasFileSync`](#hasfile-and-hasfilesync)\n  - [`readdir` and `readdirSync`](#readdir-and-readdirsync)\n  - [`readdirs` and `readdirsSync`](#readdirs-and-readdirssync)\n  - [`filter` and `filterSync`](#filter-and-filtersync)\n  - [`conjunction` and `conjunctionSync`](#conjunction-and-conjunctionsync)\n  - [`disjunction` and `disjunctionSync`](#disjunction-and-disjunctionsync)\n  - [`allElements` and `allElementsSync`](#allelements-and-allelementssync)\n  - [`firstElement` and `firstElementSync`](#firstelement-and-firstelementsync)\n  - [`onlyElement` and `onlyElementSync`](#onlyelement-and-onlyelementsync)\n- [About](#about)\n  - [Building the documentation](#building-the-documentation)\n  - [Running the tests](#running-the-tests)\n  - [Building the library](#building-the-library)\n  - [Authors](#authors)\n  - [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n\u003c/details\u003e\n\n## API\n\n\u003cdetails\u003e\n\n\u003csummary\u003eComplete list of exported functions\u003c/summary\u003e\n\nFinders:\n\n- [`findFile` and `findFileSync`](#findFile-and-findFileSync)\n- [`findAllFiles` and `findAllFilesSync`](#findAllFiles-and-findAllFilesSync)\n- [`findOnlyFile` and `findOnlyFileSync`](#findOnlyFile-and-findOnlyFileSync)\n\nFiles:\n\n- [`downwardFiles` and `downwardFilesSync`](#downwardFiles-and-downwardFilesSync)\n- [`upwardFiles` and `upwardFilesSync`](#upwardFiles-and-upwardFilesSync)\n\nDirectories:\n\n- [`downwardDirectories` and `downwardDirectoriesSync`](#downwardDirectories-and-downwardDirectoriesSync)\n- [`upwardDirectories` and `upwardDirectoriesSync`](#upwardDirectories-and-upwardDirectoriesSync)\n\nFilters:\n\n- [`ofBasename`, `ofName`, `ofDirname` and `ofExtname`](#ofBasename-ofName-ofDirname-and-ofExtname)\n- [`hasPathSegments`](#hasPathSegments)\n- [`isFile` and `isFileSync`](#isFile-and-isFileSync)\n- [`isDirectory` and `isDirectorySync`](#isDirectory-and-isDirectorySync)\n- [`hasFile` and `hasFileSync`](#hasFile-and-hasFileSync)\n- [`conjunction` and `conjunctionSync`](#conjunction-and-conjunctionSync)\n- [`disjunction` and `disjunctionSync`](#disjunction-and-disjunctionSync)\n\nIterable `readdir`:\n\n- [`readdir` and `readdirSync`](#readdir-and-readdirSync)\n- [`readdirs` and `readdirsSync`](#readdirs-and-readdirsSync)\n\nIterable utilities:\n\n- [`filter` and `filterSync`](#filter-and-filterSync)\n- [`allElements` and `allElementsSync`](#allElements-and-allElementsSync)\n- [`firstElement` and `firstElementSync`](#firstElement-and-firstElementSync)\n- [`onlyElement` and `onlyElementSync`](#onlyElement-and-onlyElementSync)\n\n\u003c/details\u003e\n\n### `findFile` and `findFileSync`\n\nFinds the first file that matches all of the given filters in the given\ndirectories.\nIf no directory is supplied, then the current working directory is read.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\nfindFile(\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring | null\u003e;\n\nfindFile(\n  directories: string | AsyncIterable\u003cstring\u003e | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring | null\u003e;\n\nfindFileSync(...tests: Array\u003cFilterSync\u003cstring\u003e\u003e): string | null;\n\nfindFileSync(\n  directories: string | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilterSync\u003cstring\u003e\u003e\n): string | null;\n```\n\n### `findAllFiles` and `findAllFilesSync`\n\nFinds all the files that match all of the given filters in the given\ndirectories.\nIf no directory is supplied, then the current working directory is read.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\nfindAllFiles(\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring[]\u003e;\n\nfindAllFiles(\n  directories: string | AsyncIterable\u003cstring\u003e | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring[]\u003e;\n\nfindAllFilesSync(...tests: Array\u003cFilterSync\u003cstring\u003e\u003e): string[];\n\nfindAllFilesSync(\n  directories: string | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilterSync\u003cstring\u003e\u003e\n): string[];\n```\n\n### `findOnlyFile` and `findOnlyFileSync`\n\nFinds the first and only file in its directory that matches all of the given\nfilters.\nIf no directory is supplied, then the current working directory is read.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\nfindOnlyFile(\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring | null\u003e;\n\nfindOnlyFile(\n  directories: string | AsyncIterable\u003cstring\u003e | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilter\u003cstring\u003e | FilterSync\u003cstring\u003e\u003e\n): Promise\u003cstring | null\u003e;\n\nfindOnlyFileSync(...tests: Array\u003cFilterSync\u003cstring\u003e\u003e): string | null;\n\nfindOnlyFileSync(\n  directories: string | Iterable\u003cstring\u003e,\n  ...tests: Array\u003cFilterSync\u003cstring\u003e\u003e\n): string | null;\n```\n\n### `downwardDirectories` and `downwardDirectoriesSync`\n\nReturns an iterable over the existing downward files from a start path. Symbolic\nlinks are followed and handled such that no directory is traversed twice.\n\n\u003e Specifications\n\n```ts\ndownwardDirectories(): AsyncIterable\u003cstring\u003e;\n\ndownwardDirectories(maximumDepth: number): AsyncIterable\u003cstring\u003e;\n\ndownwardDirectories(startDirectory: string): AsyncIterable\u003cstring\u003e;\n\ndownwardDirectories(startDirectory: string,\n                    maximumDepth: number): AsyncIterable\u003cstring\u003e;\n\ndownwardDirectoriesSync(): Iterable\u003cstring\u003e;\n\ndownwardDirectoriesSync(maximumDepth: number): Iterable\u003cstring\u003e;\n\ndownwardDirectoriesSync(startDirectory: string): Iterable\u003cstring\u003e;\n\ndownwardDirectoriesSync(startDirectory: string,\n                        maximumDepth: number): Iterable\u003cstring\u003e;\n```\n\n\u003e Example\n\nAssuming this file system, where the current working directory is `/Documents`:\n\n```plaintext\n/\n└── Documents\n    ├── Images\n    |   └── image.jpeg\n    └── project\n        ├── node_modules\n        └── package.json\n```\n\n```js\nconst { downwardDirectoriesSync } = require(\"find-files-by-patterns\");\n\n[\n  ...downwardDirectoriesSync()\n]; /*=\u003e `[ '/Documents/Images',\n           '/Documents/project',\n           '/Documents/project/node_modules' ]`*/\n[...downwardDirectoriesSync(1)]; /*=\u003e `[ '/Documents/Images',\n                                         '/Documents/project' ]`*/\n[...downwardDirectoriesSync(\n  \"/Documents/project\"\n)]; //=\u003e `[ '/Documents/project/node_modules' ]`\n[...downwardDirectoriesSync(\n  \"/Documents\", 1\n)]; //=\u003e `[ '/Documents/Images', '/Documents/project' ]`\n```\n\n### `upwardDirectories` and `upwardDirectoriesSync`\n\nReturns an iterable over the existing directories upwards from a start path.\n\n\u003e Specifications\n\n```ts\nupwardDirectories(): AsyncIterable\u003cstring\u003e;\n\nupwardDirectories(startPath: string): AsyncIterable\u003cstring\u003e;\n\nupwardDirectories(startPath: string,\n                  maximumHeight: number): AsyncIterable\u003cstring\u003e;\n\nupwardDirectories(startPath: string, endPath: string): AsyncIterable\u003cstring\u003e;\n\nupwardDirectoriesSync(): Iterable\u003cstring\u003e;\n\nupwardDirectoriesSync(startPath: string): Iterable\u003cstring\u003e;\n\nupwardDirectoriesSync(startPath: string,\n                      maximumHeight: number): Iterable\u003cstring\u003e;\n\nupwardDirectoriesSync(startPath: string, endPath: string): Iterable\u003cstring\u003e;\n```\n\n\u003e Example\n\nAssuming this file system, where the current working directory is\n`/Documents/project`:\n\n```plaintext\n/\n└── Documents\n    ├── Images\n    |   └── image.jpeg\n    └── project\n        ├── node_modules\n        └── package.json\n```\n\n```js\nconst { upwardDirectoriesSync } = require(\"find-files-by-patterns\");\n\n[...upwardDirectoriesSync()]; //=\u003e `[ '/Documents', '/' ]`\n[...upwardDirectoriesSync(1)]; //=\u003e `[ '/Documents' ]`\n[...upwardDirectoriesSync(\n  \"/Documents/Images/image.jpeg\"\n)]; //=\u003e `[ '/Documents/Images', '/Documents', '/' ]`\n[...upwardDirectoriesSync(\n  \"/Documents/Images/image.jpeg\", 2\n)]; //=\u003e `[ '/Documents/Images', '/Documents' ]`\n[...upwardDirectoriesSync(\n  \"/Documents/Images/image.jpeg\", \"/Documents\"\n)]; //=\u003e `[ '/Documents/Images', '/Documents' ]`\n```\n\n### `downwardFiles` and `downwardFilesSync`\n\nReturns and iterable over the files in each downward directory yielded by\n`downwardDirectories` or `downwardDirectoriesSync`.\n\n\u003e Specifications\n\n```ts\ndownwardFiles(): AsyncIterable\u003cstring\u003e;\n\ndownwardFiles(maximumDepth: number): AsyncIterable\u003cstring\u003e;\n\ndownwardFiles(startDirectory: string): AsyncIterable\u003cstring\u003e;\n\ndownwardFiles(startDirectory: string,\n              maximumDepth: number): AsyncIterable\u003cstring\u003e;\n\ndownwardFilesSync(): Iterable\u003cstring\u003e;\n\ndownwardFilesSync(maximumDepth: number): Iterable\u003cstring\u003e;\n\ndownwardFilesSync(startDirectory: string): Iterable\u003cstring\u003e;\n\ndownwardFilesSync(startDirectory: string,\n                  maximumDepth: number): Iterable\u003cstring\u003e;\n```\n\n### `upwardFiles` and `upwardFilesSync`\n\nReturns and iterable over the files in each upward directory yielded by\n`upwardDirectories` or `upwardDirectoriesSync`.\n\n\u003e Specifications\n\n```ts\nupwardFiles(): AsyncIterable\u003cstring\u003e;\n\nupwardFiles(startPath: string): AsyncIterable\u003cstring\u003e;\n\nupwardFiles(startPath: string, maximumHeight: number): AsyncIterable\u003cstring\u003e;\n\nupwardFiles(startPath: string, endPath: string): AsyncIterable\u003cstring\u003e;\n\nupwardFilesSync(): Iterable\u003cstring\u003e;\n\nupwardFilesSync(startPath: string): Iterable\u003cstring\u003e;\n\nupwardFilesSync(startPath: string, maximumHeight: number): Iterable\u003cstring\u003e;\n\nupwardFilesSync(startPath: string, endPath: string): Iterable\u003cstring\u003e;\n```\n\n### `ofBasename`, `ofName`, `ofDirname` and `ofExtname`\n\nDetermines whether or not a path's `basename`, `name`, `dirname` or `extname`\nmatches any of a sequence of segment testers.\nA segment tester can be a string, a regular expression or a function.\n\n- If it is a string, then the segment must correspond to it for the path to\n  match.\n- If it is a regular expression, then the segment must test against it for the\n  path to match.\n- If it is a function, then the segment must make it return `true` for the path\n  to match.\n\n\u003e Specifications\n\n```ts\ntype SegmentTester = string | RegExp | ((segment: string) =\u003e boolean);\n\nofBasename(...tests: SegmentTester[]): FilterSync\u003cstring\u003e;\n\nofName(...tests: SegmentTester[]): FilterSync\u003cstring\u003e;\n\nofDirname(...tests: SegmentTester[]): FilterSync\u003cstring\u003e;\n\nofExtname(...tests: SegmentTester[]): FilterSync\u003cstring\u003e;\n```\n\n\u003e Example\n\n```js\nconst { ofBasename, ofName,\n        ofDirname, ofExtname } = require(\"find-files-by-patterns\");\n\nconst isMarkdownFile = ofExtname(\".md\", \".markdown\");\nconst isIndexFile = ofName(\"index\");\nconst isDataFilename = ofBasename(/^data/);\nconst isInDocuments = ofDirname(\"/Documents\");\n\nisMarkdownFile(\"/Documents/article.md\"); //=\u003e `true`\nisMarkdownFile(\"/Documents/data.json\"); //=\u003e `false`\nisIndexFile(\"/Documents/index.html\"); //=\u003e `true`\nisIndexFile(\"/Documents/index.md\"); //=\u003e `true`\nisDataFilename(\"/Documents/data.json\"); //=\u003e `true`\nisInDocuments(\"/Documents/data.json\"); //=\u003e `true`\nisInDocuments(\"/Documents/src/index.js\"); //=\u003e `false`\n```\n\n### `hasPathSegments`\n\nDetermines whether or not all the paths segments of a path match a sequence of\nsegment testers.\nA segment tester can be a string, a regular expression or a function.\n\n- If it is a string, then the segment must correspond to it for the path to\n  match.\n- If it is a regular expression, then the segment must test against it for the\n  path to match.\n- If it is a function, then the segment must make it return `true` for the path\n  to match.\n\n\u003e Specifications\n\n```ts\ntype SegmentTester = string | RegExp | ((segment: string) =\u003e boolean);\n\nhasPathSegments(...tests: SegmentTester[]): FilterSync\u003cstring\u003e;\n```\n\n\u003e Example\n\n```js\nconst { hasPathSegments } = require(\"find-files-by-patterns\");\n\nconst isIgnored = hasPathSegments(segment =\u003e segment.startsWith(\"_\"));\n\nisIgnored(\"project/src/_ignored.json\"); //=\u003e `true`\n\nisIgnored(\"project/_ignored/data.json\"); //=\u003e `true`\n\nisIgnored(\"project/src/data.yaml\"); //=\u003e `false`\n```\n\n### `isFile` and `isFileSync`\n\nDetermines whether or not a path exists on the file system and is a file.\n\n\u003e Specifications\n\n```ts\nisFile(path: string): Promise\u003cboolean\u003e;\n\nisFileSync(path: string): boolean;\n```\n\n### `isDirectory` and `isDirectorySync`\n\nDetermines whether or not a path exists on the file system and is a directory.\n\n\u003e Specifications\n\n```ts\nisDirectory(path: string): Promise\u003cboolean\u003e;\n\nisDirectorySync(path: string): boolean;\n```\n\n### `hasFile` and `hasFileSync`\n\nReturns a filter which determines whether or not a path is a directory that has\na file which matches a filter.\n\n\u003e Specifications\n\n```ts\nhasFile(test: Filter\u003cstring\u003e | FilterSync\u003cstring\u003e): Filter\u003cstring\u003e;\n\nhasFileSync(test: FilterSync\u003cstring\u003e): FilterSync\u003cstring\u003e;\n```\n\n\u003e Example\n\nAssuming this file system, where the current working directory is\n`/Documents/project`:\n\n```plaintext\n/\n└── Documents\n    ├── Images\n    |   └── image.jpeg\n    └── project\n        ├── node_modules\n        └── package.json\n```\n\n```js\nconst { findFileSync, upwardDirectoriesSync,\n  hasFileSync, ofBasename } = require(\"find-files-by-patterns\");\n\nconst imagesDirectory = findFileSync(\n  upwardDirectoriesSync(),\n  hasFileSync(ofBasename(\"image.jpeg\"))\n); //=\u003e `/Documents/Images`\n```\n\n### `readdir` and `readdirSync`\n\nReturns an iterable over the fully qualified file names in the given directory.\n\n\u003e Specifications\n\n```ts\nreaddir(directory: string): AsyncIterable\u003cstring\u003e;\n\nreaddirSync(directory: string): Iterable\u003cstring\u003e;\n```\n\n### `readdirs` and `readdirsSync`\n\nReturns an iterable over the fully qualified file names in the given sequence of\ndirectories.\n\n\u003e Specifications\n\n```ts\nreaddirs(directory: string): AsyncIterable\u003cstring\u003e;\n\nreaddirsSync(directory: string): Iterable\u003cstring\u003e;\n```\n\n### `filter` and `filterSync`\n\nFilters out the iterated elements of an iterable for which the filter function\nreturns `false`.\nThis is analogous to the array filter method.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\nfilter\u003cT\u003e(iterable: Iterable\u003cT\u003e | AsyncIterable\u003cT\u003e,\n          filter: Filter\u003cT\u003e | FilterSync\u003cT\u003e): AsyncIterable\u003cT\u003e;\n\nfilterSync\u003cT\u003e(iterable: Iterable\u003cT\u003e,\n              filter: FilterSync\u003cT\u003e): Iterable\u003cT\u003e;\n```\n\n\u003e Example\n\n```js\nconst { filterSync, hasPathSegments } = require(\"find-files-by-patterns\");\n\nconst paths = [\n  \"/Documents/project\",\n  \"/Documents/project/data.json\",\n  \"/Documents/project/_directory\",\n  \"/Documents/project/_directory/data.json\"\n];\n[...filterSync(paths, hasPathSegments(segment =\u003e !segment.startsWith(\"_\")))];\n//=\u003e `[ '/Documents/project', '/Documents/project/data.json' ]`\n```\n\n### `conjunction` and `conjunctionSync`\n\nCompounds a sequence of filters using logical conjunction.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\nconjunction\u003cT\u003e(filters: Array\u003cFilter\u003cT\u003e | FilterSync\u003cT\u003e\u003e): Filter\u003cT\u003e;\n\nconjunctionSync\u003cT\u003e(filters: Array\u003cFilterSync\u003cT\u003e\u003e): FilterSync\u003cT\u003e;\n```\n\n\u003e Example\n\n```js\nconst { ofBasename, ofExtname,\n  conjunctionSync } = require(\"find-files-by-patterns\");\n\nconst validDataExtensions = [\".json\", \".yaml\", \".csv\"];\nconst isDataFile = conjunctionSync([\n  ofBasename(basename =\u003e basename.startsWith(\"data\")),\n  ofExtname(...validDataExtensions)\n]);\n\nisDataFile(\"/Documents/project/data.json\"); //=\u003e `true`\nisDataFile(\"/Documents/project/data.yaml\"); //=\u003e `true`\nisDataFile(\"/Documents/project/_data.json\"); //=\u003e `false`\n```\n\n### `disjunction` and `disjunctionSync`\n\nCompounds a sequence of filters using logical disjunction.\n\n\u003e Specifications\n\n```ts\ntype Filter\u003cT\u003e = (element: T) =\u003e Promise\u003cboolean\u003e;\ntype FilterSync\u003cT\u003e = (element: T) =\u003e boolean;\n\ndisjunction\u003cT\u003e(filters: Array\u003cFilter\u003cT\u003e | FilterSync\u003cT\u003e\u003e): Filter\u003cT\u003e;\n\ndisjunctionSync\u003cT\u003e(filters: Array\u003cFilterSync\u003cT\u003e\u003e): FilterSync\u003cT\u003e;\n```\n\n\u003e Example\n\n```js\nconst { ofBasename, disjunctionSync } = require(\"find-files-by-patterns\");\n\nconst isDataFilename = disjunctionSync([\n  ofBasename(\"data.json\"),\n  ofBasename(\"_data.json\")\n]);\n\nisDataFilename(\"/Documents/project/data.json\"); //=\u003e `true`\nisDataFilename(\"/Documents/project/_data.json\"); //=\u003e `true`\nisDataFilename(\"/Documents/project/data.yaml\"); //=\u003e `false`\n```\n\n### `allElements` and `allElementsSync`\n\nConverts an iterable to an array.\n\n\u003e Specifications\n\n```ts\nallElements\u003cT\u003e(iterable: AsyncIterable\u003cT\u003e): Promise\u003cT[]\u003e;\n\nallElementsSync\u003cT\u003e(iterable: Iterable\u003cT\u003e): T[];\n```\n\n### `firstElement` and `firstElementSync`\n\nReturns the first element of an iterable.\n\n\u003e Specifications\n\n```ts\nfirstElement\u003cT\u003e(iterable: AsyncIterable\u003cT\u003e): Promise\u003cT | null\u003e;\n\nfirstElementSync\u003cT\u003e(iterable: Iterable\u003cT\u003e): T | null;\n```\n\n### `onlyElement` and `onlyElementSync`\n\nReturns the only yielded element of an iterable.\nIf there is more than one element yielded by the iterable, then an error is\nthrown.\n\n\u003e Specifications\n\n```ts\nonlyElement\u003cT\u003e(iterable: AsyncIterable\u003cT\u003e): Promise\u003cT | null\u003e;\n\nonlyElementSync\u003cT\u003e(iterable: Iterable\u003cT\u003e): T | null;\n```\n\n## About\n\n### Building the documentation\n\n```sh\nnpm run doc\n```\n\n### Running the tests\n\n```sh\nnpm run test\n```\n\n### Building the library\n\n```sh\nnpm run build\n```\n\n### Authors\n\n- **Marc-Antoine Ouimet** - [MartyO256](https://github.com/MartyO256)\n\n### License\n\nThis project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md)\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMartyO256%2Ffind-files-by-patterns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMartyO256%2Ffind-files-by-patterns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMartyO256%2Ffind-files-by-patterns/lists"}