JavaScript Basics: Match Path Strings with path.matchesGlob

A tool may need to filter an existing list of paths without walking the filesystem. Node’s path.matchesGlob tests one path string against a glob. Use the POSIX variant explicitly when the input list uses forward slashes on every platform.

Prepare a scratch directory

Tested on Linux with Node.js v24.19.0. You need the named runtime, Bash, a text editor, and the standard mktemp, rm, and rmdir utilities. The .mjs extension selects ES modules. Assertions check the demonstrated behavior; no npm packages or remote services are needed.

Keep using the same terminal. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-path-matches-glob.mjs:

import assert from 'node:assert/strict';
import path from 'node:path';

const files = ['src/main.js', 'src/lib/tool.js', 'src/readme.md', 'test/main.js'];
const shallow = files.filter(name => path.posix.matchesGlob(name, 'src/*.js'));
const recursive = files.filter(name => path.posix.matchesGlob(name, 'src/**/*.js'));
assert.deepEqual(shallow, ['src/main.js']);
assert.deepEqual(recursive, ['src/main.js', 'src/lib/tool.js']);
console.log('One directory:', shallow.join(', '));
console.log('Recursive:', recursive.join(', '));

assert.equal(path.posix.matchesGlob('src/main.js', 'src/*.{js,ts}'), true);
assert.equal(path.posix.matchesGlob('src/main.ts', 'src/*.{js,ts}'), true);
assert.equal(path.posix.matchesGlob('src/main.css', 'src/*.{js,ts}'), false);
console.log('Brace alternatives accept js and ts: true');
assert.throws(() => path.posix.matchesGlob(null, '*.js'), TypeError);
console.log('Non-string path: rejected');

Run it:

node demonstrate-path-matches-glob.mjs

Observed output:

One directory: src/main.js
Recursive: src/main.js, src/lib/tool.js
Brace alternatives accept js and ts: true
Non-string path: rejected

Read the result

A single star stays within the selected directory level in these patterns, while a double-star component also matches deeper paths. The filter keeps the original list order; it does not sort or discover files. Brace alternatives allow either of two suffixes. The final assertion verifies that this API expects strings rather than silently accepting a null path.

Apply it carefully

These examples target Node 24.8 or newer, where the API is stable. Glob syntax is not regular-expression syntax, and a match does not establish that a file exists or has the expected content. Test dotfiles, separators, and escaping against your intended inputs before adopting a pattern. Matching is not path authorization: validate and resolve actual filesystem access separately, including symlink and traversal behavior where relevant.

The official reference describes the API and its options. The checks above cover the specific fixture, not every possible input or environment.

Clean up

Remove the source and then the empty practice directory:

rm -- demonstrate-path-matches-glob.mjs
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect the remaining files rather than deleting unknown contents.

Acknowledgements

This post was created with assistance from AI.