filehound 2.0.0-beta.2 → 2.0.0

package/dist/filehound.js

@@ -0,0 +1,498 @@
+import * as path from 'node:path';
+import { EventEmitter } from 'node:events';
+import { from } from './arrays.js';
+import { reducePaths } from './files.js';
+import { matchAll } from './matchers.js';
+import { FileType } from './filetype.js';
+import { walkAsync } from './walker/async.js';
+import { walkSync } from './walker/sync.js';
+const fileTypes = Object.values(FileType);
+/**
+ * A fluent query for searching the file system.
+ *
+ * @typeParam T - the type of each match: a path, or a {@link FileWithStats}
+ * when {@link FileHound.includeFileStats} is set
+ *
+ * @remarks
+ * Configure a query by chaining methods, then run it with {@link FileHound.find}
+ * or {@link FileHound.findSync}. Once a search has started the query is locked
+ * and can no longer be modified.
+ *
+ * @example
+ * ```ts
+ * import { FileHound, ext } from 'filehound';
+ *
+ * const files = await FileHound.create()
+ *   .paths('/tmp')
+ *   .match(ext('json'))
+ *   .depth(1)
+ *   .find();
+ * ```
+ */
+export class FileHound extends EventEmitter {
+    #searchPaths;
+    #maxDepth;
+    #types;
+    #matchExpression;
+    #skipDirectories = [];
+    #ignoreHiddenFiles = false;
+    #ignoreHiddenDirectories = false;
+    #ignoreSymlinks = false;
+    #includeFileStats = false;
+    #queryLocked = false;
+    constructor() {
+        super();
+        this.#searchPaths = [process.cwd()];
+        this.#types = [FileType.REGULAR];
+    }
+    /**
+     * Static factory method to create an instance of FileHound
+     *
+     * @returns a new FileHound instance
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const filehound = FileHound.create();
+     * ```
+     */
+    static create() {
+        return new FileHound();
+    }
+    /**
+     * Executes one or more FileHound queries and combines their results
+     *
+     * @param args - the FileHound instances to execute
+     * @returns a Promise of all matches. If the Promise fulfils,
+     * the fulfilment value is an array of all files matched by any of the queries
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.any(fh1, fh2);
+     * ```
+     */
+    static async any(...args) {
+        const pending = args.map(fh => fh.find());
+        const files = await Promise.all(pending);
+        return files.flat();
+    }
+    paths(...args) {
+        this.#throwIfQueryLocked();
+        this.#searchPaths = [...new Set(from(args))].map(path.normalize);
+        return this;
+    }
+    /**
+     * Specifies the criteria that files must satisfy to be included in the
+     * results. Defaults to matching all files.
+     *
+     * @param query - the predicate used to test each file
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @throws `TypeError`
+     * Thrown if the query is not a valid matcher.
+     * @example
+     * ```ts
+     * import { FileHound, ext } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .match(ext('json'))
+     *   .find();
+     * ```
+     */
+    match(query) {
+        this.#throwIfQueryLocked();
+        if (query === null || query === undefined || typeof query !== 'object' || typeof query.test !== 'function' || typeof query.testSync !== 'function') {
+            throw new TypeError('Match expression must be a valid matcher');
+        }
+        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
+     * still returned when {@link FileHound.type} includes directories.
+     *
+     * @param depth - the maximum search depth (a non-negative integer)
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @throws `RangeError`
+     * Thrown if depth is negative or not an integer.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .depth(0)
+     *   .find(); // array of file names only in the current directory
+     * ```
+     */
+    depth(depth) {
+        this.#throwIfQueryLocked();
+        if (depth < 0 || !Number.isSafeInteger(depth)) {
+            throw new RangeError('Depth must be a positive integer');
+        }
+        this.#maxDepth = depth;
+        return this;
+    }
+    /**
+     * Specifies the types of file system entry to return. Defaults to
+     * regular files only.
+     *
+     * @param types - one or more file types
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @throws `RangeError`
+     * Thrown if no file types are given.
+     * @throws `TypeError`
+     * Thrown if an invalid file type is given.
+     * @example
+     * ```ts
+     * import { FileHound, FileType } from 'filehound';
+     *
+     * const directories = await FileHound.create()
+     *   .type(FileType.DIRECTORY)
+     *   .find();
+     * ```
+     */
+    type(...types) {
+        this.#throwIfQueryLocked();
+        this.#validateTypeArguments(types);
+        this.#types = types;
+        return this;
+    }
+    /**
+     * Excludes hidden files (names beginning with a dot) from the results
+     *
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .ignoreHiddenFiles()
+     *   .find();
+     * ```
+     */
+    ignoreHiddenFiles() {
+        this.#throwIfQueryLocked();
+        this.#ignoreHiddenFiles = true;
+        return this;
+    }
+    /**
+     * Excludes hidden directories (names beginning with a dot), and their
+     * contents, from the search
+     *
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .ignoreHiddenDirectories()
+     *   .find();
+     * ```
+     */
+    ignoreHiddenDirectories() {
+        this.#throwIfQueryLocked();
+        this.#ignoreHiddenDirectories = true;
+        return this;
+    }
+    /**
+     * Excludes symbolic links from the search. Linked files are not matched
+     * and linked directories are not searched.
+     *
+     * @remarks
+     * By default, symbolic links are followed: a linked file is matched as its
+     * target and a linked directory is searched. Broken links, and links back to
+     * a directory already being searched, are always skipped.
+     *
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .ignoreSymlinks()
+     *   .find();
+     * ```
+     */
+    ignoreSymlinks() {
+        this.#throwIfQueryLocked();
+        this.#ignoreSymlinks = true;
+        return this;
+    }
+    /**
+     * Returns each match with its stats, as `{ path, stats }`, in place of
+     * its path. Stats already fetched by a predicate are reused.
+     *
+     * @returns the FileHound instance, typed to return {@link FileWithStats} matches
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .includeFileStats()
+     *   .find();
+     *
+     * files.forEach(({ path, stats }) => console.log(path, stats.size));
+     * ```
+     */
+    includeFileStats() {
+        this.#throwIfQueryLocked();
+        this.#includeFileStats = true;
+        return this;
+    }
+    /**
+     * Asynchronously executes a file search. Once called, the query is
+     * locked and can no longer be modified.
+     *
+     * @param options - a signal to stop the search
+     * @returns a Promise of all matches. If the Promise fulfils,
+     * the fulfilment value is an array of all matching files
+     *
+     * @remarks
+     * Emits a `match` event for each matching file, an `error` event if the
+     * search fails or is aborted and an `end` event when the search completes.
+     *
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const filehound = FileHound.create();
+     * const files = await filehound.find();
+     *
+     * console.log(files);
+     * ```
+     * @example
+     * Giving up on a search after five seconds:
+     * ```ts
+     * const files = await FileHound.create()
+     *   .paths('/')
+     *   .find({ signal: AbortSignal.timeout(5000) });
+     * ```
+     */
+    async find(options = {}) {
+        this.#queryLocked = true;
+        const found = [];
+        try {
+            for await (const results of this.#getNextBatch(options.signal)) {
+                for (const result of results) {
+                    found.push(result);
+                    this.emit('match', result);
+                    options.signal?.throwIfAborted();
+                }
+            }
+            return found;
+        }
+        catch (error) {
+            this.emit('error', error);
+            throw error;
+        }
+        finally {
+            this.emit('end');
+        }
+    }
+    /**
+     * Asynchronously executes a file search, returning matches one at a time
+     * as they are found, in the same order as {@link FileHound.find}. Once
+     * called, the query is locked and can no longer be modified.
+     *
+     * @remarks
+     * The search runs ahead of the loop by a bounded amount, so a large search
+     * can be read without holding every match in memory. Breaking out of the
+     * loop stops the search.
+     *
+     * Emits a `match` event as each match is returned, an `error` event if the
+     * search fails or is aborted and an `end` event when the search finishes:
+     * when every match has been returned, the search fails or is aborted, or
+     * the loop is left early.
+     *
+     * @param options - a signal to stop the search
+     * @returns an async iterator of matches
+     * @example
+     * ```ts
+     * import { FileHound, ext } from 'filehound';
+     *
+     * const query = FileHound.create()
+     *   .paths('/tmp')
+     *   .match(ext('json'));
+     *
+     * for await (const file of query.iterate()) {
+     *   console.log(file);
+     * }
+     * ```
+     */
+    iterate(options = {}) {
+        this.#queryLocked = true;
+        return this.#iterate(options.signal);
+    }
+    /**
+     * Synchronously executes a file search. Once called, the query is
+     * locked and can no longer be modified. No events are emitted.
+     *
+     * @returns an array of all matching files
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const filehound = FileHound.create();
+     * const files = filehound.findSync();
+     * console.log(files);
+     * ```
+     */
+    findSync() {
+        this.#queryLocked = true;
+        return this.getPaths()
+            .flatMap(dir => this.#searchSync(dir))
+            .map(file => this.#toResultSync(file));
+    }
+    /**
+     * Returns the paths that will be searched. When no depth is set, any path
+     * that is a subdirectory of another search path is removed, as it would
+     * otherwise be searched twice.
+     *
+     * @returns a copy of the search paths
+     */
+    getPaths() {
+        const paths = this.#maxDepth !== undefined
+            ? this.#searchPaths
+            : reducePaths(this.#searchPaths);
+        return [...paths];
+    }
+    #throwIfQueryLocked() {
+        if (this.#queryLocked) {
+            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');
+        }
+        types.forEach((type) => {
+            if (!fileTypes.includes(type)) {
+                throw new TypeError(`Invalid file type: ${type}.`);
+            }
+        });
+    }
+    #getMatchExpression() {
+        return this.#matchExpression ?? matchAll();
+    }
+    async #toResult(file) {
+        if (this.#includeFileStats) {
+            return { path: file.getName(), stats: await file.getStats() };
+        }
+        return file.getName();
+    }
+    #toResultSync(file) {
+        if (this.#includeFileStats) {
+            return { path: file.getName(), stats: file.getStatsSync() };
+        }
+        return file.getName();
+    }
+    #searchSync(dir) {
+        return walkSync(dir, this.#getMatchExpression(), this.#getOptions());
+    }
+    async *#iterate(signal) {
+        try {
+            for await (const results of this.#getNextBatch(signal)) {
+                for (const result of results) {
+                    this.emit('match', result);
+                    yield result;
+                    signal?.throwIfAborted();
+                }
+            }
+        }
+        catch (error) {
+            this.emit('error', error);
+            throw error;
+        }
+        finally {
+            this.emit('end');
+        }
+    }
+    async *#getNextBatch(signal) {
+        for (const dir of this.getPaths()) {
+            for await (const files of walkAsync(dir, this.#getMatchExpression(), this.#getOptions(signal))) {
+                yield this.#includeFileStats
+                    ? await Promise.all(files.map(file => this.#toResult(file)))
+                    : files.map(file => file.getName());
+            }
+        }
+    }
+    #getOptions(signal) {
+        return {
+            ignoreHiddenDirectories: this.#ignoreHiddenDirectories,
+            ignoreHiddenFiles: this.#ignoreHiddenFiles,
+            ignoreSymlinks: this.#ignoreSymlinks,
+            maxDepth: this.#maxDepth,
+            fileTypes: this.#types,
+            skipDirectories: this.#skipDirectories,
+            signal
+        };
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,4 @@
+export declare function findSubDirectories(paths: string[]): string[];
+export declare function notSubDirectory(subDirs: string[]): (s: string) => boolean;
+export declare function isSubDirectory(base: string, candidate: string): boolean;
+export declare function reducePaths(searchPaths: string[]): string[];

package/dist/files.js

@@ -0,0 +1,37 @@
+import * as path from 'node:path';
+// dirname is a fixed point at a root (`/`, `C:\`) and at `.`
+function hasParent(parent) {
+    return path.dirname(parent) !== parent;
+}
+function getParent(dir) {
+    return path.dirname(dir);
+}
+function getSubDirectories(base, allPaths) {
+    return allPaths.filter((candidate) => {
+        return base !== candidate && isSubDirectory(base, candidate);
+    });
+}
+export function findSubDirectories(paths) {
+    return paths.flatMap(p => getSubDirectories(p, paths));
+}
+export function notSubDirectory(subDirs) {
+    return (p) => !subDirs.includes(p);
+}
+export function isSubDirectory(base, candidate) {
+    let parent = candidate;
+    while (hasParent(parent)) {
+        if (base === parent) {
+            return true;
+        }
+        parent = getParent(parent);
+    }
+    return false;
+}
+export function reducePaths(searchPaths) {
+    if (searchPaths.length === 1) {
+        return searchPaths;
+    }
+    const sortedPaths = searchPaths.toSorted();
+    const subDirs = findSubDirectories(sortedPaths);
+    return sortedPaths.filter(notSubDirectory(subDirs));
+}

package/dist/filetype.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The types of file system entry that a search can return. The values are
+ * plain strings, so `'directory'` can be passed in place of `FileType.DIRECTORY`.
+ */
+export declare const FileType: {
+    /** Regular files only: not sockets, FIFOs or devices */
+    readonly REGULAR: "regular";
+    readonly DIRECTORY: "directory";
+};
+export type FileType = typeof FileType[keyof typeof FileType];

package/dist/filetype.js

@@ -0,0 +1,9 @@
+/**
+ * The types of file system entry that a search can return. The values are
+ * plain strings, so `'directory'` can be passed in place of `FileType.DIRECTORY`.
+ */
+export const FileType = {
+    /** Regular files only: not sockets, FIFOs or devices */
+    REGULAR: 'regular',
+    DIRECTORY: 'directory'
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FileHound, type FileWithStats, type SearchOptions } from './filehound.js';
+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

@@ -0,0 +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';