tinyglobby

tinyglobby is a minimal glob-matching library for Node.js designed to replace globby and fast-glob without giving up their behavior. It supports the same core options - directory expansion, negation, brace expansion, extglobs, and both absolute and relative path modes - while pulling in only two subdependencies (fdir and picomatch) compared to globby’s 23 and fast-glob’s 17.

Under the hood it uses a custom partial-matcher to prune the directory crawl early, plus depth-offset tracking so it never walks further than the patterns require. Both async (glob) and sync (globSync) entry points are exported, and it ships as a modern dual ESM/CJS package built with tsdown.

What You Get

• Drop-in glob() and globSync() APIs - Async and sync entry points that accept a pattern string or array, matching common fast-glob/globby call signatures.
• Directory expansion - Bare directory patterns like src automatically expand to src/** so directory-only entries still match every file inside.
• Negation and ignore patterns - Supports !pattern negation inline with the pattern list as well as a dedicated ignore option.
• Absolute or relative results - Toggle absolute to get full paths back instead of paths relative to cwd.
• Custom filesystem adapter - Pass an fs option to override readdir/stat/realpath implementations for testing or virtual filesystems.
• Debug logging - Set debug: true (or TINYGLOBBY_DEBUG) to log matched/skipped paths during a crawl.

Common Use Cases

• Build tool integration - Bundlers and compilers resolve source and asset file lists without pulling in a heavy glob dependency chain.
• Migrating off fast-glob/globby - Projects reduce their dependency count by swapping to tinyglobby’s smaller footprint while keeping matching behavior compatible.
• CLI file targeting - Command-line tools accept glob patterns from users to select which files to lint, format, or process.
• Test fixture discovery - Test runners and fixture loaders enumerate spec files or fixture directories matching a pattern.

Under The Hood

Architecture tinyglobby is organized into four small, single-purpose modules: index.ts exposes the public glob/globSync API and resolves options against sane defaults; patterns.ts normalizes raw patterns into match/ignore lists and computes the crawl root plus a depth offset (processPatterns/normalizePattern); crawler.ts wires the processed patterns into an fdir crawler with picomatch-based filters and an exclude predicate; and utils.ts holds the path-formatting, escaping, and partial-matching helpers shared by the other modules. This separation means pattern-normalization logic can evolve independently of the crawling strategy, and the path-formatting math in utils.ts has no dependency on either. Because the library wraps fdir’s crawler and picomatch’s matcher rather than reimplementing filesystem traversal, a change to the core crawling abstraction would primarily touch crawler.ts and patterns.ts, leaving the escaping/formatting utilities untouched.

Tech Stack The library is written in TypeScript and published as an ESM-first, dual-format package (.mjs/.cjs/.d.cts) built with tsdown, a Rolldown-based bundler. Its only runtime dependencies are fdir (a fast directory crawler) and picomatch (glob-to-regex matching); everything else - @biomejs/biome for linting/formatting, typescript for type-checking, and tinybench for benchmarking against fast-glob - lives in devDependencies. Tests run on Node’s built-in node:test runner rather than a third-party framework, with fs-fixture used to materialize realistic temporary filesystem trees (including symlinks) for behavioral assertions.

Code Quality The test suite combines broad behavioral coverage in index.test.ts - directory expansion, negation, symlinks, dot-files - with focused unit tests per utility (partial-matcher, isDynamicPattern, escapePath, convertPathToPattern, ensureNonDriveRelativePath), and CI runs both Biome’s linter/formatter and the full test suite across Ubuntu and Windows matrices, which matters given how path-separator-sensitive this kind of code is. Source comments are used deliberately to explain non-obvious matching edge cases rather than restate the code, and the codebase favors explicit throws (e.g. rejecting simultaneous positional and options-based patterns) over silently swallowed errors.

What Makes It Unique tinyglobby’s core claim - matching globby/fast-glob semantics with a fraction of the dependency count - is backed by a genuinely custom optimization: a partial-matcher (getPartialMatcher) that evaluates glob patterns segment-by-segment against a candidate directory path, letting the crawler prune entire subtrees before ever calling readdir on them, combined with depth-offset tracking that narrows the crawl root to the static prefix shared by all patterns. Both are documented in source comments as the product of extended iteration rather than a first-pass implementation, and together they let the library reuse existing crawling/matching primitives (fdir, picomatch) while still avoiding unnecessary filesystem work that a naive wrapper around those same primitives would incur.