structured types #
Types come two ways. The flat strings (typeSignature, type, returnType) are the TypeScript checker's own rendering. Beside them, a TypeJson tree in typeInfo (returnTypeInfo for return types) gives the structure, for rendering types with links and highlighting.
typeInfo appears on variables, type aliases, variable members, component props,
parameters, and tuple elements; returnTypeInfo on functions, function members,
overloads, and callback props.
A returnPredicate's typeInfo and thisTypeInfo sit
beside their flat strings the same way. Types the output carries as source text have trees
too: a generic parameter's constraintInfo and defaultTypeInfo, a @throws entry's typeInfo, and a class's or interface's extendsInfo and implementsInfo. The heritage arrays hold one tree
per entry, whatever its shape, so they line up by index with extends and implements; the rest follow the rule below. Such a tree follows the written type:
a reference keeps its written type arguments and the name written (a callable alias included),
array syntax reads as an array of the written element, and a computed type
(keyof A, typeof a) is
a terminal node over its text, with no tree at all when it's the whole type. A union's members
and a tuple's elements follow the same rules, one by one.
When it's present #
A tree is absent when the flat string says everything: intrinsics, bare references, and object
and function types. It's present when it adds structure: union and intersection members, a
reference's type arguments, array elements, and tuple elements with their labels and ?/... markers.
A type alias's typeSignature prints only its name, so an alias carries its tree
whatever the shape, except object and function types, which its members cover.
Intrinsic and literal aliases (type A = string) print
structurally and get no tree.
Written annotations #
Where a position has a written annotation, the tree follows what was written, while the flat
string stays the checker's rendering. A reference keeps the name and type arguments written: x: Uuid reads as Uuid beside a flat string & Brand<"Uuid">, and a type argument equal to its
default isn't filled in. A computed type (keyof A, typeof a, A['b']) is
an other node over its source text, even as the whole type, since the flat string
prints what it computes to. A union's members and a tuple's elements follow their own written
types the same way (keyof A | null keeps keyof A), and an object or function type whose checker printing loses a name the
source wrote reads as the written type, even as the whole type: theme?: { theme: Theme } is { theme: Theme; } where the flat string expands Theme. A name the checker or the alias registry gives a computed type wins over
its source text, and a registry name over a written generic it stands for, so a renderer never
trades a linkable name for computed text.
A type alias's own declaration still documents its definition, a typeof over a
package's value keeps the checker's expansion, and a module-private alias's name gives way to
what it stands for, since nothing could link it.
Nodes #
The node kinds are intrinsic, literal, reference, array, tuple, union, intersection, function, object, and other.
- Union and intersection members keep alias names. Union members follow the order the author
wrote them, with
nullandundefinedlast, while the flat strings use TypeScript's internal order, so read the tree for author intent. A union with no written form (inferred,keyof, mapped) keeps TypeScript's order in both. - A literal's
valueis its runtime value, except that a bigint is its text ("1n") and a non-finite number a string ("Infinity"). - A named generic instantiation is a
referencewithtypeArgs(Snippet<[a: string]>), and other callables arefunctionnodes. Object literal and function types areobjectandfunctionnodes carrying the checker's text, or, where that loses a name the source wrote (an expanded lost alias), the written type printed on one line:{ theme: Theme; }. - Arrays and tuples carry
readonly, and the optional-propertyundefinedis dropped, sinceoptional: truesays it. Thetextof a terminal node drops it too, at every optional property, parameter, and tuple element inside ({ a?: string; }), so only the flat string printsa?: string | undefined.
Lost alias names #
TypeScript drops the name of an alias over an indexed access or conditional type, like type Foo = z.infer<typeof S> or valibot's InferOutput, and prints its expanded structure wherever it's used. The tree
recovers the name as {kind: "reference", name: "Foo"},
from the annotation written at that position or by matching the project's exported aliases. A
name recovered by matching also carries module, the ModuleJson.path declaring it, and wins over a written generic it stands for: a position written z.infer<typeof S> still reads as Foo.
A brand loses its name another way: a schema library's brand computes to the library's own
generic (fuz_schema's Branded<string, "Uuid">), which
the checker prints in place of Uuid. Matching recovers it the same way, so an
inferred position reads as Uuid beside the flat Branded<string, "Uuid">. Only the alias named by the
brand itself matches; another alias of the same brand doesn't take its uses.
An exported alias neither way recovers warns alias_lost (see diagnostics). Declaring it as an interface keeps its name: interface Foo extends z.infer<typeof S> {}, which
documents the inferred properties as its members.
Rendering #
typeJsonToTokens flattens a tree into tokens, deciding spacing,
separators, and parentheses, so a renderer only decides what each token looks like: link name tokens, highlight code tokens, and print text as-is. typeJsonToText joins them into a plain string.
import {typeJsonToTokens} from 'svelte-docinfo/declaration-helpers.js';
if (declaration.typeInfo) typeJsonToTokens(declaration.typeInfo);
// [{kind: 'name', name: 'Map'}, {kind: 'text', text: '<'},
// {kind: 'code', text: 'string'}, {kind: 'text', text: ', '},
// {kind: 'name', name: 'Tome'}, {kind: 'text', text: '>'}]Module paths #
TypeScript prints a module object as typeof import("…") with an absolute path. svelte-docinfo rewrites the path in every type text, flat and
structured: a module in the output becomes its ModuleJson.path, usable as a
lookup key, a package its path below node_modules/, and any other file a path
relative to the project root. In a tree, a module object is an other node.