# dop251/goja architecture

> Architecture diagram of the GitHub repository dop251/goja, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dop251/goja
- Repository: https://github.com/dop251/goja

## Overview

Goja is a pure-Go ECMAScript engine: a Go host supplies JavaScript source and values, the front end parses and compiles programs, and the runtime executes them and returns values or errors. The runtime also provides ECMAScript objects and built-ins, plus conversion between Go and JavaScript values. The README documents source maps and host-controlled integrations; sampled excerpts do not establish all internal wiring, so uncertain links are omitted.

Main entry points: [`runtime.go`](https://github.com/dop251/goja/blob/master/runtime.go) (Runtime API), [`parser/parser.go`](https://github.com/dop251/goja/blob/master/parser/parser.go) (Parser), [`builtin_global.go`](https://github.com/dop251/goja/blob/master/builtin_global.go) (ECMAScript built-ins), [`vm.go`](https://github.com/dop251/goja/blob/master/vm.go) (Virtual machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Parsing and compilation"]
  node_parser["Parser<br/>[parser.go]"]
  node_ast["AST<br/>[node.go]"]
  node_sourcefiles["Source positions<br/>[file.go]"]
  node_compiler["Compiler<br/>[compiler.go]"]
end

subgraph group_execution["Runtime execution"]
  node_runtime["Runtime API<br/>[runtime.go]"]
  node_vm["Virtual machine<br/>[vm.go]"]
end

subgraph group_language["JavaScript values"]
  node_values["Values<br/>[value.go]"]
  node_objects["Objects<br/>[object.go]"]
  node_builtins["ECMAScript built-ins<br/>[builtin_global.go]"]
  node_regexp["Regular expressions<br/>[regexp.go]"]
  node_dates["Date handling<br/>[date.go]"]
  node_strings["String representation<br/>[string.go]"]
end

subgraph group_interop["Host integration"]
  node_hostvalues["Go value conversion"]
  node_sourcemaps["Source maps<br/>[file.go]"]
  node_cli["Command-line runner<br/>[main.go]"]
end

node_host(("Go host"))

node_host -->|"creates and calls"| node_runtime
node_host -->|"supplies values"| node_hostvalues
node_runtime -->|"compiles source"| node_compiler
node_compiler -->|"parses source"| node_parser
node_parser -->|"builds AST"| node_ast
node_parser -->|"records positions"| node_sourcefiles
node_compiler -->|"produces program"| node_vm
node_runtime -->|"runs program"| node_vm
node_runtime -->|"initializes"| node_builtins
node_vm -->|"evaluates"| node_values
node_vm -->|"operates on"| node_objects
node_builtins -->|"uses"| node_objects
node_builtins -->|"provides regex"| node_regexp
node_builtins -->|"provides dates"| node_dates
node_values -->|"represents strings"| node_strings
node_runtime -->|"converts values"| node_hostvalues
node_parser -.->|"loads mappings"| node_sourcemaps
node_cli -->|"runs scripts"| node_runtime
node_cli -->|"reads source"| node_host

click node_parser "https://github.com/dop251/goja/blob/master/parser/parser.go"
click node_ast "https://github.com/dop251/goja/blob/master/ast/node.go"
click node_sourcefiles "https://github.com/dop251/goja/blob/master/file/file.go"
click node_compiler "https://github.com/dop251/goja/blob/master/compiler.go"
click node_runtime "https://github.com/dop251/goja/blob/master/runtime.go"
click node_vm "https://github.com/dop251/goja/blob/master/vm.go"
click node_values "https://github.com/dop251/goja/blob/master/value.go"
click node_objects "https://github.com/dop251/goja/blob/master/object.go"
click node_builtins "https://github.com/dop251/goja/blob/master/builtin_global.go"
click node_regexp "https://github.com/dop251/goja/blob/master/regexp.go"
click node_dates "https://github.com/dop251/goja/blob/master/date.go"
click node_strings "https://github.com/dop251/goja/blob/master/unistring/string.go"
click node_hostvalues "https://github.com/dop251/goja/blob/master/object_goreflect.go"
click node_sourcemaps "https://github.com/dop251/goja/blob/master/file/file.go"
click node_cli "https://github.com/dop251/goja/blob/master/goja/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parser,node_ast,node_sourcefiles,node_compiler toneBlue
class node_runtime,node_vm toneAmber
class node_values,node_objects,node_builtins,node_regexp,node_dates,node_strings toneMint
class node_hostvalues,node_sourcemaps,node_cli toneRose
class node_host toneIndigo
```

## Components

### Parsing and compilation

- [Parser](https://github.com/dop251/goja/blob/master/parser/parser.go): `parser/parser.go`
- [AST](https://github.com/dop251/goja/blob/master/ast/node.go): `ast/node.go`
- [Source positions](https://github.com/dop251/goja/blob/master/file/file.go): `file/file.go`
- [Compiler](https://github.com/dop251/goja/blob/master/compiler.go): `compiler.go`

### Runtime execution

- [Runtime API](https://github.com/dop251/goja/blob/master/runtime.go): `runtime.go`
- [Virtual machine](https://github.com/dop251/goja/blob/master/vm.go): `vm.go`

### JavaScript values

- [Values](https://github.com/dop251/goja/blob/master/value.go): `value.go`
- [Objects](https://github.com/dop251/goja/blob/master/object.go): `object.go`
- [ECMAScript built-ins](https://github.com/dop251/goja/blob/master/builtin_global.go): `builtin_global.go`
- [Regular expressions](https://github.com/dop251/goja/blob/master/regexp.go): `regexp.go`
- [Date handling](https://github.com/dop251/goja/blob/master/date.go): `date.go`
- [String representation](https://github.com/dop251/goja/blob/master/unistring/string.go): `unistring/string.go`

### Host integration

- [Go value conversion](https://github.com/dop251/goja/blob/master/object_goreflect.go): `object_goreflect.go`
- [Source maps](https://github.com/dop251/goja/blob/master/file/file.go): `file/file.go`
- [Command-line runner](https://github.com/dop251/goja/blob/master/goja/main.go): `goja/main.go`

### Other components

- **Go host**

## Connections

- Go host → Runtime API: creates and calls
- Go host → Go value conversion: supplies values
- Runtime API → Compiler: compiles source
- Compiler → Parser: parses source
- Parser → AST: builds AST
- Parser → Source positions: records positions
- Compiler → Virtual machine: produces program
- Runtime API → Virtual machine: runs program
- Runtime API → ECMAScript built-ins: initializes
- Virtual machine → Values: evaluates
- Virtual machine → Objects: operates on
- ECMAScript built-ins → Objects: uses
- ECMAScript built-ins → Regular expressions: provides regex
- ECMAScript built-ins → Date handling: provides dates
- Values → String representation: represents strings
- Runtime API → Go value conversion: converts values
- Parser → Source maps: loads mappings
- Command-line runner → Runtime API: runs scripts
- Command-line runner → Go host: reads source
