Skip to content

perf: faster minimatch() and filter() pattern cache - #339

Merged
isaacs merged 3 commits into
isaacs:mainfrom
hood:perf/fn-cache
Nov 10, 2026
Merged

isaacs merged 3 commits into
isaacs:mainfrom
hood:perf/fn-cache

Conversation

@hood

@hood hood commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Makes minimatch(path, pattern) 2.3x faster and minimatch.filter() 2.8x faster on everyday globs. Matching itself is unchanged. The time saved was all spent finding the cached Minimatch object.

  • Cache: keyed by options, then by pattern. With no options it uses a constant key, so there's no JSON.stringify and no new string to hash. The cache now has two generations, as quick-lru does: a hit is two Map.gets, with no delete + set.
  • filter(): makes its Minimatch once, the first time it tests a path. An invalid pattern still throws at that first call.

Closes #338

Results

15,505 paths (benchmark/realistic-paths.json) × 10 globs. Each figure is the median of 5 alternating process runs, each of those the median of 15 rounds. Range in brackets.

API 11.0.5 (ea0a4a6) this PR change
minimatch(f, p) 37.29 ms [34.95-38.17] 16.15 ms [15.40-16.63] 2.31x
minimatch(f, p, { dot: true }) 39.98 ms [39.04-41.34] 28.29 ms [27.25-29.08] 1.41x
minimatch.filter(p) 49.17 ms [46.77-50.77] 17.50 ms [17.35-18.23] 2.81x
minimatch.defaults({ dot: true })(f, p) 44.05 ms 32.44 ms 1.36x
Minimatch#match (not changed) 14.54 ms 14.41 ms same

minimatch(f, p) is now within 12% of Minimatch#match, and filter() within 21%.

The match counts are identical on both builds: 35,020, and 35,213 with dot. benchmark/realistic.mjs gives the same totals (33.52 vs 33.53 ms).

xychart-beta
  title "ms, 15.5k paths x 10 globs (lower is better)"
  x-axis ["minimatch()", "minimatch(dot)", "filter()", "Minimatch#match"]
  y-axis "ms" 0 --> 50
  bar [37.29, 39.98, 49.17, 14.54]
  bar [16.15, 28.29, 17.50, 14.41]
Loading

Behavior changes

  • The cache holds 256 to 512 objects, in place of exactly 256. Each object used within the last 256 inserts is kept. The README and changelog now say "at least the 256".
  • filter() uses the options as they are at its first test. A later change to the options object no longer applies to that filter. minimatch() still applies such changes (test/cache.ts).

Tests

  • npm test: 7303/7303 pass, with full coverage. oxlint and prettier --check are clean.
  • New tests in test/cache.ts: a pattern used again from the old generation, and the filter() options.

Repro

git checkout ea0a4a6 && npm run prepare && cp -R dist /tmp/mm-base
git checkout perf/fn-cache && npm run prepare
for i in 1 2 3 4 5; do node fnbench.mjs /tmp/mm-base/esm/index.js; node fnbench.mjs $PWD/dist/esm/index.js; done
fnbench.mjs
import { readFileSync } from 'node:fs'
const { Minimatch, minimatch, filter } = await import(process.argv[2])
const paths = JSON.parse(readFileSync(new URL('benchmark/realistic-paths.json', 'file://' + process.cwd() + '/'),'utf8'))
const pats = ['**/*.js','**/*.{js,mjs,cjs,ts,mts,cts}','**/*.d.ts','**/node_modules/**','**/test/**/*.@(js|ts)','**/!(*.d).ts','**/*.md','**/[A-Z]*.md','**/package.json','**/LICENSE*']
const med=a=>(a.sort((x,y)=>x-y),a[a.length>>1])
const out = {}
const b=(n,fn)=>{const ts=[];let c=0;for(let r=0;r<15;r++){const t=performance.now();c=fn();ts.push(performance.now()-t)}out[n]={ms:+med(ts).toFixed(2),min:+ts[0].toFixed(2),max:+ts[ts.length-1].toFixed(2),found:c}}
b('Minimatch#match, 10 patterns', ()=>{const ms=pats.map(p=>new Minimatch(p));let n=0;for(const f of paths)for(const m of ms)if(m.match(f))n++;return n})
b('minimatch(f, p), 10 patterns', ()=>{let n=0;for(const f of paths)for(const p of pats)if(minimatch(f,p))n++;return n})
b('minimatch(f, p, {dot}), 10 patterns', ()=>{let n=0;for(const f of paths)for(const p of pats)if(minimatch(f,p,{dot:true}))n++;return n})
b('filter(p), 10 patterns', ()=>{let n=0;for(const p of pats)n+=paths.filter(filter(p)).length;return n})
b('defaults({dot})(f, p), 10 patterns', ()=>{const mm=minimatch.defaults({dot:true});let n=0;for(const f of paths)for(const p of pats)if(mm(f,p))n++;return n})
console.log(JSON.stringify(out))

Comment thread src/index.ts
p: string,
pattern: string,
options: MinimatchOptions = {},
options?: MinimatchOptions,

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How much of the perf improvement comes from making this optional? This is a breaking change, Glob uses the .options in a few places.

@hood hood Nov 9, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Free to double check, but I sanity checked the output bundle to verify my assumption and - as far as I remember - the emitted .d.ts files are byte-identical between this proposal and the latest released version, as options = {} already compiled to options?: MinimatchOptions. So no breaking change in my book 😄.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, ok, but the object always has an options field then?

Sorry, I'm traveling this week, only looking at code on my phone, and so you're not yet getting the frontier model /effort xhigh isaacs ;)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, it does. Only the minimatch() function's parameter became optional. The Minimatch constructor still has options = {}, and the cache builds instances with { ...options }, which gives {} for undefined. So mm.options is always an object, and filter()/defaults() didn't change. Checked on the built output: minimatch(p, pat), minimatch(p, pat, undefined) and filter(pat)(p) all give mm.options as {}.

No worries, safe travels! 😄 As a matter of fact, thank you 2x for checking this while traveling! 🙇

Comment thread changelog.md
patterns.
- `minimatch()` keeps the 256 `Minimatch` objects that it used most
recently, so it does not compile the same pattern again.
- `minimatch()` keeps at least the 256 `Minimatch` objects that it

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the cache size is no longer bounded? That could be a problem.

Comment thread src/index.ts
Comment on lines +140 to +143
if (cacheSize >= cacheMax) {
oldCache = cache
cache = new Map()
cacheSize = 0

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, i see, it's not that the cache is no longer bounded, it's just not an LRU anymore. When it hits the max, you're throwing the whole thing away and starting over with no cache.

That might be a good approach, but I'm not sure. It's definitely a significant behavior change. I'll need to benchmark this against some representative samples, to ensure it's not just optimized for the benchmark.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, no, not starting over with no cache. Items do get pulled forward into the new cache. Still, I need to comb through this carefully to ensure we understand the behavior change.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, yeah, I was mistaken. This is still just a normal LRU, it's just doing the two-stage trick that works for small N / small memory, where frequent disposal is more expensive than the cost of duplicating the data. Good change! (I'd explored such a trick in the lru-cache module, but it is not good if you want to have strict memory-usage contracts, and not ideal for larger data sets, which that module supports. But here it's fine.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, basically for a fixed N of small objects the extra generation costs less than a delete + set for every hit.

isaacs and others added 2 commits November 10, 2026 13:55
Also, remove basically all cases where `JSON.stringify` would get used.

optionsKey() now loops over the keys of the options object, in place
of reading each known option by name. Its speed no longer depends on
how many object shapes it has seen. Before, after 6 other shapes,
{ dot: true } took about 31 ms on the realistic-paths benchmark. Now
it takes about 19 ms (HEAD before the key work: about 27 ms).

The loop reads inherited keys, and the cached object now gets a copy
that keeps them too. So minimatch() and filter() use inherited
options, the same as new Minimatch().

This drops the benchmark timing down considerably by improving cache key
calculation and also making more things share a cache entry that have
the same behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@isaacs
isaacs merged commit d1431cd into isaacs:main Nov 10, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

minimatch() spends more time on its cache key than on matching

2 participants