filehound 2.0.0-beta.2 → 2.0.0-beta.3

package/README.md

@@ -1,39 +1,61 @@
 # Filehound
 
-![npm](https://img.shields.io/npm/v/filehound.svg)
-[![Build Status](https://travis-ci.org/nspragg/filehound.svg)](https://travis-ci.org/nspragg/filehound) [![Coverage Status](https://coveralls.io/repos/github/nspragg/filehound/badge.svg?branch=master)](https://coveralls.io/github/nspragg/filehound?branch=master)
+[![NPM downloads](https://img.shields.io/npm/dm/filehound.svg?style=flat)](https://npmjs.org/package/filehound)
+[![CI](https://github.com/nspragg/filehound/actions/workflows/ci.yml/badge.svg)](https://github.com/nspragg/filehound/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/nspragg/filehound/badge.svg?branch=master)](https://coveralls.io/github/nspragg/filehound?branch=master)
  ![license](https://img.shields.io/badge/license-MIT-blue.svg) 
 ![github-issues](https://img.shields.io/github/issues/nspragg/filehound.svg)
 ![stars](https://img.shields.io/github/stars/nspragg/filehound.svg)
 ![forks](https://img.shields.io/github/forks/nspragg/filehound.svg)
 > Flexible and fluent interface for searching the file system
 
-![nodei.co](https://nodei.co/npm/filehound.png?downloads=true&downloadRank=true&stars=true)
-
-
 ## Installation
 
 ```
 npm install --save filehound
 ```
 
-## Demo
+Requires Node.js 24 or later.
 
-<img src="https://cloud.githubusercontent.com/assets/917111/13683231/7e915c2c-e6fd-11e5-9d58-e7228cf76ccf.gif" width="600"/>
+Upgrading from V1? See the [migration guide](./MIGRATING.md).
 
 ## Usage
 
 The example below prints all of the files in a directory that have the `.json` file extension:
 
 ```js
-const FileHound = require('filehound');
+import { FileHound, ext } from 'filehound';
 
-const files = FileHound.create()
+const files = await FileHound.create()
   .paths('/some/dir')
-  .ext('json')
+  .match(ext('json'))
   .find();
 
-files.then(console.log);
+console.log(files);
+```
+
+### Iterating over matches
+
+`find()` waits for the whole search to finish. To handle each match as it's found, loop over `iterate()` instead. Matches come in the same order as `find()`, and the search only runs a little ahead of the loop, so a large search doesn't hold every match in memory:
+
+```js
+import { FileHound, ext } from 'filehound';
+
+const query = FileHound.create()
+  .paths('/some/dir')
+  .match(ext('json'));
+
+for await (const file of query.iterate()) {
+  console.log(file);
+}
+```
+
+Leaving the loop early stops the search, for example to find the first match only:
+
+```js
+for await (const file of query.iterate()) {
+  console.log(`First match: ${file}`);
+  break;
+}
 ```
 
 ## Documentation
@@ -53,3 +75,7 @@ npm run coverage
 ## Contributing
 
 See [contributing guide](./CONTRIBUTING.md)
+
+## Related modules
+
+- Finding files by content - [FileSniffer](https://github.com/nspragg/filesniffer)

package/dist/arrays.d.ts

@@ -0,0 +1 @@
+export declare function from<T>(args: (T | T[])[]): T[];

package/dist/arrays.js

@@ -0,0 +1,4 @@
+export function from(args) {
+    const [first] = args;
+    return Array.isArray(first) ? first : args;
+}

package/dist/file.d.ts

@@ -0,0 +1,108 @@
+import { type Dirent, type Stats } from 'node:fs';
+export type FileKind = Pick<Stats, 'isDirectory' | 'isFile'>;
+/**
+ * A read-only view of a file found by a search, as passed to predicates such
+ * as {@link applyFilter}. It has no methods that change the file system.
+ *
+ * @remarks
+ * Predicates may be called ahead of the matches being returned, at the same
+ * time as each other, and on files that are never returned, for example when
+ * a loop over {@link FileHound.iterate} is left early. So a predicate should
+ * have no side effects.
+ *
+ * A file's stats are fetched once, then shared by every predicate and by
+ * {@link FileHound.includeFileStats}.
+ */
+export interface FileView {
+    /** The path, as found from the search path */
+    getName(): string;
+    /** The absolute path */
+    getAbsolutePath(): string;
+    /** The absolute path, normalised */
+    getCanonicalPath(): string;
+    /** The path relative to the search path */
+    getRelativePath(): string;
+    /** The extension, without the leading dot, or an empty string */
+    getPathExtension(): string;
+    /** Whether the path, relative to the search path, matches a glob pattern */
+    isMatch(globPattern: string): boolean;
+    /** Whether this is a directory, or a link to one */
+    isDirectory(): Promise<boolean>;
+    /** Whether this is a directory, or a link to one */
+    isDirectorySync(): boolean;
+    /** Whether this is a regular file, or a link to one */
+    isFile(): Promise<boolean>;
+    /** Whether this is a regular file, or a link to one */
+    isFileSync(): boolean;
+    /** Whether this is a symbolic link */
+    isSymbolicLink(): Promise<boolean>;
+    /** Whether this is a symbolic link */
+    isSymbolicLinkSync(): boolean;
+    /** Whether this is hidden: its name, or for a directory any in its path, begins with a dot */
+    isHidden(): Promise<boolean>;
+    /** Whether this is hidden: its name, or for a directory any in its path, begins with a dot */
+    isHiddenSync(): boolean;
+    /** The stats, as returned by `fs.stat` */
+    getStats(): Promise<Stats>;
+    /** The stats, as returned by `fs.statSync` */
+    getStatsSync(): Stats;
+    /** The size in bytes */
+    size(): Promise<number>;
+    /** The size in bytes */
+    sizeSync(): number;
+    /** When the contents were last modified */
+    lastModified(): Promise<Date>;
+    /** When the contents were last modified */
+    lastModifiedSync(): Date;
+    /** When the file was last accessed */
+    lastAccessed(): Promise<Date>;
+    /** When the file was last accessed */
+    lastAccessedSync(): Date;
+    /** When the file's status, such as its permissions, last changed */
+    lastChanged(): Promise<Date>;
+    /** When the file's status, such as its permissions, last changed */
+    lastChangedSync(): Date;
+    /** Whether the file exists and can be read */
+    exists(): Promise<boolean>;
+    /** Whether the file can be read */
+    isReadable(): Promise<boolean>;
+    /** Whether the file can be written to */
+    isWritable(): Promise<boolean>;
+    /** Whether the file can be executed */
+    isExecutable(): Promise<boolean>;
+}
+export declare function getKnownKind(file: File): FileKind | undefined;
+export declare function getChildren(dir: File): Promise<File[]>;
+export declare function getChildrenSync(dir: File): File[];
+export declare class File implements FileView {
+    #private;
+    constructor(pathname: string, dirent?: Dirent, root?: string);
+    isDirectorySync(): boolean;
+    isFileSync(): boolean;
+    isDirectory(): Promise<boolean>;
+    isFile(): Promise<boolean>;
+    isSymbolicLinkSync(): boolean;
+    isSymbolicLink(): Promise<boolean>;
+    isHiddenSync(): boolean;
+    isHidden(): Promise<boolean>;
+    getName(): string;
+    getAbsolutePath(): string;
+    getCanonicalPath(): string;
+    getRelativePath(): string;
+    getPathExtension(): string;
+    lastModifiedSync(): Date;
+    lastAccessedSync(): Date;
+    lastChangedSync(): Date;
+    sizeSync(): number;
+    lastModified(): Promise<Date>;
+    lastAccessed(): Promise<Date>;
+    lastChanged(): Promise<Date>;
+    size(): Promise<number>;
+    getStatsSync(): Stats;
+    getStats(): Promise<Stats>;
+    isWritable(): Promise<boolean>;
+    isReadable(): Promise<boolean>;
+    isExecutable(): Promise<boolean>;
+    exists(): Promise<boolean>;
+    isMatch(globPattern: string): boolean;
+}

package/dist/file.js

@@ -0,0 +1,184 @@
+var _a;
+import { constants, lstatSync, readdirSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+// What only the walker needs. These are functions rather than methods, so a
+// predicate can't reach them. Only code inside File can see its private
+// fields, so they're set from its static block.
+let knownKindOf;
+let childrenOf;
+let childrenOfSync;
+// The kind readdir gave, so needs no I/O. Undefined for links, whose targets
+// are reported, and for files made without a dirent, such as a walk's root.
+export function getKnownKind(file) {
+    return knownKindOf(file);
+}
+// A directory's entries, with their kinds from readdir
+export function getChildren(dir) {
+    return childrenOf(dir);
+}
+export function getChildrenSync(dir) {
+    return childrenOfSync(dir);
+}
+export class File {
+    #dir;
+    #pathname;
+    // Type info from readdir, saving a stat call
+    #dirent;
+    // The directory a search started from; glob patterns are matched relative to it
+    #root;
+    // Fetched once, so predicates and results share a single stat call
+    #stats;
+    static {
+        knownKindOf = file => file.#dirent?.isSymbolicLink() ? undefined : file.#dirent;
+        childrenOf = async (dir) => dir.#children();
+        childrenOfSync = dir => dir.#childrenSync();
+    }
+    constructor(pathname, dirent, root) {
+        this.#dir = process.cwd();
+        this.#pathname = pathname;
+        this.#dirent = dirent;
+        this.#root = root;
+    }
+    isDirectorySync() {
+        return this.#getKindSync().isDirectory();
+    }
+    isFileSync() {
+        return this.#getKindSync().isFile();
+    }
+    async isDirectory() {
+        return (await this.#getKind()).isDirectory();
+    }
+    async isFile() {
+        return (await this.#getKind()).isFile();
+    }
+    isSymbolicLinkSync() {
+        return this.#dirent?.isSymbolicLink() ?? lstatSync(this.#pathname).isSymbolicLink();
+    }
+    async isSymbolicLink() {
+        return this.#dirent?.isSymbolicLink() ?? (await fsp.lstat(this.#pathname)).isSymbolicLink();
+    }
+    isHiddenSync() {
+        if (!this.isDirectorySync()) {
+            return this.#isHiddenFile();
+        }
+        return this.#isHiddenDirectory();
+    }
+    async isHidden() {
+        if (!await this.isDirectory()) {
+            return this.#isHiddenFile();
+        }
+        return this.#isHiddenDirectory();
+    }
+    getName() {
+        return this.#pathname;
+    }
+    getAbsolutePath() {
+        return path.resolve(this.#dir, this.#pathname);
+    }
+    getCanonicalPath() {
+        return path.normalize(this.getAbsolutePath());
+    }
+    // Relative to the search root, or the working directory like fs.glob
+    getRelativePath() {
+        return path.relative(this.#root ?? this.#dir, this.#pathname);
+    }
+    getPathExtension() {
+        return path.extname(this.#pathname).substring(1);
+    }
+    lastModifiedSync() {
+        return this.getStatsSync().mtime;
+    }
+    lastAccessedSync() {
+        return this.getStatsSync().atime;
+    }
+    lastChangedSync() {
+        return this.getStatsSync().ctime;
+    }
+    sizeSync() {
+        return this.getStatsSync().size;
+    }
+    async lastModified() {
+        return (await this.getStats()).mtime;
+    }
+    async lastAccessed() {
+        return (await this.getStats()).atime;
+    }
+    async lastChanged() {
+        return (await this.getStats()).ctime;
+    }
+    async size() {
+        return (await this.getStats()).size;
+    }
+    getStatsSync() {
+        this.#stats ??= statSync(this.#pathname);
+        return this.#stats;
+    }
+    async getStats() {
+        this.#stats ??= await fsp.stat(this.#pathname);
+        return this.#stats;
+    }
+    async isWritable() {
+        return this.#access(constants.W_OK);
+    }
+    async isReadable() {
+        return this.#access(constants.R_OK);
+    }
+    async isExecutable() {
+        return this.#access(constants.X_OK);
+    }
+    async exists() {
+        return this.#access(constants.R_OK);
+    }
+    isMatch(globPattern) {
+        return path.matchesGlob(this.getRelativePath(), globPattern);
+    }
+    async #children() {
+        if (!await this.isDirectory()) {
+            return [];
+        }
+        const prefix = this.#childPrefix();
+        return (await fsp.readdir(this.#pathname, { withFileTypes: true })).map(entry => this.#child(prefix, entry));
+    }
+    #childrenSync() {
+        if (!this.isDirectorySync()) {
+            return [];
+        }
+        const prefix = this.#childPrefix();
+        return readdirSync(this.#pathname, { withFileTypes: true }).map(entry => this.#child(prefix, entry));
+    }
+    // path.join is the costliest step of a walk, so it runs once per directory
+    // rather than once per entry. Entry names never contain a separator, so
+    // prefix + name is exactly what path.join would give.
+    #childPrefix() {
+        return path.join(this.#pathname, '_').slice(0, -1);
+    }
+    #child(prefix, entry) {
+        return new _a(prefix + entry.name, entry, this.#root ?? this.#pathname);
+    }
+    #getKindSync() {
+        return knownKindOf(this) ?? this.getStatsSync();
+    }
+    async #getKind() {
+        return knownKindOf(this) ?? this.getStats();
+    }
+    #isHiddenFile() {
+        return (/^\./).test(path.basename(this.#pathname));
+    }
+    // Normalising first means either separator is handled on Windows
+    #isHiddenDirectory() {
+        return path.normalize(this.#pathname)
+            .split(path.sep)
+            .some(segment => segment.startsWith('.') && segment !== '.' && segment !== '..');
+    }
+    async #access(permission) {
+        try {
+            await fsp.access(this.#pathname, permission);
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }
+}
+_a = File;

package/dist/filehound.d.ts

@@ -0,0 +1,322 @@
+import { EventEmitter } from 'node:events';
+import type { Stats } from 'node:fs';
+import { type FilePredicate } from './matchers.js';
+import { FileType } from './filetype.js';
+/**
+ * Options for {@link FileHound.find} and {@link FileHound.iterate}.
+ */
+export type SearchOptions = {
+    /**
+     * Stops the search when aborted. The search then rejects with the
+     * signal's reason, which is an `AbortError` unless another is given.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * A match returned when {@link FileHound.includeFileStats} is set.
+ */
+export type FileWithStats = {
+    /** the path of the matching file */
+    path: string;
+    /** the file's stats, as returned by `fs.stat` */
+    stats: Stats;
+};
+/**
+ * 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 declare class FileHound<T = string> extends EventEmitter {
+    #private;
+    constructor();
+    /**
+     * 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(): 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 any<T>(...args: FileHound<T>[]): Promise<T[]>;
+    /**
+     * Defines the search paths: the directories to search. Duplicate paths are
+     * removed and each path is normalised. Defaults to the current working directory.
+     *
+     * @param paths - one or more directory paths
+     * @returns the FileHound instance
+     * @throws `Error`
+     * Thrown if the query is locked because a search has started. A path that
+     * doesn't exist, or isn't a directory, is rejected when the search runs.
+     * @example
+     * ```ts
+     * import { FileHound } from 'filehound';
+     *
+     * const files = await FileHound.create()
+     *   .paths('/tmp', '/etc') // or ['/tmp', '/etc']
+     *   .find();
+     * ```
+     */
+    paths(...paths: string[]): this;
+    /**
+     * Defines the search paths from an array.
+     *
+     * @param paths - an array of paths
+     * @returns the FileHound instance
+     */
+    paths(paths: string[]): 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: FilePredicate): 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: number): 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: FileType[]): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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(): FileHound<FileWithStats>;
+    /**
+     * 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) });
+     * ```
+     */
+    find(options?: SearchOptions): Promise<T[]>;
+    /**
+     * 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?: SearchOptions): AsyncGenerator<T>;
+    /**
+     * 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(): T[];
+    /**
+     * 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(): string[];
+}