get-tsconfig 4.13.6 → 5.0.0-beta.2

package/README.md

@@ -9,14 +9,12 @@
 
 Find and parse `tsconfig.json` files.
 
-### Features
-- Zero dependency (not even TypeScript)
+## Features
+- Tiny! `9 kB` Minified + Gzipped
 - Tested against TypeScript for correctness
-- Supports comments & dangling commas in `tsconfig.json`
 - Resolves [`extends`](https://www.typescriptlang.org/tsconfig/#extends)
 - Fully typed `tsconfig.json`
 - Validates and throws parsing errors
-- Tiny! `7 kB` Minified + Gzipped
 
 <br>
 
@@ -33,168 +31,198 @@ npm install get-tsconfig
 ```
 
 ## Why?
-For TypeScript related tooling to correctly parse `tsconfig.json` file without depending on TypeScript.
 
-## API
+TypeScript tooling (bundlers, linters, loaders, test runners) needs to read `tsconfig.json` to understand compiler options, path aliases, and file inclusion rules. But TypeScript's own config parser is buried inside the compiler and requires TypeScript as a dependency.
 
-### getTsconfig(searchPath?, configName?, cache?)
+`get-tsconfig` provides the same functionality as a lightweight, standalone library — tested against TypeScript for correctness.
 
-Searches for a tsconfig file (defaults to `tsconfig.json`) in the `searchPath` and parses it. (If you already know the tsconfig path, use [`parseTsconfig`](#parsetsconfigtsconfigpath-cache) instead). Returns `null` if a config file cannot be found, or an object containing the path and parsed TSConfig object if found.
-
-Returns:
+## Quick start
 
 ```ts
-type TsconfigResult = {
+import { getTsconfig, isFileIncluded, resolvePathAlias } from 'get-tsconfig'
 
-    /**
-     * The path to the tsconfig.json file
-     */
-    path: string
+// Find and parse the nearest tsconfig.json
+const tsconfig = getTsconfig()
 
-    /**
-     * The resolved tsconfig.json file
-     */
-    config: TsConfigJsonResolved
+// To resolve path aliases (compilerOptions.paths):
+if (tsconfig) {
+    const resolved = resolvePathAlias(tsconfig, '@/utils/helper')
+    // → ['/project/src/utils/helper']
+}
+
+// To check if a file belongs to this tsconfig:
+if (tsconfig && isFileIncluded(tsconfig, '/project/src/index.ts')) {
+    // Use tsconfig.config.compilerOptions for transformation
 }
 ```
 
-#### searchPath
-Type: `string`
+## Finding & reading tsconfig
 
-Default: `process.cwd()`
+These functions find, read, and parse tsconfig files from the filesystem. All return a `TsconfigResult`:
+
+```ts
+type TsconfigResult<Config = TsconfigJsonResolved> = {
+    path: string
+    config: Config
+    sources: string[]
+}
+```
 
-Accepts a path to a file or directory to search up for a `tsconfig.json` file.
+- **path**: absolute path to the tsconfig file
+- **config**: the fully resolved config (extends merged, options normalized)
+- **sources**: paths of all tsconfig files that contributed to the resolved config via [`extends`](https://www.typescriptlang.org/tsconfig/#extends). When there are no `extends`, this is just `[path]`. Since `extends` can be an array, the order does not imply a linear chain.
 
-#### configName
+### getTsconfig(searchPath?, options?)
+
+Searches for a tsconfig file and parses it. If you already know the path, use [`readTsconfig`](#readtsconfigtsconfigpath-options) instead. Returns `undefined` if not found.
+
+#### searchPath
 Type: `string`
 
-Default: `tsconfig.json`
+Default: `process.cwd()`
 
-The file name of the TypeScript config file.
+Path to a file or directory. The directory tree is searched up for `tsconfig.json`.
 
-#### cache
-Type: `Map<string, any>`
+#### options
+Type: `GetTsconfigOptions`
 
-Default: `new Map()`
+```ts
+type GetTsconfigOptions = {
+    configName?: string // default: 'tsconfig.json'
+    cache?: Map<string, unknown>
+    includes?: boolean // default: false
+}
+```
 
-Optional cache for fs operations.
+- **configName**: file name to search for (e.g. `'jsconfig.json'`)
+- **cache**: snapshot cache for fs operations. Reusing after filesystem changes can return stale results.
+- **includes**: when `true`, validates the file is a root file (matched by `include`/`files` globs, not excluded) before accepting the tsconfig. Matches VS Code's Language Server behavior. Default matches `tsc` CLI behavior (nearest tsconfig). Note: this checks glob matching only — a file can still be part of a TypeScript program via transitive imports even if not matched by `include`.
 
 #### Example
 
 ```ts
 import { getTsconfig } from 'get-tsconfig'
 
-// Searches for tsconfig.json starting in the current directory
-console.log(getTsconfig())
-
-// Find tsconfig.json from a TypeScript file path
-console.log(getTsconfig('./path/to/index.ts'))
+// Find from current directory
+getTsconfig()
 
-// Find tsconfig.json from a directory file path
-console.log(getTsconfig('./path/to/directory'))
+// Find from a file path
+getTsconfig('./src/index.ts')
 
-// Explicitly pass in tsconfig.json path
-console.log(getTsconfig('./path/to/tsconfig.json'))
+// Search for jsconfig.json
+getTsconfig('.', { configName: 'jsconfig.json' })
 
-// Search for jsconfig.json - https://code.visualstudio.com/docs/languages/jsconfig
-console.log(getTsconfig('.', 'jsconfig.json'))
+// Language Server behavior — validate the file is included
+getTsconfig('./src/index.ts', { includes: true })
 ```
 
----
-
-### parseTsconfig(tsconfigPath, cache?)
+### findTsconfig(searchPath?, options?)
 
-Parse the tsconfig file provided. Used internally by `getTsconfig`. Returns the parsed tsconfig as `TsConfigJsonResolved`.
+Like `getTsconfig`, but returns only the path (`string | undefined`) without parsing. Same options.
 
-#### tsconfigPath
-Type: `string`
-
-Required path to the tsconfig file.
+```ts
+import { findTsconfig } from 'get-tsconfig'
 
-#### cache
-Type: `Map<string, any>`
+findTsconfig() // → '/project/tsconfig.json'
+```
 
-Default: `new Map()`
+### readTsconfig(tsconfigPath, options?)
 
-Optional cache for fs operations.
+Reads and resolves a tsconfig at a known path. Used internally by `getTsconfig`.
 
-#### Example
+```ts
+type ReadTsconfigOptions = {
+    cache?: Map<string, unknown>
+}
+```
 
 ```ts
-import { parseTsconfig } from 'get-tsconfig'
+import { readTsconfig } from 'get-tsconfig'
 
-// Must pass in a path to an existing tsconfig.json file
-console.log(parseTsconfig('./path/to/tsconfig.custom.json'))
+const { path, config } = readTsconfig('./tsconfig.json')
 ```
 
----
+## Tsconfig `extends`
+
+`readTsconfig` and `getTsconfig` fully resolve the [`extends`](https://www.typescriptlang.org/tsconfig/#extends) chain and return a flattened config. These two functions expose the chain for use cases like watch mode and config auditing.
 
-### createFileMatcher(tsconfig: TsconfigResult, caseSensitivePaths?: boolean)
+### getExtendsChain(tsconfigPath, options?)
 
-Given a `tsconfig.json` file, it returns a file-matcher function that determines whether it should apply to a file path.
+Collects the full extends chain. Returns an array of `TsconfigResult<TsconfigJson>` entries — each containing the raw (unmerged) config with `extends` resolved to absolute paths. (`TsconfigJson` is the raw tsconfig.json shape, including the `extends` field.)
+
+`chain[0]` is the root. Ancestors follow in resolution order.
 
 ```ts
-type FileMatcher = (filePath: string) => TsconfigResult['config'] | undefined
+type GetExtendsChainOptions = {
+    cache?: Map<string, unknown>
+}
 ```
 
-#### tsconfig
-Type: `TsconfigResult`
+```ts
+import { getExtendsChain } from 'get-tsconfig'
 
-Pass in the return value from `getTsconfig`, or a `TsconfigResult` object.
+const chain = getExtendsChain('./tsconfig.json')
+// [
+//   { path: '/project/tsconfig.json', config: { extends: '/project/base.json', ... } },
+//   { path: '/project/base.json', config: { ... } },
+// ]
 
-#### caseSensitivePaths
-Type: `boolean`
+// Watch all files in the extends chain
+const filesToWatch = chain.map(entry => entry.path)
+```
 
-By default, it uses [`is-fs-case-sensitive`](https://github.com/privatenumber/is-fs-case-sensitive) to detect whether the file-system is case-sensitive.
+### resolveExtendsChain(chain)
 
-Pass in `true` to make it case-sensitive.
+Merges a collected extends chain into a resolved tsconfig. Pure function — no filesystem access.
 
-#### Example
+```ts
+import { getExtendsChain, resolveExtendsChain } from 'get-tsconfig'
 
-For example, if it's called with a `tsconfig.json` file that has `include`/`exclude`/`files` defined, the file-matcher will return the config for files that match `include`/`files`, and return `undefined` for files that don't match or match `exclude`.
+const chain = getExtendsChain('./tsconfig.json')
 
-```ts
-const tsconfig = getTsconfig()
-const fileMatcher = tsconfig && createFileMatcher(tsconfig)
-
-/*
- * Returns tsconfig.json if it matches the file,
- * undefined if not
- */
-const configForFile = fileMatcher?.('/path/to/file.ts')
-const distCode = compileTypescript({
-    code: sourceCode,
-    tsconfig: configForFile
-})
+// Modify before merging
+chain[0].config.compilerOptions = {
+    ...chain[0].config.compilerOptions,
+    sourceMap: true
+}
+
+const result = resolveExtendsChain(chain)
+// TsconfigResult { path, config, sources }
 ```
 
----
+## Working with a tsconfig
+
+These functions take a parsed `TsconfigResult` (from `getTsconfig` or `readTsconfig`) and answer questions about it. They cache compiled state per tsconfig object — do not mutate the tsconfig after the first call.
+
+### isFileIncluded(tsconfig, filePath)
 
-### createPathsMatcher(tsconfig: TsconfigResult)
+Checks whether an absolute file path matches a tsconfig's `files`, `include`, and `exclude` globs — i.e., whether it's a **root file**. Case sensitivity is auto-detected from the filesystem. Non-absolute paths return `false`.
 
-Given a tsconfig with [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths) defined, it returns a matcher function.
+> [!NOTE]
+> This checks glob matching only, not transitive imports. A file outside `include` can still be part of the TypeScript program if it's imported by a root file. `exclude` only filters the initial glob matching — it doesn't prevent transitively imported files from being compiled.
 
-The matcher function accepts an [import specifier (the path to resolve)](https://nodejs.org/api/esm.html#terminology), checks it against `compilerOptions.paths`, and returns an array of possible paths to check:
 ```ts
-function pathsMatcher(specifier: string): string[]
+import { getTsconfig, isFileIncluded } from 'get-tsconfig'
+
+const tsconfig = getTsconfig()
+
+if (tsconfig && isFileIncluded(tsconfig, '/path/to/file.ts')) {
+    // file is a root file of this tsconfig
+}
 ```
 
-This function only returns possible paths and doesn't actually do any resolution. This helps increase compatibility wtih file/build systems which usually have their own resolvers.
+### resolvePathAlias(tsconfig, specifier)
 
-#### Example
+Resolves an [import specifier](https://nodejs.org/api/esm.html#terminology) against [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths). Returns an array of possible file paths, or an empty array if no match. Does not perform actual file resolution.
 
 ```ts
-import { getTsconfig, createPathsMatcher } from 'get-tsconfig'
+import { getTsconfig, resolvePathAlias } from 'get-tsconfig'
 
 const tsconfig = getTsconfig()
-const pathsMatcher = createPathsMatcher(tsconfig)
-
-const exampleResolver = (request: string) => {
-    if (pathsMatcher) {
-        const tryPaths = pathsMatcher(request)
 
-        // Check if paths in `tryPaths` exist
-    }
+const tryPaths = tsconfig && resolvePathAlias(tsconfig, '@/utils/helper')
+if (tryPaths?.length) {
+    // Check if paths in tryPaths exist
 }
 ```
 

package/dist/index.d.mts

@@ -2044,45 +2044,151 @@ type TsConfigJson = {
 	references?: TsConfigJson.References[];
 };
 
-type TsConfigJsonResolved = Except<TsConfigJson, 'extends'>;
-type TsConfigResult = {
+type TsconfigJsonResolved = Except<TsConfigJson, 'extends'>;
+type TsconfigResult<Config = TsconfigJsonResolved> = {
     /**
-     * The path to the tsconfig.json file
+     * The tsconfig.json content. When using the default type parameter,
+     * this is the fully resolved config (extends merged, options normalized).
+     */
+    config: Config;
+    /**
+     * Absolute path to the tsconfig.json file
      */
     path: string;
     /**
-     * The resolved tsconfig.json file
+     * Paths of all tsconfig files that contributed to this config (via `extends`).
+     * `sources[0]` is the root tsconfig (same as `.path`), followed by extended
+     * configs in resolution order.
+     *
+     * Only present on resolved results (not on intermediate chain entries).
      */
-    config: TsConfigJsonResolved;
+    sources?: string[];
+};
+type TsconfigCache<value = any> = Map<string, value>;
+type TsconfigSearchOptions = {
+    configName?: string;
+    cache?: TsconfigCache;
+    includes?: boolean;
+};
+type GetTsconfigOptions = TsconfigSearchOptions;
+type FindTsconfigOptions = TsconfigSearchOptions;
+type TsconfigCacheOptions = {
+    cache?: TsconfigCache;
 };
-type Cache<value = any> = Map<string, value>;
+type ReadTsconfigOptions = TsconfigCacheOptions;
+type GetExtendsChainOptions = TsconfigCacheOptions;
 
 /**
- * Finds a tsconfig file, defaulting to `tsconfig.json`, starting from a given path.
+ * Searches for a tsconfig file by walking up the directory tree.
+ *
+ * @param searchPath Path to a source file or directory to search from (default: `process.cwd()`).
+ * @param options Optional search configuration.
+ * @param options.configName Config file name (default: `tsconfig.json`).
+ * @param options.cache Cache for previous results (default: new `Map()`).
+ * @param options.includes When true, validates that the tsconfig applies to the
+ * `searchPath` file via `include`/`exclude`/`files`. See {@link getTsconfig}
+ * for details. Default: `false`.
+ * @returns The path to the found tsconfig file, or `undefined` if not found.
+ */
+declare const findTsconfig: (searchPath?: string, options?: FindTsconfigOptions) => string | undefined;
+/**
+ * Finds and reads a tsconfig file by walking up the directory tree.
+ *
+ * By default, returns the nearest tsconfig found (matching `tsc` CLI behavior).
  *
- * @param searchPath Starting directory (default: `process.cwd()`).
- * @param configName Config file name (default: `tsconfig.json`).
- * @param cache Cache for previous results (default: new `Map()`).
- * @returns The tsconfig file path and parsed contents, or `null` if not found.
+ * When `includes` is true and `searchPath` is a file path, validates
+ * that the found tsconfig applies to the file (via `files`, `include`, and
+ * `exclude`). If the file isn't matched, continues searching parent directories.
+ * This matches VS Code's TypeScript Language Server behavior.
+ *
+ * Reference:
+ * - `tsc` CLI uses `findConfigFile()` which returns the nearest tsconfig without validation:
+ *   https://github.com/microsoft/TypeScript/blob/b19a9da2a3b8/src/compiler/program.ts#L328
+ * - Language Server uses `isMatchedByConfig()` to verify the file belongs to the project:
+ *   https://github.com/microsoft/TypeScript/blob/b19a9da2a3b8/src/server/editorServices.ts#L4486
+ *
+ * @param searchPath Path to a source file or directory to search from (default: `process.cwd()`).
+ * @param options Optional search configuration.
+ * @param options.configName Config file name (default: `tsconfig.json`).
+ * @param options.cache Cache for previous results (default: new `Map()`).
+ * @param options.includes When true, validates that the tsconfig applies to the
+ * `searchPath` file via `include`/`exclude`/`files`. Default: `false`.
+ * @returns The tsconfig file path and parsed contents, or `undefined` if not found.
  */
-declare const getTsconfig: (searchPath?: string, configName?: string, cache?: Cache) => TsConfigResult | null;
+declare const getTsconfig: (searchPath?: string, options?: GetTsconfigOptions) => TsconfigResult | undefined;
 
 /**
- * Parses a tsconfig file at a given path
+ * Collects the extends chain for a tsconfig file.
+ *
+ * Walks the filesystem to discover all configs in the extends chain,
+ * returning them as a flat array with `extends` resolved to absolute paths.
+ *
+ * @param tsconfigPath - Path to the tsconfig file.
+ * @param options - Optional read configuration.
+ * @param options.cache - Cache for filesystem reads (default: new `Map()`).
+ * @returns Array of `{ path, config }` entries. `chain[0]` is the root config.
+ * Ordered root-first, deepest ancestor last.
+ */
+declare const getExtendsChain: (tsconfigPath: string, options?: GetExtendsChainOptions) => TsconfigResult<TsConfigJson>[];
+/**
+ * Reads and resolves a tsconfig file at a given path
  *
  * @param tsconfigPath - Path to the tsconfig file.
- * @param cache - Cache for storing parsed tsconfig results (default: new `Map()`).
- * @returns The parsed and resolved tsconfig JSON.
+ * @param options - Optional read configuration.
+ * @param options.cache - Cache for filesystem reads and resolution results
+ * (default: new `Map()`).
+ * @returns The resolved absolute path and config. The path is the same one used
+ * internally for extends resolution.
  */
-declare const parseTsconfig: (tsconfigPath: string, cache?: Cache<string>) => TsConfigJsonResolved;
+declare const readTsconfig: (tsconfigPath: string, options?: ReadTsconfigOptions) => TsconfigResult;
 
 /**
- * Reference:
- * https://github.com/microsoft/TypeScript/blob/3ccbe804f850f40d228d3c875be952d94d39aa1d/src/compiler/moduleNameResolver.ts#L2465
+ * Resolves a collected extends chain into a merged tsconfig.
+ *
+ * Pure function — no filesystem access. Expects the output of
+ * `getExtendsChain` or an equivalent acyclic, root-first chain
+ * with `extends` resolved to absolute paths.
+ *
+ * @param chain - Array of `{ path, config }` entries. `chain[0]` is the
+ * root config. Must be acyclic — cyclic extends will cause infinite recursion.
+ * @returns The resolved tsconfig with path and fully merged config.
  */
-declare const createPathsMatcher: (tsconfig: TsConfigResult) => ((specifier: string) => string[]) | null;
+declare const resolveExtendsChain: (chain: TsconfigResult<TsConfigJson>[]) => TsconfigResult;
 
-type FileMatcher = (filePath: string) => (TsConfigJsonResolved | undefined);
-declare const createFilesMatcher: ({ config, path: tsconfigPath, }: TsConfigResult, caseSensitivePaths?: boolean) => FileMatcher;
+/**
+ * Resolves a specifier against a tsconfig's `compilerOptions.paths` mappings.
+ *
+ * Returns an array of possible file paths to check. Returns an empty
+ * array when no `paths` are configured or no pattern matches.
+ * Does not perform actual file resolution — compatible with any
+ * file/build system resolver.
+ *
+ * Results are cached per tsconfig object. The tsconfig must not be
+ * mutated after the first call.
+ *
+ * @param tsconfig - The resolved tsconfig to resolve against (treat as immutable).
+ * @param specifier - The import specifier to resolve.
+ * @returns Array of possible file paths, or empty array if no match.
+ */
+declare const resolvePathAlias: (tsconfig: TsconfigResult, specifier: string) => string[];
+
+/**
+ * Checks whether a file is included by a tsconfig's `files`, `include`,
+ * and `exclude` settings.
+ *
+ * Case sensitivity is auto-detected from the filesystem, matching
+ * TypeScript's behavior.
+ *
+ * The `filePath` must be absolute. Non-absolute paths return `false`.
+ *
+ * Compiled patterns are cached per tsconfig object. The tsconfig must
+ * not be mutated after the first call — mutation will not invalidate
+ * the cache and may return stale results.
+ *
+ * @param tsconfig - The resolved tsconfig to check against (treat as immutable).
+ * @param filePath - Absolute path to the file.
+ * @returns `true` if the file is included, `false` otherwise.
+ */
+declare const isFileIncluded: (tsconfig: TsconfigResult, filePath: string) => boolean;
 
-export { type Cache, type FileMatcher, TsConfigJson, type TsConfigJsonResolved, type TsConfigResult, createFilesMatcher, createPathsMatcher, getTsconfig, parseTsconfig };
+export { type FindTsconfigOptions, type GetExtendsChainOptions, type GetTsconfigOptions, type ReadTsconfigOptions, type TsconfigCache, TsConfigJson as TsconfigJson, type TsconfigJsonResolved, type TsconfigResult, findTsconfig, getExtendsChain, getTsconfig, isFileIncluded, readTsconfig, resolveExtendsChain, resolvePathAlias };