picomatch

Extglobs allow for more complex pattern matching based on occurrences of a pattern:

By default, risky quantified extglobs are treated literally. You can increase the nesting limit using the maxExtglobRecursion option.

const pm = require('picomatch');

// *(pattern) matches ZERO or more of "pattern"
console.log(pm.isMatch('a', 'a*(z)')); // true
console.log(pm.isMatch('az', 'a*(z)')); // true
console.log(pm.isMatch('azzz', 'a*(z)')); // true

// +(pattern) matches ONE or more of "pattern"
console.log(pm.isMatch('a', 'a+(z)')); // false
console.log(pm.isMatch('az', 'a+(z)')); // true

// supports multiple extglobs
console.log(pm.isMatch('foo.bar', '!(foo).!(bar)')); // false

// supports nested extglobs
console.log(pm.isMatch('foo.bar', '!(!(foo)).!(!(bar))')); // true

// increase the limit to allow a small amount of nested quantified extglobs
console.log(pm.isMatch('aaa', '+(+(a))', { maxExtglobRecursion: 1 })); // true

The picomatch() function and its associated API methods accept an options object to customize matching behavior. Common configuration tasks include:

• Case Sensitivity: Use nocase: true for case-insensitive matching (overridden by flags).
• Dotfiles: Enable matching of dotfiles by setting dot: true.
• Path Handling: Use basename: true (or matchBase: true) to match patterns without slashes against the basename of a path. Use windows: true to accept backslashes as path separators.
• Glob Features: Enable/disable specific features like noglobstar (disables **), noextglob (disables +(a|b)), nobrace (disables {a,b}), or nonegate (disables ! negation).
• Strictness: Use strictBrackets: true to throw errors on imbalanced brackets, braces, or parens.
• Performance: fastpaths is enabled by default (true) to skip full parsing for common patterns.

Picomatch provides lifecycle hooks via options to perform actions when items are processed:

• onMatch: Called when an item matches the pattern.
• onIgnore: Called when an item is excluded by an ignore pattern.
• onResult: Called for every item, regardless of whether it matched or was ignored.

Each callback receives an object containing { glob, regex, input, output }.

const onMatch = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onMatch });
isMatch('foo');
isMatch('bar');
isMatch('baz');

const onIgnore = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onIgnore, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');

const onResult = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onResult, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');

The expandRange option allows you to provide a custom function for expanding ranges in brace patterns (e.g., {a..z}). The function receives the range values as two arguments and must return a string to be used in the generated regex. It is recommended to wrap returned strings in parentheses.

This is useful when integrating with libraries like fill-range to handle complex range expansions.

const fill = require('fill-range');
const regex = pm.makeRe('foo/{01..25}/bar', {
  expandRange(a, b) {
    return `(${fill(a, b, { toRegex: true })})`;
  }
});

console.log(regex);
//=> /^(?:foo\/((?:0[1-9]|1[0-9]|2[0-5]))\/bar)$/

console.log(regex.test('foo/00/bar'))  // false
console.log(regex.test('foo/01/bar'))  // true
console.log(regex.test('foo/10/bar')) // true
console.log(regex.test('foo/22/bar')) // true
console.log(regex.test('foo/25/bar')) // true
console.log(regex.test('foo/26/bar')) // false