class Chain<T>

Simple helper class for resolving "hierarchy chains".

A chain is a representation of a linear hierarchy; Every item can have at most one parent and one child. Upon addition, they will be resolved to a conclusive hierarchy chain, represented by an array.

The representation of an item can be anything, but needs to be consistent (generic class parameter T).

Chain<T>(): Chain<T>

No description.

add(item: T, parent: T): T[]

Add an item along with its parent. The algorithm will add them to a (potentially pre-existing) chain.

Returns The chain that the items were added onto. NOTE that these chains may be deleted in successive calls to `add()`! It is good practice to use a WeakSet or WeakMap when storing them somewhere.

get(): Set<T[]>

Get the set of all chains.

getChainFromItem(item: T): false | T[]

Find the chain (or false) from a given item.

class Controller

Handles JSON mutation, Lume environments, DOM parsing, etc.

Controller(config: Options = {}): Controller

No description.

cssDestFile?: string

See also Options.cssDestFile

nunjucksDirPath: string

local path to the folder containing all Nunjucks templates.

cssFilePath: string

local path to the trdoc CSS file.

envInit: undefined | (env: Environment) => void

See also Options.envInit

defaultEnv: undefined | Environment

A Environment created the potentially supplied Options.defaultJSON.

build(json?: object): string

Get the rendered HTML string from the supplied TypeDoc object or the configured default object if not supplied.

This will render the actual reference in a <main> and both the overview and the outline in an <aside>.

Parameters

• json: A TypeDoc JSON as JavaScript object.

See also Options.defaultJSON

buildMain(json?: object): string

Same as build, but only render the main part of the reference.

buildOverview(json?: object): string

Same as build, but only render the reference overview.

buildOutline(json?: object): string

Same as build, but only render the reference outline.

buildFromFileContent(content: string): string

Get the rendered HTML string from a TypeDoc JSON file.

Parameters

• content: The un-parsed content of the TypeDoc JSON file.

jsonPageLoader(content: string): object

Lume page loader, rendering the contents of the supplied TypeDoc JSON path.

Parameters

• content: The un-parsed content of the TypeDoc JSON file.

createEnvironment(json: object): Environment

Create an Environment with the supplied TypeDoc object as base. Calls envInit with the created environment for further customization.

Parameters

• json: The TypeDoc JSON as JavaScript object.

getEnv(json?: object): Environment

Get either a newly created Environment from the supplied TypeDoc object or return the default Environment if nothing is passed.

Parameters

• json: The TypeDoc JSON as JavaScript object.

Throws

Throws if nothing has been passed and no default Env exists.

class Environment

Handles the necessary operations needed for a template to be built. Significant fields:

• A TypeDoc object that is mutated in place to fit the template's needs.
• A new Nunjucks environment with all filters needed by the template

See also

• TypedocJSONMutator
• IndentationHandler

Environment(

json: object,
nunjucksDirPath: string

): Environment

No description.

visibility: {

private: boolean,
internal: boolean,
inherited: boolean

}

Controls the default visibility options (exposed through the checkboxes on the top right) of the resulting documentation front-end.

Default

{
  private: false,
  internal: false,
  inherited: false,
}

njk: any

A new Nunjucks environment that's used to compile the reference template.

md: any

A new Markdown-It environment that's used to render inline markdown via the "md" filter.

json: object

The supplied TypeDoc JSON as JavaScript object.

IMPORTANT: It is heavily mutated in place, so if you need to use the intact object after building a doc from it, you will need to make a deep copy.

mutator: TypedocJSONMutator

No description.

indentHandler: IndentationHandler

No description.

render(): string

See also Controller.build

renderMain(): string

See also Controller.buildMain

renderOverview(): string

See also Controller.buildOverview

renderOutline(): string

See also Controller.buildOutline

mutateJSON(): void

Call all predefined mutators. The order is important.

See also TypedocJSONMutator

addMandatoryFilters(): void

Add filters that are mandatory for the pre-defined Nunjucks templates to work.

resolveTarget(target: number): undefined | TypeDocDescriptor

Get the target descriptor for the specified ID.

class IndentationHandler

Contains methods to dynamically wrap & indent specific DOM elements (namely containers like arrays, objects, etc.) once they exceed a specified width.

See also indentLengthThreshold for a way to modify the tested length.

IndentationHandler(): IndentationHandler

No description.

indentLengthThreshold: number

Character length threshold dictating above which length a method should be broken up and indented.

indentAvoidThreshold: number

Character length threshold dictating when an indent should be avoided if its content is of up to this length.

static indentableBodies: string[]

Classes that should be indented. Is prioritized from top to bottom.

static independentBodies: string[]

Classes that don't depend on added breaks in between their child elements.

static collapsibleBodies: string[]

Classes that may be collapsed, e.g. the array in [{ index: 1 }]

addIndent(content: { val: string }): string

Add indent to the specified text content. The text content must be a valid, parsable HTML string.

static recursivelyIndentNode(

node: Node,
currentClass: string,
avoidThreshold: number,
lines: string[]

): undefined | true

No description.

static isBody(element: any): | boolean

Checks whether an element is indentable as per indentableBodies

static isIndependentBody(element: any): | boolean

Checks whether an element is independent as per independentBodies

static isCollapsibleBody(element: any): | boolean

Checks whether an element is collapsible as per collapsibleBodies

static addIndentationBreaks(parentElement: HTMLElement): void

Insert a <br> element between each of the supplied element's children.

static addIndentationWrapper(element: HTMLElement): void

Wrap the child content of the supplied element in an <div class=indent> tag.

static getBreakableLines(

input: string,
threshold: number

): string[]

Get a list of all lines that go over the line length threshold from an arbitrary string input.

static getModifiedHTMLString(input: string): string

Remove any newlines, insert newlines after <br> tags and compress whitespace.

This is done because the indenter uses newlines as markers to determine line breaks. The whitespace is compressed to prevent length inaccuracies.

static postProcessHTMLString(input: string): string

No description.

static modifyStringAndCreateElement(content: string): Node

No description.

static before(element: Node, insertedElem: Node): void

No description.

static after(element: Node, insertedElem: Node): void

No description.

static createElement(

type: string,
classes?: string

): HTMLElement

No description.

static createTextNode(content: string): TextNode

No description.

static children(element: HTMLElement): HTMLElement[]

Get all HTMLElement children.

static childElementCount(element: HTMLElement): number

No description.

static firstElementChild(element: HTMLElement): any

No description.

static lastElementChild(element: HTMLElement): any

No description.

class TypedocJSONMutator

Contains methods that mutate the typedoc JSON object.

TypedocJSONMutator(json: object): TypedocJSONMutator

No description.

json: object

No description.

targetByID: Map<number, TypeDocDescriptor>

Contains all TypeDocDescriptors indexed by their ID.

decrementingID: number

ID that can be used when registering new reflections. Is currently unused but might prove useful, who knows.

Remarks

It is your responsibility to decrement it after using it!

hierarchyChains: Chain<TypeDocDescriptor>

Contains all same-kind, same-hierarchy-level extends chains of all items.

Relies on sortByHierarchy in order to be filled.

replaceReflectionKind(): void

Convert every "kind" value (number/enum) to its actual string representation.

renameNamedParameters(newName: string = '_args'): void

Replace the default __namedParameters parameter name for rest parameters that had no name with a better one.

Remarks

ORDERING: Needs to be called after replaceReflectionKind.

markDeclarationsInternal(): void

Mark a declaration as internal by adding the flag _isInternal to it, iff all of its signatures are marked as @\internal.

orderTypeAliasToTop(): void

Order objects of kind "TypeAlias" to the top of a namespace's and module's children.

This is to ensure readability as a type alias does not have a definitive header in the Nunjucks template.

This would also be resolved automatically when TypeDoc's kind order setting is set to order type aliases on top.

Remarks

ORDERING: Needs to be called after replaceReflectionKind.

numberMultipleInternals(): void

Give every "<internal>" module a unique name by an incrementing ID so that they can be referenced without collision.

mergeSignatureDocs(): void

Order and merge multiple signatures in which only one signature carries a comment such that only the last signature carries the comment.

resolveDescriptors(): void

Extend every TypeDocDescriptor by helper properties and the actual object reference (as described in the interface).

The data is stored in targetByID, indexed by the object id.

addVariantFieldCollection(): void

Create a children collection for classes and interfaces that is keyed by children variants, additionally making a distinction between static and non-static items.

This is utilized when building the outline in order to group all such items by their variants without having to rely on TypeDoc's (user-customizable) ordering.

Remarks

ORDERING: Needs to be called after replaceReflectionKind.

sortByHierarchy(): void

Constructs hierarchy chains of all reflections that are of the same kind and have the same parent.

Then, every chain's items are deleted and re-added (speak: sorted) at the index of the first item to match their hierarchy.

Example

Initial reflection ordering:
C1 extends C4; C2 extends C6; C3; C4; C5 extends C6; C6
Constructed hierarchy chain(s):
[ C1, C4 ]
+----^
[ C2, C5, C6 ]
+---+----^
After re-ordering:
C1 extends C4; C4; C2 extends C6, C5 extends C6; C6; C3; C4

Remarks

ORDERING: Needs to be called after resolveDescriptors and orderExtendedBy (and thus, replaceReflectionKind)

See also

• Chain
• hierarchyChains

resolveInheritance(): void

Resolve the inheritance such that every item is mapped to its greatest parent or itself if it doesn't have a parent. The mapping is represented by targetByID.

This is done by collecting every "inheritance chain" over all objects. An inheritance chain is a representation of the linear child-parent hierachy.

Remarks

ORDERING: Needs to be called after resolveDescriptors

orderExtendedBy(): void

Replace the default extendedTypes hierarchy with one that's indexed by its target's kinds.

Before:

extendedTypes: [
  { target: 1 },
  { target: 2 },
  { target: 3 }
]

After (where target 1 and 3 are of kind "Class" and target 2 is of kind "Interface"):

extendedTypesCollection: {
  Class: [ { target: 1 }, { target: 3 } ]
  Interface: [ { target: 2 } ],
}

Remarks

ORDERING: Needs to be called after resolveInheritance and replaceReflectionKind.

See also https://typedoc.org/api/classes/Models.DeclarationReflection.html#extendedTypes

orderProjectChildren(): void

Replace the default project children hierarchy with one that's indexed by kinds.

Before:

children: [
  { kind: 256, id: 1 },
  { kind: 256, id: 2 },
  { kind: 128, id: 3 }
]

After (along with replaceReflectionKind, where 256 = "Interface" and 128 = "Class"):

childrenCollection: {
  Interface: [ { id: 1 }, { id: 2 } ],
  Class: [ { id: 3 } ]
}

Remarks

ORDERING: Needs to be called after replaceReflectionKind.

static getKeyCollection(

array: any[],
keyGetter: (child: object) => string

): Record<string, object[]>

Take an array and return an object of arrays.

Every array child is queried for an arbitrary (user defined) key string – Children with the same keys get collected in the same array which is the value of the key.

Parameters

• array: The array to be converted to a collection.

• keyGetter: The key query. Is called with every child – its return value is used as collection key.

See also orderProjectChildren and orderExtendedBy for examples of this!

static iterateJSON(

item: any,
callback: MutationIteratorCallback,
ignore: string[] = []

): void

Recursively iterate over an arbitrary object, calling the callback on all objects in order of appearance (no arrays)*.

*This assumes that the input is of JSON format, thus not containing arbitrary JS objects like Regexp.

Parameters

• item: Any object up for recursive iteration.

• callback: The function that is called with each iteration.

• ignore: Ignore a field from iteration.

  Think about adding a value here when you're adding one or
  multiple fields to an object.
  This helps prevent potential infinite loops and improves performance.
  

See also MutationIteratorResult for the passed object.