or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Anymatch

Anymatch is a flexible string matching library that enables developers to match strings against various types of matchers including direct strings, glob patterns, regular expressions, and custom functions. It offers a unified API for testing strings against single matchers or arrays of mixed matcher types, with support for negation patterns and optional index return modes.

Package Information

  • Package Name: anymatch
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install anymatch

Core Imports

const anymatch = require('anymatch');

For ES modules:

import anymatch from 'anymatch';

TypeScript with named imports:

import anymatch, { type Matcher, type Tester } from 'anymatch';

Basic Usage

const anymatch = require('anymatch');

// Define various matcher types
const matchers = [
  'path/to/file.js',           // Direct string match
  'path/anyjs/**/*.js',        // Glob pattern  
  /foo\.js$/,                  // Regular expression
  string => string.includes('bar') && string.length > 10  // Custom function
];

// Test strings against matchers
anymatch(matchers, 'path/to/file.js');     // true
anymatch(matchers, 'path/anyjs/baz.js');   // true  
anymatch(matchers, 'path/to/foo.js');      // true
anymatch(matchers, 'path/to/bar.js');      // true
anymatch(matchers, 'bar.js');              // false

// Get index of matching matcher
anymatch(matchers, 'foo.js', {returnIndex: true}); // 2

// Create curried function for reuse
const matcher = anymatch(matchers);
['foo.js', 'bar.js'].filter(matcher);  // ['foo.js']

Capabilities

String Matching

Tests strings against various matcher types and returns boolean results or matcher indices.

declare const anymatch: {
  /** Create a curried matcher function */
  (matchers: AnymatchMatcher): AnymatchTester;
  /** Create a curried matcher function with options */
  (matchers: AnymatchMatcher, testString: null, returnIndex: true | PicomatchOptions): AnymatchTester;
  /** Match string and return matcher index */
  (matchers: AnymatchMatcher, testString: string | any[], returnIndex: true | PicomatchOptions): number;
  /** Match string and return boolean result */
  (matchers: AnymatchMatcher, testString: string | any[]): boolean;
};

Usage Examples:

// Basic string matching
anymatch('*.js', 'file.js');           // true
anymatch('*.js', 'file.css');          // false

// Regular expression matching  
anymatch(/\.js$/, 'script.js');        // true
anymatch(/\.js$/, 'script.ts');        // false

// Function matching
const isLongFile = name => name.length > 10;
anymatch(isLongFile, 'very-long-filename.js');  // true
anymatch(isLongFile, 'short.js');               // false

// Array of matchers
const matchers = ['*.js', /\.ts$/, name => name.includes('test')];
anymatch(matchers, 'app.js');          // true (matches first)
anymatch(matchers, 'app.ts');          // true (matches second)  
anymatch(matchers, 'app.test.css');    // true (matches third)
anymatch(matchers, 'app.css');         // false

// Return matcher index instead of boolean
anymatch(matchers, 'app.js', {returnIndex: true});     // 0
anymatch(matchers, 'app.ts', {returnIndex: true});     // 1
anymatch(matchers, 'app.test.css', {returnIndex: true}); // 2
anymatch(matchers, 'app.css', {returnIndex: true});    // -1

Curried Function Creation

Creates a reusable matcher function bound to specific matchers.

interface AnymatchTester {
  /** Test string and return matcher index */
  (testString: string | any[], returnIndex: true): number;
  /** Test string and return boolean result */
  (testString: string | any[]): boolean;
}

Usage Examples:

// Create reusable matcher
const isJavaScript = anymatch(['*.js', '*.jsx', '*.ts', '*.tsx']);

// Use as predicate function
const files = ['app.js', 'style.css', 'test.ts', 'image.png'];
const jsFiles = files.filter(isJavaScript);  // ['app.js', 'test.ts']

// Use with different return modes
isJavaScript('app.js');              // true
isJavaScript('app.js', true);        // 0 (index of first matcher)
isJavaScript('style.css');           // false
isJavaScript('style.css', true);     // -1

Negation Patterns

Supports negation patterns using ! prefix to exclude matches.

/**
 * Matchers can include negation patterns starting with '!' to exclude matches
 * Negation patterns are processed first and take precedence over positive matches
 */

Usage Examples:

// Exclude specific patterns
const matchers = ['*.js', '!test/*.js'];
anymatch(matchers, 'app.js');           // true
anymatch(matchers, 'test/spec.js');     // false (excluded by negation)

// Multiple negations
const matchers2 = ['**/*.js', '!node_modules/**', '!test/**'];
anymatch(matchers2, 'src/app.js');            // true
anymatch(matchers2, 'node_modules/lib.js');   // false
anymatch(matchers2, 'test/spec.js');          // false

Array Arguments for Function Matchers

Function matchers can receive the full argument array when testString is an array.

/**
 * When testString is an array, function matchers receive all array elements as arguments
 * The first element is used as the string for non-function matchers
 */

Usage Examples:

// Function matcher receiving multiple arguments
const matchWithContext = (filename, size, modified) => {
  return filename.endsWith('.js') && size > 1000;
};

const matchers = [matchWithContext];

// Pass array with filename and metadata
anymatch(matchers, ['app.js', 2048, '2023-01-01']);  // true
anymatch(matchers, ['tiny.js', 500, '2023-01-01']);  // false

Types

/** Function type that takes a string and returns boolean */
type AnymatchFn = (testString: string) => boolean;

/** Union type for individual matcher patterns */
type AnymatchPattern = string | RegExp | AnymatchFn;

/** Single pattern or array of patterns */
type AnymatchMatcher = AnymatchPattern | AnymatchPattern[];

/** Curried function type with overloads */
interface AnymatchTester {
  (testString: string | any[], returnIndex: true): number;
  (testString: string | any[]): boolean;
}

/** Exported type aliases */
export type Matcher = AnymatchMatcher;
export type Tester = AnymatchTester;

Configuration Options

interface PicomatchOptions {
  /** Enable dot file matching (default: false) */
  dot?: boolean;
  /** Additional picomatch options */
  [key: string]: any;
}

Note: The third parameter to anymatch can be either:

  • true - shorthand for returning index instead of boolean
  • PicomatchOptions object - configuration for glob pattern matching including any picomatch options
  • For backward compatibility, objects with returnIndex: true are also supported

The anymatch function uses picomatch for glob pattern matching and accepts all picomatch options.

Usage Examples:

// Enable dot file matching
anymatch('.*', '.hidden', {dot: true});        // true
anymatch('.*', '.hidden');                     // false (default)

// Return index instead of boolean
anymatch('*.js', 'app.js', true);              // 0

// Pass picomatch options for glob matching
anymatch('**/*.js', 'path/file.js', {
  dot: true,
  noglobstar: false,
  nocase: true
});

// Backward compatibility with returnIndex option
anymatch('*.js', 'app.js', {returnIndex: true});  // 0

Platform Compatibility

  • Node.js: Requires Node.js >= 8
  • Cross-platform: Handles path separators automatically via normalize-path dependency
  • Bash Parity: Windows-style backslashes are not supported as separators

Dependencies

  • picomatch: Used for glob pattern matching with full picomatch options support
  • normalize-path: Used for cross-platform path normalization

Error Handling

// Throws TypeError for invalid arguments
anymatch(null, 'test');              // TypeError: anymatch: specify first argument
anymatch(['*.js'], 123);             // TypeError: anymatch: second argument must be a string: got [object Number]