multimatch

multimatch extends minimatch.match() with support for multiple patterns, enabling pattern matching against multiple glob patterns simultaneously. It processes arrays of file paths and patterns, supporting both positive matches (inclusion) and negative matches (exclusion with '!' prefix), making it ideal for file filtering operations in build tools, CLI utilities, and file processing applications.

Package Information

• Package Name: multimatch
• Package Type: npm
• Language: JavaScript (with TypeScript definitions)
• Installation: npm install multimatch

Core Imports

import multimatch from 'multimatch';

For CommonJS:

const multimatch = require('multimatch');

TypeScript with type imports:

import multimatch, { type Options } from 'multimatch';

Basic Usage

import multimatch from 'multimatch';

// Basic pattern matching
multimatch(['unicorn', 'cake', 'rainbows'], '*');
//=> ['unicorn', 'cake', 'rainbows']

// Multiple patterns with negation
multimatch(['unicorn', 'cake', 'rainbows'], ['*', '!cake']);
//=> ['unicorn', 'rainbows']

// Single pattern as string
multimatch(['foo', 'bar', 'baz'], 'f*');
//=> ['foo']

// File path matching
multimatch(['vendor/js/foo.js', 'vendor/js/bar.js'], '**/*.js');
//=> ['vendor/js/foo.js', 'vendor/js/bar.js']

Capabilities

Pattern Matching

The main function that matches paths against multiple glob patterns with support for inclusion and exclusion patterns.

/**
 * Extends minimatch.match() with support for multiple patterns
 * @param paths - The paths to match against (string or array of strings)
 * @param patterns - Globbing patterns to use (string or array of strings)
 * @param options - Optional minimatch options
 * @returns Array of matching paths in the order of input paths
 */
function multimatch(
  paths: string | readonly string[],
  patterns: string | readonly string[],
  options?: Options
): string[];

Pattern Behavior:

• Positive patterns (e.g., *, foo) add matches to results
• Negative patterns (e.g., !foo) subtract matches from results
• Pattern order matters - patterns are applied sequentially
• Lone negations (e.g., ['!foo']) never match anything - use ['*', '!foo'] instead

Usage Examples:

// Multiple positive patterns
multimatch(['foo', 'bar', 'baz'], ['foo', 'bar']);
//=> ['foo', 'bar']

// Combining positive and negative patterns
multimatch(['foo', 'bar', 'baz'], ['*', '!bar']);
//=> ['foo', 'baz']

// Pattern order affects results
multimatch(['foo', 'bar', 'baz'], ['!*a*', '*r', 'f*']);
//=> ['foo', 'bar']

// Complex glob patterns
multimatch(['vendor/js/foo.js', 'vendor/css/bar.css'], ['**/*.js', '!**/foo.*']);
//=> []

Edge Cases:

• Empty inputs return empty array: multimatch([], ['*']) → []
• No patterns return empty array: multimatch(['foo'], []) → []
• Results maintain original input order
• Accepts both string and array inputs for paths and patterns

Types

import { type MinimatchOptions } from 'minimatch';

/**
 * Configuration options extending minimatch options
 */
type Options = Readonly<MinimatchOptions>;

The Options type extends all minimatch options including:

• dot - Allow patterns to match filenames starting with a period
• noglobstar - Disable ** globstar matching
• nocase - Perform case-insensitive matching
• debug - Enable debug output
• And all other minimatch options

Pattern Syntax

multimatch supports all minimatch glob patterns:

• * - Matches any number of characters, but not /
• ? - Matches a single character, but not /
• ** - Matches any number of characters, including /, as long as it's the only thing in a path part
• {} - Allows for a comma-separated list of "or" expressions
• ! - At the beginning of a pattern negates the match
• [...] - Character class matching
• +(pattern) - One or more occurrences
• *(pattern) - Zero or more occurrences
• ?(pattern) - Zero or one occurrence
• @(pattern) - Exactly one occurrence