Write README

Development dependencies  have been added to run linters prior to committing.
The README file has been redacted.
The implementation of `hasFile` and `hasFileSync` has been changed in order to use a single filter function.
Some documentation interfaces are now exported in order for TypeDoc to list them.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "find-files-by-patterns",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Find files by patterns in directories, upwards or downwards from other paths.",
   "license": "MIT",
   "author": "Marc-Antoine Ouimet <ouimetmarcantoine@gmail.com>",
@@ -28,7 +28,17 @@
     "doc": "typedoc --out ./doc/ ./src --mode file --module commonjs",
     "test": "mocha --opts ./mocha.opts",
     "test:watch": "mocha --opts ./mocha.opts --watch-extensions ts --watch",
-    "coverage": "nyc npm run test"
+    "coverage": "nyc npm run test",
+    "pre-commit": "lint-staged && npm run format"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run pre-commit"
+    }
+  },
+  "lint-staged": {
+    "*.ts": ["tslint --force --format verbose", "git add"],
+    "*.md": ["markdown-toc -i", "git add"]
   },
   "devDependencies": {
     "@types/chai": "^4.1.7",
@@ -37,6 +47,9 @@
     "@types/node": "^10.12.18",
     "chai": "^4.2.0",
     "coveralls": "^3.0.2",
+    "husky": "^1.2.1",
+    "lint-staged": "^8.1.0",
+    "markdown-toc": "^1.2.0",
     "mocha": "^5.2.0",
     "mock-fs": "^4.7.0",
     "nyc": "^13.1.0",

src/directories.ts

@@ -12,7 +12,7 @@ import { isDirectory, isDirectorySync } from "./stat";
  * A downward directories fetcher constructs an iterable over the directories
  * downwards from a given directory path.
  */
-interface DownwardDirectoriesFetcher extends Function {
+export interface DownwardDirectoriesFetcher extends Function {
   /**
    * Constructs an iterable over the downward directories starting from the
    * current working directory. Symbolic links are followed, and the directories
@@ -74,7 +74,7 @@ interface DownwardDirectoriesFetcher extends Function {
  * A downward directories fetcher constructs an iterable over the directories
  * downwards from a given directory path.
  */
-interface DownwardDirectoriesFetcherSync extends Function {
+export interface DownwardDirectoriesFetcherSync extends Function {
   /**
    * Constructs an iterable over the downward directories starting from the
    * current working directory. Symbolic links are followed, and the directories
@@ -267,7 +267,7 @@ const overloadedUpwardPaths = (
  * An upward directories fetcher constructs an iterable over the directories
  * upwards from a given directory path.
  */
-interface UpwardDirectoriesFetcher extends Function {
+export interface UpwardDirectoriesFetcher extends Function {
   /**
    * Constructs an iterable over the upward directories starting from the
    * current working directory. The current working directory is not yielded.
@@ -323,7 +323,7 @@ interface UpwardDirectoriesFetcher extends Function {
  * An upward directories fetcher constructs an iterable over the directories
  * upwards from a given directory path.
  */
-interface UpwardDirectoriesFetcherSync extends Function {
+export interface UpwardDirectoriesFetcherSync extends Function {
   /**
    * Constructs an iterable over the upward directories starting from the
    * current working directory. The current working directory is not yielded.

src/fileFinders.ts

@@ -107,7 +107,7 @@ export const findFileSync: FileFinderSync = (
 };
 
 /**
- * @see [[StrictFileFinder]] The specifications of the function.
+ * @see [[OnlyFileFinder]] The specifications of the function.
  */
 export const findOnlyFile: OnlyFileFinder = async (
   directories?:
@@ -133,7 +133,7 @@ export const findOnlyFile: OnlyFileFinder = async (
 };
 
 /**
- * @see [[StrictFileFinderSync]] The specifications of the function.
+ * @see [[OnlyFileFinderSync]] The specifications of the function.
  */
 export const findOnlyFileSync: OnlyFileFinderSync = (
   directories?: string | Iterable<string> | FilterSync<string>,

src/files.ts

@@ -97,7 +97,7 @@ export const handleDownwardFilesOverload = (
  * A downward files fetcher constructs an iterable over the files downwards from
  * a given directory path.
  */
-interface DownwardFilesFetcher extends Function {
+export interface DownwardFilesFetcher extends Function {
   /**
    * Constructs an iterable over the downward files starting from the current
    * working directory. Symbolic links are followed, and the directories are
@@ -154,7 +154,7 @@ interface DownwardFilesFetcher extends Function {
  * A downward files fetcher constructs an iterable over the files downwards from
  * a given directory path.
  */
-interface DownwardFilesFetcherSync extends Function {
+export interface DownwardFilesFetcherSync extends Function {
   /**
    * Constructs an iterable over the downward files starting from the current
    * working directory. Symbolic links are followed, and the directories are
@@ -385,7 +385,7 @@ function* constrainedDownwardFilesSync(
  * An upward file fetcher constructs an iterable over the files in upward
  * directories relative to a start path.
  */
-interface UpwardFilesFetcher extends Function {
+export interface UpwardFilesFetcher extends Function {
   /**
    * Constructs an iterable over the files in the upward directories relative to
    * the current working directory, up to the root inclusively of the current
@@ -458,7 +458,7 @@ interface UpwardFilesFetcher extends Function {
  * An upward file fetcher constructs an iterable over the files in upward
  * directories relative to a start path.
  */
-interface UpwardFilesFetcherSync extends Function {
+export interface UpwardFilesFetcherSync extends Function {
   /**
    * Constructs an iterable over the files in the upward directories relative to
    * the current working directory, up to the root inclusively of the current

src/hasFile.ts

@@ -6,57 +6,42 @@ import {
   FilterSync,
   filterSync,
 } from "./filter";
+import { firstElement, firstElementSync } from "./iterable";
 import { readdir, readdirSync } from "./readdirs";
 import { isDirectory, isDirectorySync } from "./stat";
 
 /**
  * Constructs a filter which determines whether of not a directory has a file or
- * directory's path that passes a given sequence of tests. The returned filter
- * will arbitrarily be false for any path that isn't a directory. The path
- * should have already been resolved.
- * @param tests The tests to perform on each files' path until there is a match.
- * @throws If any of the tests throws an error for any of the files in the
- * directory.
+ * directory's path that passes a given test. The returned filter will
+ * arbitrarily be false for any path that isn't a directory. The path should
+ * have already been resolved.
+ * @param test The test to perform on each files' path until there is a match.
+ * @throws If the test throws an error for any of the files in the directory.
  * @returns A filter which determines whether of not a directory has a file or
- * directory's path that passes a given sequence of tests.
+ * directory's path that passes a given test.
  */
 export const hasFile = (
-  ...tests: Array<Filter<string> | FilterSync<string>>
-): Filter<string> => {
-  const test = conjunction(tests);
-  return conjunction([
+  test: Filter<string> | FilterSync<string>,
+): Filter<string> =>
+  conjunction([
     isDirectory,
-    async (directory: string): Promise<boolean> => {
-      for await (const match of filter(readdir(directory), test)) {
-        return true;
-      }
-      return false;
-    },
+    async (directory: string): Promise<boolean> =>
+      (await firstElement(filter(readdir(directory), test))) !== null,
   ]);
-};
 
 /**
  * Constructs a filter which determines whether of not a directory has a file or
- * directory's path that passes a given sequence of tests. The returned filter
- * will arbitrarily be false for any path that isn't a directory. The path
- * should have already been resolved.
- * @param tests The tests to perform on each files' path until there is a match.
- * @throws If any of the tests throws an error for any of the files in the
- * directory.
+ * directory's path that passes a given test. The returned filter will
+ * arbitrarily be false for any path that isn't a directory. The path should
+ * have already been resolved.
+ * @param test The test to perform on each files' path until there is a match.
+ * @throws If the test throws an error for any of the files in the directory.
  * @returns A filter which determines whether of not a directory has a file or
- * directory's path that passes a given sequence of tests.
+ * directory's path that passes a given test.
  */
-export const hasFileSync = (
-  ...tests: Array<FilterSync<string>>
-): FilterSync<string> => {
-  const test = conjunctionSync(tests);
-  return conjunctionSync([
+export const hasFileSync = (test: FilterSync<string>): FilterSync<string> =>
+  conjunctionSync([
     isDirectorySync,
-    (directory: string): boolean => {
-      for (const match of filterSync(readdirSync(directory), test)) {
-        return true;
-      }
-      return false;
-    },
+    (directory: string): boolean =>
+      firstElementSync(filterSync(readdirSync(directory), test)) !== null,
   ]);
-};

src/index.ts

@@ -16,6 +16,7 @@ export {
   onlyElement,
   onlyElementSync,
 } from "./iterable";
+export { readdir, readdirSync, readdirs, readdirsSync } from "./readdirs";
 
 export {
   hasPathSegments,
@@ -42,10 +43,23 @@ export {
   OnlyFileFinderSync,
 } from "./fileFinders";
 
-export { downwardFiles, downwardFilesSync } from "./files";
+export {
+  downwardFiles,
+  downwardFilesSync,
+  upwardFiles,
+  upwardFilesSync,
+  DownwardFilesFetcher,
+  DownwardFilesFetcherSync,
+  UpwardFilesFetcher,
+  UpwardFilesFetcherSync,
+} from "./files";
 export {
   downwardDirectories,
   downwardDirectoriesSync,
   upwardDirectories,
   upwardDirectoriesSync,
+  DownwardDirectoriesFetcher,
+  DownwardDirectoriesFetcherSync,
+  UpwardDirectoriesFetcher,
+  UpwardDirectoriesFetcherSync,
 } from "./directories";

src/path.ts

@@ -7,7 +7,7 @@ import {
   parse,
   sep,
 } from "path";
-import { conjunctionSync, disjunctionSync, FilterSync } from "./filter";
+import { disjunctionSync, FilterSync } from "./filter";
 
 /**
  * A segment tester is a type which can be used to test a substring of a path.
@@ -169,20 +169,17 @@ export function* segments(path: string): Iterable<string> {
  * Constructs a filter which determines whether or not all the path segments of
  * a path pass a sequence of tests. In order for a path to match, there must not
  * be a path segment that fails a test. If no tests are provided, then the
- * matcher will return `false` regardless of the path it checks.
+ * filter will return `false` regardless of the path it checks.
  * @param tests The sequence of tests each path segment must pass in order for
  * the path to match.
  * @throws If any of the tests throws an error for any path segment.
  * @returns A filter that determines whether or not all the path segments of a
  * path pass a sequence of tests
  */
 export const hasPathSegments = (
-  ...tests: Array<FilterSync<string>>
+  ...tests: SegmentTester[]
 ): FilterSync<string> => {
-  if (tests.length === 0) {
-    return () => false;
-  }
-  const test = conjunctionSync(tests);
+  const test = ofSegmentFilter(tests);
   return (path: string) => {
     for (const segment of segments(path)) {
       if (!test(segment)) {

test/hasFile.spec.ts

@@ -41,9 +41,6 @@ describe("hasFile", () => {
   it("should return `false` for a path that is a directory and doesn't have any matching file", async () => {
     assert.isFalse(await hasFile(ofExtname(".html"))("/home/user/directory"));
   });
-  it("should return `false` for a path that is an empty directory and no tests are given", async () => {
-    assert.isFalse(await hasFile()("/home/user/directory"));
-  });
   it("should throw an error if any of the tests throws an error", async () => {
     assert.isFalse(await hasFile(error)("/home/user/directory"));
   });
@@ -77,9 +74,6 @@ describe("hasFileSync", () => {
   it("should return `false` for a path that is a directory and doesn't have any matching file", () => {
     assert.isFalse(hasFileSync(ofExtname(".html"))("/home/user/directory"));
   });
-  it("should return `false` for a path that is an empty directory and no tests are given", () => {
-    assert.isFalse(hasFileSync()("/home/user/directory"));
-  });
   it("should throw an error if any of the tests throws an error", () => {
     assert.isFalse(hasFileSync(errorSync)("/home/user/directory"));
   });