matcher

matcher

Simple wildcard matching

Useful when you want to accept loose string input and regexes/globs are too convoluted.

Install

npm install matcher

Usage

import {matcher, isMatch} from 'matcher';

matcher(['foo', 'bar', 'moo'], ['*oo', '!foo']);
//=> ['moo']

matcher(['foo', 'bar', 'moo'], ['!*oo']);
//=> ['bar']

matcher('moo', ['']);
//=> []

matcher('moo', []);
//=> []

matcher([''], ['']);
//=> ['']

isMatch('unicorn', 'uni*');
//=> true

isMatch('unicorn', '*corn');
//=> true

isMatch('unicorn', 'un*rn');
//=> true

isMatch('rainbow', '!unicorn');
//=> true

isMatch('foo bar baz', 'foo b* b*');
//=> true

isMatch('unicorn', 'uni\\*');
//=> false

isMatch(['foo', 'bar'], 'f*');
//=> true

isMatch(['foo', 'bar'], ['a*', 'b*']);
//=> true

isMatch('unicorn', ['']);
//=> false

isMatch('unicorn', []);
//=> false

isMatch([], 'bar');
//=> false

isMatch([], []);
//=> false

isMatch([''], ['']);
//=> true

// With `allPatterns` option
isMatch('foobar', ['foo*', '*bar'], {allPatterns: true});
//=> true

isMatch('foo', ['foo*', '*bar'], {allPatterns: true});
//=> false

API

It matches even across newlines. For example, foo*r will match foo\nbar.

matcher(inputs, patterns, options?)

Accepts a string or an array of strings for both inputs and patterns.

Returns an array of inputs filtered based on the patterns.

isMatch(inputs, patterns, options?)

Accepts a string or an array of strings for both inputs and patterns.

Returns a boolean of whether any of the given inputs matches at least one of the patterns.

inputs

Type: string | string[]

The string or array of strings to match.

options

Type: object

caseSensitive

Type: boolean
Default: false

Make matching case-sensitive. When false, treats uppercase and lowercase characters as being the same.

Ensure you use this correctly. For example, files and directories should be matched case-insensitively, while most often, object keys should be matched case-sensitively.

import {isMatch} from 'matcher';

isMatch('UNICORN', 'UNI*', {caseSensitive: true});
//=> true

isMatch('UNICORN', 'unicorn', {caseSensitive: true});
//=> false

isMatch('unicorn', ['tri*', 'UNI*'], {caseSensitive: true});
//=> false

allPatterns

Type: boolean
Default: false

Require all negated patterns to not match and any normal patterns to match at least once. Otherwise, it will be a no-match condition.

import {matcher} from 'matcher';

// Find text strings containing both "edge" and "tiger" in arbitrary order, but not "stunt".
const demo = (strings) => matcher(strings, ['*edge*', '*tiger*', '!*stunt*'], {allPatterns: true});

demo(['Hey, tiger!', 'tiger has edge over hyenas', 'pushing a tiger over the edge is a stunt']);
//=> ['tiger has edge over hyenas']

import {matcher} from 'matcher';

matcher(['foo', 'for', 'bar'], ['f*', 'b*', '!x*'], {allPatterns: true});
//=> ['foo', 'for', 'bar']

matcher(['foo', 'for', 'bar'], ['f*'], {allPatterns: true});
//=> []

patterns

Type: string | string[]

Use * to match zero or more characters.

A leading ! negates the pattern.

An input string will be omitted, if it does not match any non-negated patterns present, or if it matches a negated pattern, or if no pattern is present.

Benchmark

npm run bench

Related

• matcher-cli - CLI for this module
• multimatch - Extends minimatch.match() with support for multiple patterns

Similar packages

Other packages similar to matcher

minimatch

Minimatch is a package for matching file paths against glob patterns. It is more focused on file system operations and supports a wide range of globbing features. Compared to 'matcher', 'minimatch' is more powerful for complex pattern matching but may be overkill for simple string matching tasks.

micromatch

Micromatch is a fast and lightweight glob matcher for JavaScript. It provides extensive support for advanced globbing patterns and is optimized for performance. While 'micromatch' offers more features and flexibility, 'matcher' is simpler and easier to use for basic string matching.

multimatch

Multimatch is a package that allows you to match multiple patterns against an array of strings. It is built on top of 'minimatch' and provides a convenient API for handling multiple patterns. 'Multimatch' is useful when you need to apply several patterns at once, whereas 'matcher' is more straightforward for single pattern matching.