Core Matching

/**
 * Creates a matcher function from one or more glob patterns
 * @param {string|string[]} glob - One or more glob patterns
 * @param {object} options - Configuration options
 * @param {boolean} returnState - Whether to return state information with matcher
 * @returns {function} Matcher function
 */
function picomatch(glob, options, returnState = false);

/**
 * Matcher function returned by picomatch()
 * @param {string} input - String to test against pattern
 * @param {boolean} returnObject - Whether to return detailed result object
 * @returns {boolean|object} Match result
 */
type MatcherFunction = (input: string, returnObject?: boolean) => boolean | MatchResult;

const picomatch = require('picomatch');

// Single pattern
const isMatch = picomatch('*.js');
console.log(isMatch('file.js'));    // => true
console.log(isMatch('file.txt'));   // => false

// Multiple patterns - returns true if ANY pattern matches
const isMatchAny = picomatch(['*.js', '*.ts', '*.json']);
console.log(isMatchAny('config.json')); // => true

// Get detailed result object
const matcher = picomatch('src/**/*.js');
const result = matcher('src/utils/helper.js', true);
console.log(result.isMatch); // => true
console.log(result.output);  // => 'src/utils/helper.js'

// With returnState option
const matcherWithState = picomatch('*.js', {}, true);
console.log(matcherWithState.state); // => { /* parsed state object */ }

/**
 * Create matcher with options
 * @param {string} pattern - Glob pattern
 * @param {PicomatchOptions} options - Configuration options
 * @returns {function} Configured matcher function
 */
function picomatch(pattern, options);

// Case insensitive matching
const matcher = picomatch('*.JS', { nocase: true });
console.log(matcher('file.js')); // => true

// Ignore specific patterns
const isMatch = picomatch('**/*.js', { 
  ignore: ['**/node_modules/**', '**/test/**'] 
});
console.log(isMatch('src/app.js'));           // => true
console.log(isMatch('node_modules/lib.js'));  // => false

// Windows path handling
const winMatcher = picomatch('src\\**\\*.js', { windows: true });
console.log(winMatcher('src\\utils\\file.js')); // => true

// Match only basename
const baseMatcher = picomatch('*.js', { basename: true });
console.log(baseMatcher('path/to/file.js')); // => true

// Custom callbacks
const callbackMatcher = picomatch('*.js', {
  onMatch: (result) => console.log('Matched:', result.input),
  onResult: (result) => console.log('Tested:', result.input)
});

/**
 * Create matcher for multiple patterns
 * @param {string[]} patterns - Array of glob patterns
 * @param {PicomatchOptions} options - Configuration options
 * @returns {function} Matcher that returns true if ANY pattern matches
 */
function picomatch(patterns, options);

// Multiple file extensions
const isSourceFile = picomatch(['*.js', '*.ts', '*.jsx', '*.tsx']);
console.log(isSourceFile('component.jsx')); // => true

// Complex pattern combinations
const isTestFile = picomatch([
  '**/*.test.js',
  '**/*.spec.js', 
  '**/test/**/*.js',
  '**/__tests__/**/*.js'
]);
console.log(isTestFile('src/utils.test.js')); // => true
console.log(isTestFile('__tests__/app.js'));  // => true

// Mixed patterns with options
const matcher = picomatch(['src/**/*.js', 'lib/**/*.ts'], {
  ignore: '**/node_modules/**'
});

interface PicomatchOptions {
  /** Force Windows-style path handling */
  windows?: boolean;
  /** Patterns to ignore */
  ignore?: string | string[];
  /** Callback for match events */
  onMatch?: (result: MatchResult) => void;
  /** Callback for all results */
  onResult?: (result: MatchResult) => void;
  /** Callback for ignored matches */
  onIgnore?: (result: MatchResult) => void;
  /** Enable/disable fast path optimizations */
  fastpaths?: boolean;
  /** Custom path format function */
  format?: (path: string) => string;
  /** Enable capture groups */
  capture?: boolean;
  /** Match anywhere in string (not anchored) */
  contains?: boolean;
  /** Match only basename (equivalent to basename) */
  basename?: boolean;
  /** Match only basename */
  matchBase?: boolean;
  /** Case insensitive matching */
  nocase?: boolean;
  /** Enable debug mode */
  debug?: boolean;
  /** Custom regex flags */
  flags?: string;
  /** Disable globstars (**) */
  noglobstar?: boolean;
  /** Disable extglobs (+(a|b)) */
  noextglob?: boolean;
  /** Disable braces ({a,b}) */
  nobrace?: boolean;
  /** Disable brackets ([abc]) */
  nobracket?: boolean;
  /** Custom expand range function for brackets */
  expandRange?: (left: string, right: string, options: object) => string;
  /** Strict slash handling */
  strictSlashes?: boolean;
  /** Unescape regex characters */
  unescape?: boolean;
  /** Maximum regex length */
  maxLength?: number;
  /** POSIX character classes */
  posix?: boolean;
  /** Dot handling in patterns */
  dot?: boolean;
  /** Custom star replacement */
  star?: string;
  /** Bash compatibility mode */
  bash?: boolean;
}

interface MatchResult {
  /** Original glob pattern */
  glob: string;
  /** Parsed state object */
  state: {
    input: string;
    tokens: Token[];
    output: string;
    negated: boolean;
    fastpaths: boolean;
  };
  /** Compiled regular expression */
  regex: RegExp;
  /** Whether POSIX mode is enabled */
  posix: boolean;
  /** Input string being tested */
  input: string;
  /** Formatted output string */
  output: string;
  /** Regex match result */
  match: RegExpExecArray | null;
  /** Whether the pattern matched */
  isMatch: boolean;
}

interface Token {
  /** Token type (star, text, globstar, etc.) */
  type: string;
  /** Token value */
  value: string;
  /** Compiled output for token */
  output?: string;
  /** Whether token is escaped */
  escaped?: boolean;
  /** Whether token is negated */
  negated?: boolean;
}