glob

Glob resolves shell-style wildcard patterns like **/*.js into lists of matching file paths, giving Node.js programs the same globbing power the Unix shell has at the command line. It supports globstar recursion, brace expansion, character classes, negation, and fine-grained ignore rules, returning results as arrays, async/sync iterators, or backpressure-aware Minipass streams.

Authored by Isaac Z. Schlueter and depended on by npm itself, ESLint, Mocha, and thousands of other build tools, glob is one of the most widely installed packages in the JavaScript ecosystem with hundreds of millions of weekly downloads. Version 13 is written in TypeScript, ships both ESM and CommonJS builds, and exposes a rich options surface for cwd control, symlink handling, file-type objects, and cancellation.

What You Get

• Async and synchronous APIs (glob, globSync) that resolve to arrays of matching file paths
• Streaming and iterator interfaces (globStream, globIterate) for processing large result sets with backpressure
• A reusable Glob class that caches filesystem reads across repeated walks in the same directory tree
• Rich options including globstar recursion, brace expansion, custom ignore functions, withFileTypes Path objects, and AbortSignal cancellation
• First-class TypeScript types with dual ESM and CommonJS builds

Common Use Cases

• Collecting source files for build tools, bundlers, and test runners
• Selecting files to lint, format, or transform by wildcard pattern
• Cleaning or copying files matching a pattern in scripts and task runners
• Streaming large directory trees while filtering with custom ignore rules

Under The Hood

Architecture

The public surface in src/index.ts re-exports the Glob class (src/glob.ts) and thin functional wrappers (glob, globSync, globStream, globIterate and their sync variants) that each construct a Glob and delegate to it. src/glob.ts normalizes options and parses the input into immutable Pattern objects (src/pattern.ts), which the Processor (src/processor.ts) walks against the filesystem via the GlobWalker/GlobStream machinery in src/walker.ts. Directory reads are delegated to path-scurry for cached, symlink-aware traversal, individual path segments are matched with minimatch, and results are emitted through minipass streams so async, sync, iterator, and streaming call styles all share one core walk. Ignore logic lives in src/ignore.ts, and src/has-magic.ts provides magic-character detection.

Tech Stack

Written in TypeScript targeting Node 18/20/22+, glob has just three runtime dependencies: minimatch (pattern-to-regex compilation and escape/unescape), minipass (streams), and path-scurry (cached filesystem walking). It builds with tshy to emit both ESM and CommonJS outputs plus minified bundles via esbuild, is linted with oxlint, and formatted with Prettier.

Code Quality

The repository has an extensive test/ directory (40+ tap test files covering absolute paths, symlinks, custom filesystems via memfs, ignore rules, Windows path handling, and bash-comparison fixtures), with tap snapshots committed. The code is strongly typed with heavily overloaded signatures so return types narrow correctly based on the withFileTypes option, and the walker separates async and sync paths explicitly rather than papering over them.

API Design The API is ergonomic and progressive: a one-line await glob('**/*.js') covers the common case, while the Glob class, streams, and iterators serve advanced needs, and a prior Glob instance can be passed as the options object to share caches. TypeScript overloads make withFileTypes return the right type automatically, and the README is exhaustive with runnable examples for every method and option. As of v13 the CLI moved to a separate glob-bin package, keeping the library dependency lean.