quickjs

package module
v0.0.0-...-7c7bd24 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2025 License: BSD-3-Clause Imports: 15 Imported by: 0

README

Go Reference LiberaPay receives patrons

logo_png

quickjs

Package quickjs is a pure Go embeddable Javascript engine. It supports the ECMA script 14 (ES2023) specification including modules, asynchronous generators, proxies and BigInt.

See also the original C QuickJS library.

Documentation

Overview

Package quickjs is a pure Go embeddable Javascript engine. It supports the ECMA script 14 (ES2023) specification including modules, asynchronous generators, proxies and BigInt.

See also the original C QuickJS library.

Supported platforms and architectures

These combinations of GOOS and GOARCH are currently supported 

OS      Arch
-------------
darwin  amd64
darwin  arm64
freebsd amd64
freebsd arm64
linux   386
linux   amd64
linux   arm
linux   arm64
linux   loong64
linux   ppc64le
linux   riscv64
linux   s390x
windows amd64
windows arm64

Builders

Builder results are available here.

Performance

This package @v0.13.2

vs https://pkg.go.dev/github.com/dop251/goja@v0.0.0-20250309171923-bcd7cc6bf64c 

goos: linux
goarch: amd64
pkg: modernc.org/quickjs/compare
cpu: AMD Ryzen 9 3900X 12-Core Processor
BenchmarkArewefastyet/ccgo-24  1  128224839492 ns/op       169848 B/op          73 allocs/op
BenchmarkArewefastyet/goja-24  1  173825845377 ns/op  26122785512 B/op  1492473123 allocs/op
PASS
ok  	modernc.org/quickjs/compare	302.069s
make[1]: Opouští se adresář „/home/jnml/src/modernc.org/quickjs/compare“

Notes

Parts of the documentation were copied from the quickjs documentation, see LICENSE-QUICKJS for details.

Example (Ping)

Multiple concurrent Javascript virtual machines communicating via Go channels. 

package main // import "modernc.org/quickjs"

import (
	"fmt"
)

// Multiple concurrent Javascript virtual machines communicating via Go channels.
func main() {
	tx := make(chan string, 1)
	rx := make(chan string, 1)
	client, _ := NewVM()
	defer client.Close()
	registerFuncs(client, tx, rx)
	go func() { // Start the server.
		server, _ := NewVM()
		defer server.Close()
		registerFuncs(server, rx, tx)
		server.Eval("send(receive()+' reply');", EvalGlobal)
	}()
	fmt.Println(client.Eval("send('ping'); receive();", EvalGlobal)) // Ping the server.
}

func registerFuncs(m *VM, tx, rx chan string) {
	m.RegisterFunc("send", func(s string) { tx <- s }, false)
	m.RegisterFunc("receive", func() string { return <-rx }, false)
}

Output:
ping reply <nil>

Index

Examples

Constants

View Source 
const (
	EvalGlobal      = lib.MJS_EVAL_TYPE_GLOBAL // global code
	EvalModule      = lib.MJS_EVAL_TYPE_MODULE // module code
	EvalCompileOnly = lib.MJS_EVAL_FLAG_COMPILE_ONLY
)

Eval flags.

Variables

View Source 
var (

	// UndefinedValue is a Value representing Javascript value 'undefined'. It is
	// not associated with any particular VM.
	UndefinedValue = Value{/* contains filtered or unexported fields */}
)

Functions

This section is empty.

Types

type Atom 

type Atom = lib.TJSAtom

Atom is an unique identifier of, for example, a string value. Atom values are VM-specific.

type Object 

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

Object represents the value of a Javascript object, but not the javascript object instance itself. Do not compare instances of Object.

func (*Object) MarshalJSON 

func (o *Object) MarshalJSON() (r []byte, err error)

MarshalJSON implements encoding/json.Marshaler.

Example

JSON marshalling. 

m, _ := NewVM()
defer m.Close()
obj, _ := m.Eval("obj = {a: 42+314, b: 'foo'}; obj;", EvalGlobal)
s, _ := (obj.(*Object).MarshalJSON())
fmt.Printf("%s\n", s)

Output:
{"a":356,"b":"foo"}

func (*Object) String 

func (o *Object) String() string

String implements fmt.Stringer.

Example

JSON marshalling. 

m, _ := NewVM()
defer m.Close()
obj, _ := m.Eval("obj = {a: 42+314, b: 'foo'}; obj;", EvalGlobal)
fmt.Printf("%s\n", obj)

Output:
{"a":356,"b":"foo"}

type Undefined 

type Undefined struct{}

Undefined represents the Javascript value "undefined".

func (Undefined) String 

func (u Undefined) String() string

String implements fmt.Stringer.

type Unsupported 

type Unsupported struct{}

Unsupported represents an unsupported Javascript value.

func (Unsupported) String 

func (u Unsupported) String() string

String implements fmt.Stringer.

type VM 

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

VM represents a Javascript context (or Realm). Each VM has its own global objects and system objects.

Note: VM is not safe for concurrent use by multiple goroutines.

func NewVM 

func NewVM() (*VM, error)

NewVM returns a newly created VM.

func (*VM) Call 

func (m *VM) Call(function string, args ...any) (r any, err error)

Call evaluates 'function(args...)' and returns the resulting (value, error).

Argument types must be one of: 

Go argument type                        Javascript argument type
----------------------------------------------------------------
nil                                     null
Undefined                               undefined
string                                  string
int*/uint* (value in int32 range)       int
int*/uint* (value out of int32 range)   float
bool                                    bool
float64                                 float64
*math/big.Int                           BigInt
*Object                                 object
Value                                   native Javascript Value
any other type                          object from JSON produced by encoding.json/Marshall(arg)
Example (Function)

Call a Javascript function. 

m, _ := NewVM()
defer m.Close()
fmt.Println(m.Call("parseInt", "1234"))

Output:
1234 <nil>
Example (Method)

Call a Javascript method. 

m, _ := NewVM()
defer m.Close()
fmt.Println(m.Call("Math.abs", -1234))

Output:
1234 <nil>

func (*VM) CallValue 

func (m *VM) CallValue(function string, args ...any) (r Value, err error)

CallValue is like Call but returns (Value, error) like EvalValue

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) Close 

func (m *VM) Close() error

Close releases the resources held by 'm'.

func (*VM) Compile 

func (m *VM) Compile(code string, filename string, flags int) ([]byte, error)

func (*VM) Eval 

func (m *VM) Eval(javascript string, flags int) (r any, err error)

Eval evaluates a script or module source in 'javascript'. 

Javascript result type  Go result type                          Go result error
-------------------------------------------------------------------------------
exception               nil                                     non-nil
null                    nil                                     nil
undefined               Undefined                               nil
string                  string                                  nil
int                     int                                     nil
bool                    bool                                    nil
float64                 float64                                 nil
BigInt                  *math/big.Int                           nil
object                  *Object                                 nil
any other type          Unsupported                             nil
Example (Exception)

Getting exception. 

m, _ := NewVM()
defer m.Close()
fmt.Println(m.Eval("throw new Error('failed');", EvalGlobal))

Output:
<nil> Error: failed
Example (Expression)

Evaluate a simple Javascript expression. 

m, _ := NewVM()
defer m.Close()
fmt.Println(m.Eval("1+2", EvalGlobal))

Output:
3 <nil>
Example (Object)

Object example. 

m, _ := NewVM()
defer m.Close()
fmt.Println(m.Eval("obj = {a: 42+314, b: 'foo'}; obj;", EvalGlobal))

Output:
{"a":356,"b":"foo"} <nil>

func (*VM) EvalAwait 

func (m *VM) EvalAwait(javascript string, flags int) (r any, err error)

func (*VM) EvalThis 

func (m *VM) EvalThis(obj Value, javascript string, flags int) (r any, err error)

EvalThis is like eval but sets javascript 'this' to 'obj'.

func (*VM) EvalThisAwait 

func (m *VM) EvalThisAwait(obj Value, javascript string, flags int) (r any, err error)

func (*VM) EvalThisValue 

func (m *VM) EvalThisValue(obj Value, javascript string, flags int) (r Value, err error)

EvalThisValue is like EvalValue but sets javascript 'this' to obj.

func (*VM) EvalValue 

func (m *VM) EvalValue(javascript string, flags int) (r Value, err error)

EvalValue evaluates a script or module source in 'javascript' and returns the resulting Value, or an error, if any.

Exceptions thrown during evaluation of the script are returned as Go errors.

If no error is returned, the caller must properly handle the returned Value using Dup/Free.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) GetProperty 

func (m *VM) GetProperty(this Value, prop Atom) (r any, err error)

GetProperty returns this.prop.

func (*VM) GetPropertyValue 

func (m *VM) GetPropertyValue(this Value, prop Atom) (r Value, err error)

GetPropertyValue returns this.prop.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) GlobalObject 

func (m *VM) GlobalObject() (r Value)

GlobalObject returns m's global object.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) LoadModule 

func (m *VM) LoadModule(code string, moduleName string, loadOnly bool) (r Value, err error)

func (*VM) LoadModuleBytecode 

func (m *VM) LoadModuleBytecode(buf []byte, loadOnly bool) (r Value, err error)

func (*VM) LoadModuleFile 

func (m *VM) LoadModuleFile(filePath string, moduleName string) (r Value, err error)

func (*VM) NewAtom 

func (m *VM) NewAtom(s string) (r Atom, err error)

NewAtom returns an unique indentifier of 's' or an error, if any.

func (*VM) NewFloat64 

func (m *VM) NewFloat64(n float64) Value

NewFloat64 returns a new Value from 'n'.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) NewInt 

func (m *VM) NewInt(n int) Value

NewInt returns a new Value from 'n'.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) NewMustAtom 

func (m *VM) NewMustAtom(s string) Atom

func (*VM) NewMustObjectValue 

func (m *VM) NewMustObjectValue() Value

func (*VM) NewMustString 

func (m *VM) NewMustString(s string) Value

func (*VM) NewObjectValue 

func (m *VM) NewObjectValue() (r Value, err error)

NewObjectValue returns a new Value representing '{}'.

func (*VM) NewString 

func (m *VM) NewString(s string) (r Value, err error)

NewString returns a new Value from 's'.

Note: See the Value documentation for details about manual memory management of Value objects.

func (*VM) RegisterFunc 

func (m *VM) RegisterFunc(name string, f any, wantThis bool) (err error)

RegisterFunc registers a Go function 'f' and makes it callable from Javascript.

The 'f' argument can be a regular Go function, a closure, a method expression or a method value. All of them are called 'Go function' below.

The Go function can have zero or more parameters. If 'wantThis' is true then the first parameter of the Go function will get the Javascript value of 'this'. Depending on context, 'this' can be Javascript null or undefined.

Go functions with multiple results return them as an Javascript array.

Go nil errors are converted to Javascript null.

Go non-nil errors are converted to Javascript strings using the Error() method.

Any Go <-> Javascript failing type conversion between arguments/return values throws a Javascript type error exception.

There is a limit on the total number of currently registered Go functions.

Note: The 'name' argument should be a valid Javascript identifier. It is not currently enforced but this may change later.

Example (Error)

Call error returning Go function from Javascript. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(a int) error {
	if a < 0 {
		return fmt.Errorf("negative")
	}
	return nil
}, false)
fmt.Println(m.Eval("gofunc(-1)", EvalGlobal))
fmt.Println(m.Eval("gofunc(1)", EvalGlobal))

Output:
negative <nil>
<nil> <nil>
Example (MultipleReturn)

Call multiple return Go function from Javascript. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(a, b int) (int, int) { return 10 * a, 100 * b }, false)
fmt.Println(m.Eval("gofunc(2, 3)", EvalGlobal))

Output:
[20,300] <nil>
Example (SingleReturn)

Call single return Go function from Javascript. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(a, b, c int) int { return a + b*c }, false)
fmt.Println(m.Eval("gofunc(2, 3, 5)", EvalGlobal))

Output:
17 <nil>
Example (ThisNonNull)

Passing Javascript 'this' to a Go function. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(this any) any { return this }, true)
fmt.Println(m.Eval("var obj = { foo: 314, method: gofunc }; obj.method()", EvalGlobal))

Output:
{"foo":314} <nil>
Example (ThisNonNull2)

Passing Javascript 'this' to a Go function. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(this any, n int) (any, int) { return this, 10 * n }, true)
fmt.Println(m.Eval("var obj = { foo: 314, method: gofunc }; obj.method(42)", EvalGlobal))

Output:
[{"foo":314},420] <nil>
Example (ThisNull)

Passing undefined Javascript 'this' to a Go function. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(this any) any { return this }, true)
fmt.Println(m.Eval("gofunc()", EvalGlobal))

Output:
undefined <nil>
Example (ThisNull2)

Passing undefined Javascript 'this' to a Go function. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(this any, n int) (any, int) { return this, 10 * n }, true)
fmt.Println(m.Eval("gofunc(42)", EvalGlobal))

Output:
[null,420] <nil>
Example (Void)

Call void Go function from Javascript. 

m, _ := NewVM()
defer m.Close()
m.RegisterFunc("gofunc", func(a, b, c int) { fmt.Println(a + b*c) }, false)
fmt.Println(m.Eval("gofunc(2, 3, 5)", EvalGlobal))

Output:
17
undefined <nil>

func (*VM) SetDefaultModuleLoader 

func (m *VM) SetDefaultModuleLoader()

SetDefaultModuleLoader will enable loading module using the default module loader.

Example

Enabling the module loader. 

m, _ := NewVM()
defer m.Close()
m.SetDefaultModuleLoader()
// testdata/power.js:
//  export const name = "Power";
//
//  export function square(x) {
//  	return x*x;
//  }
//
//  export function cube(x) {
//  	return x*x*x;
//  }
m.Eval("import * as Power from './testdata/power.js'; globalThis.Power = Power;", EvalModule)
fmt.Println(m.Eval("[Power.square(2), Power.cube(2)];", EvalGlobal))

Output:
[4,8] <nil>

func (*VM) SetProperty 

func (m *VM) SetProperty(this Value, prop Atom, val any) (err error)

SetProperty sets this.prop = val.

func (*VM) SetPropertyValue 

func (m *VM) SetPropertyValue(this Value, prop Atom, val Value) (err error)

SetPropertyValue sets this.prop = val.

func (*VM) StdAddHelpers 

func (m *VM) StdAddHelpers() error

StdAddHelpers adds the 'print' and 'console' global objects to 'm'.

type Value 

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

Value represents a native Javascript value. Values are reference counted and their lifetime is managed by an independent Javascript garbage collector. To avoid memory corruption/leaks caused by tripping the Javascript GC, a Value must not

  • be copied. Use the Dup method instead.
  • become unreachable without calling its Free method.
  • be used after its Free() method was called.
  • outlive its VM.

It is recommended to use native Go values instead of Value where possible.

When passing a Value down the call stack use Dup. For example in main 

v, _ := EvalValue(someScript)
defer v.Free()
foo(v.Dup()) // Instead of foo(v)

In 'foo' Free must be used. For example 

func foo(v Value) {
        defer v.Free()
        ...
}

This ensures the/only topmost Free marks 'v' eligible for garbage collection.

Beware that the correct setup/handling becomes more complicated when using closures, Values are sent through a channel etc. In particular, if a goroutine 1 passes a Dup of 'v' to goroutine 2 and goroutine 1 completes and thus frees 'v' before goroutine 2 completes, the reference counting mechanism will fail. In other words, every Free must be strictly paired with the Dup that preceded obtaining the Value and the Dup/Free calls must respect the original nesting. This is correct. 

Dup             // in main
        Dup     // in foo
        Free    // in foo
Free            // in main

This will fail, for example in the above discussed goroutines scenario. 

Dup            // in g1
        Dup    // in g2
Free           // in g1
        Free   // in g2

The fix might be in this case to arrange goroutine 1 to wait for goroutine 2 to complete before executing Free in goroutine 1.

See TestMemgrind for an example of how to detect memory leaks caused not only by improper Value use.

func (Value) Any 

func (v Value) Any() (r any, err error)

Any attemtps to convert 'v' to any using the same rules as there are for the return value of VM.Eval.

func (Value) Await 

func (v Value) Await() Value

func (Value) Dup 

func (v Value) Dup() Value

Dup returns a copy of 'v' while updating its reference count.

func (*Value) Free 

func (v *Value) Free()

Free marks 'v' as no longer used and updates its reference count. 'v' must not be used afterwards.

func (Value) GetProperty 

func (v Value) GetProperty(prop Atom) (r any, err error)

GetProperty returns v.prop.

func (Value) GetPropertyValue 

func (v Value) GetPropertyValue(prop Atom) (r Value, err error)

GetPropertyValue returns v.prop.

func (Value) IsPromise 

func (v Value) IsPromise() bool

func (Value) IsUndefined 

func (v Value) IsUndefined() bool

IsUndefined reports whether 'v' represents the Javascript value 'undefined'.

func (Value) MarshalJSON 

func (v Value) MarshalJSON() (r []byte, err error)

MarshalJSON implements encoding/json.Marshaler.

func (Value) MustAny 

func (v Value) MustAny() any

func (Value) MustGetProperty 

func (v Value) MustGetProperty(prop Atom) any

func (Value) MustGetPropertyValue 

func (v Value) MustGetPropertyValue(prop Atom) Value

func (Value) MustMarshalJSON 

func (v Value) MustMarshalJSON() []byte

func (Value) MustSetProperty 

func (v Value) MustSetProperty(prop Atom, val any)

func (Value) MustSetPropertyValue 

func (v Value) MustSetPropertyValue(prop Atom, val Value)

func (Value) SetProperty 

func (v Value) SetProperty(prop Atom, val any) (err error)

SetProperty sets v.prop = val.

func (Value) SetPropertyValue 

func (v Value) SetPropertyValue(prop Atom, val Value) (err error)

SetPropertyValue sets v.prop = val.

func (*Value) VM 

func (v *Value) VM() *VM

VM returns the VM associated with 'v'.

Source Files

View all Source files

Directories

Path Synopsis
Package fmt exposes some functionality of the Go stdlib fmt package to a quickjs.VM.
 Package fmt exposes some functionality of the Go stdlib fmt package to a quickjs.VM.

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.