# Comparison with GopherJS

GopherJS is the most mature Go→JavaScript implementation and the main reference. goesm is not a GopherJS clone. By emitting ESM-ready TypeScript that any bundler (Vite, Rolldown, esbuild; `goesm build` uses esbuild) or TypeScript-aware runtime consumes, it hands off what GopherJS implements itself and simplifies the rest with modern JS primitives.

The GopherJS column summarises its upstream README and compatibility documents and the design of its compiler and prelude (master as of 2026-10; each GopherJS release targets one Go release, currently the Go 1.21 line).

| aspect | GopherJS | goesm (PoC) | simplified / changed in goesm |
|---|---|---|---|
| package loading | its own build package (based on go/build, with module support); the stdlib is loaded together with the natives overlay | fully delegated to `golang.org/x/tools/go/packages` (the go command resolves modules / go.work / GOPROXY); the replaced stdlib packages are substituted while go/packages parses them (`ParseFile`) | no module or build resolution code |
| Go version | each release supports one Go version (natives depend on the stdlib version) | goesm does not pin a version: go/types from the toolchain that built goesm is the frontend (`go tool goesm` follows the module's toolchain). Go 1.27 generic methods pass | new syntax is accepted as soon as go/types accepts it; only lowering cases need adding. The Go-source replacements (`runtime`, `internal/reflectlite`, `sync`) only follow the API the rest of the stdlib uses, not its internals |
| AST / type info | generates JS directly from go/ast + go/types (own analyses: blocking, escape, ...) | also lowers the typed AST directly (no SSA; see ARCHITECTURE.md §4) | the output is TypeScript, not JS: no JS printer, minifier or bundler |
| output format | one script (its own `$packages` registry), its own dead code elimination | one Go package = one TypeScript ES module (`<import path>.ts`) importing the others with relative `.ts` specifiers; `goesm build` bundles them with esbuild, or emits one ESM per package with `-split` | ESM, tree shaking, code splitting, minification and target lowering are the host bundler's |
| integers | `int` is 32-bit (emulates a 32-bit platform); `int64`/`uint64` are exact as high/low pairs | `int` is 64-bit as in Go's wasm type checking but a JS number (exact below 2^53, no 64-bit wrap-around); 8–32-bit are exact; `int64`/`uint64` are exact BigInts | `int` is faster than GopherJS' pairs but inexact above 2^53; `int64` is exact either way ([bench/](https://github.com/goesm-dev/goesm/tree/v0.0.1-beta.9/bench) measures both) |
| strings | JS strings treated as byte sequences | the same (one code unit = one byte) | — |
| maps | runtime `$keyFor` turns keys into strings and stores `{k, v}` in a JS object | JS `Map` + hash keys from type descriptors (primitives are used as keys directly; structs / interfaces / NaN are serialised for Go equality) | primitive keys need no stringification |
| pointers | non-struct pointers are objects with getter / setter closures; a struct pointer is the struct object | nearly the same idea: `.v` accessor Cell / FieldPtr / IndexPtr, structs / arrays are the object itself, identity guaranteed by a cache kept on the object | creation goes through a few runtime functions (replaceable for future unsafe) |
| interfaces | non-struct values are wrapped in `T.wrapped`; structs get their dynamic type from the constructor; methods live on JS prototypes | an object with `t` (dynamic type descriptor) and `v` (value). Types with methods called through interfaces have box classes whose prototypes hold the methods; a boxed struct value, and a pointer to a struct, are struct objects themselves. Other values are `Iface{t, v}`, dispatched through the descriptor's method table | the dynamic type is always explicit (`MyInt(1)` and `int(1)` differ), and calls resolve per hidden class as JS class methods do |
| goroutines | functions marked by blocking analysis become resumable state machines (a `$s` switch and saved frames) resumed by its own scheduler | functions marked by a similar blocking analysis become **`async function`s** with `await` at blocking points; goroutines start as microtasks | no state machine generation or stack saving; the JS engine's async stack traces work as is; neither preempts |
| channels | runtime send / recv queues and `$select` | runtime wait queues; immediate completion is synchronous, a Promise only when blocking | blocking semantics stay at the runtime boundary while Promises express suspension |
| defer / panic / recover | per-goroutine defer stack and panic state in the runtime, tied into the state machine | a `Defers` frame per function with JS `try/catch/finally` + a labelled `break` | named result updates and defers after return are expressed with JS control flow; goroutine-local recover state is not implemented |
| reflect | reflect implemented in natives; detailed metadata on type objects | type descriptors (kind, fields, tags, method sets, type arguments) are always emitted; `reflect` and `internal/reflectlite` are replaced by Go source over them (enough for `fmt` and `encoding/json`) | reflect is ordinary Go source over the descriptors, not hand-written natives |
| runtime | a large hand-written JS prelude + natives replacing stdlib code | a small TS runtime (`@goesm/runtime`, emitted as `@goesm/runtime/*.ts` next to the package modules, only what the fixtures need); `runtime`, `internal/reflectlite` and `sync` are replaced by Go source; functions without a Go body are natives, one ES export each | the runtime and the natives are tree-shaken by the bundler too |
| source maps | its own JS printer emits JS→Go maps directly | goesm only builds TS→Go maps; in `goesm build` esbuild composes them into JS→Go (other bundlers may stop at the `.ts`) | final map generation, composition and minification tracking are the bundler's |
| unsafe | only a small part | the patterns the stdlib needs: `unsafe.Pointer` round trips, `unsafe.String` / `unsafe.Slice` over slice elements; reinterpreting memory is a diagnostic (an ArrayBuffer / DataView representation is planned, ARCHITECTURE.md §7) | — |
| generics | supported (type arguments passed to the runtime) | erasure + type descriptor dictionary parameters | — |

## Summary

* Ideas taken from GopherJS: lowering directly from the typed AST, limiting goroutine support to the functions that need it through blocking analysis, strings as byte sequences, struct pointer = struct object.
* Simplified by TypeScript + the host bundler: the JS printer, bundler / output format, minification, tree shaking, final source map generation, ES target support.
* Simplified by modern JS primitives: goroutine state machines → async/await, defer → try/finally, maps → JS `Map`, package registry → ES modules.
* Where GopherJS is ahead: exact 64-bit `int`, standard library coverage and maturity. [bench/](https://github.com/goesm-dev/goesm/tree/v0.0.1-beta.9/bench) compares the speed, startup and size of the two (and of Go's and TinyGo's WebAssembly).
