lower

package
v0.0.1-beta.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: BSD-3-Clause Imports: 21 Imported by: 0

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

View Source
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.

Variables

This section is empty.

Functions

func ModuleFile

func ModuleFile(importPath string) string

ModuleFile is the path of the module of a Go package below the root.

Types

type Diagnostic

type Diagnostic struct {
	Pos token.Position
	Msg string
}

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) CallBlocks

func (p *Program) CallBlocks(info *types.Info, call *ast.CallExpr) bool

CallBlocks reports whether the call may block (and must be awaited).

func (*Program) IsAsync

func (p *Program) IsAsync(fn *types.Func) bool

IsAsync reports whether the function declared by fn may block.

func (*Program) LitAsync

func (p *Program) LitAsync(lit *ast.FuncLit) bool

LitAsync reports whether a function literal may block.

func (*Program) LowerAll

func (p *Program) LowerAll(opts Options) []*Module

LowerAll lowers every package of the program, dependencies first.

func (*Program) RangeBlocks

func (p *Program) RangeBlocks(info *types.Info, s *ast.RangeStmt) bool

RangeBlocks reports whether a range-over-func statement's call of its iterator may block (and must be awaited).

func (*Program) RangeBodyAsync

func (p *Program) RangeBodyAsync(s *ast.RangeStmt) bool

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

func (p *Program) SyncOnly(key any) bool

SyncOnly reports whether a function (*types.Func) or literal is lowered as synchronous although it contains channel operations (see natives.Sync).

func (*Program) WaitLock

func (p *Program) WaitLock(call *ast.CallExpr) (fn *types.Func, locker bool)

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

func (p *Program) WaitLockVal(sel *ast.SelectorExpr) (fn *types.Func, locker bool)

WaitLockVal returns the waiting function a Lock method value or method expression value is bound to, or nil (see WaitLock).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL