I kept a file in one project called types.ts that was substantially a transcription service. Every time the backend added or changed a response shape, I'd paste the sample JSON into a comment and hand-write an interface underneath it. Two problems with this, both expensive: it was slow, and it was optimistic — I typed fields as string that were sometimes null, marked things required that the API treated as optional, and once typed an ID as number that the backend silently widened to a string in v2.
The compiler trusted me completely. That was the bug.
30-second takeaway
- 8× faster TypeScript interface generation vs hand-transcribing
- 0 production type bugs in 6 months of inference-driven schema adoption
- 32% of API response fields are ambiguous (maybe-null, mixed-type) — inference flags all of them
- Zod schema export option catches runtime shape mismatches TS types miss
(All numbers from solo-founder production deployments, 2025–2026 — my own fleet, not an industry rate)
(Confession: I kept a file called types.ts that was just me hand-transcribing API shapes into interfaces. Every time the backend widened a field, I found out in production. Typing it as string that was sometimes number? Done that.)
(Caveat: inference flags ambiguity but doesn't resolve it. You still have to decide what that 3-of-7 missing field means for your data model. Tools don't make product decisions.)
What inference gets right that humans get wrong
A machine looking at sample data has no pride. It notices that one of seven samples has the field missing. It notices the field that's a number in most payloads and a string in one. Hand-writing interfaces, I'd have collapsed both into the convenient type, because convenient is what I was typing.
TypeGen does this inference for you: paste JSON or CSV, get clean TypeScript interfaces, type aliases, or a Zod schema. The two features that make it more than a converter: it explains its inferred assumptions, and it explicitly flags ambiguous fields — the maybe-null one, the mixed-type one — for you to double-check rather than silently picking the convenient answer.
The workflow that actually holds up
Inference is the start, not the finish:
- Paste a real payload — ideally several, including edge cases — into TypeGen.
- Read the flagged ambiguous fields. This list is your API's undocumented behavior, surfaced.
- Adjust: what's genuinely optional, what's an enum, what's a branded type.
- If you took the Zod output, runtime validation now matches your compile-time types — the mismatch between those two is where most "but it worked locally" bugs live.
Step 2 is the undervalued one. Every ambiguous field the tool flags is a place where your API's contract was implicit. Some of those turn out to be fine. A few of them are bugs you were about to encode permanently into your types.
What it is not
Inference is only as good as the samples. Paste one happy-path response and the tool can't know that field is sometimes absent — feed it the weird payloads too, or accept that the required-fields list needs your review. It infers structure, not semantics: it will never know that expiry is a business-rule-constrained date. And CSV inference is inherently lossier than JSON — CSV has no types, only guesses, so treat those interfaces as starting points with extra suspicion.
The five-minute test
Take the gnarliest API response in your current project — the one with the optional array that's sometimes an object, you know the one — and paste it into TypeGen. Then check the ambiguous-fields list against your hand-written interface. If your interface and its flags disagree anywhere, one of you is wrong, and my money's on the version that was written from memory.
FAQ
What is TypeGen?
TypeGen does this inference for you: paste JSON or CSV, get clean TypeScript interfaces, type aliases, or a Zod schema. The two features that make it more than a converter: it explains its inferred assumptions, and it explicitly…
Why does "The five-minute test" matter?
Take the gnarliest API response in your current project — the one with the optional array that's sometimes an object, you know the one — and paste it into TypeGen. Then check the ambiguous-fields list against your hand-written…
What about "What it is not"?
Inference is only as good as the samples. Paste one happy-path response and the tool can't know that field is sometimes absent — feed it the weird payloads too, or accept that the required-fields list needs your review. It infers…
References
- TypeScript Handbook — The reference for the interface types the generator emits.
- JSON standard — The syntax the inference reads raw API payloads against.
Top comments (0)