filehound 2.0.0-beta.3 → 2.0.0

package/README.md

@@ -61,6 +61,8 @@ for await (const file of query.iterate()) {
 ## Documentation
 For more examples and API details, see [API documentation](https://nspragg.github.io/filehound/)
 
+Runnable examples are in the [examples](examples/) directory. Each one searches the current directory, for example `node by-extension.mts`.
+
 ## Test
 
 ```

package/dist/filehound.d.ts

@@ -118,6 +118,40 @@ export declare class FileHound<T = string> extends EventEmitter {
      * ```
      */
     match(query: FilePredicate): this;
+    /**
+     * Skips directories by name: a directory whose name matches any of the
+     * given names is neither searched nor returned. Use it to keep the search
+     * out of directories such as `node_modules`, which a {@link FileHound.match}
+     * predicate can only exclude from the results after searching them.
+     * Calling it again replaces the names.
+     *
+     * @remarks
+     * Each name is matched against a directory's name only, not its path,
+     * following Node's [`path.matchesGlob`](https://nodejs.org/api/path.html#pathmatchesglobpath-pattern).
+     * A plain name, such as `'node_modules'`, matches exactly, and a glob, such
+     * as `'build-*'`, matches any name it describes. Every directory below the
+     * search paths is tested, including linked directories, but not the search
+     * paths themselves.
+     *
+     * @param names - one or more directory names or globs
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @throws `RangeError`
+     * Thrown if no names are given.
+     * @throws `TypeError`
+     * Thrown if a name is not a non-empty string, or contains a path separator.
+     * @example
+     * ```ts
+     * import { FileHound, ext } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .skipDirectories('node_modules', '.git', 'build-*')
+     *   .match(ext('js'))
+     *   .find();
+     * ```
+     */
+    skipDirectories(...names: string[]): this;
     /**
      * Specify the directory search depth. If set to zero, recursive searching
      * will be disabled. Directories at the limit are not searched, but are

package/dist/filehound.js

@@ -34,6 +34,7 @@ export class FileHound extends EventEmitter {
     #maxDepth;
     #types;
     #matchExpression;
+    #skipDirectories = [];
     #ignoreHiddenFiles = false;
     #ignoreHiddenDirectories = false;
     #ignoreSymlinks = false;
@@ -108,6 +109,45 @@ export class FileHound extends EventEmitter {
         this.#matchExpression = query;
         return this;
     }
+    /**
+     * Skips directories by name: a directory whose name matches any of the
+     * given names is neither searched nor returned. Use it to keep the search
+     * out of directories such as `node_modules`, which a {@link FileHound.match}
+     * predicate can only exclude from the results after searching them.
+     * Calling it again replaces the names.
+     *
+     * @remarks
+     * Each name is matched against a directory's name only, not its path,
+     * following Node's [`path.matchesGlob`](https://nodejs.org/api/path.html#pathmatchesglobpath-pattern).
+     * A plain name, such as `'node_modules'`, matches exactly, and a glob, such
+     * as `'build-*'`, matches any name it describes. Every directory below the
+     * search paths is tested, including linked directories, but not the search
+     * paths themselves.
+     *
+     * @param names - one or more directory names or globs
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @throws `RangeError`
+     * Thrown if no names are given.
+     * @throws `TypeError`
+     * Thrown if a name is not a non-empty string, or contains a path separator.
+     * @example
+     * ```ts
+     * import { FileHound, ext } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .skipDirectories('node_modules', '.git', 'build-*')
+     *   .match(ext('js'))
+     *   .find();
+     * ```
+     */
+    skipDirectories(...names) {
+        this.#throwIfQueryLocked();
+        this.#validateDirectoryNames(names);
+        this.#skipDirectories = names;
+        return this;
+    }
     /**
      * Specify the directory search depth. If set to zero, recursive searching
      * will be disabled. Directories at the limit are not searched, but are
@@ -375,6 +415,20 @@ export class FileHound extends EventEmitter {
             throw new Error('Cannot modify query after search has started');
         }
     }
+    #validateDirectoryNames(names) {
+        if (names.length === 0) {
+            throw new RangeError('At least one directory name must be specified');
+        }
+        names.forEach((name) => {
+            if (typeof name !== 'string' || name.length === 0) {
+                throw new TypeError(`Invalid directory name: ${String(name)}.`);
+            }
+            // Only a directory's name is matched, so a path could never match
+            if (name.includes('/') || name.includes(path.sep)) {
+                throw new TypeError(`Directory name must not contain a path separator: ${name}.`);
+            }
+        });
+    }
     #validateTypeArguments(types) {
         if (types.length === 0) {
             throw new RangeError('At least one file type must be specified');
@@ -437,6 +491,7 @@ export class FileHound extends EventEmitter {
             ignoreSymlinks: this.#ignoreSymlinks,
             maxDepth: this.#maxDepth,
             fileTypes: this.#types,
+            skipDirectories: this.#skipDirectories,
             signal
         };
     }

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { FileHound, type FileWithStats, type SearchOptions } from './filehound.j
 export { FileType } from './filetype.js';
 export type { FileView } from './file.js';
 export { type FilePredicate, accessed, applyFilter, applyFilterSync, changed, discard, ext, glob, isEmpty, like, matchAll, modified, not, size, sizeEquals } from './matchers.js';
+export { ExpressionError } from 'unit-compare';

package/dist/index.js

@@ -1,3 +1,6 @@
 export { FileHound } from './filehound.js';
 export { FileType } from './filetype.js';
 export { accessed, applyFilter, applyFilterSync, changed, discard, ext, glob, isEmpty, like, matchAll, modified, not, size, sizeEquals } from './matchers.js';
+// Thrown by size() and the date matchers for an invalid expression, so it can
+// be caught without depending on unit-compare
+export { ExpressionError } from 'unit-compare';

package/dist/matchers.d.ts

@@ -158,15 +158,21 @@ export declare function ext(extensions: string[]): FilePredicate;
  */
 export declare function matchAll(): FilePredicate;
 /**
- * Matches files by size, using a comparison with optional units, such as
- * `'>10k'` or `'<=1mb'`. The operators are `<`, `<=`, `>`, `>=` and `==`,
- * which is the default, and the units are `b`, `k`, `m`, `g` and `t`, in
- * multiples of 1024. Use {@link sizeEquals} for an exact number of bytes.
+ * Matches files by size, using an expression of an optional operator, a
+ * whole number and an optional unit, such as `'>10kb'` or `'<= 1 mb'`.
+ *
+ * The operators are `<`, `<=`, `>`, `>=` and `==` (or `=`), which is the
+ * default. The units, in multiples of 1024, are bytes (`b`, the default),
+ * kilobytes (`k`, `kb`), megabytes (`m`, `mb`), gigabytes (`g`, `gb`) and
+ * terabytes (`t`, `tb`), in any case. Use {@link sizeEquals} for an exact
+ * number of bytes.
  *
  * @param expression - the size expression
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  * @example
  * ```ts
  * FileHound.create().match(size('>1mb'));
@@ -242,6 +248,11 @@ export declare function like(pattern: string): FilePredicate;
 /**
  * Excludes files whose path satisfies any of the given regular expression patterns
  *
+ * @remarks
+ * Used with {@link FileHound.match}, a discarded directory is left out of the
+ * results but still searched. To keep the search out of it, pass its name
+ * to {@link FileHound.skipDirectories} instead.
+ *
  * @param patterns - one or more regular expression patterns
  * @returns the predicate
  * @example
@@ -251,16 +262,28 @@ export declare function like(pattern: string): FilePredicate;
  */
 export declare function discard(...patterns: string[]): FilePredicate;
 /**
- * Matches files by when they were last modified, using a comparison of their
- * age with optional units, such as `'<2 days'` or `'>8h'`. The operators are
- * `<`, `<=`, `>` and `=`, which is the default and compares to the second.
- * The units are minutes (`m`, `min`), hours (`h`) and days (`d`), which is
- * the default.
+ * Matches files by when they were last modified, using an expression of their
+ * age: an optional operator, a whole number and an optional unit, such as
+ * `'<2 days'`, `'>8h'` or `'>=1 week'`.
+ *
+ * The operators are `<`, `<=`, `>`, `>=` and `==` (or `=`), which is the
+ * default. The units are minutes (`m`, `min`, `mins`, `minute`, `minutes`),
+ * hours (`h`, `hour`, `hours`), days (`d`, `day`, `days`, the default) and
+ * weeks (`w`, `week`, `weeks`), in any case.
+ *
+ * @remarks
+ * Ages are compared in whole units, like `find -mtime`: a file modified two
+ * and a half days ago is 2 days old, so it matches `'=2 days'`, `'>=2 days'`
+ * and `'<3 days'`, but not `'>2 days'`. Days and weeks are calendar days, so
+ * stay correct across daylight saving changes. Ages are measured when each
+ * file is tested.
  *
  * @param expression - the age expression
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  * @example
  * ```ts
  * FileHound.create().match(modified('<2 days'));
@@ -275,6 +298,8 @@ export declare function modified(expression: string): FilePredicate;
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  */
 export declare function accessed(expression: string): FilePredicate;
 /**
@@ -285,6 +310,8 @@ export declare function accessed(expression: string): FilePredicate;
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  */
 export declare function changed(expression: string): FilePredicate;
 /**

package/dist/matchers.js

@@ -146,11 +146,14 @@ export class Size extends AbstractFilePredicate {
         return this.#isMatch(file.sizeSync());
     }
 }
+// Ages are measured when a file is tested, not when the predicate is made, so
+// a predicate kept and reused later still compares against the current time
+const MEASURED_WHEN_TESTED = Object.freeze({ now: () => Date.now() });
 export class Modified extends AbstractFilePredicate {
     #isMatch;
     constructor(expression) {
         super();
-        this.#isMatch = parseAge(expression);
+        this.#isMatch = parseAge(expression, MEASURED_WHEN_TESTED);
     }
     async test(file) {
         return this.#isMatch(await file.lastModified());
@@ -163,7 +166,7 @@ export class Accessed extends AbstractFilePredicate {
     #isMatch;
     constructor(expression) {
         super();
-        this.#isMatch = parseAge(expression);
+        this.#isMatch = parseAge(expression, MEASURED_WHEN_TESTED);
     }
     async test(file) {
         return this.#isMatch(await file.lastAccessed());
@@ -176,7 +179,7 @@ export class Changed extends AbstractFilePredicate {
     #isMatch;
     constructor(expression) {
         super();
-        this.#isMatch = parseAge(expression);
+        this.#isMatch = parseAge(expression, MEASURED_WHEN_TESTED);
     }
     async test(file) {
         return this.#isMatch(await file.lastChanged());
@@ -212,15 +215,21 @@ function expressionFor(matcher, expression, example) {
     return expression;
 }
 /**
- * Matches files by size, using a comparison with optional units, such as
- * `'>10k'` or `'<=1mb'`. The operators are `<`, `<=`, `>`, `>=` and `==`,
- * which is the default, and the units are `b`, `k`, `m`, `g` and `t`, in
- * multiples of 1024. Use {@link sizeEquals} for an exact number of bytes.
+ * Matches files by size, using an expression of an optional operator, a
+ * whole number and an optional unit, such as `'>10kb'` or `'<= 1 mb'`.
+ *
+ * The operators are `<`, `<=`, `>`, `>=` and `==` (or `=`), which is the
+ * default. The units, in multiples of 1024, are bytes (`b`, the default),
+ * kilobytes (`k`, `kb`), megabytes (`m`, `mb`), gigabytes (`g`, `gb`) and
+ * terabytes (`t`, `tb`), in any case. Use {@link sizeEquals} for an exact
+ * number of bytes.
  *
  * @param expression - the size expression
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  * @example
  * ```ts
  * FileHound.create().match(size('>1mb'));
@@ -313,6 +322,11 @@ export function like(pattern) {
 /**
  * Excludes files whose path satisfies any of the given regular expression patterns
  *
+ * @remarks
+ * Used with {@link FileHound.match}, a discarded directory is left out of the
+ * results but still searched. To keep the search out of it, pass its name
+ * to {@link FileHound.skipDirectories} instead.
+ *
  * @param patterns - one or more regular expression patterns
  * @returns the predicate
  * @example
@@ -336,16 +350,28 @@ function cleanExtension(fileExtension) {
     return fileExtension;
 }
 /**
- * Matches files by when they were last modified, using a comparison of their
- * age with optional units, such as `'<2 days'` or `'>8h'`. The operators are
- * `<`, `<=`, `>` and `=`, which is the default and compares to the second.
- * The units are minutes (`m`, `min`), hours (`h`) and days (`d`), which is
- * the default.
+ * Matches files by when they were last modified, using an expression of their
+ * age: an optional operator, a whole number and an optional unit, such as
+ * `'<2 days'`, `'>8h'` or `'>=1 week'`.
+ *
+ * The operators are `<`, `<=`, `>`, `>=` and `==` (or `=`), which is the
+ * default. The units are minutes (`m`, `min`, `mins`, `minute`, `minutes`),
+ * hours (`h`, `hour`, `hours`), days (`d`, `day`, `days`, the default) and
+ * weeks (`w`, `week`, `weeks`), in any case.
+ *
+ * @remarks
+ * Ages are compared in whole units, like `find -mtime`: a file modified two
+ * and a half days ago is 2 days old, so it matches `'=2 days'`, `'>=2 days'`
+ * and `'<3 days'`, but not `'>2 days'`. Days and weeks are calendar days, so
+ * stay correct across daylight saving changes. Ages are measured when each
+ * file is tested.
  *
  * @param expression - the age expression
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  * @example
  * ```ts
  * FileHound.create().match(modified('<2 days'));
@@ -362,6 +388,8 @@ export function modified(expression) {
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  */
 export function accessed(expression) {
     return new Accessed(expressionFor('accessed', expression, '<2 days'));
@@ -374,6 +402,8 @@ export function accessed(expression) {
  * @returns the predicate
  * @throws `TypeError`
  * Thrown if the expression is not a string.
+ * @throws `ExpressionError`
+ * Thrown if the expression can't be parsed or has an unknown unit.
  */
 export function changed(expression) {
     return new Changed(expressionFor('changed', expression, '<2 days'));

package/dist/walker/walk.d.ts

@@ -7,6 +7,7 @@ export type WalkOptions = {
     ignoreHiddenDirectories: boolean;
     ignoreSymlinks: boolean;
     fileTypes: FileType[];
+    skipDirectories: readonly string[];
     signal?: AbortSignal;
 };
 export declare const EntryType: {

package/dist/walker/walk.js

@@ -1,4 +1,4 @@
-import { dirname, resolve } from 'node:path';
+import { basename, dirname, matchesGlob, resolve } from 'node:path';
 import { FileType } from '../filetype.js';
 import { isSyncPredicate } from '../matchers.js';
 // Every entry has one. FileType is the public subset; anything else, such as a
@@ -39,15 +39,25 @@ export class Walk {
                 return false;
         }
     }
-    // Hidden directories are neither returned nor walked
+    // Hidden directories, when ignored, and those named by skipDirectories are
+    // neither returned nor walked. Only names are tested, so the async walk
+    // can skip a directory before reading it ahead.
     shouldSkipDirectory(dir) {
-        return this.#opts.ignoreHiddenDirectories && dir.isHiddenSync();
+        return (this.#opts.ignoreHiddenDirectories && dir.isHiddenSync()) || this.#isSkippedName(dir);
     }
     // depth counts levels below the root, which is 0. A directory beyond
     // maxDepth is still returned, like any other entry at its level, but not walked.
     canDescend(depth) {
         return this.#opts.maxDepth === undefined || depth <= this.#opts.maxDepth;
     }
+    #isSkippedName(dir) {
+        const skip = this.#opts.skipDirectories;
+        if (skip.length === 0) {
+            return false;
+        }
+        const name = basename(dir.getName());
+        return skip.some(pattern => matchesGlob(name, pattern));
+    }
     #typeEnabled(type) {
         return this.#opts.fileTypes.includes(type);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filehound",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0",
   "description": "Find files the easy way",
   "type": "module",
   "main": "dist/index.js",
@@ -26,9 +26,10 @@
     "prepublishOnly": "npm run clean && npm run build",
     "test": "mocha",
     "posttest": "npm run lint",
-    "lint": "eslint src test bench",
+    "lint": "eslint src test bench examples scripts",
     "coverage": "c8 mocha",
-    "bench": "npm run build && node bench/bench.mjs"
+    "bench": "npm run build && node bench/bench.mjs",
+    "examples": "npm run build && node scripts/run-examples.mjs"
   },
   "repository": {
     "type": "git",