Documentation
¶
Overview ¶
Package frontend turns TypeScript and modern JavaScript source into the JavaScript dialect the engine executes.
For the run path bento uses esbuild's single-file transform, which is pure Go and fast. It strips TypeScript types, lowers recent syntax to a stable target, and leaves module semantics intact. The heavier typescript-go frontend is used for type checking and for the ahead-of-time compile path, not here.
Index ¶
- Constants
- Variables
- func IsBentoAmbientPath(p string) bool
- type ConfigOverrides
- type Diagnostic
- type DiagnosticCategory
- type FileKind
- type FileSystem
- type ForClauses
- type ImportKind
- type LiteralKind
- type LiteralValue
- type LoadOptions
- type Node
- type NodeKind
- type Options
- type Param
- type Pos
- type Position
- type Program
- func (p *Program) Aliased(s Symbol) Symbol
- func (p *Program) Children(n Node) []Node
- func (p *Program) Declarations(s Symbol) []Node
- func (p *Program) DeclaredTypeAt(n Node) (declared, narrowed Type, ok bool)
- func (p *Program) Diagnostics() []Diagnostic
- func (p *Program) ElementType(t Type) (Type, bool)
- func (p *Program) ForClauses(n Node) ForClauses
- func (p *Program) Imports(f SourceFile) []ResolvedImport
- func (p *Program) IntersectionMembers(t Type) []Type
- func (p *Program) IsModule(f SourceFile) bool
- func (p *Program) LineColumn(f SourceFile, at Pos) Position
- func (p *Program) LiteralValue(t Type) (LiteralValue, bool)
- func (p *Program) ModuleEarlyErrors() []string
- func (p *Program) NumberIndexType(t Type) (Type, bool)
- func (p *Program) Properties(t Type) []Property
- func (p *Program) Revision() string
- func (p *Program) ShorthandValueSymbolAt(n Node) (Symbol, bool)
- func (p *Program) SignatureAt(n Node) (Signature, bool)
- func (p *Program) Signatures(t Type) (call, construct []Signature)
- func (p *Program) SourceFiles() []Node
- func (p *Program) StringIndexType(t Type) (Type, bool)
- func (p *Program) SymbolAt(n Node) (Symbol, bool)
- func (p *Program) Text(n Node) string
- func (p *Program) TupleElements(t Type) ([]TupleElem, bool)
- func (p *Program) TypeArguments(t Type) []Type
- func (p *Program) TypeAt(n Node) Type
- func (p *Program) TypeOfSymbol(s Symbol) Type
- func (p *Program) TypeSymbol(t Type) (Symbol, bool)
- func (p *Program) UnionMembers(t Type) []Type
- func (p *Program) Widen(t Type) Type
- type Property
- type ResolvedImport
- type Result
- type Signature
- type SourceFile
- type Span
- type Symbol
- type SymbolFlags
- type TupleElem
- type Type
- type TypeFlags
Constants ¶
const ( TypeAny = adapter.TypeAny TypeUnknown = adapter.TypeUnknown TypeNever = adapter.TypeNever TypeVoid = adapter.TypeVoid TypeUndefined = adapter.TypeUndefined TypeNull = adapter.TypeNull TypeBoolean = adapter.TypeBoolean TypeNumber = adapter.TypeNumber TypeBigInt = adapter.TypeBigInt TypeString = adapter.TypeString TypeSymbol = adapter.TypeSymbol TypeLiteral = adapter.TypeLiteral TypeObject = adapter.TypeObject TypeUnion = adapter.TypeUnion TypeIntersection = adapter.TypeIntersection TypeTypeParameter = adapter.TypeTypeParameter TypeEnum = adapter.TypeEnum TypeNonPrimitive = adapter.TypeNonPrimitive )
TypeFlags values.
const ( NodeUnknown = adapter.NodeUnknown NodeSourceFile = adapter.NodeSourceFile NodeFunctionDeclaration = adapter.NodeFunctionDeclaration NodeFunctionExpression = adapter.NodeFunctionExpression NodeArrowFunction = adapter.NodeArrowFunction NodeMethodDeclaration = adapter.NodeMethodDeclaration NodeGetAccessor = adapter.NodeGetAccessor NodeSetAccessor = adapter.NodeSetAccessor NodeConstructor = adapter.NodeConstructor NodeClassDeclaration = adapter.NodeClassDeclaration NodeInterfaceDeclaration = adapter.NodeInterfaceDeclaration NodeTypeAliasDeclaration = adapter.NodeTypeAliasDeclaration NodeEnumDeclaration = adapter.NodeEnumDeclaration NodeVariableStatement = adapter.NodeVariableStatement NodeVariableDeclaration = adapter.NodeVariableDeclaration NodeParameter = adapter.NodeParameter NodePropertyDeclaration = adapter.NodePropertyDeclaration NodeBlock = adapter.NodeBlock NodeReturnStatement = adapter.NodeReturnStatement NodeIfStatement = adapter.NodeIfStatement NodeForStatement = adapter.NodeForStatement NodeForOfStatement = adapter.NodeForOfStatement NodeForInStatement = adapter.NodeForInStatement NodeWhileStatement = adapter.NodeWhileStatement NodeSwitchStatement = adapter.NodeSwitchStatement NodeTryStatement = adapter.NodeTryStatement NodeThrowStatement = adapter.NodeThrowStatement NodeExpressionStatement = adapter.NodeExpressionStatement NodeIdentifier = adapter.NodeIdentifier NodeCallExpression = adapter.NodeCallExpression NodeNewExpression = adapter.NodeNewExpression NodePropertyAccessExpression = adapter.NodePropertyAccessExpression NodeElementAccessExpression = adapter.NodeElementAccessExpression NodeBinaryExpression = adapter.NodeBinaryExpression NodePrefixUnaryExpression = adapter.NodePrefixUnaryExpression NodePostfixUnaryExpression = adapter.NodePostfixUnaryExpression NodeConditionalExpression = adapter.NodeConditionalExpression NodeTemplateExpression = adapter.NodeTemplateExpression NodeTaggedTemplateExpression = adapter.NodeTaggedTemplateExpression NodeObjectLiteralExpression = adapter.NodeObjectLiteralExpression NodeArrayLiteralExpression = adapter.NodeArrayLiteralExpression NodeAwaitExpression = adapter.NodeAwaitExpression NodeYieldExpression = adapter.NodeYieldExpression NodeSpreadElement = adapter.NodeSpreadElement NodeParenthesizedExpression = adapter.NodeParenthesizedExpression NodeAsExpression = adapter.NodeAsExpression NodeTypeAssertion = adapter.NodeTypeAssertion NodeNonNull = adapter.NodeNonNull // Literals and keyword-valued expressions. NodeNumericLiteral = adapter.NodeNumericLiteral NodeStringLiteral = adapter.NodeStringLiteral NodeBigIntLiteral = adapter.NodeBigIntLiteral NodeNoSubstitutionTemplateLiteral = adapter.NodeNoSubstitutionTemplateLiteral NodeTrueKeyword = adapter.NodeTrueKeyword NodeFalseKeyword = adapter.NodeFalseKeyword NodeNullKeyword = adapter.NodeNullKeyword // Class-body keywords. NodeThisKeyword = adapter.NodeThisKeyword NodeSuperKeyword = adapter.NodeSuperKeyword NodeWithStatement = adapter.NodeWithStatement )
NodeKind values. The full set lives in the adapter package; these are the kinds the partitioner and lowering branch on today, aliased so a consumer names frontend.NodeFunctionDeclaration.
const ( SymbolVariable = adapter.SymbolVariable SymbolFunction = adapter.SymbolFunction SymbolClass = adapter.SymbolClass SymbolInterface = adapter.SymbolInterface SymbolTypeAlias = adapter.SymbolTypeAlias SymbolEnum = adapter.SymbolEnum SymbolNamespace = adapter.SymbolNamespace SymbolMethod = adapter.SymbolMethod SymbolProperty = adapter.SymbolProperty SymbolAlias = adapter.SymbolAlias )
SymbolFlags values.
const ( FileTS = adapter.FileTS FileTSX = adapter.FileTSX FileJS = adapter.FileJS FileJSX = adapter.FileJSX FileDTS = adapter.FileDTS FileJSON = adapter.FileJSON )
FileKind values.
const ( ImportRelative = adapter.ImportRelative ImportBare = adapter.ImportBare ImportNode = adapter.ImportNode ImportGo = adapter.ImportGo ImportJSON = adapter.ImportJSON ImportAsset = adapter.ImportAsset )
ImportKind values.
const ( CategoryError = adapter.CategoryError CategoryWarning = adapter.CategoryWarning CategorySuggestion = adapter.CategorySuggestion CategoryMessage = adapter.CategoryMessage )
DiagnosticCategory values.
const ( LiteralNone = adapter.LiteralNone LiteralString = adapter.LiteralString LiteralNumber = adapter.LiteralNumber LiteralBoolean = adapter.LiteralBoolean LiteralBigInt = adapter.LiteralBigInt )
LiteralKind values.
Variables ¶
var ErrNoRoots = errors.New(
"frontend: Load requires at least one root file (tsconfig include discovery is a later slice)")
ErrNoRoots reports that Load was called with no entry files. tsconfig include discovery, which fills the root set from the project when none is given, is a later slice; until then a caller names its roots explicitly.
"frontend: real typescript-go adapter unavailable (no fork revision pinned); " +
"use frontend.Wrap with a supplied adapter")
ErrRealAdapterUnavailable reports that no real typescript-go-backed checker can be constructed in this build. It is a defensive guard only: bento consumes typescript-go through the tamnd/typescript fork, whose public shim exposes the checker, so the real adapter is always available and RealAdapterAvailable returns true (see pkg/frontend/adapter/version.go). The error remains so a build that somehow dropped the pin fails loudly rather than nil-crashing.
var ErrTopLevelAwait = errors.New("top-level await requires the ES module format")
ErrTopLevelAwait reports that a source uses top-level await, which cannot be represented in the CommonJS output format. The runtime catches this and runs the module through the native ES module path instead, where top-level await is legal. It is returned by Transpile, wrapped, so callers test with errors.Is.
Functions ¶
func IsBentoAmbientPath ¶
IsBentoAmbientPath reports whether a declaration's file is the synthetic library bento writes itself, as opposed to the TypeScript standard library the checker bundles. Both are .d.ts files, so a consumer that has to tell a global bento declares (process, module, require) from one it merely inherits (name, parseInt, Symbol) asks this rather than reading the path.
Types ¶
type ConfigOverrides ¶
type ConfigOverrides struct {
Strict *bool
NoImplicitAny *bool
SkipLibCheck *bool
AllowJS *bool
CheckJS *bool
AllowUnreachableCode *bool
ImportHelpers *bool
Target string
Paths map[string][]string
}
ConfigOverrides are compiler-option overrides applied on top of the resolved tsconfig. Zero-valued fields leave the tsconfig value in place.
type Diagnostic ¶
type Diagnostic struct {
Code int
Category DiagnosticCategory
Message string
File *SourceFile
Span Span
Related []Diagnostic
}
Diagnostic is a checker or parser diagnostic, passed through from typescript-go without rewording so bento errors match tsc byte for byte.
type DiagnosticCategory ¶
type DiagnosticCategory = adapter.DiagnosticCategory
Classification enum aliases. The underlying values live in the adapter package.
type FileSystem ¶
type FileSystem interface {
ReadFile(path string) (string, bool)
FileExists(path string) bool
DirectoryExists(path string) bool
}
FileSystem replaces the real file system for a load. A nil FileSystem reads through the OS. Tests and the bundler feed virtual modules through it.
type ForClauses ¶
ForClauses is a for statement's four parts read by role. Body is always present. Init, Cond, and Incr each carry a node only when the source wrote that clause, reported by the matching HasInit, HasCond, HasIncr flag, so a caller lowers for(;;), for(let i=0;;i++), and every other shape without guessing which clauses a bare child list dropped.
type ImportKind ¶
type ImportKind = adapter.ImportKind
Classification enum aliases. The underlying values live in the adapter package.
type LiteralKind ¶
type LiteralKind = adapter.LiteralKind
Classification enum aliases. The underlying values live in the adapter package.
type LiteralValue ¶
type LiteralValue = adapter.LiteralValue
Classification enum aliases. The underlying values live in the adapter package.
type LoadOptions ¶
type LoadOptions struct {
// Dir is the project root; tsconfig discovery starts here.
Dir string
// ConfigPath, if set, names a tsconfig explicitly and skips discovery.
ConfigPath string
// Roots are entry files; if empty they come from the tsconfig include set.
Roots []string
// Overrides are compiler-option overrides applied on top of the tsconfig.
Overrides ConfigOverrides
// FS, if non-nil, replaces the real file system.
FS FileSystem
}
LoadOptions controls how a typed program is loaded. It mirrors the parts of a tsconfig bento honors, plus bento-specific knobs. It is named LoadOptions rather than Options because the transpile path already owns frontend.Options.
type Node ¶
type Node interface {
Kind() NodeKind
Pos() Pos
End() Pos
File() SourceFile
}
Node is an opaque handle to an AST node. Consumers ask the Program about it rather than reading its fields, so the concrete typescript-go node shape stays behind the adapter.
type Options ¶
type Options struct {
// Filename is the original path, used for diagnostics and loader detection.
Filename string
// SourceMap requests an inline source map appended to Code.
SourceMap bool
}
Options controls a transpile.
type Position ¶
Position is a resolved line and column: 1-based line, 0-based column, the convention tsc uses so bento diagnostics line up with it.
type Program ¶
type Program struct {
// contains filtered or unexported fields
}
Program is bento's typed-program handle. It wraps an adapter.TSAdapter and an opaque program handle, and turns the adapter's handle-returning calls into the value-returning queries the partitioner and lowering consume. The interners map opaque type and symbol handles to small integer ids, so a bento Type or Symbol carries an id, never a typescript-go object, and the program looks the handle back up when a follow-up structural query comes in.
func Load ¶
func Load(opts LoadOptions) (*Program, error)
Load discovers or reads the tsconfig, constructs the compiler host, builds the typescript-go program, runs the binder, and wraps the result in a bento Program. It does not force a full type check; the checker runs lazily on first query.
It returns ErrRealAdapterUnavailable while the real adapter is blocked upstream. The wiring above it (tsconfig resolution, host construction, root discovery) is stable and lands in follow-up slices; the one missing piece is the adapter.TSAdapter implementation, which is why the failure is a single clear error rather than a panic.
func Wrap ¶
func Wrap(a adapter.TSAdapter, h adapter.ProgramHandle) *Program
Wrap builds a Program over a given adapter and program handle. Load uses it with the real adapter, the only implementation; taking an interface keeps the typescript-go coupling behind the adapter package rather than leaking it here. It is the single constructor for a Program so the interners are always initialized.
func (*Program) Aliased ¶
Aliased follows an import or export alias to the symbol it ultimately names.
func (*Program) Children ¶
Children returns the direct child nodes of a node, so a consumer can walk a body without ever touching a typescript-go node.
func (*Program) Declarations ¶
Declarations returns the declaration nodes for a symbol; a symbol can have several, for overloads or merged interfaces.
func (*Program) DeclaredTypeAt ¶
DeclaredTypeAt returns the un-narrowed declared type of the variable used at n alongside the narrowed type from TypeAt, so the partitioner can tell when a branch relies on narrowing.
func (*Program) Diagnostics ¶
func (p *Program) Diagnostics() []Diagnostic
Diagnostics returns all syntactic and semantic diagnostics for the program, passed through from the checker so bento output matches tsc.
func (*Program) ElementType ¶
ElementType returns the element type of an array or tuple type, and ok=false for a non-array.
func (*Program) ForClauses ¶
func (p *Program) ForClauses(n Node) ForClauses
ForClauses returns a for statement's initializer, condition, incrementor, and body by role, with a flag for each of the three optional header clauses. It reads roles straight off the node, so an omitted clause is reported as absent rather than silently collapsing onto another role the way a bare child walk would. The node must be a for statement.
func (*Program) Imports ¶
func (p *Program) Imports(f SourceFile) []ResolvedImport
Imports returns the resolved imports of a source file, each mapping a written specifier to the file it resolved to and the kind of import it is.
func (*Program) IntersectionMembers ¶
IntersectionMembers returns the constituent types of an intersection, or a single-element slice for a non-intersection. It is how the lowerer sees through a branded alias (number & { __brand }) to the underlying primitive a go: defined type projects to (section 6.11).
func (*Program) IsModule ¶
func (p *Program) IsModule(f SourceFile) bool
IsModule reports whether a source file is an ECMAScript module rather than a script. Imports does not answer this: a JavaScript file's edges include its require calls, so a CommonJS script has imports and is still a script. The difference decides whether the file is strict-mode source, and with it whether the legacy forms Annex B keeps for sloppy scripts are legal in it.
func (*Program) LineColumn ¶
func (p *Program) LineColumn(f SourceFile, at Pos) Position
LineColumn resolves a byte offset in a file to a Position.
func (*Program) LiteralValue ¶
func (p *Program) LiteralValue(t Type) (LiteralValue, bool)
LiteralValue returns the literal value of a literal type, so lowering can fold closed unions into integer tags and refine integers. The no-answer zero Type, which is what an error-typed node like a computed key over an unresolved symbol answers with, has no literal and no handle to resolve, so folding it declines.
func (*Program) ModuleEarlyErrors ¶
ModuleEarlyErrors returns the static-semantics early errors the program's import declarations carry that the checker does not surface, each a human-readable message. An AOT build rejects a module that carries one rather than reach the lowerer and hand it back, matching the SyntaxError an engine throws before running the module.
func (*Program) NumberIndexType ¶
NumberIndexType returns the value type of a type's numeric index signature, the element union the checker gives an array or tuple viewed as an array, and ok=false for a type with no numeric indexer. Unlike ElementType it answers for a tuple, so lowering can materialize a tuple as a value.Array when an array method is borrowed on it.
func (*Program) Properties ¶
Properties returns the named members of an object type, each with its own type and optionality.
func (*Program) Revision ¶
Revision reports the pinned typescript-go revision the backing adapter was built against, empty for the fake or a not-yet-pinned real adapter.
func (*Program) ShorthandValueSymbolAt ¶
ShorthandValueSymbolAt returns the local binding an object-literal shorthand member reads, so the use walk can credit `{ x }` to the outer `x` rather than to the property the shorthand declares. It reports false for a node that is not a shorthand member.
func (*Program) SignatureAt ¶
SignatureAt returns the signature the checker resolved for a specific call, new expression, or function declaration node, after overload resolution.
func (*Program) Signatures ¶
Signatures returns the call signatures and construct signatures of a function type separately, because lowering emits a Go func for the former and a constructor for the latter.
func (*Program) SourceFiles ¶
SourceFiles returns the top-level node of each file, the roots a consumer walks to enumerate declarations. The synthetic ambient library bento injects (its Node global declarations) is filtered out here, so it is invisible to every consumer the way lib.d.ts is: it supplies globals to the checker but is not a file the program lists, lowers, or reports on.
func (*Program) StringIndexType ¶
StringIndexType returns the value type of a type's string index signature, the string in { [x: string]: string }, and ok=false for a type with no string indexer. It lets lowering tell a dictionary shape from a fixed one so an index-signature object lowers to a dynamic bag rather than a struct that would drop the signature.
func (*Program) SymbolAt ¶
SymbolAt returns the symbol a name node resolves to, and ok=false for a node that resolves to no symbol.
func (*Program) Text ¶
Text returns n's own source text with no leading trivia, the identifier name, literal, or operator token lowering emits into the generated Go.
func (*Program) TupleElements ¶
TupleElements returns the positional elements of a tuple type, the [K, V] in a [string, number], and false for a non-tuple. Each element carries its element type, whether the position is optional or the rest tail, and its label, so lowering can spell the positional struct the tuple maps to. This is the query that separates a tuple from the array ElementType reports on: an array has one element type for every index, a tuple has a fixed sequence of them.
func (*Program) TypeArguments ¶
TypeArguments returns the instantiated type arguments of a generic type, the [T] in a Generator<T> or a Map<K, V>. It reads the element type off a built-in generic whose members the structural queries do not expand, so lowering can spell the Go representation the generic maps to. A non-generic type returns no arguments.
func (*Program) TypeAt ¶
TypeAt returns the type of the expression at n, with flow narrowing applied at n's exact position. This is the query the partitioner runs on every parameter, local, and return, and the query lowering runs on every expression.
func (*Program) TypeOfSymbol ¶
TypeOfSymbol returns the declared type of a symbol at its declaration.
func (*Program) TypeSymbol ¶
TypeSymbol returns the symbol a type was declared by, and ok=false for an anonymous type. Lowering uses it to walk from a class instance type back to the class declaration that names it.
func (*Program) UnionMembers ¶
UnionMembers returns the constituent types of a union, or a single-element slice for a non-union.
type Property ¶
type Property struct {
Name string
Type Type
Optional bool
Readonly bool
// WriteType is the type a write to the member accepts. It equals Type for a
// plain property and widens to the setter type for a divergent accessor.
WriteType Type
// DivergentAccessor is true when the member is a get/set accessor pair whose
// write type differs from its read type.
DivergentAccessor bool
}
Property is one member of an object type.
type ResolvedImport ¶
type ResolvedImport struct {
Specifier string
Resolved SourceFile
Kind ImportKind
}
ResolvedImport is one edge in the module graph.
type Result ¶
type Result struct {
// Code is the emitted JavaScript.
Code string
// SourceMap is the inline or external source map, empty when disabled.
SourceMap string
}
Result is the outcome of transpiling one source file.
func Transpile ¶
Transpile converts one TypeScript or JavaScript file to CommonJS JavaScript targeting a stable syntax level the engine supports. The loader is chosen from the file extension so .ts, .tsx, .jsx, .mts, and .cts all work.
func TranspileESM ¶
TranspileESM converts one TypeScript or JavaScript file to ES module output, preserving import and export statements and top-level await so the engine can link and run it natively. It is the path for modules the CommonJS format cannot express.
type Signature ¶
Signature is bento's view of a call or construct signature. Lowering reads it to emit a Go function signature; the partitioner reads it to decide whether every parameter and the return are lowerable.
type SourceFile ¶
SourceFile identifies a file in the program and lets consumers turn offsets into human positions for diagnostics and source maps.
type Symbol ¶
type Symbol struct {
Name string
Flags SymbolFlags
// contains filtered or unexported fields
}
Symbol is bento's view of a bound declaration. Identity is by the opaque id, so two Symbol values name the same symbol when their ids are equal.
type SymbolFlags ¶
type SymbolFlags = adapter.SymbolFlags
Classification enum aliases. The underlying values live in the adapter package.
type TupleElem ¶
TupleElem is one positional element of a tuple type: its element type, whether the position is optional or the rest tail, and its label when the source named it. Lowering reads the slice to spell the positional struct a tuple maps to.
type Type ¶
type Type struct {
Flags TypeFlags
// contains filtered or unexported fields
}
Type is bento's view of a TypeScript type: a small handle carrying the coarse flags eagerly, with structural detail fetched through Program methods so the typescript-go type object never crosses the adapter boundary.
func (Type) Identity ¶
Identity returns a small integer stable within one Program that is equal for two Type values naming the same underlying type. It is enough to break cycles when a consumer walks a recursive type (an object whose field type refers back to itself) without exposing the typescript-go type object. Two Type values from different programs may share an id, so use it only within one program's traversal.