tessl/npm-get-tsconfig

Find and parse the tsconfig.json file from a directory path

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

File Pattern Matching

Name: tessl/npm-get-tsconfig
Author: tessl

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));
}