Documentation
¶
Overview ¶
Package lower is goesm's semantic lowering: it walks the typed Go AST (syntax from go/parser, semantics from go/types, both run by the go toolchain via go/packages) and emits one TypeScript module per Go package. Go-specific semantics that JavaScript lacks are expressed as calls into @goesm/runtime. Go's type checker makes every typing decision; the TypeScript types only describe the result (CI checks them with tsc).
Index ¶
- Constants
- func EmbeddedFiles(fset *token.FileSet, pkg *packages.Package) ([]string, error)
- func ModuleFile(importPath string) string
- type Diagnostic
- type Module
- type Options
- type Program
- func (p *Program) CallAlwaysAsync(info *types.Info, call *ast.CallExpr) bool
- func (p *Program) CallBlocks(info *types.Info, call *ast.CallExpr) bool
- func (p *Program) Facts() (digests map[*packages.Package][32]byte, ok bool)
- func (p *Program) IsAsync(fn *types.Func) bool
- func (p *Program) LitAsync(lit *ast.FuncLit) bool
- func (p *Program) LowerAll(opts Options) []*Module
- func (p *Program) LowerPackage(pkg *packages.Package, opts Options) *Module
- func (p *Program) RangeBlocks(info *types.Info, s *ast.RangeStmt) bool
- func (p *Program) RangeBodyAsync(s *ast.RangeStmt) bool
- func (p *Program) SortedDiags() []Diagnostic
- func (p *Program) SortedWarns() []Diagnostic
- func (p *Program) SyncOnly(key any) bool
- func (p *Program) WaitLock(call *ast.CallExpr) (fn *types.Func, locker bool)
- func (p *Program) WaitLockVal(sel *ast.SelectorExpr) (fn *types.Func, locker bool)
Constants ¶
const ( RuntimeFile = "@goesm/runtime/index.ts" NativesFile = "@goesm/runtime/natives.ts" ProgramFile = "@goesm/runtime/program.ts" )
Layout of the generated TypeScript: the module of Go package p is the file p + ".ts" below the output root (example.com/app/cart.ts, strings.ts), and the runtime is @goesm/runtime/index.ts (natives: natives.ts) next to them. Modules import each other with relative specifiers ending in .ts, which TypeScript (allowImportingTsExtensions), Vite, Rolldown, esbuild and Bun resolve without configuration. A Go import path cannot start with "@", so the runtime never collides with a Go package.
const NoCheck = "// @ts-nocheck\n/* eslint-disable */\n"
NoCheck heads every generated module and runtime file: the code is type-checked by goesm's own tests (TestTSC), and a project's tsconfig (noUnusedLocals, noFallthroughCasesInSwitch, an ES2017 target that has no BigInt literals) or linter should not re-check it. Importers still see the modules' types.
Variables ¶
This section is empty.
Functions ¶
func EmbeddedFiles ¶
EmbeddedFiles returns the files the //go:embed directives of pkg embed, as absolute paths, sorted: the lowering reads them (internal/build hashes them into the cache key of the package's module).
func ModuleFile ¶
ModuleFile is the path of the module of a Go package below the root.
Types ¶
type Diagnostic ¶
Diagnostic is a lowering diagnostic at an original .go position. These are goesm limitations ("not yet supported"), never Go compile errors: the frontend has already accepted the program.
func (Diagnostic) String ¶
func (d Diagnostic) String() string
type Module ¶
type Module struct {
Path string // Go import path
TS string // TypeScript source including an inline source map
Map []byte // generated TS -> .go source map (also inlined in TS)
Native bool // false: nothing to emit (e.g. package unsafe)
}
Module is the lowering result for one Go package.
type Options ¶
type Options struct {
// Entry is the import path whose `func main`, if present, runs when the
// module is evaluated.
Entry string
}
Options control lowering.
type Program ¶
type Program struct {
Fset *token.FileSet
Pkgs []*packages.Package
// TracksGoroutines is set when the program uses goroutine-local storage
// (runtime.GetTraceContextFromGLS and friends): async functions then
// restore the running goroutine after every await.
TracksGoroutines bool
// Deps are the packages of third-party modules (see loader.Program).
// Like the standard library, their functions that goesm cannot lower
// become stubs that panic when called.
Deps map[*packages.Package]bool
Diags []Diagnostic
// Warns are standard library and dependency functions that were
// replaced by stubs that panic when called.
Warns []Diagnostic
// contains filtered or unexported fields
}
Program holds whole-program facts needed while lowering any one package.
func NewProgram ¶
func NewProgram(fset *token.FileSet, pkgs []*packages.Package, std map[*packages.Package]bool) *Program
NewProgram analyses the loaded packages (dependencies first). std is the set of standard library packages.
func (*Program) CallAlwaysAsync ¶
CallAlwaysAsync reports whether a call that may block is always of an async function, which returns a Promise: a call of a declared function or method, or a waiting lock. A call of a function value or an interface method may be of a function that is not async.
func (*Program) CallBlocks ¶
CallBlocks reports whether the call may block (and must be awaited).
func (*Program) Facts ¶
Facts returns, for every package, a digest of the whole-program facts that lowering it reads: what the blocking, address and linkname analyses decided about the functions, literals, range statements and variables the package declares, and the answers to the per-node questions the lowering asks the Program (CallBlocks, CallAlwaysAsync, RangeBlocks, WaitLock, WaitLockVal). The module of a package is fully determined by its own source, the source of the packages it depends on, these digests for itself and its dependencies, and the Program-wide switches; internal/build keys its cache on them. Positions in the digests are offsets within files, so editing one package does not change the digests of the others.
ok is false if a fact could not be attributed to a package, in which case nothing may be cached.
Every Program field that lowering reads must be covered here; TestFactsCoverProgram fails when lowering reads one that is not.
func (*Program) LowerPackage ¶
LowerPackage lowers one package of the program. LowerAll is LowerPackage for every package; lowering one package never depends on whether another was lowered, which lets internal/build reuse cached modules.
func (*Program) RangeBlocks ¶
RangeBlocks reports whether a range-over-func statement's call of its iterator may block (and must be awaited).
func (*Program) RangeBodyAsync ¶
RangeBodyAsync reports whether the body of a range-over-func loop (its yield function) may block.
func (*Program) SortedDiags ¶
func (p *Program) SortedDiags() []Diagnostic
SortedDiags returns diagnostics in position order.
func (*Program) SortedWarns ¶
func (p *Program) SortedWarns() []Diagnostic
SortedWarns returns warnings in position order.
func (*Program) SyncOnly ¶
SyncOnly reports whether a function (*types.Func) or literal is lowered as synchronous although it contains channel operations (see natives.Sync).
func (*Program) WaitLock ¶
WaitLock returns the waiting function to call instead of a Lock or RLock call, or nil. For a sync.Locker call it is lockerSlow, a method of a helper type whose receiver is unused, taking the Locker as its argument.
func (*Program) WaitLockVal ¶
WaitLockVal returns the waiting function a Lock method value or method expression value is bound to, or nil (see WaitLock).