API for parsing *.json config files into a complete config objects

Suggestion

Dedicated public beginner-friendly API (ideally, an asynchronous function on the ts namespace) for parsing tsconfig.json / jsconfig.json files into a complete config object.

🔍 Search Terms

parse JSON config tsconfig tsconfig.json jsconfig.json

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn’t be a breaking change in existing TypeScript/JavaScript code
• This wouldn’t change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn’t a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript’s Design Goals.

⭐ Suggestion

The suggestion is to have a single function that in its simplest form (overload) would take a string, – path to the config file (either tsconfig.json or jsconfig.json, shouldn’t matter), and return (either synchronously or asynchronously) the fully compiled complete configuration object with all the properties initialized (either explicitly from the provided config(s) or implicitly, from known defaults).

See Motivating Example below for why I can’t use existing functions on ts namespace.

The suggestion is related to issue #44516 and this StackOverflow question.

📃 Motivating Example

I know that there are already a couple of functions on the imported ts namespace whose purpose is to read/parse/compile config, given its filepath/stringified contents/parsed contents. These include:

• ts.readConfigFile
• ts.parseConfigFileTextToJson
• ts.readJsonConfigFile
• ts.parseJsonConfigFileContent

However, they either provide incomplete functionality (e.g., ts.readConfigFile is just a glorified JSON.parse, it doesn’t – for example – crawl parent configs) or are ridiculously complicated to use (e.g., ts.parseConfigFileTextToJson require 3-9 arguments, the third of which is some kind of host object, that has to have a readDirectory method, that in turn requires 4-5 arguments, and has to actually do something, which I honestly don’t know why I can’t just use fs.readdirSync).

I need a function that takes a path to json and returns a complete config object.

💻 Use Cases

I’m thinking of a couple of variants of the function (for the sake of an example, it is called readConfig):

// given these
type Path = string | Buffer | URL;
interface Config {
  include?: string[], exclude?: string[], files?: string[], compilerOptions: { /*...*/ }, /* other properties of *.json config files */
}

/**
 * Find file by path, parse it, extend parent config objects, fill in missing defaults, return the resulting config object
 * If an error occurs, throw it
 */
/* 1 */ function readConfigSync(path: Path): Config;

/**
 * Find file by path, parse it, extend parent config objects, fill in missing defaults, invoke `callback(null, <resulting config object>)`
 * If an error occurs, invoke `callback(<error>)`
 */
/* 2 */ function readConfig(path: Path, callback: (...args: [ err: unknown ] | [ err: null, config: Config ]) => void): void;

/**
 * Find file by path, parse it, extend parent config objects, fill in missing defaults, return promise that resolves to the default config object
 * If an error occurs, return promise that rejects with the error
 */
/* 3 */ function readConfig(path: Path): Promise<Config>;

/**
 * Return the default config object
 * If an error occurs, throw it
 */
/* 4 */ function readConfigSync(): Config;

/**
 * Invoke `callback(null, <default config object>)`
 * If an error occurs, invoke `callback(<error>)`
 */
/* 5 */ function readConfig(callback: (...args: [ err: unknown ] | [ err: null, config: Config ]) => void): void;

/**
 * Return promise that resolves to the default config object
 * If an error occurs, return promise that rejects with the error
 */
/* 6 */ function readConfig(): Promise<Config>;

Also, shout out to functions that return { config?: Config; error?: unknown }, which, however, are not idiomatic to Node.JS.

[RyanCavanaugh]

That sample still works today with surprisingly few tweaks:

import ts = require("typescript");
import fs = require("fs");
import path = require("path");

function reportDiagnostics(diagnostics: ts.Diagnostic[]): void { 
    diagnostics.forEach(diagnostic => {
        let message = "Error";
        if (diagnostic.file && diagnostic.start) {
            let { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
            message += ` ${diagnostic.file.fileName} (${line + 1},${character + 1})`;
        }
        message += ": " + ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
        console.log(message);
    });
}

function readConfigFile(configFileName: string) { 
    // Read config file
    const configFileText = fs.readFileSync(configFileName).toString();  

    // Parse JSON, after removing comments. Just fancier JSON.parse
    const result = ts.parseConfigFileTextToJson(configFileName, configFileText);
    const configObject = result.config;
    if (!configObject) {
        reportDiagnostics([result.error!]);
        process.exit(1);;
    }

    // Extract config infromation
    const configParseResult = ts.parseJsonConfigFileContent(configObject, ts.sys, path.dirname(configFileName));
    if (configParseResult.errors.length > 0) {
        reportDiagnostics(configParseResult.errors);
        process.exit(1);
    }
    return configParseResult;
}


function compile(configFileName: string): void {
    // Extract configuration from config file
    let config = readConfigFile(configFileName);

    // Compile
    let program = ts.createProgram(config.fileNames, config.options);
    let emitResult = program.emit();

    // Report errors
    reportDiagnostics(ts.getPreEmitDiagnostics(program).concat(emitResult.diagnostics));

    // Return code
    let exitCode = emitResult.emitSkipped ? 1 : 0;
    process.exit(exitCode);
}

compile(process.argv[2]);

[dominikg]

some of you may be interested in tsconfck

import { parse } from 'tsconfck';
const {
	tsconfigFile, // full path to found tsconfig
	tsconfig, // tsconfig object including merged values from extended configs
	extended, // separate unmerged results of all tsconfig files that contributed to tsconfig
	solution, // solution result if tsconfig is part of a solution
	referenced // referenced tsconfig results if tsconfig is a solution
} = await parse('foo/bar.ts');

It also offers a similar parseNative function, which uses the typescript functions mentioned above

And last but not least a cli wrapper for simple checks

# print tsconfig for foo/bar.ts to stdout
npx tsconfck parse foo/bar.ts