Docs · How it works

How it works

ts-capture turns implicit any into real types by watching your code run — usually under your existing test suite — and writing back the types it observed. There is no static guessing: a parameter becomes string because it was actually called with a string.

Input
// Before — implicit any on the parameter
function greet(name) {
  return "Hello, " + name;
}
greet("World");
Expected
// After apply — the observed type is written back; the return is left to
// TypeScript, which infers `string` from it
function greet(name: string) {
  return "Hello, " + name;
}
greet("World");

The pipeline has three stages: observe → merge → apply.

1. Observe #

Your source is instrumented — wrapped so each function records the runtime types of its arguments and return value — and then run. As it runs, each process writes its observations to a per-process JSON dump named ts-capture-types-<uuid>.json under TS_CAPTURE_TYPES_DIR.

There are three ways to instrument, depending on your stack — pick one:

Way How When
Bundler plugin @ts-capture/vite (Vitest/Vite), @ts-capture/esbuild, @ts-capture/babel-plugin You run tests through a bundler/transform. Source on disk is never modified.
Node preload NODE_OPTIONS='--require @ts-capture/core/preload' No build tooling — plain node, ts-node, Mocha, etc.
CLI, in place ts-capture instrument <file> --in-place One-off / scripted runs; rewrites the file (commit it first).

The plugin and preload paths instrument in memory, so code that lints, format-checks, or type-checks on-disk source before testing stays green.

Observation reads your values — including getters #

To describe a value, the walker reads it: every own enumerable property of an object, every element of an array, Map or Set. That means:

The walk is depth-limited, but not side-effect free: treat an instrumented run as a diagnostic run, not as your normal CI run — and never attach one to a production process.

2. Merge #

A real test run produces many dump files — Vitest's forks pool emits one per worker, for example. ts-capture merge consolidates them into a single types.json:

npx ts-capture merge ./.ts-capture --out types.json

Merging is also where observations of the same position from different runs are combined — e.g. a parameter seen as both string and number becomes string | number.

3. Apply #

ts-capture apply reads types.json and writes the inferred annotations into your source files:

npx ts-capture apply types.json --dry-run   # preview, write nothing
npx ts-capture apply types.json             # write the changes

This is the stage that modifies your code on disk, so run it from a clean, committed working tree — the apply then reads as a git diff you can review in full and revert with git checkout ..

Apply is conservative by design:

Because apply only fills gaps and is gated by the type-checker, a run that finds nothing safe to add changes nothing.

What observation costs #

ts-capture's transform-time instrumentation adds 18-31% wall-time overhead on synthetic benches (linear axes — file count, call count, type complexity). On the hono test suite (3457 tests, 284 source files) it runs in 246s with ts-capture observation enabled vs 33s baseline, ~7.5× slower, with all tests passing. Observation is for a test run you start on purpose, not every run.

Why not V8 native coverage? #

ts-capture is forced to use transform-time instrumentation because shape observation requires actual runtime values, not just hit counts. V8's coverage protocol exposes line/branch hit counts only — useful for coverage tools like c8, but insufficient for a tool that needs to walk values to compute their structural type. We inherit transform- time's known weaknesses (per-call overhead, language-feature lag, sourcemap complexity) by necessity.

Where to go next #