Document LanguageName migration and keep the README sample typechecking#2907
Closed
schani wants to merge 1 commit into
Closed
Document LanguageName migration and keep the README sample typechecking#2907schani wants to merge 1 commit into
schani wants to merge 1 commit into
Conversation
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>
Member
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2905.
Problem
Since quicktype-core 23.1.0, the
langoption ofquicktype()and the parameter ofjsonInputForTargetLanguage()are typed asLanguageName | TargetLanguageinstead ofstring | TargetLanguage. The widely-circulated README-style sample that wraps quicktype in a helper takingtargetLanguage: stringno longer typechecks (TS2345/TS2322), and the resolution — the exportedLanguageNametype andisLanguageName()type guard — was only discoverable by readingdist/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 —
LanguageNameandisLanguageNameare 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:quicktypefrom JavaScript" sample is now TypeScript withtargetLanguage: LanguageNameparameters (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 astringwithisLanguageName()(which accepts everything quicktype accepts — canonical names, display names, and extensions), withlanguageNamed()→TargetLanguageinstance mentioned as the alternative.test/unit/readme-sample.test.ts: extracts the TypeScript code blocks from that README section and compiles them withtsc --strictagainst the built quicktype-core, so the sample — and the public exports it relies on — can't silently rot again.Verification
npm run buildandnpm run test:unitpass (8 files, 67 tests, including the new one).targetLanguage: stringhelper against the built package reproduces exactly the TS2345/TS2322 errors from the issue, confirming the test setup catches the regression class.npm packed quicktype-core 24.0.0 into a standalone scratch project, extracted the README snippets verbatim, compiled withtsc --strict, and ran them — the sample emits the expected Swift and Python output.package.jsonversions touched, per repo convention.🤖 Generated with Claude Code