Configuration reference
ts-capture reads an optional ts-capture., discovered by
walking up from the working directory (findConfigFile). Options can be set
there or overridden ad hoc on the CLI; both resolve to the same values.
{
"infer": {
"literal": { "string": true, "stringMaxLength": 24 },
"patternDetection": { "isoDate": true }
},
"apply": {
"skipFiles": ["src/**/*.generated.ts", "!src/generated/keep.ts"]
}
}# CLI override — only infer.* flags. Values are coerced:
# "true"/"false" -> boolean, numeric -> number, else string.
npx ts-capture apply types.json --infer.literal.string=true --infer.literal.stringMaxLength=24
Every flag's default matches ts-capture's behavior with no config present — the config layer is a no-op until you opt in. A partial config deep-merges over the defaults, so you only specify what you change.
Top-level keys #
| Key | Purpose |
|---|---|
infer |
Inference behavior (the bulk of the knobs — see below). |
apply |
ts-capture apply CLI behavior (currently skipFiles). |
common |
Shared compiler options (rootDir, tsConfig) — resolved against the config dir. |
instrument |
Per-run instrumentation options (advanced). Read by the register loader only, not by the bundler plugins. |
applyTypes |
Per-file applier options (advanced; distinct from the apply CLI layer). |
common / instrument / applyTypes are compiler/instrumentation plumbing;
most users only touch infer and apply.
infer.* #
Merge behavior #
| Flag | Default | What it does |
|---|---|---|
recursiveObjectMerge |
true |
Recursively merge nested object value types across observations, and lists of objects held by a property. |
crossSampleArrayMerge |
false |
Merge T[] | U[] cross-sample observations into (T | U)[]. Lists of objects merge without it. |
rewriteCommonBase |
false |
Collapse a union of class instances to their most-specific shared ancestor. Requires runtime-side LiteralOptions.. |
lubFallback |
false |
When the legacy object merge bails, fall back to anti-unification (type-ir); emits unknown for disjoint polymorphic positions. |
Scope & existing types #
| Flag | Default | What it does |
|---|---|---|
skipRedundantAnnotations |
true |
Skip any annotation TypeScript already infers as well or better — variables, fields, return types, and contextually typed parameters. Uses the TypeChecker when a project is available, falling back to a syntactic check otherwise. On a const such an annotation is lossy, not merely redundant: TS infers the literal type and the annotation widens it. Turning it off asks for restatement, not for destruction: the guards that refuse to erase an enum, drop a union arm, overwrite a polymorphic this or widen a unique symbol hold whatever this flag says. Judged against the project as apply leaves it, not as it was on disk: a file's parameters and return types are written first, its locals, class fields and callbacks are then checked against the result, and files are processed in import order so a callee typed earlier in the run counts. The second pass needs typecheckVerify. A return type the run saw narrower than what TypeScript infers once the parameters are written, as when the tests never took a return null branch, is written as TypeScript's type. Where TypeScript inferred that type before the run, writing it is a restatement, and it is written only with this flag off. |
honorAsCasts |
true |
Honor user-written as Type / <Type> casts on a varDecl RHS (cast wins over the observed type). Set false for observation-wins. |
preferNamedInScope |
true |
Replace a structural object type with an exact-matching in-scope interface/type name. A union of literals is written as an in-scope alias of literals too, when the observed arms are all of its arms, or at least two of them and no other alias holds them ("active" | "inactive" becomes Status); this needs literal. on, since a widened observation is string. Set false to always keep the structural form. |
requireTypeRefInScope |
true |
Skip an annotation referencing a name not reachable as a type at the target file (avoids TS2304). |
ignoreExistingTypes |
false |
Emit even at already-annotated positions. Produces syntactically invalid TS — a measurement tool, not a rewrite; the CLI warns on stderr. |
Verification & recognition #
| Flag | Default | What it does |
|---|---|---|
cstAware |
true |
Use the AST/CST-aware applier instead of the legacy string-offset applier. |
typecheckVerify |
true |
TypeChecker-in-the-loop: drop any candidate annotation that would introduce a new diagnostic in the target file or its importers. First-run cost scales with observation count. |
recognizeBuiltinShapes |
true |
Rewrite a structural shape matching a built-in (Promise/Map/Set/Date/RegExp/Error) to the named ref. Disable for projects with classes that shadow built-ins. |
literal.* — preserve literal types instead of widening #
| Flag | Default | What it does |
|---|---|---|
literal. |
false |
Preserve string-literal types (e.g. "yes" | "no") up to stringMaxLength. |
literal. |
16 |
Max length of string literals to preserve. Ignored when string is false. |
literal. |
false |
Preserve number-literal types (42 instead of number). |
literal. |
false |
Preserve boolean-literal types (true/false individually). |
// Observed: greet always called with "hi" / "bye"; with infer.literal.string on
function greet(kind) {
return kind;
}function greet(kind: "hi" | "bye") {
return kind;
}With literal. off (the default), the same observations widen to
kind: string.
Literals are a two-sided switch. The runtime collector widens at observation time and never reads
ts-capture., soconfig. json literal.in the config file alone changes nothing:* types.still holdsjson string. Turn the same flags on for the run that observes, through theTS_CAPTURE_LITERAL_*environment variables or the@ts-capture/plugin'svite literalOptions, and ininfer.forliteral. * apply. One side without the other widens: the collector recordsstring, orapplycollapses the recorded"hi" | "bye"back tostring.
These flags put observed data in your source. A literal annotation is the value your code actually saw, copied verbatim into a
.file and intots types.— on a suite running against real fixtures that can be a token prefix, an e-mail address or a customer name. Enable them where the values are genuinely enumerable domain constants (json "asc" | "desc", status codes). See Observed values in your output.
patternDetection.* — recognize string shapes #
| Flag | Default | What it does |
|---|---|---|
patternDetection. |
false |
Detect ISO date strings and emit Date. |
patternDetection. |
false |
Detect UUID-shaped strings. |
patternDetection. |
false |
Detect URL-shaped strings. |
Output shaping #
| Flag | Default | What it does |
|---|---|---|
narrowOptional. |
true |
Prefer T | undefined over T | null when both are observed. |
emitDiagnosticComments |
false |
Emit / markers next to coarse/fallback annotations (generic-fn, shape-capped). |
maxAnnotationChars |
4096 |
Suppress an annotation whose final type string exceeds this cap (TS inference takes over for that position). |
emitConflictComments |
true |
Leave a note where the run observed null or undefined at a position whose type forbids it. The site gets no annotation — see Notes. |
outputMode |
"annotations" |
"annotations" writes the type. "comments" writes what it would write and changes no code. "both" writes the type with a note saying why. See Notes. |
narrowParamShapes |
false |
Write a parameter's object shape with only the properties the function body reads from it. The whole shape stays wherever the body passes the parameter on, returns it or stores it, and a shape that matches an in-scope type in full is written as that type. Opt in: it can give a caller an excess-property error, which typecheckVerify then rejects (why). |
aliasRepeatedShapes |
false |
Declare a shape that several annotations in one file spell out, once, after the imports, and write its name at each of them. The name comes from the first position holding the shape (product gives Product, an array products gives Product, a shape only held by a property is named after the property); a name the file already uses or has in scope is passed over for the next position's. Only shapes with at least two properties seen at least twice are declared, and only when an annotation naming the shape is written. A shape matching an in-scope type is written as that type, as before. Opt in: the declarations are new lines, and the names are guesses a reader may want to change. |
Notes #
Apply writes two kinds of comment, both marked so they can be told apart at a
glance and found with grep.
[conflict] — the run saw what the type forbids. The position gets no
annotation:
// @ts-capture[conflict]: `renderTemplate` observed `undefined`, TypeScript infers `string`
const renderTemplate = this.reflectRenderTemplate(callback);
That is from a real run against nestjs/nest. TypeScript believes the value is
always a string; the code produced undefined. Whether the fix is to widen the type or to stop
producing undefined is not something an observation can decide, so ts-capture
reports it and leaves the code alone. On by default, in every outputMode.
A conflict needs the project: what TypeScript infers comes from the checker,
so without a tsconfig. (see --project in the CLI reference)
no conflict is found. And only null or undefined counts. When the run also
saw a value of another kind outside the type, the position is not a conflict,
because comparing those needs more than the text of the types.
[proposal] and [applied] — what an annotation would be, or was. Turned
on with outputMode:
// @ts-capture[proposal]: `args` would be `number[]`
// @ts-capture: observed 374 times; TypeScript infers `any`
const args = Reflect.getOwnMetadata(OPTIONAL_DEPS_METADATA, target) || [];
"comments" is a preview in the editor, where --dry-run is one in the
terminal: read the proposals in place, against their neighbours, then run apply
for real. "both" writes the annotation and keeps only what the annotation
cannot say.
Where one line carries several notes they move to the positions they describe,
because a name cannot tell them apart — const a = (d) => (d) => (d) => null;
has three positions and one name between them:
const a =
(d: string /* @ts-capture[applied]: observed once */) =>
(d: number /* @ts-capture[applied]: observed once */) =>
null;
Apply owns every note #
Every whole line and every block comment carrying / or
/ belongs to apply, and each run removes the ones it finds
before writing the ones that hold now — including a note you wrote by hand.
Nothing checks a comment the way tsc checks an annotation, so a note left
behind would simply lie: about a conflict that has been fixed, or about code
that has since been deleted. Rewriting them every run is what keeps them true,
and the price is that the marker is the tool's, not yours.
@ts-capture-ignore is not affected. It is a directive you write, the
marker match stops short of it, and apply never removes it.
The count in a note — observed 374 times, observed once — is context for
you, not a verdict. A value seen once is as likely a config object read at
startup as one arbitrary caller's payload, and nothing in the number separates
those. A person can, by looking at where the value came from, which is why the
count is in the note and in no rule.
// skipRedundantAnnotations is on by default — TS already infers number here
let count = 0;// Left untouched: ts-capture does not add `: number` TS would infer anyway
let count = 0;apply.* #
| Flag | Default | What it does |
|---|---|---|
skipFiles |
test files (*., *.) |
Gitignore-style globs for files apply should skip. Additive on top of the built-in test default; last match wins; a leading ! re-includes. Supports *, **, ?, brace alternation. |
{
"apply": {
"skipFiles": ["src/**/*.{gen,generated}.ts", "!src/generated/keep.ts"]
}
}Environment variables #
The runtime collector is configured by env, not by ts-capture. —
it runs inside your process, before any config file is read. (The rows marked
read at build time are the exception: whatever instruments the code reads
them, so they must be set in that process.)
| Variable | Default | What it does |
|---|---|---|
TS_CAPTURE_TYPES_DIR |
os. |
Directory for the per-process ts-capture-types-<uuid>. dumps. Created if missing. |
TS_CAPTURE_OBSERVE_ANNOTATED |
unset | Read at build time, by every adapter: 1 or true also observes parameters and return types that already have a type, for verify to compare. apply never writes over them. |
TS_CAPTURE_ENABLED |
unset | @ts-capture/ only, read at build time: false switches the plugin off; the enabled option wins over it. |
TS_CAPTURE_LITERAL_STRING |
same as infer. |
Runtime equivalent of that flag. |
TS_CAPTURE_LITERAL_STRING_MAX_LENGTH |
same as infer. |
Runtime equivalent of that flag. |
TS_CAPTURE_LITERAL_NUMBER |
same as infer. |
Runtime equivalent of that flag. |
TS_CAPTURE_LITERAL_BOOLEAN |
same as infer. |
Runtime equivalent of that flag. |
TS_CAPTURE_MAX_ANNOTATION_CHARS |
same as infer. |
Cap on serialized type size. |
TS_CAPTURE_CAPTURE_CLASS_HIERARCHY |
false |
@ts-capture/ only: record class hierarchies (pairs with infer.). |
TS_CAPTURE_TRANSPORT_URL |
unset | @ts-capture/ only, read at build time: send browser observations to this URL instead of the dev server. |
Every example in these docs sets
TS_CAPTURE_TYPES_DIRexplicitly. If you don't, dumps land inos.and nothing cleans them up. See Observed values in your output for what a dump contains.tmpdir()