fdir Documentation

At its core, fdir is a directory walker that takes a rootDirectory path and various flags/filters to recursively output all file paths.

To maximize performance, fdir uses a conditional function building strategy. Instead of using heavy branching logic during the walk, it builds tiny, specialized internal functions based on the provided flags. These functions are designed to be inlined by the JavaScript engine, which reduces branching overhead and memory allocations during the filesystem traversal.

fdir uses a builder pattern to configure a crawler instance fluently. Instead of passing a large configuration object to a single function, you chain configuration methods on a new fdir instance, call .crawl(path) to prepare the crawler, and finally call one of the execution methods (.withPromise(), .withCallback(), or .sync()).

Example workflow:

new fdir()
  .withBasePath()
  .crawl("path/to/dir")
  .sync();

To perform a basic synchronous crawl of a directory, instantiate fdir, call .crawl() with your target path, and end with .sync().

const files = new fdir().crawl("/path/to/dir").sync();

To use fdir, instantiate the fdir builder, configure your desired options (like withFullPaths()), and specify the target directory with crawl(). You can then retrieve the files either synchronously using .sync() or asynchronously using .withPromise().

import { fdir } from "fdir";

// create the builder
const api = new fdir().withFullPaths().crawl("path/to/dir");

// get all files in a directory synchronously
const files = api.sync();

// or asynchronously
api.withPromise().then((files) => {
  // do something with the result here.
});

Depending on your module system, import fdir as follows:

ES5 Require:

const { fdir } = require("fdir");

ES6 Import:

import { fdir } from "fdir";

You can install fdir using npm or Yarn to use it as a high-speed directory crawler and globber in your NodeJS projects.

$ npm i fdir

$ yarn add fdir

To use fdir, ensure you have Node.js installed and use one of the following package managers:

Using yarn:

$ yarn add fdir

Using npm:

$ npm install fdir

Depending on your Options, fdir returns one of three primary output types:

1. PathsOutput: An array of strings (string[]) representing the paths found. This is the default behavior.
2. OnlyCountsOutput (Counts): An object containing the total number of files and directories found.
   • files: number
   • directories: number
   • dirs: number (Deprecated, use directories instead)
3. GroupOutput (Group[]): An array of objects grouping files by their parent directory.
   • directory: string (The path to the directory)
   • files: string[] (Array of file paths within that directory)
   • dir: string (Deprecated, use directory instead)

If you prefer not to use method chaining, you can pass an Options object directly to crawlWithOptions.

Supported Options:

type Options = {
  includeBasePath?: boolean;
  includeDirs?: boolean;
  normalizePath?: boolean;
  maxDepth?: number;
  maxFiles?: number;
  resolvePaths?: boolean;
  suppressErrors?: boolean;
  group?: boolean;
  onlyCounts?: boolean;
  filters: FilterFn[];
  resolveSymlinks?: boolean;
  useRealPaths?: boolean;
  excludeFiles?: boolean;
  excludeSymlinks?: boolean;
  exclude?: ExcludeFn;
  relativePaths?: boolean;
  pathSeparator: PathSeparator;
  signal?: AbortSignal;
  globFunction?: Function;
};

Example:

new fdir()
  .crawlWithOptions("path/to/dir", {
    includeBasePath: true,
  })
  .sync();

Apply glob filters to include only matching files. fdir uses picomatch internally, but you must install it manually if you want to use custom glob functions.

• glob(...string[]): Applies a glob filter to all files.
• globWithOptions(string[], Object): Applies a glob filter with specific matcher options.
• withGlobFunction(Function): Uses a provided function (like picomatch) to perform the matching.

Example:

// Using built-in glob
const crawler = new fdir().glob("./**/*.js", "./**/*.md");

// Using a custom glob function
import picomatch from 'picomatch';
const crawler = new fdir().withGlobFunction(picomatch);

To optimize performance when you only need the totals, use onlyCounts(). This changes the output from an array of paths to an object containing files and dirs counts.

Example:

const { files, dirs } = new fdir().onlyCounts().sync();