or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

file-matching.md index.md path-resolution.md

tile.json

File Pattern Matching

File pattern matching functionality for determining which files are included in TypeScript compilation based on tsconfig.json include, exclude, and files patterns.

Capabilities

File Matcher Creation

Creates a file matcher function that determines whether a specific file path should be processed according to the TypeScript configuration.

/**
 * Creates a file matcher function based on tsconfig include/exclude patterns
 * @param tsconfig - The parsed tsconfig result from getTsconfig or parseTsconfig
 * @param caseSensitivePaths - Whether file paths are case sensitive (auto-detected by default)
 * @returns FileMatcher function or throws error for invalid input
 */
function createFilesMatcher(
  tsconfig: TsConfigResult,
  caseSensitivePaths?: boolean
): FileMatcher;

/**
 * Function that tests whether a file path matches the tsconfig patterns
 * @param filePath - Absolute path to the file to test
 * @returns The tsconfig if file matches, undefined if excluded or doesn't match
 */
type FileMatcher = (filePath: string) => (TsConfigJsonResolved | undefined);

Usage Examples:

import { getTsconfig, createFilesMatcher, type FileMatcher, type TsConfigResult } from "get-tsconfig";

const tsconfig = getTsconfig("./my-project");
if (tsconfig) {
  const fileMatcher = createFilesMatcher(tsconfig);
  
  // Test specific files
  const config1 = fileMatcher("/project/src/index.ts");     // Returns config if included
  const config2 = fileMatcher("/project/node_modules/pkg/index.js"); // Returns undefined (excluded)
  const config3 = fileMatcher("/project/dist/output.js");   // Returns undefined (excluded)
  
  // Use in file processing
  const files = ["/project/src/a.ts", "/project/src/b.js", "/project/test/spec.ts"];
  const includedFiles = files.filter(file => fileMatcher(file));
}

Pattern Matching Rules

The file matcher implements TypeScript's file inclusion logic:

Files Array: If files is specified, only listed files are included
Include Patterns: Glob patterns for files to include (default: ["**/*"])
Exclude Patterns: Glob patterns for files to exclude (default: output directories)
Extension Filtering: Only files with supported extensions (.ts, .tsx, .d.ts, .js, .jsx if allowJs is enabled)
Implicit Globs: Directory patterns like src are expanded to src/**/*

Supported Glob Patterns:

* - Matches any characters except path separator
** - Matches any characters including path separators (recursive)
? - Matches any single character except path separator
Directory names automatically become directory/**/* patterns

Default Exclusions:

node_modules directory and subdirectories
bower_components directory and subdirectories
jspm_packages directory and subdirectories
Output directories specified in compilerOptions.outDir
Declaration output directories specified in compilerOptions.declarationDir

Case Sensitivity Handling

File matching respects file system case sensitivity:

import { createFilesMatcher } from "get-tsconfig";

// Auto-detect case sensitivity (recommended)
const matcher1 = createFilesMatcher(tsconfig);

// Force case-sensitive matching
const matcher2 = createFilesMatcher(tsconfig, true);

// Force case-insensitive matching 
const matcher3 = createFilesMatcher(tsconfig, false);

Error Conditions

The file matcher will throw errors in these cases:

Unresolved extends: If the tsconfig still contains unresolved extends properties
Relative tsconfig path: If the tsconfig path is not absolute
Invalid file path: If the tested file path is not absolute

Error Handling Example:

import { getTsconfig, createFilesMatcher, type FileMatcher, type TsConfigResult } from "get-tsconfig";

try {
  const tsconfig = getTsconfig();
  if (tsconfig) {
    const fileMatcher = createFilesMatcher(tsconfig);
    
    // This will throw - file path must be absolute
    const result = fileMatcher("./relative/path.ts");
  }
} catch (error) {
  console.error("File matcher error:", error.message);
}

Integration with Build Tools

Common integration patterns for build tools and file processors:

import { getTsconfig, createFilesMatcher, type FileMatcher, type TsConfigResult } from "get-tsconfig";
import { glob } from "glob";

// Find all TypeScript files that match the project configuration
async function getProjectFiles(projectDir: string): Promise<string[]> {
  const tsconfig = getTsconfig(projectDir);
  if (!tsconfig) {
    throw new Error("No tsconfig.json found");
  }
  
  const fileMatcher = createFilesMatcher(tsconfig);
  
  // Get all potential files
  const allFiles = await glob("**/*.{ts,tsx,js,jsx}", { 
    cwd: projectDir, 
    absolute: true 
  });
  
  // Filter using tsconfig patterns
  return allFiles.filter(file => fileMatcher(file));
}