Skip to content

Document LanguageName migration and keep the README sample typechecking#2907

Closed
schani wants to merge 1 commit into
masterfrom
docs/language-name-migration
Closed

Document LanguageName migration and keep the README sample typechecking#2907
schani wants to merge 1 commit into
masterfrom
docs/language-name-migration

Conversation

@schani

@schani schani commented Jul 10, 2026

Copy link
Copy Markdown
Member

Fixes #2905.

Problem

Since quicktype-core 23.1.0, the lang option of quicktype() and the parameter of jsonInputForTargetLanguage() are typed as LanguageName | TargetLanguage instead of string | TargetLanguage. The widely-circulated README-style sample that wraps quicktype in a helper taking targetLanguage: string no longer typechecks (TS2345/TS2322), and the resolution — the exported LanguageName type and isLanguageName() type guard — was only discoverable by reading dist/language/types.d.ts. Anyone upgrading from 23.0.x straight to 24.0.0 hits this without any migration guidance.

Approach

No API changes are needed — LanguageName and isLanguageName are already exported from quicktype-core's public entry point. The types stay strict; this PR documents them and pins the docs to the API with a test:

  • README: the "Calling quicktype from JavaScript" sample is now TypeScript with targetLanguage: LanguageName parameters (with a note that plain-JS users just drop the annotations), is self-contained/runnable, and gains a snippet showing the escape hatch for dynamic language names: narrow a string with isLanguageName() (which accepts everything quicktype accepts — canonical names, display names, and extensions), with languageNamed()TargetLanguage instance mentioned as the alternative.
  • MIGRATING.md: new "Stricter language-name typing in quicktype-core" section describing when the change landed (23.1.0), the exact error symptoms, and both migration styles; the existing "no public API changes in 24" sentence is qualified so it no longer contradicts what upgraders from ≤23.0.x experience.
  • New test test/unit/readme-sample.test.ts: extracts the TypeScript code blocks from that README section and compiles them with tsc --strict against the built quicktype-core, so the sample — and the public exports it relies on — can't silently rot again.

Verification

  • npm run build and npm run test:unit pass (8 files, 67 tests, including the new one).
  • Negative check: compiling the old targetLanguage: string helper against the built package reproduces exactly the TS2345/TS2322 errors from the issue, confirming the test setup catches the regression class.
  • End-to-end: npm packed quicktype-core 24.0.0 into a standalone scratch project, extracted the README snippets verbatim, compiled with tsc --strict, and ran them — the sample emits the expected Swift and Python output.
  • No package.json versions touched, per repo convention.

🤖 Generated with Claude Code

Since quicktype-core 23.1.0, the `lang` option of quicktype() and the
parameter of jsonInputForTargetLanguage() are typed as
`LanguageName | TargetLanguage` instead of `string | TargetLanguage`.
The README sample wrapped quicktype in helpers taking untyped language
parameters, so the widely-copied TypeScript variant using
`targetLanguage: string` fails with TS2345/TS2322 — and the fix
(the exported `LanguageName` type and `isLanguageName` type guard)
was undocumented. Fixes #2905.

- Update the README "Calling quicktype from JavaScript" sample to
  TypeScript with `LanguageName` parameters, make it self-contained,
  and add a snippet showing how to narrow dynamic language names with
  the `isLanguageName` type guard (mentioning `languageNamed` as the
  TargetLanguage-instance alternative).
- Add a migration section to MIGRATING.md describing the stricter
  typing, when it landed, the error symptoms, and both fixes; qualify
  the "no public API changes" claim accordingly.
- Add test/unit/readme-sample.test.ts, which extracts the TypeScript
  blocks from that README section and compiles them with tsc --strict
  against the built quicktype-core, so the sample and the exports it
  relies on cannot silently rot again.

No runtime or API changes; LanguageName and isLanguageName were
already exported from the public entry point.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@schani

schani commented Jul 10, 2026

Copy link
Copy Markdown
Member Author

Closing: we've decided the fuzzy language-name matching (display names / extensions in languageNamed/isLanguageName) reintroduced by #2883 was a mistake, and this PR documents that behavior. #2883 is being reverted instead.

@schani schani closed this Jul 10, 2026
@schani schani deleted the docs/language-name-migration branch July 10, 2026 21:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant