or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-wildcard-match

A tiny and extremely fast library for compiling and matching basic glob patterns

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/wildcard-match@5.1.x

To install, run

npx @tessl/cli install tessl/npm-wildcard-match@5.1.0

index.mddocs/

Wildcard Match

Wildcard Match is a tiny and extremely fast JavaScript library for compiling and matching basic glob patterns. It takes one or more glob patterns, compiles them into a RegExp, and returns a function for matching strings against it. The library supports ?, *, and ** wildcards with customizable separators.

Package Information

  • Package Name: wildcard-match
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install wildcard-match

Core Imports

import wcmatch from "wildcard-match";

For CommonJS:

const wcmatch = require("wildcard-match");

When loaded via CDN, wildcard-match is available as the global function wcmatch.

Basic Usage

import wcmatch from "wildcard-match";

// Create a matcher
const isMatch = wcmatch("src/**/*.?s");

// Test strings
isMatch("src/components/header/index.js"); // => true
isMatch("src/README.md"); // => false

// Access matcher properties
isMatch.pattern; // => 'src/**/*.?s'
isMatch.options; // => { separator: true }
isMatch.regexp; // => /^src[/\\]+?(?:[^/\\]*?[/\\]+?)*?[^/\\]*?\.[^/\\]s[/\\]*?$/

// Immediate matching (single use)
wcmatch("*.example.com", ".")("foo.example.com"); // => true

// Multiple patterns
const multiMatch = wcmatch(["src/*", "test/*"]);
multiMatch("src/index.js"); // => true
multiMatch("test/spec.js"); // => true

Architecture

Wildcard Match is built around several key components that work together to provide fast pattern matching:

  • Pattern Transformation Engine: Converts glob patterns into optimized regular expressions using a custom transform algorithm
  • Separator Handling System: Flexible separator detection and matching that supports cross-platform paths, custom delimiters, and segment-based matching
  • RegExp Compilation: Optimized regular expression generation with support for custom flags and multi-pattern OR logic
  • Matcher Function Factory: Returns bound functions with embedded RegExp and metadata for optimal performance during repeated matching
  • Input Validation Layer: Comprehensive type checking and error handling for patterns, options, and sample strings

The compilation process transforms glob wildcards (?, *, **) into RegExp patterns while respecting separator boundaries and escape sequences. The resulting matcher functions provide direct access to the compiled RegExp and original configuration for debugging and introspection.

Capabilities

Pattern Compilation

Compiles one or more glob patterns into a RegExp and returns a matching function.

/**
 * Compiles one or more glob patterns into a RegExp and returns an isMatch function.
 * The isMatch function takes a sample string as its only argument and returns true
 * if the string matches the pattern(s).
 */
function wcmatch(
  pattern: string | string[],
  options?: string | boolean | WildcardMatchOptions
): isMatch;

Parameters:

  • pattern: Single pattern string or array of patterns to compile
  • options: Options object, or shorthand for separator setting

Usage Examples:

// Single pattern
const matcher = wcmatch("src/*.js");

// Multiple patterns
const multiMatcher = wcmatch(["*.js", "*.ts"]);

// With separator option (shorthand)
const domainMatcher = wcmatch("*.example.com", ".");

// With full options
const caseInsensitive = wcmatch("*.TXT", { flags: "i" });

String Matching

Tests if a sample string matches the compiled pattern(s).

/**
 * Tests if a sample string matches the pattern(s) that were used to compile
 * the regular expression and create this function.
 */
interface isMatch {
  (sample: string): boolean;
  /** Compiled regular expression */
  regexp: RegExp;
  /** Original pattern or array of patterns that was used to compile the RegExp */
  pattern: string | string[];
  /** Options that were used to compile the RegExp */
  options: WildcardMatchOptions;
}

Usage Examples:

const isMatch = wcmatch("src/**/*.js");

// Test various strings
isMatch("src/index.js"); // => true
isMatch("src/components/Button.js"); // => true
isMatch("test/spec.js"); // => false

// Access properties
console.log(isMatch.pattern); // => "src/**/*.js"
console.log(isMatch.regexp); // => RegExp object

Array Operations

The returned function works seamlessly with native array methods.

Usage Examples:

const isMatch = wcmatch("src/*.js");
const paths = ["readme.md", "src/index.js", "src/components/body.js"];

paths.filter(isMatch); // => ["src/index.js"]
paths.some(isMatch); // => true
paths.every(isMatch); // => false
paths.find(isMatch); // => "src/index.js"
paths.findIndex(isMatch); // => 1

Wildcard Syntax

Wildcard-match supports the following glob syntax:

  • ? - matches exactly one arbitrary character excluding separators
  • * - matches zero or more arbitrary characters excluding separators
  • ** - matches any number of segments when used as a whole segment in a separated pattern
  • \ - escapes the following character making it be treated literally

Examples:

// Single character wildcard
wcmatch("src/?ar")("src/bar"); // => true
wcmatch("src/?ar")("src/car"); // => true

// Multi-character wildcard
wcmatch("src/*.js")("src/index.js"); // => true
wcmatch("src/*.js")("src/component.js"); // => true

// Multi-segment wildcard
wcmatch("src/**/index.js")("src/components/header/index.js"); // => true

// Escaped wildcards
wcmatch("literal\\*")("literal*"); // => true

Separator Handling

Wildcard-match can work with custom separators for different use cases beyond file paths.

Default Behavior (separator: true):

  • / in patterns matches both / and \ in samples
  • Enables cross-platform path matching

Custom Separators:

// Domain matching with dot separator
const matchDomain = wcmatch("*.example.com", { separator: "." });
matchDomain("subdomain.example.com"); // => true

// Comma-separated values
const matchCSV = wcmatch("one,**,four", ",");
matchCSV("one,two,three,four"); // => true

// No segmentation (separator: false)
const matchAnything = wcmatch("foo?ba*", false);
matchAnything("foo/bar/qux"); // => true

Separator Rules:

  • Single separator in pattern matches one or more separators in sample
  • Trailing separator in pattern requires trailing separator(s) in sample
  • No trailing separator in pattern allows optional trailing separators in sample

Configuration Options

Option Details:

  • separator:
    • true (default): / matches both / and \
    • false: No segmentation, wildcards match across entire string
    • string: Custom separator character(s)
  • flags: Standard RegExp flags ("i" for case-insensitive, "g" for global, etc.)

Usage Examples:

// Case-insensitive matching
const caseInsensitive = wcmatch("*.TXT", { flags: "i" });
caseInsensitive("readme.txt"); // => true

// Multi-character separator
const pathMatcher = wcmatch("home**user", { separator: "::" });
pathMatcher("home::documents::user"); // => true

Error Handling

The library throws specific errors for invalid inputs:

  • TypeError: When pattern is not a string or array
  • TypeError: When options parameter has wrong type
  • TypeError: When sample passed to isMatch is not a string
  • Error: When backslash \ is used as separator (reserved for escaping)

Examples:

// Invalid pattern type
wcmatch(123); // TypeError: The first argument must be a single pattern string or an array of patterns

// Invalid options type
wcmatch("pattern", 123); // TypeError: The second argument must be an options object or a string/boolean separator

// Invalid sample type
const matcher = wcmatch("*.js");
matcher(123); // TypeError: Sample must be a string, but number given

// Invalid separator
wcmatch("pattern", { separator: "\\" }); // Error: \ is not a valid separator because it is used for escaping

Types

interface WildcardMatchOptions {
  /** Separator to be used to split patterns and samples into segments */
  separator?: string | boolean;
  /** Flags to pass to the RegExp */
  flags?: string;
}

interface isMatch {
  /**
   * Tests if a sample string matches the pattern(s)
   */
  (sample: string): boolean;
  /** Compiled regular expression */
  regexp: RegExp;
  /** Original pattern or array of patterns that was used to compile the RegExp */
  pattern: string | string[];
  /** Options that were used to compile the RegExp */
  options: WildcardMatchOptions;
}

/**
 * Compiles one or more glob patterns into a RegExp and returns an isMatch function.
 */
declare function wcmatch(
  pattern: string | string[],
  options?: string | boolean | WildcardMatchOptions
): isMatch;

export default wcmatch;