or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md core-resolution.md index.md resolver-factory.md utilities.md

tile.json

Configuration Management

Option normalization and TypeScript project configuration management for handling various project structures and settings.

Capabilities

Normalize Options

Normalizes and validates TypeScript resolver options, handles project detection, and manages configuration caching.

/**
 * Normalizes TypeScript resolver options and handles project detection
 * @param options - Raw TypeScript resolver options
 * @param cwd - Current working directory (defaults to process.cwd())
 * @returns Normalized and validated options
 */
function normalizeOptions(
  options?: TypeScriptResolverOptions | null,
  cwd?: string
): TypeScriptResolverOptions;

Usage Examples:

import { normalizeOptions } from "eslint-import-resolver-typescript";

// Basic normalization
const normalized = normalizeOptions({
  project: "./tsconfig.json",
  alwaysTryTypes: true
});

// With custom working directory
const normalizedWithCwd = normalizeOptions(
  { project: "configs/tsconfig.json" },
  "/path/to/project"
);

// Normalize empty options (uses defaults)
const defaults = normalizeOptions();
console.log(defaults.extensions); // ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json', '.node']

Option Normalization Features

The normalization process handles several complex scenarios:

Project Path Resolution: Converts relative paths to absolute paths
Glob Pattern Expansion: Expands glob patterns to actual configuration files
Default Detection: Automatically finds tsconfig.json or jsconfig.json files
Multi-Project Handling: Manages multiple TypeScript configurations
Caching: Caches normalized options for performance
Validation: Validates configuration file existence and accessibility

Configuration Types

interface TypeScriptResolverOptions extends NapiResolveOptions {
  /** TypeScript project configuration paths (file path, directory, or glob patterns) */
  project?: string[] | string;
  /** Whether to always try to resolve @types packages (default: true) */
  alwaysTryTypes?: boolean;
  /** Whether Bun core modules should be accounted for */
  bun?: boolean;
  /** Suppress multiple projects warning */
  noWarnOnMultipleProjects?: boolean;
  
  // Configuration object for TypeScript compiler
  tsconfig?: {
    /** Path to TypeScript configuration file */
    configFile?: string;
    /** TypeScript project references handling */
    references?: 'auto' | boolean;
  };
}

Project Configuration Patterns

Single Configuration File:

const options = normalizeOptions({
  project: "./tsconfig.json"
});

Directory-based Configuration:

const options = normalizeOptions({
  project: "path/to/folder" // Will look for tsconfig.json or jsconfig.json
});

Multiple Configurations:

const options = normalizeOptions({
  project: [
    "packages/module-a/tsconfig.json",
    "packages/module-b/jsconfig.json"
  ]
});

Glob Pattern Configurations:

// Single glob pattern
const globOptions = normalizeOptions({
  project: "packages/*/tsconfig.json"
});

// Multiple glob patterns
const multiGlobOptions = normalizeOptions({
  project: [
    "packages/*/tsconfig.json",
    "other-packages/*/jsconfig.json"
  ]
});

// Complex glob pattern
const complexGlobOptions = normalizeOptions({
  project: "packages/*/{ts,js}config.json"
});

Default Values

The normalization process applies these default values:

// Mutable variable holding the default configuration file path
declare let defaultConfigFile: string;

// Default condition names for package.json exports
declare const defaultConditionNames: string[];
// ['types', 'import', 'esm2020', 'es2020', 'es2015', 'require', 'node', 'node-addons', 'browser', 'default']

// Default file extensions to resolve
declare const defaultExtensions: string[];
// ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json', '.node']

// Default extension aliases for TypeScript compilation
declare const defaultExtensionAlias: Record<string, string[]>;
/* {
  '.js': ['.ts', '.tsx', '.d.ts', '.js'],
  '.ts': ['.ts', '.d.ts', '.js'],
  '.jsx': ['.tsx', '.d.ts', '.jsx'],
  '.tsx': ['.tsx', '.d.ts', '.jsx', '.js'],
  '.cjs': ['.cts', '.d.cts', '.cjs'],
  '.cts': ['.cts', '.d.cts', '.cjs'],
  '.mjs': ['.mts', '.d.mts', '.mjs'],
  '.mts': ['.mts', '.d.mts', '.mjs']
} */

// Default package.json main fields priority
declare const defaultMainFields: string[];
// ['types', 'typings', 'fesm2020', 'fesm2015', 'esm2020', 'es2020', 'module', 'jsnext:main', 'main']

Configuration File Detection

The normalization process follows this detection algorithm:

Explicit Configuration: If project is specified, use those paths
Directory Scanning: If project points to directories, scan for config files
Glob Expansion: Expand glob patterns to actual configuration files
Default Detection: Fall back to root tsconfig.json or jsconfig.json
Validation: Verify that configuration files exist and are readable

// Detection priority order:
const DEFAULT_CONFIGS = ['tsconfig.json', 'jsconfig.json'];
const DEFAULT_TRY_PATHS = ['', ...DEFAULT_CONFIGS];

Multi-Project Handling

For projects with multiple TypeScript configurations:

const options = normalizeOptions({
  project: [
    "frontend/tsconfig.json",
    "backend/tsconfig.json",
    "shared/tsconfig.json"
  ],
  noWarnOnMultipleProjects: true // Suppress warning about multiple projects
});

Without noWarnOnMultipleProjects, the resolver will warn:

"Multiple projects found, consider using a single tsconfig with references to speed up"

Caching Behavior

The normalization process implements intelligent caching:

Configuration Caching: Caches normalized options by configuration file and options hash
File System Caching: Caches file existence checks and directory scans
Glob Result Caching: Caches glob pattern expansion results

Cache keys are generated using stable hashing of the configuration:

import { stableHash } from 'stable-hash-x';

const optionsHash = stableHash(options);
const cacheKey = `${configFile}\0${optionsHash}`;

Error Handling

The normalization process handles various error conditions:

Missing Configuration Files: Continues with default behavior if optional configs are missing
Invalid Glob Patterns: Throws descriptive errors for malformed patterns
Permission Issues: Handles file system permission problems gracefully
Circular References: Detects and prevents circular configuration references

Performance Optimization

Several optimizations improve normalization performance:

Lazy Evaluation: Defers expensive operations until needed
Path Caching: Caches resolved file paths
Pattern Matching: Uses efficient glob matching algorithms
Memory Management: Implements bounded caches to prevent memory leaks