Docs · Why runtime observation

Why runtime observation

Most type tools work statically — they read your source and reason about it. ts-capture instead watches your code run and records the types values actually had. This is a deliberate trade-off, and it determines where the tool helps and where it doesn't.

The case for observing at runtime #

A static tool can only infer what the source already constrains. The hardest anys — a parameter no annotation pins down, a callback argument, a JSON.parse result — are exactly the ones static inference gives up on, because the information isn't in the source. It is in the runtime: the value that actually flowed through. ts-capture reads it there.

The approach isn't new: TypeWiz (archived 2021) pioneered runtime type collection for TypeScript and directly inspired ts-capture.

The cost is that observation needs real executions (usually your test suite) and adds run-time overhead — see What observation costs. The payoff is types for positions a static tool leaves as any.

The deeper consequence of that trade-off: the output is a function of which code paths ran, not of the code itself. A static tool gives the same answer every time; ts-capture gives the answer your last run earned, so two different test selections produce different annotations and neither is wrong. Apply from a run that represents how the code is really used, and re-observe after meaningfully expanding the suite. Reading your values also has real side effects — see Observation reads your values.

When ts-capture helps most #

When ts-capture helps least #

For codebases already strictly typed end-to-end, the value is smaller and the regression risk higher — read What it cannot infer and Review & apply safely before running apply on production code.