Xantham.Generator Namespace
| Type/Module | Description |
|
`audit-coverage`. |
|
|
Session bootstrap: locate the compiler, start a mailbox over the package directory, create a program over the package's declaration entry, and bind the session the whole run shares. |
|
|
|
|
|
`classify-literal-unions`. |
|
|
|
|
|
A finding union read once through reflection: prefix, tag reader and per-case tiers, cached per type. Reading is a dictionary hit and a tag read; the reflection happens once. |
|
|
A conditional type's mapping facts (§4.11). |
|
|
Everything a pass may reach for, created once per run by `Bootstrap.start`. Passes never create programs; the session here is the only wire access they have. |
|
|
A deterministic source-order key parsed from a declaration node handle (`index.kind.path`). The handle is otherwise opaque; only the file path and node index are read, and only for ordering output the way the author ordered source. |
|
|
`dedupe-overloads`. |
|
|
`detect-tagged-unions`. |
|
|
Group emission (O7): which groups a run writes as their own module, and what stops one. |
|
|
|
|
|
|
|
|
|
|
|
Where a harvested name came from, which is what decides how a *value* binds in JavaScript. Types are unaffected: an interface is the same F# declaration either way. |
|
|
The type ids an export resolves to. A symbol can be both a type and a value (a class), so the two are separate fields rather than one. |
|
|
|
|
|
One thing a pass had to say about a symbol: a widening, a drop, or an ergonomic rewrite. Findings are the raw material of the fidelity manifest - a silent drop is a bug by definition, so every non-Exact emission produces one of these. |
|
|
|
|
|
A type abbreviation: an exported alias whose right side is a reference, not a shape of its own (callback aliases to delegates, alias-of-alias, primitive aliases). |
|
|
An interface member. Overloads are consecutive `FsMethod` entries sharing a name -
overloaded abstract members are legal F#.
A construct signature of a *constructor object* - the thing `typeof Request` names, and the
type of a `declare var Request: { new (...): Request }` (§4.4). F# has no first-class
constructor-object type, so the object is declared as an interface of its own and each of
its construct signatures becomes an `[ |
|
|
|
|
|
What makes a declaration an F# *class* rather than an interface (§4.4): the import that binds the JavaScript constructor and the parameters a derived class passes to it. An F# interface admits no `inherit`, so a TypeScript class written to be derived from - an entrypoint an ambient module exports - reaches F# only in this form. |
|
|
A numeric TS enum as an F# enum - `type E = A = 1` (§4.7). |
|
|
What one *bound* member is - a member whose body is not F# but a reference into JavaScript, carried by an `ImportBinding`. Two kinds of declaration hold these: the `Exports` type, whose members are the module's value exports, and a class, whose statics live on the constructor object rather than on an instance. |
|
|
One bound member: an `Exports` member, or a class static. |
|
|
A TypeScript index signature rendered as F#: an `Item` member under `[ |
|
|
|
|
|
A literal payload carried by a StringEnum case (D12: mixed literal unions keep their
non-string members as `[ |
|
|
A unit of measure standing for a branding intersection (§4.6, D11). It has no body: a
measure is a name and nothing else, and the brand it marks is written at the *uses*, as
`string |
|
|
|
|
|
|
|
|
|
|
|
A declaration TypeScript *computes* and F# cannot reproduce: a mapped type, a conditional or a template literal at an operand the checker could not resolve (§4.10, §4.11). There is no structure to emit - the structure is a function of an argument not yet supplied - so the declaration is erased and keeps only its name and arity, which is enough for uses of it to stay distinct from each other and from `obj`. Its single case is private, so the only way in or out is a cast, which is exactly the guarantee the generator can honestly make. |
|
|
|
|
|
|
|
|
One case of a `[ |
|
|
One field of a tagged-union case. The name is the JS property key verbatim: Fable emits the field under its F# name, and backtick escaping is transparent there (`` ``type`` `` reaches JS as `type`), so no separate compiled name is needed. |
|
|
A discriminated union the checker proved is tagged (D4, §4.5(2)): every member is an object type carrying the same property, and that property's type is a distinct string literal in each. Fable erases the DU to a plain object literal, so this is Exact *and* pattern-matchable - by far the best consumer experience, which is why §4.5 says to detect it aggressively. |
|
|
A type parameter (§4.9), bound by a declaration or by a generic signature of its own. The constraint is carried only when F# can express it - a subtype constraint against another generated interface. TypeScript bounds that have no F# form (`extends string`, `extends keyof T`) are dropped with a finding rather than approximated, because a wrong constraint rejects correct code. |
|
|
The F# type written at a reference position. Phase B covers primitives, `option`, arrays, delegates (D5) and references to declarations this run generates; everything else widens to `FsObj` with a finding saying so. |
|
|
One case of a `[ |
|
|
|
|
|
Per-package generator configuration, read from `xantham.json` next to the package manifest when present (decision O4 in `docs/plans/generator-architecture.md`). |
|
|
What the generator does with one group's types (O7). `Inline` is decided but not yet built; it arrives with demand-driven resolution. |
|
|
|
|
|
Tier 1 - Harvest: the Wire-driven inventory of what the author exported. No mapping decisions live here; the tier's invariant is that every export of the entry module appears exactly once, aliases followed to their origin. |
|
|
One export of the entry module, aliases already followed to their origin so re-exports appear once under the name they are exported as. A global type library has no module to export from, and its ambient declarations arrive here too - see `ExportOrigin`. |
|
|
`harvest-globals`. |
|
|
|
|
|
What every finding union provides beyond its attributes: the human-readable message, which interpolates the case's payload and so cannot be an attribute. |
|
|
How a value export is bound to its JavaScript module. |
|
|
How a `K extends keyof T` variable is written in F# (§4.10, the open keyof regime). TypeScript's key variable has no F# counterpart of its own: a bare `'K` would be an unconstrained variable saying nothing about T's keys, and every use of it - including the `T[K]` it selects - would have to widen to obj. The support package carries the idiom instead, so `'K` is not bound at all; its uses are written as one of these. |
|
|
The F# destination of one mapped name (O7's `map`). |
|
|
Member and parameter shaping: `Shape.parametersOf` and `membersOf`. |
|
|
The naming contract (O7): the deterministic scheme mapping package identities to F# module names. Pinned, because a `reference` group's templated names must be exactly what a `ship` run of that group produces - independently generated packages have to agree on every name here. Renaming anything below is a breaking change to every shipped binding. |
|
|
The package boundary a symbol or type originates from, classified from its declaration's file path (decision O7). Resolution depth and reference rendering are decided per group. |
|
|
|
|
|
A nano-pass: one conceptual transformation over its tier's model, in the pipeline's uniform async shape whether it talks to the compiler or not. |
|
|
What a pass produced: the advanced model, or the model plus the findings that say where the pass fell short of Exact. |
|
|
The pipeline: per tier, a plain fold over that tier's pass list; between tiers, total transition functions (decision O1 - accumulating records, so reading an artifact that does not exist yet is a compile error, not a runtime one). Passes run strictly sequentially (decision O3); concurrency lives inside passes, where the mailbox batches it. |
|
|
The manifest key prefix of a finding union, and for a per-pass union the name of the pass it belongs to. Explicit rather than derived from the type name so a rename never moves a key. |
|
|
Tier 4 - Render: F# source text plus the fidelity manifest, from the shaped model alone. The printer is generator-owned (decision O2): no formatter dependency, golden stability over delegated style, and the compile gate absorbs the correctness risk. The tier's invariant is byte-identical output for an identical model - nothing here may consult the clock, the environment, or hash order. |
|
|
|
|
|
`repair-arity`. |
|
|
Tier 2 - Resolve: the type table. Breadth-first from the harvested exports' types, batched per generation frontier through the mailbox, memoized on `TypeResponse.Id`. The tier's invariant is closure: every type id a `TypeFacts` refers to is in the table or recorded in `NotFollowed` with its reason. |
|
|
One index signature (`[key: string]: V`) as the resolve tier records it. These are invisible to property enumeration - `getPropertiesOfType` returns nothing for a type whose only content is an index signature - so a type can carry these and no members at all, and the shape tier has to consult both before deciding a type has no shape worth declaring. |
|
|
A property or parameter, resolved: the symbol plus the derived facts every shape pass would otherwise re-ask the wire for. |
|
|
|
|
|
`resolve-export-types`. |
|
|
|
|
|
`resolve-type-table`. |
|
|
What a run reports back: where the fidelity manifest's numbers come from. |
|
|
`shape-aliases`. |
|
|
`shape-classes`. |
|
|
`shape-exports`. |
|
|
`shape-interfaces`. |
|
|
|
|
|
`shape-interfaces`. `synthesize-anonymous`. Wave two, lane A: the pass had no findings of its own, because until the `three` recon nothing had measured what it does to a shape that reaches itself - 518 declarations and 369,116 lines, stopped only by the depth cutoff. |
|
|
`synthesize-paramobjects`. |
|
|
How faithfully a generated construct represents its TypeScript source, per `docs/plans/generator-type-mapping.md` §1. Declaration order is severity order: a symbol's tier is the worst tier among its findings, and structural comparison on this type is that "worst". |
|
|
The tier a finding case carries. Applied through the four sealed subclasses below, so the choice is restricted to the `Tier` cases and never spelled as a string. |
|
|
|
|
|
|
|
|
A `TypeResponse` plus the derived facts of the kinds the skeleton resolves: object members, call signatures, union membership. Everything else stays on the raw response. |
|
|
Type parameter binding: `Shape.typeParamsOf`, `aliasTypeParams`, key variables and erasure. |
|
|
`Shape.typeRef` and the helpers under it: what happens to a type at a reference position. |
|
|
|