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 JSImportSpecifier(file, target string) (old, new string)
- func ModuleFile(importPath string) string
- type Diagnostic
- type Module
- type Options
- type Program
- func (p *Program) BoxOf(T types.Type) *boxInfo
- 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) CallBlocksIn(info *types.Info, call *ast.CallExpr, assume *types.Func) bool
- func (p *Program) CalledMethod(fn *types.Func) bool
- func (p *Program) DynMethod(fn *types.Func) bool
- func (p *Program) Facts() (digests map[*packages.Package][32]byte, ok bool)
- func (p *Program) HasClone(fn *types.Func) bool
- func (p *Program) ImportedEntry(path string) 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) PureEmitter(pkg *types.Package) *pkgEmitter
- func (p *Program) RangeBlocks(info *types.Info, s *ast.RangeStmt) bool
- func (p *Program) RangeBodyAsync(s *ast.RangeStmt) bool
- func (p *Program) RegexpJS() map[string]string
- func (p *Program) SetEntries(paths []string)
- func (p *Program) SortedDiags() []Diagnostic
- func (p *Program) SortedWarns() []Diagnostic
- func (p *Program) SyncClone(info *types.Info, call *ast.CallExpr, assume *types.Func) bool
- func (p *Program) SyncOnly(key any) bool
- func (p *Program) UnicodeClasses() 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" JSABIFile = "@goesm/runtime/jsabi.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 JSImportSpecifier ¶
JSImportSpecifier is the specifier a module written to file imports the file target with: generated modules import the JS and TS files of //goesm:import directives by absolute path, recorded in Module.Files, and internal/build makes them relative to where it writes the 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)
// Files are the JS and TS files the module imports for //goesm:import
// directives, by absolute path (see JSImportSpecifier).
Files []string
}
Module is the lowering result for one Go package.
type Options ¶
type Options struct {
// Entries are the import paths of the packages a build starts from
// (one for a program, several when one program serves several entry
// points, such as the components of an app). An entry's `func main`,
// if present, runs when its module is evaluated, and JavaScript calls
// its exported functions and methods.
Entries []string
}
Options control lowering.
type Program ¶
type Program struct {
Fset *token.FileSet
Pkgs []*packages.Package
// Entries are the paths of the packages a build starts from, whose
// exported functions and methods JavaScript calls (Options.Entries);
// see reach.go.
Entries map[string]bool
// 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 (*Program) BoxOf ¶
BoxOf is boxOf, cached. It depends only on DynMethod and CalledMethod of the methods of T, which Facts covers.
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) CallBlocksIn ¶
CallBlocksIn is CallBlocks for a call in the synchronous clone of assume (paramsync.go), or, for a nil assume, anywhere else.
func (*Program) CalledMethod ¶
CalledMethod reports whether method fn, listed in method tables (DynMethod), may be called through them: whether the program calls an interface method that it implements, and stores a type with the method in an interface value. A method left out has an entry without its function.
func (*Program) DynMethod ¶
DynMethod reports whether method fn (a method of a concrete type, possibly promoted) belongs in method tables.
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, SyncClone, and CallBlocksIn for the calls in clones). 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) ImportedEntry ¶
ImportedEntry reports whether the entry package path is also imported by another package of the program, as a component's package imports a package that JavaScript imports too. JavaScript calls the exported functions of an entry under their Go names, through wrappers that convert its values (exportWrapper); such an entry also exports the functions themselves, for the Go code importing it, as Name$go, and its exported methods as Type$Method$go (goMethodSuffix).
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) PureEmitter ¶
PureEmitter returns an emitter of the package pkg that only answers whether its functions return pure expressions (returnsPure), for the lowering of an importer of pkg.
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) RegexpJS ¶
RegexpJS returns the jsPattern entries of the patterns the program compiles, if it matches every regular expression with a RegExp (regexpjs.go), or nil.
func (*Program) SetEntries ¶
NewProgram analyses the loaded packages (dependencies first). std is the set of standard library packages. SetEntries sets the entry packages (Options.Entries).
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) SyncClone ¶
SyncClone reports whether call calls the synchronous clone of its function (see above). assume is the function whose clone the call is in, or nil.
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) UnicodeClasses ¶
UnicodeClasses reports whether the program may parse a regular expression with a Unicode class (\p or \P): whether reachable code outside regexp passes a pattern that is not a constant to one of patternFuncs, or one with \p or \P, refers to one without calling it, or reaches (*regexp.Regexp).UnmarshalText. regexp/syntax's unicodeTable is not lowered otherwise.
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).