Picomatch

Picomatch is a minimal, dependency-free glob matching library for JavaScript. It compiles glob patterns (wildcards, globstars, extglobs, braces, and POSIX character classes) into native regular expressions, giving you accurate Bash-style pattern matching without the overhead of shelling out or maintaining a bundled pattern engine.

It is the matching engine underneath micromatch and is used directly or transitively by build tools, test runners, and file watchers across the JavaScript ecosystem, including Jest, Astro, Rollup, Storybook, Snowpack, and fast-glob, and is reported as a dependency of more than five million projects.

What You Get

• A picomatch(glob, options) function that compiles one or more glob patterns into a reusable matcher function
• Full Bash-compatible glob syntax: wildcards (*, ?), globstars (**), extglobs (!(a|b), +(a)), brace expansion ({a,b}), and POSIX bracket expressions ([[:alpha:]])
• Lower-level primitives (.scan, .parse, .compileRe, .makeRe, .toRegex) for implementors who want to inspect or reuse the parsing pipeline directly
• A dependency-free picomatch/posix entry point for environments without Node.js path detection
• Options for negation, dotfile matching, basename-only matching, custom ignore patterns, and match/result callbacks (onMatch, onIgnore, onResult)

Common Use Cases

• Filtering file paths in a file watcher (e.g. deciding which changed files should trigger a rebuild)
• Implementing include/exclude glob options in a build tool, bundler, or test runner
• Matching against user-supplied glob patterns in CLI tools without invoking a shell
• Powering higher-level glob libraries (micromatch, fast-glob) that need an accurate, fast matching primitive

Under The Hood

Architecture - The public entry point (index.js) wraps the core matcher in lib/picomatch.js with OS detection, defaulting options.windows via utils.isWindows() before delegating to the shared implementation (also reachable dependency-free through posix.js). Matching is a three-stage pipeline: lib/scan.js (391 lines) walks the pattern character-by-character to split it into a static prefix/base and the actual glob segment, lib/parse.js (the largest file at ~1,416 lines / 35KB) tokenizes and translates glob syntax such as extglobs, braces, and POSIX classes into a regex source string, and picomatch.compileRe wraps that source in anchors and negation logic before toRegex compiles it into a real RegExp. picomatch() itself returns a closure holding the compiled regex so repeat calls against many input strings reuse the same RegExp instead of re-parsing the pattern.

Tech Stack - Zero runtime dependencies; the package is pure, dependency-free JavaScript targeting Node >=12 with a CommonJS main/lib layout. Dev tooling is ESLint 8 plus Mocha/nyc for tests and coverage, with fill-range only as a devDependency used in the test suite, and gulp-format-md/verb for generating the README from .verb.md.

Code Quality - The test/ directory contains 37 spec files covering bash-compatibility, extglobs, braces, brackets, negation, dotfiles, malicious-input handling, and Windows/POSIX slash behavior, run via npm run mocha with nyc coverage reporting (test:cover) wired into CI. Source files use consistent JSDoc blocks with runnable examples above every exported function, 'use strict' pragmas, and small single-purpose helpers in lib/utils.js (e.g. escapeRegex, toPosixSlashes, basename) rather than inlined logic, though the parser (lib/parse.js) is dense and stateful by necessity of handling recursive glob grammar.

API Design - The primary API is a single function, picomatch(glob, options), that returns a matcher you call with a string, which keeps the common case to one line (picomatch('*.js')('a.js')). Every exported method mirrors this minimal-argument style and is documented inline with copy-pasteable examples, and lower-level primitives (.scan, .parse, .makeRe, .compileRe) are exposed for tool authors who need to inspect or reuse pipeline internals without forking the library, at the cost of a larger overall surface area for newcomers who only need the top-level function.