filehound 2.0.0-beta.2 → 2.0.0

package/README.md

@@ -1,44 +1,68 @@
 # 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
 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
 
 ```
@@ -53,3 +77,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;