TypeScript Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• tsconfig.json
• tsconfig.eslint.json
• package.json
• biome.json
• src/index.ts
• src/compile.ts

The TypeScript configuration in this project establishes a modern development environment focused on ESM (EcmaScript Modules) compatibility, strict type safety, and efficient build orchestration. The project utilizes a tiered configuration approach where a base configuration defines the compilation standards, and specialized configurations extend it for tooling such as ESLint.

The primary objective of this configuration is to transform the source TypeScript files located in src/ into a distributable dist/ directory containing optimized JavaScript and corresponding declaration files. This setup ensures that nth-check can be consumed both as a high-performance library and a type-safe dependency.

Sources: tsconfig.json:1-30, package.json:1-25

Build Pipeline Architecture

The project employs tsc as the primary compiler for generating production assets. The build process is integrated into the npm lifecycle scripts, ensuring that types are emitted during the build phase while being checked without emission during linting.

The diagram above illustrates how the main configuration drives the transformation from source to distribution.
Sources: package.json:28-40, tsconfig.json:8-12

Compiler Options

The core compilation logic is defined in tsconfig.json. The project targets es2022, reflecting a requirement for modern Node.js environments (specifically >=20.19.0 as defined in the engines).

Core Compilation Settings

Option	Value	Description
target	es2022	Specifies the JavaScript language version for emitted code.
module	nodenext	Sets the module system to Node.js's modern ESM/CJS resolution.
moduleResolution	nodenext	Ensures resolution algorithms match Node.js's native behavior.
outDir	dist	Redirects output structure to the dist directory.
rootDir	src	Specifies the root directory of input files.
declaration	true	Generates .d.ts files for consumers.

Sources: tsconfig.json:3-12, package.json:54-56

Strictness and Quality Checks

The project enables strict mode along with several additional flags to prevent common programming errors and ensure cleaner codebases.

• Type Safety: strict: true enables the full suite of strict type-checking options.
• Module Integrity: isolatedModules: true and isolatedDeclarations: true ensure that files can be safely transpiled by tools that do not have access to the full type system.
• Unused Code: noUnusedLocals and noUnusedParameters are enabled to maintain lean code.
• Switch Safety: noFallthroughCasesInSwitch prevents accidental logic errors in complex parsing switches.

Sources: tsconfig.json:14-25

Specialized Configurations

The project uses inheritance to manage different requirements for compilation and linting.

ESLint Configuration (tsconfig.eslint.json)

This file extends the base configuration to include test files which are otherwise excluded from the production build. It sets noEmit: true because its purpose is purely for type-aware linting via typescript-eslint.

The class diagram represents the inheritance relationship between the production and linting configurations.
Sources: tsconfig.eslint.json:1-11, tsconfig.json:27-35

Module Distribution

The TypeScript configuration supports the package's exports strategy. The package.json defines the entry points that correspond to the files generated by tsc.

{
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "default": "./dist/index.js"
        }
    }
}

This configuration ensures that both TypeScript and JavaScript consumers receive the correct files with appropriate type definitions.
Sources: package.json:11-18, tsconfig.json:8-10

Code Formatting and Linting Integration

While tsconfig.json handles type checking and emission, it works in tandem with Biome and ESLint for style and static analysis.

• Biome: Configured in biome.json to handle formatting (spaces, width 4) and linting rules that complement TypeScript's checks, such as noInferrableTypes and useConsistentTypeDefinitions.
• Type-aware Linting: The script lint:ts runs tsc --noEmit -p tsconfig.eslint.json to perform a full project type check without generating files.

Sources: biome.json:15-20, package.json:36, biome.json:44-50

Summary

The TypeScript configuration of nth-check is designed for a modern ESM-first workflow. By leveraging nodenext module resolution and strict type-checking flags, the project ensures high reliability for its core logic of parsing and compiling CSS selectors. The use of specialized configurations for linting allows the project to maintain a strict boundary between production source code and test infrastructure while maintaining consistent type safety across the entire repository.