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 null and undefined last, 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 value is 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 reference with typeArgs (Snippet<[a: string]>), and other callables are function nodes. Object literal and function types are object and function nodes 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-property undefined is dropped, since optional: true says it. The text of a terminal node drops it too, at every optional property, parameter, and tuple element inside ({ a?: string; }), so only the flat string prints a?: 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.