fast-glob

fast-glob is a Node.js library for matching files and directories using glob patterns, built for speed on large file trees. It reimplements glob matching from scratch instead of wrapping the older glob package, with a provider-based architecture (sync, async, and stream) that lets callers pick the execution mode that fits their use case.

The library is a common dependency inside build tools, linters, and bundlers (webpack, ESLint, ts-node, and many others) precisely because its performance profile matters at scale — scanning tens of thousands of files repeatedly during a build or watch loop. It supports the full glob syntax (**, brace expansion, extglob, negation) plus options for absolute paths, dot-file matching, and custom filesystem adapters.

What You Get

• Synchronous, asynchronous (Promise-based), and Node.js Stream APIs for glob matching, chosen per call site
• Full glob syntax support including ** globstar, brace expansion {a,b}, extglob, and negation patterns
• A pluggable provider architecture (src/providers) separating pattern matching from filesystem reading
• Options for absolute paths, dot-file inclusion, symlink following, and case sensitivity
• A dedicated benchmark suite (src/benchmark) used to guard performance regressions across releases

Common Use Cases

• File discovery inside build tools and bundlers that need to resolve glob patterns from config (e.g. include/exclude arrays) to real file lists
• Linters and formatters (ESLint-style tools) scanning a project for files matching configured patterns while respecting ignore rules
• Test runners collecting test files matching a pattern like **/*.spec.ts across a large monorepo
• Static site generators and codemods that need to enumerate matching files before a batch transform

Under The Hood

Architecture - The codebase is split into clear layers: src/providers implements the async/sync/stream execution strategies behind a shared interface, src/managers (task manager) groups and optimizes raw glob patterns into base-directory tasks before matching starts, src/readers handles the actual filesystem traversal (delegating to @nodelib/fs.walk and @nodelib/fs.stat under the hood), and src/utils holds pattern-parsing helpers built on micromatch/picomatch-style matching via @nodelib/fs.walk’s deps. src/settings.ts centralizes and normalizes user-supplied options into one internal settings object consumed by every provider.

Tech Stack - Written in TypeScript, compiled to out/ (CommonJS + type declarations) for publishing. It depends on the @nodelib/fs.* family (fs.stat, fs.scandir, fs.walk) for low-level, optimized filesystem operations, plus merge2, micromatch, and glob-parent for pattern-related utilities — deliberately composing small, focused packages rather than reimplementing filesystem walking itself.

Code Quality - Tests are colocated as .spec.ts files alongside implementation (24 spec files against 60 non-spec source files), with a dedicated __snapshots__ directory and fixtures/ tree used for realistic filesystem-based test scenarios. A src/tests directory holds shared test utilities used across the provider/manager/reader suites. Repository activity has slowed markedly in the last year (0 commits/month at time of analysis, last push several months ago), which is common for a mature, feature-complete utility library but worth noting for anyone evaluating long-term maintenance risk.

API Design - The primary export is a single function overloaded by call style: fastGlob(patterns, options) returns a Promise by default, with .sync() and .stream() variants for synchronous and streaming use, plus a .glob() alias and pattern-utility exports (isDynamicPattern, generateTasks, escapePath, convertPathToPattern) for advanced consumers who need to inspect or preprocess patterns themselves. This single-function-with-variants shape keeps the common case (await fastGlob('**/*.js')) a one-liner while still exposing lower-level building blocks.