moejs

package module
v0.1.0-alpha.4 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

moejs

moejs

A JavaScript runtime in pure Go, for running JavaScript plugins inside Go programs.

简体中文 | English

You compile each plugin once and give each request its own runtime. Plugin functions take Go maps, slices or JSON directly, and you read the result back as Go values, JSON, or your own struct.

moejs was written for the task plugins of new-api, and its tests and benchmarks run those plugins.

Performance

The workload is new-api's 10 task plugins and 269 recorded calls. Times are taken on the Go caller's side and include converting the arguments and the result.

moejs Sobek QuickJS (quickjs-go) V8 (v8go)
One plugin call 6.9 µs 14.3 µs 104.5 µs 56.6 µs ¹
New runtime 1.4 µs 2.2 µs 382 µs 1,153 µs ¹
Memory per runtime with the largest plugin loaded 81 KiB 264 KiB 348 KiB ² 1,544 KiB ²

¹ V8's timings varied widely on the test machine. ² The engine's own heap.

Sobek is a pure-Go engine like moejs. QuickJS and V8 run through cgo. The test machine, the full results and how to reproduce them are in docs/performance.md.

Features

  • moejs builds with CGO_ENABLED=0, cross-compiles without a C toolchain, and shows up in pprof and the race detector like any other Go code.
  • moejs converts Go maps and slices as the plugin reads them, so a plugin pays only for the parts it uses.
  • Runtimes can go back into a pool. After a request, ReleaseCallData makes the runtime let go of that request's arguments.
  • moejs runs ES module graphs and dynamic import(). Every import goes to a Go function you provide, and a plugin can load only the modules that function returns.
  • Classic scripts (strict or sloppy), eval and the Function constructor run too. A host can cap the length of dynamic code or turn it off.
  • Plugins can use async/await and top-level await. Host functions can return a promise and settle it later from Go.
  • Any goroutine can interrupt a running plugin, for timeouts and cancellation.
  • A JavaScript throw, a syntax error, an interrupt and a panic in a host function come back as *Exception, *SyntaxError, *InterruptedError and *InternalError. StackTrace returns the V8-style stack of a thrown Error.
  • Builtins are frozen and shared by every runtime. A plugin that writes to Array.prototype fails, with a TypeError in strict code. Each runtime has its own globals and time zone. For plugins that patch builtins, a host can give a runtime its own mutable copy.

Quick start

go get github.com/Calcium-Ion/moejs

moejs needs Go 1.25 or later and depends only on the standard library (tests use testify).

package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/Calcium-Ion/moejs"
)

const source = `
export function buildRequest(input) {
  return {
    method: "POST",
    url: "https://api.example.com/v1/tasks",
    headers: { authorization: "Bearer " + utils.env("API_KEY") },
    body: { prompt: input.prompt.trim(), n: input.n ?? 1 },
  };
}
export function spin() { for (;;) {} }
`

func main() {
	// Compile once. Any number of runtimes can load the same Module.
	mod, err := moejs.Compile("plugin.js", source)
	if err != nil {
		panic(err)
	}
	build, err := mod.Hook("buildRequest")
	if err != nil {
		panic(err)
	}

	// Each request gets its own runtime: install the host functions, then load the module.
	env := map[string]string{"API_KEY": "test-key"}
	rt := moejs.NewRuntime(moejs.Options{})
	err = rt.SetGlobal("utils", map[string]any{
		"env": moejs.NativeFunc(func(r *moejs.Realm, _ moejs.Value, args []moejs.Value) (moejs.Value, error) {
			name, err := r.ToString(moejs.Arg(args, 0))
			if err != nil {
				return moejs.Undefined(), err
			}
			v, ok := env[name.GoString()]
			if !ok {
				// A Go error becomes a JavaScript Error with this message.
				return moejs.Undefined(), fmt.Errorf("%s is not set", name.GoString())
			}
			return moejs.String(v), nil
		}),
	})
	if err != nil {
		panic(err)
	}
	if err := rt.Load(mod); err != nil {
		panic(err)
	}

	// JSON in, JSON out.
	input, err := rt.ParseJSON([]byte(`{"prompt": " a cat "}`))
	if err != nil {
		panic(err)
	}
	res, err := rt.Call(build, input)
	if err != nil {
		panic(err)
	}
	out, err := rt.AppendJSON(nil, res)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(out))
	// {"method":"POST","url":"https://api.example.com/v1/tasks","headers":{"authorization":"Bearer test-key"},"body":{"prompt":"a cat","n":1}}

	// Go values in, a Go struct out.
	input, err = rt.FromGo(map[string]any{"prompt": "a dog", "n": 2})
	if err != nil {
		panic(err)
	}
	if res, err = rt.Call(build, input); err != nil {
		panic(err)
	}
	var req struct {
		Method string         `json:"method"`
		Body   map[string]any `json:"body"`
	}
	if err := rt.Unmarshal(res, &req); err != nil {
		panic(err)
	}
	fmt.Println(req.Method, req.Body) // POST map[n:2 prompt:a dog]

	// A JavaScript throw comes back as *moejs.Exception.
	_, err = rt.Call(build, moejs.Null())
	var exc *moejs.Exception
	fmt.Println(errors.As(err, &exc), exc.Name(), exc.Message())
	// true TypeError Cannot read properties of null (reading 'prompt')

	// Interrupt stops a hook that runs too long. Any goroutine can call it.
	spin, _ := mod.Hook("spin")
	timer := time.AfterFunc(50*time.Millisecond, func() { rt.Interrupt("timeout") })
	defer timer.Stop()
	_, err = rt.Call(spin)
	var interrupted *moejs.InterruptedError
	fmt.Println(errors.As(err, &interrupted), interrupted.Value) // true timeout
	rt.ClearInterrupt()

	// Before the runtime goes back to a pool, let go of this request's data.
	rt.ReleaseCallData()
}

A server usually compiles each plugin once and keeps a pool of runtimes for it, one per concurrent request. The guide covers pools, module graphs, value conversion, promises and errors, and the package documentation describes every function.

JavaScript support

moejs runs ES modules and classic scripts, including sloppy mode and the web-compatibility behaviour of Annex B. The language includes classes with fields, private members and static blocks, destructuring, optional chaining, generators, async functions and async iteration. The standard library has Proxy, Reflect, BigInt, typed arrays, resizable ArrayBuffers, WeakRef, structuredClone, TextEncoder/TextDecoder, and recent additions such as the Set methods, Promise.try, Float16Array, Array.fromAsync, Math.sumPrecise and Error.isError. Regular expressions support every flag and Unicode 17 properties, and Date takes its time zones from Go.

On test262, 79,385 tests pass and 0 fail. The other 14,058 tests use features moejs does not implement and are skipped. Results by directory are in bench/test262/RESULTS.md.

Not implemented: import attributes and JSON modules, using declarations and DisposableStack, decorators, iterator helpers, Intl, Temporal, ShadowRealm, FinalizationRegistry, timers and JSON.rawJSON. TODO.md lists all of them, the known wrong results and the limits.

Status

moejs is in alpha, and the API may change between releases.

Testing

# Test inputs are downloaded separately: new-api's plugins and a pinned
# test262 revision. Tests that need them skip until they are downloaded.
bench/testdata/plugins/fetch.sh
bench/test262/fetch.sh

# Unit, audit and fuzz-corpus tests of the engine.
go test ./...

# Differential tests against Sobek, the expression corpus, the benchmarks and
# test262. bench/ is a separate Go module, so Sobek and the cgo engines are
# dependencies of bench/ only. Its V8 and QuickJS baselines need cgo.
cd bench && go test -timeout 30m ./...

Acknowledgements

moejs takes design ideas from these projects. Its code was written independently.

  • goja and Sobek: the Go interop conventions and the Export rules. Sobek is also the reference for the differential tests.
  • QuickJS: the 16-byte value layout, atoms, shape transitions and compact builtin tables.
  • V8: hidden classes, inline caches, prototype validity checks (reduced to one counter), the Ignition register interpreter, Date.parse and the Error.prototype.stack format.
  • Lua 5.x: the fixed-width register instruction encoding.
  • JavaScriptCore and SpiderMonkey: NaN-boxing.
  • esbuild: how to write a fast JavaScript parser in Go.
  • Hardened JavaScript / SES: the lockdown() model behind the shared frozen builtins.
  • quickjs-go and v8go: the cgo baselines of the benchmarks.
  • test262: the conformance suite.
  • new-api: the plugin host. Its pkg/jsplugin decides which APIs moejs has to support.

License

moejs is licensed under the Apache License 2.0.

The benchmarks run new-api's task plugins, which are licensed under AGPL-3.0 and downloaded separately by bench/testdata/plugins/fetch.sh.

Documentation

Overview

Package moejs embeds the moejs JavaScript engine in a Go host that runs ES modules as plugins: compile a module once, evaluate it in any number of runtimes, call its exported functions with Go data and read their results back as Go data or JSON bytes. 

mod, err := moejs.Compile("plugin.js", source)
hook, err := mod.Hook("protocols", "openai", "decodeRequest")
rt := moejs.NewRuntime(moejs.Options{})
err = rt.SetGlobal("utils", map[string]any{"now": moejs.NativeFunc(now)})
err = rt.Load(mod)
arg, err := rt.ParseJSON(body)
res, err := rt.Call(hook, arg)
out, err := rt.AppendJSON(nil, res)

Values are engine values (package engine) under their own names, so host functions and the host share one representation and nothing is wrapped on the way in or out. Errors are returned, never panicked: a JavaScript throw is an *Exception, an interrupt an *InterruptedError, bad source a *SyntaxError.

The jobs JavaScript queues (promise reactions, queueMicrotask callbacks) run before the method that ran it returns, getters and proxy traps included (Load, Call, Has, Get, ToGo, AppendJSON, SetGlobal, the settlers of NewPromise): the first exception a callback throws is the method's error when it succeeded otherwise, and an interrupt drops the jobs left.

A module that imports others is linked once with the modules it imports, which the host resolves (moejs never reads files or the network): 

mod, err := moejs.Link(entry, func(referrer moejs.Referrer, specifier string) (*moejs.Module, error) {
	return host.modules[specifier], nil // compiled once, by the host
})

A runtime that loads the linked module evaluates each module of its graph once; its hooks and exports are the entry's, re-exported names included. import() and import.meta are the host's too, through the Importer of Options, which resolves with the same kind of resolver: 

rt := moejs.NewRuntime(moejs.Options{Importer: &moejs.Importer{Resolve: resolve}})

A module import() loads joins the runtime's modules: one the runtime evaluated before is not evaluated again.

A Module is immutable and may be loaded by many runtimes concurrently. A Runtime is one global environment with one loaded module; it must be used from one goroutine at a time, except Interrupt and ClearInterrupt.

Index

Examples

Constants

View Source 
const (
	PromisePending   = engine.PromisePending
	PromiseFulfilled = engine.PromiseFulfilled
	PromiseRejected  = engine.PromiseRejected
)

Promise states.

View Source 
const (
	// PromiseRejectionReject: the promise was rejected with no handler.
	PromiseRejectionReject = engine.PromiseRejectionReject
	// PromiseRejectionHandle: the first handler was added to the promise,
	// rejected earlier with none.
	PromiseRejectionHandle = engine.PromiseRejectionHandle
)

Rejection tracker operations.

Variables

View Source 
var (
	Undefined = engine.Undefined
	Null      = engine.Null
	Bool      = engine.Bool
	Number    = engine.NumberValue
	Int       = engine.Int64Value
)

Value constructors, for host functions. None allocates except String.

View Source 
var (
	// ErrHookNotFound is returned when a hook's export or one of its members
	// is missing, undefined or null.
	ErrHookNotFound = errors.New("moejs: hook not found")
	// ErrNotCallable is returned when a hook names a value that is not a
	// function.
	ErrNotCallable = errors.New("moejs: hook is not a function")
	// ErrForeign is returned for a function or generator of another
	// runtime (or a bound function or proxy of one) passed to Call,
	// SetGlobal, FromGo or a settler of NewPromise: it runs only in the
	// runtime that created it. Inside a Go map or slice FromGo or SetGlobal
	// converts it is not the error: reading that member throws a TypeError
	// with ErrForeign's text.
	ErrForeign = engine.ErrForeign
	// ErrModulePending is Load's error for a module with top-level await
	// whose evaluation still awaits once no job is left.
	ErrModulePending = engine.ErrModulePending
)
View Source 
var Arg = engine.Arg

Arg returns args[i], or undefined when there are fewer arguments.

View Source 
var ErrNoResolver = engine.ErrNoResolver

ErrNoResolver is the Err of the *ResolveError of Link for a module that imports when the resolver is nil.

Functions

func PromiseResult 

func PromiseResult(p Value) (state PromiseState, result Value, ok bool)

PromiseResult reports the state of the promise p and its result: the fulfillment value or the rejection reason, undefined while pending. ok is false when p is not a promise. No user code runs, so a promise a Call returned is read as the jobs that Call ran left it.

Types

type Exception 

type Exception = engine.Exception

Exception is a thrown JavaScript value.

type Hook 

type Hook struct {
	// contains filtered or unexported fields
}

Hook is a resolved path to a function in a module (Module.Hook), which Call finds in a runtime that loaded the module. A Hook of an export the module declares itself also works in a runtime that loaded the Module Link returned for it; a re-exported name needs the Hook of that Module. The zero Hook names nothing.

func (Hook) Name 

func (h Hook) Name() string

Name returns the path joined with dots ("protocols.openai.decodeRequest").

type Importer 

type Importer struct {
	// Resolve returns the module import(specifier) names in the code of
	// referrer: the *Module whose code imports (Link's entry or a module a
	// resolver returned for its graph; Compile's module for a module Load
	// evaluated alone), or the *Script RunScript ran; nil for code of
	// neither. Eval code and the code of the Function constructors import
	// for the script or module whose code evaluates them when that code
	// uses import() or import.meta or holds a direct eval, and with a nil
	// referrer otherwise, as when a job calls eval or a constructor
	// directly, with no code of a script or module running
	// (Promise.resolve(s).then(eval)). It runs within import(), and its
	// error rejects import()'s promise: an *Exception with its value, a
	// *SyntaxError with a SyntaxError, an *InterruptedError stops the
	// running code, any other error rejects with an Error. The modules a
	// returned module imports are resolved through Resolve too, as Link
	// does.
	Resolve Resolver
	// Meta, when set, fills the import.meta object of module m when a
	// runtime first evaluates import.meta in m's code. The object has a null
	// prototype and no properties. Its error is thrown by the import.meta
	// expression, and the next evaluation calls Meta again.
	Meta func(r *Realm, m *Module, meta *Object) error
	// contains filtered or unexported fields
}

Importer is the host's side of import() and import.meta in the runtimes whose Options name it. One Importer may serve any number of runtimes, concurrently; its fields must not change once a runtime uses it, and it must not be copied then. Without an Importer, import() rejects with a TypeError and import.meta is an empty object.

import(specifier) asks Resolve for the module at once and links and evaluates it from a job: its promise settles with the module's namespace or what the resolution, the linking or the evaluation failed with. The module is the identity, as for Link: a runtime evaluates one module once, whether its code imports it statically or dynamically, so a module the runtime evaluated before is not evaluated again. The graph of a module is linked once per Importer (the graph of a module Link returned is its own), so each runtime only instantiates and evaluates it.

A module whose evaluation an interrupt stopped stays failed in the runtime: one whose top level the interrupt stopped, before or after an await; one whose next step (resuming its top level, or running it once the modules it imports evaluated) the interrupt dropped with the runtime's queued jobs; and one that imports such a module. After ClearInterrupt, an import() whose graph reaches it rejects with an Error whose message is `Cannot import "<specifier>": its evaluation was interrupted`, with the specifier import() was given. The Error holds neither the interrupt's value nor a Go error: thrown out of a hook, its *Exception unwraps to nil, where the Error of a Resolve error unwraps to that error. An import() in flight when the interrupt came stays pending, and so does a module whose top level awaits a promise the interrupt left pending, as other code awaiting it does.

Resolve and Meta are called from every goroutine that uses the Importer, concurrently. Each call runs within the call of the runtime that evaluates the import() or import.meta, or runs the job that links the module import() loaded, and Resolve may call back into that runtime.

What the Importer and its runtimes keep grows with the distinct code they see. The Importer holds every module with imports that import() loaded, with its graph, for as long as it lives. A runtime holds a record of every distinct script and module whose code uses import() or import.meta or holds a direct eval and that it ran, with the *Script or *Module, for as long as it lives, however many times the code runs, and an entry for each piece of code it compiled from a string in them (eval code and the code of the Function constructors). A host that generates modules or scripts at run time must bound how many one Importer loads and one runtime runs.

type InternalError 

type InternalError struct {
	Value any    // the recovered panic value
	Stack []byte // the goroutine stack at the panic
}

InternalError is a Go panic that escaped the engine: an engine bug or a host function that panicked. The runtime's call state is restored and the jobs left queued are dropped, but the host should drop the runtime.

func (*InternalError) Error 

func (e *InternalError) Error() string

func (*InternalError) Unwrap 

func (e *InternalError) Unwrap() error

Unwrap returns the panic value when it is an error.

type InterruptedError 

type InterruptedError = engine.InterruptedError

InterruptedError is returned when Interrupt stopped running code.

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module is a compiled ES module. It is immutable: any number of runtimes may load it, concurrently.

func Compile 

func Compile(name, source string) (*Module, error)

Compile parses and compiles an ES module. Bad source, including features the engine does not support yet, is a *SyntaxError. A module that imports others is loaded once Link linked it with them. 

func Link(entry *Module, resolve Resolver) (*Module, error)

Link resolves the modules entry imports, directly or not, asking resolve once per module and specifier, links them and returns entry linked with its graph: the Module runtimes load, whose Hook and Exports also reach the names entry re-exports. Linking happens once; the Module is immutable, and each runtime that loads it only instantiates and evaluates the graph. The Hooks of entry's own exports stay valid for the linked Module. An import that does not resolve to one binding is a *SyntaxError at the import in the importing module, and so is an indirect export; a failed resolution is a *ResolveError. Link runs no JavaScript: a panic of resolve propagates. A module that imports nothing and uses neither import() nor import.meta is returned as is.

func (*Module) Exports 

func (m *Module) Exports() []string

Exports returns the module's export names, sorted: for a module Link returned, the names it re-exports too, without those its star exports leave ambiguous.

func (*Module) Hook 

func (m *Module) Hook(export string, members ...string) (Hook, error)

Hook names an exported function, or a function below an exported object reached through own properties (members "openai", "decodeRequest" of export "protocols"). The export slot and the property keys are resolved here, once; the bindings stay live, so each Call reads the export and walks the members in the runtime at hand. An export the module does not declare, or re-export once linked, is ErrHookNotFound.

func (*Module) Name 

func (m *Module) Name() string

Name returns the name given to Compile.

func (*Module) Requests 

func (m *Module) Requests() []string

Requests returns the specifiers the module imports from, in the order they first appear in its source, nil when it imports none.

type NativeFunc 

type NativeFunc = engine.NativeFunc

NativeFunc is a host function. Returning an error throws: an *Exception or *InterruptedError as is, any other error as an Error whose message is err.Error() and which unwraps to err.

type Object 

type Object = engine.Object

Object is a JavaScript object.

type Options 

type Options struct {
	// MutableIntrinsics gives the runtime its own mutable copy of the
	// builtins (prototypes, constructors, Math, JSON). By default they are
	// built once per process, deeply frozen and shared by every runtime, and
	// writing to them throws a TypeError.
	MutableIntrinsics bool
	// TimeZone is the local time zone of Date; nil means time.Local.
	TimeZone *time.Location
	// Importer resolves the modules of import() and fills import.meta; nil
	// means import() rejects with a TypeError.
	Importer *Importer
	// MaxDynamicSource is the length in UTF-8 bytes of the longest source
	// text eval, the Function constructors and Realm.EvalScript compile:
	// longer text throws a RangeError. Zero
	// means engine.DefaultMaxDynamicSource (1 MiB), a negative value no
	// limit (engine.RealmOptions). Compile and CompileScript have no limit.
	MaxDynamicSource int
	// DisableDynamicCode makes eval of a string, the Function constructors
	// and Realm.EvalScript throw an EvalError instead of compiling anything,
	// for hosts whose code needs none (engine.RealmOptions). Compile and
	// CompileScript are not affected.
	DisableDynamicCode bool
}

Options configures NewRuntime.

type PromiseRejectionOperation 

type PromiseRejectionOperation = engine.PromiseRejectionOperation

PromiseRejectionOperation is what a rejection tracker is told (see SetPromiseRejectionTracker).

type PromiseState 

type PromiseState = engine.PromiseState

PromiseState is the state of a promise.

type Realm 

type Realm = engine.Realm

Realm is the engine state a Runtime owns; host functions receive it.

type Referrer 

type Referrer interface {
	// Name returns the name the code was compiled with.
	Name() string
	// contains filtered or unexported methods
}

A Referrer is the code that requests a module: a *Module or a *Script.

type ResolveError 

type ResolveError struct {
	File      string
	Line      int // 1-based
	Column    int // 1-based, in code points
	Specifier string
	Err       error
}

ResolveError is Link's error when the resolver fails for an import, an export-from or a star export of a module, at File, Line and Column of that entry: Err is the resolver's error, ErrNoResolver, or an error when the resolver returned no module. Load returns one too when the graph resolves the request of a module the runtime instantiated before (from import()) to another module than the runtime did; an import() of such a graph rejects with an Error of it.

func (*ResolveError) Error 

func (e *ResolveError) Error() string

Error formats as `file:line:col: cannot resolve module "specifier": err`.

func (*ResolveError) Unwrap 

func (e *ResolveError) Unwrap() error

type Resolver 

type Resolver func(referrer Referrer, specifier string) (*Module, error)

Resolver returns the module that specifier names in referrer (HostLoadImportedModule). Link asks it for the requests of the modules of a graph: the referrer is the importing *Module, Link's entry or a module the resolver returned. An Importer asks it for import() too, where the referrer can also be a *Script, or nil. moejs never reads files or the network: the host maps every specifier to a module it compiled. The module is the identity: a runtime evaluates one module once, so a resolver returns the same *Module for the same module every time, which also compiles a module shared by several graphs once. A module Link returned stands for the module it linked: its graph is not used, and Link resolves its requests again.

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is one JavaScript global environment with at most one loaded module. It must be used from one goroutine at a time; only Interrupt and ClearInterrupt may be called concurrently.

The objects its JavaScript creates are its own. Any object of another runtime can run that runtime's code when it is used, not only a function or generator but also through a method, an accessor, a proxy, a promise or a thenable, and that code reads the caches of the runtime running it: wrong results or an *InternalError. Only Go values (ToGo, FromGo) and JSON are safe to pass between runtimes. Call, SetGlobal, FromGo and the settlers of NewPromise return ErrForeign for a function or generator of another runtime (or a bound function or proxy of one), FromGo also for one inside the Go containers it converts (reading that member throws); they do not look inside other objects, and do not check a proxy of another runtime that is not callable, even inside a Go map: its traps run in the runtime that reads it.

func NewRuntime 

func NewRuntime(opts Options) *Runtime

NewRuntime creates a runtime.

func (*Runtime) AppendJSON 

func (rt *Runtime) AppendJSON(dst []byte, v Value) (out []byte, err error)

AppendJSON appends JSON.stringify(v) to dst as UTF-8. A value with no JSON form (undefined, a function, a symbol) appends null. A proxy is serialized as JSON.stringify does it: its traps run. Nesting deeper than 10,000 arrays and objects (engine.MaxToGoDepth) is a RangeError, and so is an output of more than 2^30-24 bytes: the string length limit counted in bytes of UTF-8, JSON.stringify's limit for ASCII text and reached first for other text.

The output is written into dst's spare capacity, after reserving the last output's length plus an eighth: a host that passes its previous output back (buf, err = rt.AppendJSON(buf[:0], v)) allocates only when buf has less room than that, and after one very large output a call with a small dst allocates that much again. Before any JavaScript runs (a toJSON, a Date's included, a getter, a proxy's trap) the output moves to a buffer of its own, which holds twice what is written so far and grows as the rest is written, and is appended to dst when AppendJSON returns, so a host function that JavaScript calls meanwhile may append to dst or pass it to another AppendJSON; what it appended to dst's spare capacity is overwritten then, as append(dst, text...) would overwrite it. The same holds for a job (a promise reaction, queueMicrotask) that code queued, when AppendJSON is called outside any Call: the job runs before the output is appended to dst. Inside a host function the jobs run when the outermost Call returns, after AppendJSON has returned, and one that appends to the same dst overwrites what AppendJSON appended, as any later append would: a host function should use a buffer of its own.

func (*Runtime) Call 

func (rt *Runtime) Call(h Hook, args ...Value) (res Value, err error)

Call invokes the function h names with this = undefined. A path that does not lead to a value is ErrHookNotFound, one that leads to a value that is not a function ErrNotCallable; a throw is an *Exception, an interrupt an *InterruptedError. The hooks of a module whose top level failed return Load's error. An argument that is a function or generator of another runtime is ErrForeign.

func (*Runtime) ClearInterrupt 

func (rt *Runtime) ClearInterrupt()

ClearInterrupt drops a pending interrupt.

func (*Runtime) Export 

func (rt *Runtime) Export(name string) (v Value, ok bool)

Export returns the current value of the loaded module's export name, a name it re-exports included. ok is false when there is no such export or the binding is not initialized yet, and, once the module's top level failed (Load), for a function or a module namespace object, whose code could find the module's other bindings uninitialized without the ReferenceError.

func (*Runtime) FromGo 

func (rt *Runtime) FromGo(v any) (Value, error)

FromGo converts a Go value: nil, bool, the integer and float kinds, string, json.Number, *big.Int (a bigint), Value, NativeFunc, and the JSON-shaped containers map[string]any, map[string]string, map[string][]string, []any, []string and []map[string]any. Containers convert lazily, one level when first touched, so a large argument the hook reads little of costs little; the Go value must not change while the result is in use, and JavaScript writes never reach it. Maps enumerate their keys sorted. A []byte becomes an ArrayBuffer over the same bytes, not a copy: JavaScript writes reach them, and the host must not modify them while JavaScript may read them. Other types (structs, named map types) are an error: marshal them and use ParseJSON. A Value or *Object that is a function or generator of another runtime is ErrForeign; inside a container, reading its member throws a TypeError with ErrForeign's text.

func (*Runtime) Function 

func (rt *Runtime) Function(name string, length int, fn NativeFunc) Value

Function creates a host function with a name and a length, the values of its `name` and `length` properties; a negative length is 0, as no function's length is negative.

func (*Runtime) Get 

func (rt *Runtime) Get(v Value, key string) (res Value, err error)

Get reads property key of v, running a getter and walking the prototype chain; undefined and null have no properties and read as undefined.

func (*Runtime) Has 

func (rt *Runtime) Has(h Hook) (ok bool, err error)

Has reports whether h names a function in this runtime now. A getter on the path that throws is returned as the error, and so is Load's for the hooks of a module whose top level failed.

func (*Runtime) Interrupt 

func (rt *Runtime) Interrupt(v any)

Interrupt stops running code: the pending Call (or Load, ToGo, ...) returns an *InterruptedError carrying v. It may be called from any goroutine. An interrupt that arrives while nothing runs stops the next Call, whatever the function it names, or Load, and any other method once it runs JavaScript, so a host calls ClearInterrupt before reusing the runtime.

func (*Runtime) Load 

func (rt *Runtime) Load(m *Module) (err error)

Load evaluates m's top level in this runtime. A runtime loads one module once, and a Load made while the top level runs is refused too. A module that imports others loads once Link linked it: Load then evaluates the modules of its graph first, each once, in the order of their imports; a failure of one of them is a failure of m's top level, which then does not run. In a runtime with an Importer, import() of m, or of a module of its graph, finds the instance Load evaluated. When the top level throws, is interrupted or panics (an *InternalError) before it ends or first awaits, the error is returned and the module stays loaded: Export reads the bindings initialized before the failure other than functions and module namespaces (none when an interrupt stopped the top level before it started), and Call and Has return the error for the module's hooks: a function could find the other bindings uninitialized. The jobs the top level queued run after it, when Export and the module's hooks find its bindings; while the top level itself runs they find none. A module with top-level await evaluates asynchronously: its top level resumes from those jobs, with the bindings found, and Load returns once none is left, with what the evaluation rejected with (an interrupt of those jobs wins), or ErrModulePending when it still awaits; an exported function called while it awaits throws a ReferenceError for a binding it has not initialized yet.

func (*Runtime) Module 

func (rt *Runtime) Module() *Module

Module returns the loaded module, or nil.

func (*Runtime) NewPromise 

func (rt *Runtime) NewPromise() (p Value, resolve, reject func(v Value) error)

NewPromise creates a pending promise, for a host function to return, and the functions that settle it. resolve does what the promise's resolve function does in JavaScript: it adopts a thenable and fulfills with any other value; reject rejects. The first call of either decides and later calls do nothing. Both may be called after the host function returned, from the goroutine that uses the runtime: called outside a Call, they run the jobs they queue before returning, as the end of a Call does, and return what a Call would for those (an *InterruptedError, or the first exception a queueMicrotask callback threw). A function or generator of another runtime is ErrForeign and settles nothing.

func (*Runtime) ParseJSON 

func (rt *Runtime) ParseJSON(b []byte) (Value, error)

ParseJSON is JSON.parse of b. Nesting deeper than 10,000 arrays and objects (engine.MaxToGoDepth) is a RangeError.

func (*Runtime) Realm 

func (rt *Runtime) Realm() *Realm

Realm returns the runtime's engine state, for host functions and tests that need the engine API directly.

func (*Runtime) ReleaseCallData 

func (rt *Runtime) ReleaseCallData()

ReleaseCallData drops the runtime's references to the host values of finished calls, so a pooled runtime does not keep the last request alive. A host that pools runtimes calls it after the request's last use of the runtime (Call, ToGo, Get, AppendJSON: each can run JavaScript), before it returns the runtime to its pool; Call does not, so that a request running several hooks converts its data as one, and hosts that do not pool pay nothing. Values already returned stay valid: their nodes keep their own storage, so ToGo and Get of them work after it. Between calls only; a no-op inside one (from a host function).

What JavaScript keeps stays alive with what it references: a string of a FromGo argument the module stores keeps every string converted in its period (up to 512), and an object it stores keeps its chunk and, through the root placeholder in it, the whole argument; a substring of an ASCII string shares its bytes, so storing a slice of a large one keeps all of it. The names the runtime keeps for its caches (property names, RegExp patterns) are its own copies, whether they come from map keys, a parsed JSON text or a slice of a string.

func (*Runtime) RunScript 

func (rt *Runtime) RunScript(s *Script) (res Value, err error)

RunScript runs s in the runtime's global environment and returns its completion value. Its var and function declarations become properties of the global object; its let, const and class declarations are global bindings that later scripts and the loaded module (before or after Load) see too. A declaration that conflicts with an existing global binding throws before anything runs. The jobs the script queued run before RunScript returns. A throw is an *Exception, an interrupt an *InterruptedError.

func (*Runtime) SetGlobal 

func (rt *Runtime) SetGlobal(name string, v any) (err error)

SetGlobal assigns the global variable name. v is converted by FromGo, so a host installs a namespace of functions as a map[string]any with NativeFunc values. It writes the global object, whose property a script's global let, const or class declaration of the same name shadows (ECMA-262 9.1.1.4.1).

func (*Runtime) SetPromiseRejectionTracker 

func (rt *Runtime) SetPromiseRejectionTracker(f func(p Value, op PromiseRejectionOperation))

SetPromiseRejectionTracker registers f to be called when a promise is rejected with no handler (PromiseRejectionReject) and when a promise so rejected gets its first handler (PromiseRejectionHandle), ECMAScript's HostPromiseRejectionTracker. A promise told Reject and not Handle when a Call returns has an unhandled rejection. f runs synchronously, in the reject or then that caused the operation. nil removes the tracker.

func (*Runtime) StackTrace 

func (rt *Runtime) StackTrace(exc *Exception) string

StackTrace returns the `stack` of an Error thrown in this runtime: "Name: message" and one " at ..." line per frame. It is "" when the thrown value is not an Error or its stack was replaced by a non-string. No user code runs.

func (*Runtime) ToGo 

func (rt *Runtime) ToGo(v Value) (out any, err error)

ToGo exports v: undefined and null become nil, booleans bool, strings string, integral numbers in int64 range int64 (except -0), other numbers float64, arrays []any, other objects map[string]any of their own enumerable string-keyed properties, Date time.Time, bigint *big.Int, and functions and symbols the engine value itself (*Object, *engine.Symbol). An ArrayBuffer or SharedArrayBuffer exports a copy of its bytes as a []byte, and a typed array or DataView a copy of the bytes it views (so a Uint16Array of 2 elements gives 4 bytes, little-endian); a detached buffer and a view out of its buffer's bounds give a nil []byte, and a zero-length buffer or view a non-nil empty one. A proxy exports through its traps (see engine.Realm.ToGo): []any when its target is an array, the map of its enumerable keys otherwise, the *Object when it is callable. An array or object FromGo converted from a non-empty Go map or slice exports as that Go value while JavaScript has not modified it (engine.Object.HostValue); an empty one converted to a plain array or object, and a nil map to null. A getter or trap that throws, a revoked proxy, or nesting deeper than 10,000 containers (engine.MaxToGoDepth) is returned as the error. The Go string of an ASCII string is the one v holds: for a value ParseJSON produced it may share the parsed text and keep it alive; strings.Clone what is kept.

func (*Runtime) Unmarshal 

func (rt *Runtime) Unmarshal(v Value, target any) (err error)

Unmarshal stores v in the value target points to as json.Unmarshal stores the text AppendJSON writes for v, and returns the error json.Unmarshal (or AppendJSON) would. A value made of plain objects, arrays, strings, numbers, booleans and null, and arguments FromGo converted that it returns untouched (in an `any` of target), goes into target without the text: no JSON is written or parsed, and strings are not copied (the Go string of an ASCII string is the one v holds, as with ToGo). Anything else — a toJSON method, a getter, a proxy, a Date, a target type that unmarshals itself, a value target's type rejects — makes it fall back to AppendJSON and json.Unmarshal, with their result and error; JavaScript code then runs as AppendJSON runs it. When AppendJSON would fail (a BigInt, a cycle, a Go value it cannot write, a text past the string length limit), target is left as it was: v is checked, its Go values included, before anything is written, and a value whose text could pass the limit (counting six bytes a character of most strings) goes through the round trip. An interrupt is observed every 4096 values, as AppendJSON observes it, in the check and again in the store; an argument copied into an `any` counts a value per 4096 bytes of each of its Go strings, whether a string itself or in a map[string]string, a []string or another of its containers. One pending at the call fails a large value before anything is written, and not a small one. AppendJSON also observes one inside a long JavaScript string it escapes, which Unmarshal, copying no string, does not. After an error of json.Unmarshal (a value target's type rejects) or an interrupt, target may hold part of v, as with json.Unmarshal. A string of a value ParseJSON produced may share the parsed text and keep it alive for as long as the host holds it: strings.Clone a string kept beyond the request.

type Script 

type Script struct {
	// contains filtered or unexported fields
}

Script is a compiled classic script. It is immutable: any number of runtimes may run it, concurrently, and a runtime may run it more than once.

func CompileScript 

func CompileScript(name, source string) (*Script, error)

CompileScript parses and compiles a classic script. A script is sloppy mode code unless it starts with a "use strict" directive. Bad source, including features the engine does not support yet, is a *SyntaxError.

func (*Script) Name 

func (s *Script) Name() string

Name returns the name given to CompileScript.

type SyntaxError 

type SyntaxError struct {
	File    string
	Line    int // 1-based
	Column  int // 1-based, in code points
	Message string
}

SyntaxError is a parse or early error in module source.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

Error formats as "file:line:col: SyntaxError: message".

type Value 

type Value = engine.Value

Value is a JavaScript value.

func String 

func String(s string) Value

String converts a Go string.

Source Files

View all Source files

Directories

Path Synopsis
Package bytecode defines the moejs instruction set and the compiled-function template shared between the compiler and the engine's interpreter.
 Package bytecode defines the moejs instruction set and the compiled-function template shared between the compiler and the engine's interpreter.
Package compiler translates the annotated AST produced by package syntax into bytecode.Function templates.
 Package compiler translates the annotated AST produced by package syntax into bytecode.Function templates.
internal
gen/decomp command
Command decomp generates engine/decomp_tables.go, the character decomposition data of String.prototype.localeCompare: the Decomposition_Mapping field of UnicodeData.txt (canonical and compatibility mappings, one level each, with the compatibility tag) and the non-zero Canonical_Combining_Class values.
 Command decomp generates engine/decomp_tables.go, the character decomposition data of String.prototype.localeCompare: the Decomposition_Mapping field of UnicodeData.txt (canonical and compatibility mappings, one level each, with the compatibility tag) and the non-zero Canonical_Combining_Class values.
gen/ucd command
Command ucd generates internal/regexpsyntax/unicode_tables.go, the Unicode Character Database tables of the regular-expression engine: General_Category, Script and Script_Extensions values, the binary properties of ECMA-262 table 67, the properties of strings of the v flag, simple case folding and the non-u Canonicalize mapping.
 Command ucd generates internal/regexpsyntax/unicode_tables.go, the Unicode Character Database tables of the regular-expression engine: General_Category, Script and Script_Extensions values, the binary properties of ECMA-262 table 67, the properties of strings of the v flag, simple case folding and the non-u Canonicalize mapping.
regexpsyntax
Package regexpsyntax parses ECMAScript regular expression patterns.
 Package regexpsyntax parses ECMAScript regular expression patterns.
Package syntax implements the moejs front end: a hand-written lexer, a recursive-descent parser producing a compact AST, early errors, and a scope-resolution pass whose annotations the compiler consumes directly.
 Package syntax implements the moejs front end: a hand-written lexer, a recursive-descent parser producing a compact AST, early errors, and a scope-resolution pass whose annotations the compiler consumes directly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.