quicktype-core 24.0.0: 'lang' is now a strict literal union — README-style samples using 'string' no longer typecheck; document LanguageName

[schani]

Issue Type

DX regression / documentation gap in the quicktype-core API

Context (Environment, Version, Language)

CLI, npm, or app.quicktype.io: npm package quicktype-core
Version: 24.0.0
TypeScript: 5.8.3

Description

In 24.0.0 the lang option of quicktype() (and the parameter of jsonInputForTargetLanguage()) is typed as a strict literal union (LanguageName | TargetLanguage) instead of string.

The widely-circulated usage sample (README / blog posts / Stack Overflow answers) wraps quicktype in a helper taking targetLanguage: string:

async function quicktypeJSON(targetLanguage: string, typeName: string, jsonString: string) {
    const jsonInput = jsonInputForTargetLanguage(targetLanguage);
    // ...
    return quicktype({ inputData, lang: targetLanguage });
}

This no longer typechecks:

error TS2345: Argument of type 'string' is not assignable to parameter of type '"ruby" | TargetLanguage<LanguageConfig> | "cjson" | "cJSON" | "c++" | ...'.
error TS2322: Type 'string' is not assignable to type '"ruby" | TargetLanguage<LanguageConfig> | ... | undefined'.

The fix is to use the exported LanguageName type:

import { type LanguageName } from "quicktype-core";
async function quicktypeJSON(targetLanguage: LanguageName, ...) { ... }

The stricter typing is arguably an improvement (typos in language names are caught at compile time), but it's a breaking change for anyone porting existing sample code, and LanguageName doesn't appear in the docs/README samples.

Expected Behaviour / Output

Either:

• documented migration guidance: update the README/sample code to use LanguageName, and mention the break in the 24.0.0 release notes, and/or
• an escape hatch for dynamic language names (e.g. keep isLanguageName() prominent in the docs so string values can be narrowed before the call).

Current Behaviour / Output

Code following the published examples fails to compile against 24.0.0 with TS2345/TS2322, and the resolution (LanguageName) is only discoverable by reading dist/language/types.d.ts.

Steps to Reproduce

npm install quicktype-core@24.0.0 typescript@5.8
# compile the README-style helper above with tsc --strict

Found while testing the 24.0.0 release on Node 20/22/24.

[hiSandog]

Besides exporting and documenting LanguageName, a migration example could show how to validate a runtime string before passing it to quicktype() or jsonInputForTargetLanguage(). That would preserve the stronger 24.0.0 typing without encouraging wrappers that accept CLI or configuration input to use an unsafe cast.