Skip to content
AI Engineer Guide.

concept · basics · intermediate · concept 2 of 24

TypeScript for AI

0 of 24 complete

Why it matters

A model returns text that may or may not match the shape the prompt asked for, and the compiler cannot check it. Code that casts parsed JSON to an interface compiles cleanly and fails at the first missing field, usually in front of a user. The useful pattern treats the model boundary like any other external API: parse with a runtime schema, narrow the result, and represent partial and failed states in the type system so callers must handle them.

Mental model

It is a customs declaration: the form says what is inside, and the officer still opens the box. The analogy breaks because a type assertion is a declaration with no officer, which is why the validation step cannot be skipped.

How it works

Mechanism, step by stepInteractive
  1. 1Define a runtime schema for every model output the application consumes, and parse before use.
  2. 2Infer the TypeScript type from the schema so a field change updates both at once.
  3. 3Model streaming as a discriminated union of deltas, tool calls, usage and completion, and handle every variant.
  4. 4Represent tool arguments as parsed values with an explicit failure case, not as a string that is cast later.
  5. 5Type the provider client behind an internal interface, so a provider swap does not change application types.
  6. 6Add a test that feeds malformed and truncated output through the parser and asserts a typed error.

Step 1 of 6

Define a runtime schema for every model output the application consumes, and parse before use.

Step 1/6 · step 1

Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.

What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.

Text version

The page's steps: 1. Define a runtime schema for every model output the application consumes, and parse before… 2. Infer the TypeScript type from the schema so a field change updates both at once. 3. Model streaming as a discriminated union of deltas, tool calls, usage and completion, and… 4. Represent tool arguments as parsed values with an explicit failure case, not as a string … 5. Type the provider client behind an internal interface, so a provider swap does not change… 6. Add a test that feeds malformed and truncated output through the parser and asserts a typ…

  1. Define a runtime schema for every model output the application consumes, and parse before use.
  2. Infer the TypeScript type from the schema so a field change updates both at once.
  3. Model streaming as a discriminated union of deltas, tool calls, usage and completion, and handle every variant.
  4. Represent tool arguments as parsed values with an explicit failure case, not as a string that is cast later.
  5. Type the provider client behind an internal interface, so a provider swap does not change application types.
  6. Add a test that feeds malformed and truncated output through the parser and asserts a typed error.

Trade-offs

ChoiceGood forCostFails when
Runtime validation at the boundarySafe against malformed outputParsing cost and schema maintenanceThe payload is large and hot
Type assertionNo runtime costFailures appear far from the causeThe data crosses a system boundary
Strict schema with no optional fieldsClear contractModel output fails on minor omissionsThe model is unreliable on format
Lenient parsing with repairHigher success rateSilent wrong valuesThe field carries a decision
Trade-off mapInteractive

Good for

Safe against malformed output

Cost

Parsing cost and schema maintenance

Fails when

The payload is large and hot

  1. The payload is large and hot
  2. The data crosses a system boundary
  3. The model is unreliable on format
  4. The field carries a decision

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Runtime validation at the boundary is good for Safe against malformed output, costs Parsing cost and schema maintenance, and fails when The payload is large and hot. Type assertion is good for No runtime cost, costs Failures appear far from the cause, and fails when The data crosses a system boundary. Strict schema with no optional fields is good for Clear contract, costs Model output fails on minor omissions, and fails when The model is unreliable on format. Lenient parsing with repair is good for Higher success rate, costs Silent wrong values, and fails when The field carries a decision

Failure modes

  • Cast instead of parse. A missing field becomes undefined and the failure surfaces in rendering. Debug: feed a response with the field removed through the handler and confirm it fails at the boundary.
  • Unhandled stream variant. A new event type arrives and the consumer ignores it, so content is dropped. Debug: log unknown event types and make the union exhaustive with a compile-time check.
  • Schema and type drift. The interface is edited but the validator is not, and validation passes the wrong shape. Debug: derive the type from the schema and remove hand-written duplicates.

In production

Log validation failures with the model, prompt version and a redacted sample, and alert on a rising rate, since it usually means a prompt or provider change. Cap retries on invalid output so a formatting problem cannot become a cost problem.

Common misconceptions

People think: TypeScript types protect against bad model output.

Actually: Types are erased at runtime; only validation at the boundary protects the program.

People think: Structured output mode removes the need to validate.

Actually: It raises conformance, and the response is still external input that can be truncated, refused or shaped unexpectedly.

Interview angle

Put validation at the boundary, derive the type from the schema and model streaming as a union. Mention exhaustive handling. Casting the parsed response and trusting the prompt is the mistake.

Sources